DECwindows Extensions to Motif

Document revision date: 10 November 2000

DECwindows Extensions to Motif

Contents

Index

typedef struct { int reason; XEvent *event; unsigned short newred; unsigned short newgrn; unsigned short newblu; char *newname; unsigned short origred; unsigned short origgrn; unsigned short origblu; } DXmColorMixCallbackStruct;

Callback Field Descriptions

reason
An integer set to the callback reason. See the Callback Reasons section for the values that are valid for this widget.
event
A pointer to the X event structure describing the event that generated this callback.
newred
The new red color value for the color mixing widget.
newgrn
The new green color value for the color mixing widget.
newblu
The new blue color value for the color mixing widget.
newname
Passes a color name to an application. If the user selects a named color from the Browser and then triggers a callback to the application without modifying the new color, the newname field of the callback data structure is filled in with a pointer to an ASCII, null-terminated string that contains the color's X11 name. This string is read-only, and should not be freed or modified.
If a color is generated in one of the other color models, or generated in the browser and subsequently modified, the newname field in the callback structure is set to Null.
origred
The original red color value for the color mixing widget.
origgrn
The original green color value for the color mixing widget.
origblu
The original blue color value for the color mixing widget.

Callback Reasons

XmCR_ACTIVATE
The user has activated the OK push button.
XmCR_APPLY
The user has activated the Apply push button.
XmCR_CANCEL
The user has activated the Cancel push button.

Description

The color mixing widget allows your DECwindows Motif applications to query users for a color. The color mixing widget provides users with immediate feedback, displaying each new color as it is selected. This widget uses a pop-up dialog box (or nonpop-up dialog box if you use the DXmCreateColorMix routine) that is preconfigured to contain the following subwidgets:

Subwidget Description

Scratch pad Stores intermediate colors for later use in color mixing

Color display subwidget Displays the original color and the new color.

Color model option menu subwidget Implements choice of color model.

Color mixer subwidget Provides graphic tools users can use to define new colors.

Push button subwidgets Activates color mixing widget functions.

Label subwidgets Provides descriptive information.

The color mixing widget allows a user to choose from up to five different color models:

Color Picker
The default color model for the color mixing widget on color systems (it does not display on noncolor systems or on systems with too few resources).
The color picker consists of a 10-color color spectrum and a color palette option menu, a color interpolator and its title, a smear button, and undo button, two paint bucket buttons, and arrow buttons to control the warmth and lightness of interpolator colors.
HLS (hue, lightness, saturation)
In the HLS color model, a color is specified by three characteristics: hue, lightness, and saturation. Hue is color. Lightness describes the intensity of the color (the amount of the color). Saturation describes the purity of the color or how much the color is diluted by white.
To support the HLS color model, the color mixer subwidget contains three scales that represent the ranges of hue, lightness, and saturation. The hue scale presents color values as a range between 0 and 360. The lightness and saturation scales present their values as a range of percentages between 0 and 100.
RGB (red, green, blue)
The default color model for the color mixing widget on monochrome systems.
In the RGB color model, a color is specified as a mixture of different intensities of red, green, and blue. In the X Window System, Version 11, you specify the intensity of red, green, or blue as a value between 0 and 65,535. Zero is the lowest intensity. Black is defined as a zero-intensity value for all three colors; white is 100 percent intensity for all three colors.
To support the RGB color model, the color mixer subwidget contains three scales that represent the ranges of intensity of red, green, and blue. Each scale presents these color values as a percentage between 0 and 100. In addition, the color mixer subwidget contains text widgets in which users of your application can enter RGB values directly as text. The text widgets and the scales are linked: a change in one effects a corresponding change in the other.
Browser (X11 named colors)
A scrolled window that presents the user with a list of X11 named colors. Each button in the scrolled window shows the name of an X11 color. If enough resources are available, the background is set to that color. (If the new color is not further modified by other color models, the X11 name of this color is also returned to the application as part of the color mixing widget's callback structure.) You can use the scroll bar to scroll through this color list. Clicking MB1 on a color in the list causes the color display subwidget to become filled with that color. The color browser is available on all systems.
Greyscale Mixer
A scale widget that allows generation of gray shades ranging from black to white. When the Greyscale mixer is selected, the current new color is converted to an appropriate shade of gray, which can then be adjusted with the scale widget. All shades of gray generated by this model are a mixture of equal portions of red, green, and blue, which means that they appear identically on both color and gray scale systems.
The Greyscale mixer is available on all systems.

Note
When considering whether to use a pop-up or nonpop-up color mixing widget, note the following:

The pop-up color mixing widget (which you create with the DXmCreateColorMixDialog routine) allocates the necessary color cells each time it is mapped and then releases them each time the widget is unmapped.
The nonpop-up color mixing widget (which you create with the DXmCreateColorMix routine) allocates the necessary color cells at creation time but does not release them until the widget is destroyed. As such, if color resources are limited, your application should use the pop-up color mixing widget instead of the nonpop-up version.

See the DECwindows Motif Guide to Application Programming for a complete description of the color mixing widget. See also the following routines for related information:

Routine Description

DXmCreateColorMix Creates the color mixing widget without a dialog box.

DXmColorMixGetNewColor Retrieves (returns) the current color value from the color mixing widget.

DXmColorMixSetNewColor Sets the new color red, green, and blue values in the color mixing widget.

Subwidget	Description
Scratch pad	Stores intermediate colors for later use in color mixing
Color display subwidget	Displays the original color and the new color.
Color model option menu subwidget	Implements choice of color model.
Color mixer subwidget	Provides graphic tools users can use to define new colors.
Push button subwidgets	Activates color mixing widget functions.
Label subwidgets	Provides descriptive information.

Routine	Description
DXmCreateColorMix	Creates the color mixing widget without a dialog box.
DXmColorMixGetNewColor	Retrieves (returns) the current color value from the color mixing widget.
DXmColorMixSetNewColor	Sets the new color red, green, and blue values in the color mixing widget.

Geometry Management The color mixing widget completely controls the layout of its children. Resizing The color mixing widget computes the smallest possible size required to enclose all of its children, including any of the variably sized color mixing subwidgets. The size remains fixed while the user selects different color models from the option menu.

DXmCreateCSText

Creates a compound string text widget.

Widget Class Hierarchy

Core Resource Set
\
XmPrimitive Resource Set
\
DXmCSText Resource Set

Format

Widget DXmCreateCSText (parent, name, args, num_args) Widget parent; char *name; Args *args; int num_args;

Resource Information You can set the following widget-specific resources in the args:

Boolean DXmNbidirectionalCursor; int DXmNeditingPath; XtCallbackList DXmNnofontCallback; int DXmNtextPath; XtCallbackList XmNactivateCallback; Boolean XmNautoShowCursorPosition; int XmNblinkRate; int XmNcolumns; DXmCSTextPosition XmNcursorPosition; Boolean XmNcursorPositionVisible; Boolean XmNeditable; int XmNeditMode; XtCallbackList XmNfocusCallback; XmFontlist XmNfontList; XtCallbackList XmNlosingFocusCallback; Dimension XmNmarginHeight; Dimension XmNmarginWidth; int XmNmaxLength; XtCallbackList XmNmodifyVerifyCallback; XtCallbackList XmNmotionVerifyCallback; Boolean XmNpendingDelete Boolean XmNresizeHeight: Boolean XmNresizeWidth; int XmNrows; Boolean XmNscrollHorizontal; Boolean XmNscrollLeftSide; Boolean XmNscrollTopSide; Boolean XmNscrollVertical; XmRPointer XmNselectionArray int XmNselectionArrayCount int XmNselectThreshold DXmCSTextPosition XmNtopPosition; XmString XmNvalue; XtCallbackList XmNvalueChangedCallback; Boolean XmNwordWrap;

Return Value

The identifier (widget ID) of the created compound string text widget.

Arguments

parent
The identifier (widget ID) of the parent widget.
name
The name of the created widget.
args
The application override argument list.
num_args
An integer that represents the number of arguments in the application override argument list.

Resources

DXmNbidirectionalCursor
A Boolean resource that, when True, specifies that the shape of the cursor at the insertion point will be dependent on the current editing direction. Access is CSG. The default is False.
DXmNeditingPath
A read-only value that holds the current editing text path (direction) in the compound string text widget. Initially, it is set to be equal to DXmNtextPath. This resource is used only if XmNvalue is Null. The values for this resource are as follows:

Value Description

DXmDIRECTION_RIGHT_DOWN (0) The direction of the text path is right and then down.

DXmDIRECTION_LEFT_DOWN (1) The direction of the text path is left and then down.

The default is DXmDIRECTION_RIGHT_DOWN, or 0. Access is CG.
DXmNnofontCallback
Callback made when the compound string text widget cannot find the font required to display text assigned (tagged) with a specific character set. The reason for this callback is DXmCR_NOFONT. Other callback fields are as follows:

Field Description

event A pointer to the XEvent structure that generated the callback.

charset A character set identifier for which the widget has no matching font in its font list. The callback modifies the widget font list to include an entry for the required character set.

charset_len The length of the charset string.

The default is Null. Access is C.
DXmNtextPath
A read-only value that holds the main text path (direction) of the text in the compound text widget. This resource is used only if XmNvalue is Null. It is set from the initial compound string value of the widget. The values for this resource are as follows:

Value Description

DXmDIRECTION_RIGHT_DOWN (0) The direction of the text path is right and then down.

DXmDIRECTION_LEFT_DOWN (1) The direction of the text path is left and then down.

The default is DXmDIRECTION_RIGHT_DOWN, or 0. Access is CG.
XmNactivateCallback
Callback (or callbacks) made when the user activates the CSText widget. The reason for this callback is XmCR_ACTIVATE and the associated callback structure is DXmCSTextCallbackStruct. The default is Null. Access is C.
XmNautoShowCursorPosition
A Boolean resource that, when True, ensures that the visible text contains the cursor. The default is True. Access is CSG.
XmNblinkRate
An integer indicating the blink rate of the text cursor in milliseconds. The default is 500 milliseconds. Access is CSG.
XmNcolumns
The width, in characters, of the window. The default is 20 characters (if no width is specified with the XmNwidth resource). Access is CSG.
XmNcursorPosition
An integer indicating the current location of the cursor. The default is 0. Access is CSG.
XmNcursorPositionVisible
A Boolean resource that, when True, specifies that the cursor position is marked by a blinking text cursor. The default is True. Access is CSG.
XmNeditable
A Boolean resource that, when True, indicates that the user can edit the text in the compound string text widget. When False, the user cannot edit the text. Access is CSG. The default is True.
XmNeditMode
Specifies the set of keyboard bindings used for CSText. The default set of keyboard bindings is XmSINGLE_LINE_EDIT. For multiline text, use XmMULTI_LINE_EDIT. Access is CSG.
XmNfocusCallback
Callback (or callbacks) made when the compound string text widget has accepted the input focus. The reason for this callback is XmCR_FOCUS and the associated callback structure is DXmCSTextCallbackStruct. The default is Null. Access is C.
XmNfontList
The font list to be used for the compound string text widget. The default is the current server font list (DXmDefaultFont). Access is CSG.
XmNlosingFocusCallback
Callback (or callbacks) made when the compound string text widget loses input focus. The callback reason is XmCR_LOSING_FOCUS and the associated callback structure is XmTextVerifyCallbackStruct. Other callback fields are as follows:

Field Description

event A pointer to the XEvent that generated this callback.

doit Controls whether the action that invoked the callback is performed. Setting this field to False negates the action.

currInsert The current position of the insertion cursor.

The default is Null. Access is C.
XmNmarginHeight
The number of pixels between the top or bottom edge of the window and the text. The default is 6 pixels. Access is CSG.
XmNmarginWidth
The number of pixels between the left or right edge of the window and the text. The default is 6 pixels. Access is CSG.
XmNmaxLength
The maximum length of the text, in characters, in the compound string text widget. The default is the largest integer (MAXINT). Access is CSG.
XmNmodifyVerifyCallback
Callback (or callbacks) made before text is deleted from or inserted into the CSText widget. The callback reason is XmCR_MODIFYING_TEXT_VALUE and the associated callback structure is DXmCSTextVerifyCallbackStruct. Other callback fields are as follows:

Field Description

event A pointer to the XEvent that generated this callback.

doit Controls whether the action that invoked the callback is performed. Setting this field to False negates the action.

currInsert The current position of the insertion cursor.

newInsert The position of the cursor after the action has been completed.

startPos The starting position of the text that is to be modified.

endPos The ending position of the text that is to be modified. If no text is replaced or deleted, the value is the same as startPos.

text A pointer to an XmString holding the text to be inserted.

The default is Null. Access is C.
XmNmotionVerifyCallback
Callback (or callbacks) made before the cursor is moved to another position. The callback reason is XmCR_MOVING_INSERT_CURSOR and the associated callback structure is XmTextVerifyCallbackStruct. Other callback fields are as follows:

Field Description

event A pointer to the XEvent that generated this callback.

doit Controls whether the action that invoked the callback is performed. Setting this field to False negates the action.

currInsert The current position of the insertion cursor.

newInsert The position of the cursor after the action has been completed.

The default is Null. Access is C.
XmNpendingDelete
A Boolean resource that, when True, specifies that selected text containing the insertion point is to be deleted when new text is entered. The default is True. Access is CSG.
XmNresizeHeight
A Boolean resource that specifies whether the compound string text widget resizes its height to accommodate all the text contained in the widget. When True, the compound string text widget resizes its height and the text is always displayed starting from the first position in the source, even if instructed otherwise. This resource is ignored if XmNscrollVertical is True. The default is False. Access is CSG.
XmNresizeWidth
A Boolean resource that specifies whether the compound string text widget resizes its width to accommodate all the text contained in the widget. When True, the compound string text widget resizes its width. This resource is ignored if XmNwordWrap is True. The default is False. Access is CSG.
XmNrows
The height, in characters, of the window. This resource is ignored if the XmNeditMode resource is XmSINGLE_LINE_EDIT. The default is 1 character (if no height has been specified with the XmNheight resource). Access is CSG.
XmNscrollHorizontal
A Boolean resource that, when True, adds a scroll bar that allows the user to scroll through the text horizontally. The default is False. Access is CG.
This resource is valid only for the DXmCreateScrolledCSText routine.
XmNscrollLeftSide
A Boolean resource that, when True, places the vertical scroll bar on the left side of the compound string text window. This resource is ignored if the XmNscrollVertical resource is False. Access is CG.
This resource is valid only for the DXmCreateScrolledCSText routine.
XmNscrollTopSide
A Boolean resource that, when True, places the horizontal scroll bar at the top side of the compound string text window. The default is False. Access is CG.
This resource is valid only for the DXmCreateScrolledCSText routine.
XmNscrollVertical
A Boolean resource that, when True, adds a scroll bar that allows the user to scroll through the text vertically. The default is False. Access is CG.
This resource is valid only for the DXmCreateScrolledCSText routine.
XmNselectionArray
Specifies actions that result from multiple mouse clicks. The value of this resource is an array of XmTextScanType elements. The following values (listed in the order they occur in the default array) indicate the possible actions:

Value Description

XmSELECT_POSITION Resets the insertion cursor position

XmSELECT_WORD Selects a word

XmSELECT_LINE Selects a line of text

XmSELECT_ALL Selects all of the text

The default is the default array. Access is CSG.
XmNselectionArrayCount
The number of elements in the XmNselectionArray resource. The default is 4. Access is CSG.
XmNselectThreshold
The number of pixels of motion required to select the next character during a mouse click and drag operation. The default is 5 pixels. Access is CSG.
XmNtopPosition
Displays the position of text at the top of the window. The default is 0. Access is CSG.
XmNvalue
The text contents of the compound string text widget. The default is Null. When Null, the text path and editing paths are set to DXmDIRECTION_RIGHT_DOWN. Otherwise, the text and editing paths are set from the direction of the first segment of the value. The access is CSG.
XmNvalueChangedCallback
Callback (or callbacks) made when the value of the compound string text widget changes. The reason for this callback is XmCR_VALUE_CHANGED and the associated callback structure is DXmCSTextCallbackStruct. The default is Null. Access is C.
XmNwordWrap
A Boolean resource that specifies whether word wrap is set. When True, lines are broken at word breaks and text does not run off the right edge of the window. This resource is ignored if the XmNeditMode resource is set to XmSINGLE_LINE_EDIT. The default is False. Access is CSG.

Value	Description
DXmDIRECTION_RIGHT_DOWN (0)	The direction of the text path is right and then down.
DXmDIRECTION_LEFT_DOWN (1)	The direction of the text path is left and then down.

Field	Description
event	A pointer to the XEvent structure that generated the callback.
charset	A character set identifier for which the widget has no matching font in its font list. The callback modifies the widget font list to include an entry for the required character set.
charset_len	The length of the charset string.

Value	Description
DXmDIRECTION_RIGHT_DOWN (0)	The direction of the text path is right and then down.
DXmDIRECTION_LEFT_DOWN (1)	The direction of the text path is left and then down.

Field	Description
event	A pointer to the XEvent that generated this callback.
doit	Controls whether the action that invoked the callback is performed. Setting this field to False negates the action.
currInsert	The current position of the insertion cursor.

Field	Description
event	A pointer to the XEvent that generated this callback.
doit	Controls whether the action that invoked the callback is performed. Setting this field to False negates the action.
currInsert	The current position of the insertion cursor.
newInsert	The position of the cursor after the action has been completed.
startPos	The starting position of the text that is to be modified.
endPos	The ending position of the text that is to be modified. If no text is replaced or deleted, the value is the same as startPos.
text	A pointer to an XmString holding the text to be inserted.

Field	Description
event	A pointer to the XEvent that generated this callback.
doit	Controls whether the action that invoked the callback is performed. Setting this field to False negates the action.
currInsert	The current position of the insertion cursor.
newInsert	The position of the cursor after the action has been completed.

Value	Description
XmSELECT_POSITION	Resets the insertion cursor position
XmSELECT_WORD	Selects a word
XmSELECT_LINE	Selects a line of text
XmSELECT_ALL	Selects all of the text

Resource Exceptions

The DXmCSText widget supports the Core resources XmNwidth and XmNheight differently in that the defaults for both resources are set as large as necessary to display the rows and columns with the given margin width and margin height.

Callback Information

Following are descriptions of the two callback structures used by the CSText widget: DXmCSTextCallback Structure
typedef struct { int reason; XEvent *event; char *charset; unsigned int charset_len; } DXmCSTextCallbackStruct;
DXmCSTextCallback Fields
reason
An integer set to the callback reason.
event
A pointer to the XEvent structure that generated the callback.
charset
A character set identifier for which the widget has no matching font in its font list. The callback modifies the widget font list to include an entry for the required character set.
charset_len
The length of the charset string. DXmCSTextCallback Reasons The following table lists the reasons and valid callback fields:

Reason Description Valid Fields

DXmCR_NOFONT There was no entry in the widget font list for the required character set. reason, event, charset, charset_len

XmCR_ACTIVATE The user activated the CSText widget. reason, event

XmCR_FOCUS The compound string text widget has received the input focus. reason, event

XmCR_HELP The user selected help. reason, event

XmCR_VALUE_CHANGED The user changed the value of the text in the compound string text widget. reason

XmTextVerifyCallback Structure
typedef struct { int reason; XEvent *event; Boolean doit; DXmCSTextPosition currInsert, newInsert; DXmCSTextPosition startPos, endPos; XmString text; } XmTextVerifyCallbackStruct, *XmTextVerifyPtr;
XmTextVerifyCallback Fields
reason
An integer set to the callback reason.
event
A pointer to the XEvent structure that generated the callback.
doit
Controls whether the action that invoked the callback is performed. Setting this field to False negates the action.
currInsert
The current position of the insertion cursor.
newInsert
The position of the cursor after the action has been completed. (Used only by the XmNmodifyVerifyCallback and XmNmotionVerifyCallback callback routines.)
startPos
The starting position of the text that is to be modified. (Used only by the XmNmodifyVerifyCallback callback routine.)
endPos
The ending position of the text that is to be modified. If no text is replaced or deleted, the value is the same as startPos. (Used only by the XmNmodifyVerifyCallback callback routine.)
text
A pointer to a compound string containing the text that is to be inserted. (Used only by the XmNmodifyVerifyCallback callback routine.) XmTextVerifyCallback Reasons The following table lists the reasons and valid callback fields:

Reason Description Valid Fields

XmCR_LOSING_FOCUS The compound string text widget has lost the input focus. reason, event, doit, currInsert

XmCR_MODIFYING_TEXT_VALUE The user is deleting or inserting text. reason, event, doit, currInsert, newInsert, startPos, endPos, text

XmCR_MOVING_INSERT_CURSOR The user is moving the insertion cursor to another position. reason, event, doit, currInsert, newInsert

Reason	Description	Valid Fields
DXmCR_NOFONT	There was no entry in the widget font list for the required character set.	reason, event, charset, charset_len
XmCR_ACTIVATE	The user activated the CSText widget.	reason, event
XmCR_FOCUS	The compound string text widget has received the input focus.	reason, event
XmCR_HELP	The user selected help.	reason, event
XmCR_VALUE_CHANGED	The user changed the value of the text in the compound string text widget.	reason

Reason	Description	Valid Fields
XmCR_LOSING_FOCUS	The compound string text widget has lost the input focus.	reason, event, doit, currInsert
XmCR_MODIFYING_TEXT_VALUE	The user is deleting or inserting text.	reason, event, doit, currInsert, newInsert, startPos, endPos, text
XmCR_MOVING_INSERT_CURSOR	The user is moving the insertion cursor to another position.	reason, event, doit, currInsert, newInsert

Description

The DXmCreateCSText routine creates a compound string text widget that provides your application with text editing capabilities, including the ability for users to enter and edit text in the same character set and writing direction used throughout the user interface. By default, the text window expands or shrinks as the user enters or deletes text characters. Note that the text window does not shrink below the initial size set at creation time.

Previous Next Contents Index

privacy and legal statement

5635PRO_003.HTML