DECwindows Extensions to Motif


Previous Contents Index


Chapter 2
DECwindows Toolkit Extensions

This chapter describes the new and enhanced resources and routines Digital provides to supplement those included in the OSF/Motif Toolkit.

2.1 DECwindows Resource and Routine Extensions

The following sections describe three class-specific resources and an extension to the XmStringDirectionCreate routine.

2.1.1 DXmNautoUnrealize Resource

The DXmNautoUnrealize resource is a Boolean resource that, when False, indicates that the XmBulletinBoardDialog widget (and its subclasses) creates windows for itself and its children when it is first managed and never destroys ("unrealizes") them. When True, the widget recreates the windows every time it is managed and destroys them when it is unmanaged.

When setting this resource, note the following effects on performance:

The default is False.

2.1.2 DXmNfitToScreenPolicy Resource

The DXmNfitToScreenPolicy resource, which is specific only to the dialog shell widget, automatically sizes all dialog widgets for a screen. When the DXmNfitToScreenPolicy resource is set to AS_NEEDED in an application's defaults file, the dialog shell automatically resizes and positions all dialog shells that are too big for the user's screen.

You can set this resource only in an application's defaults file (access is CG); it cannot be set in a UIL module or through a call to XtSetArg. The format for setting this resource is as follows:


*DXmfitToScreenPolicy: AS_NEEDED 

2.1.3 DXmNlayoutDirection Resource

The DXmNlayoutDirection resource is used by applications that require interpretation of direction, widget layout direction, and widget traversal direction. This resource allows the application to be configured for environments that expect direction from either left to right or from right to left. The choices (constants) for this resource are as follows:
Value Description
DXmLAYOUT_LEFT_DOWN The direction of the layout is right to left and top to bottom.
DXmLAYOUT_LEFT_UP The direction of the layout is right to left and bottom to top.
DXmLAYOUT_RIGHT_DOWN The direction of the layout is left to right and top to bottom.
DXmLAYOUT_RIGHT_UP The direction of the layout is left to right and bottom to top.

The default is DXmLAYOUT_LEFT_DOWN.

The DXmNlayoutDirection resource can be inherited by any widget that inherits the XmPrimitive, XmManager, or XmGadget widget class.

2.1.3.1 DXmNlayoutDirection in DECwindows Extensions to Motif

The behavior of the DXmNlayoutDirection resource depends on the function or widget that you use it with. DXmNlayoutDirection performs as a read/write value that holds the layout direction of the widget components, such as labels, pop ups, push buttons, and scroll bars, in relation to each other for the following functions:

Table 2-1 describes the effect this resource has on the DXmLAYOUT_LEFT_DOWN and DXmLAYOUT_RIGHT_DOWN values for these functions.

Table 2-1 DXmNlayoutDirection Values
DXmLAYOUT_LEFT_DOWN DXmLAYOUT_RIGHT_DOWN
The direction of the layout is right to left and top to bottom. The direction of the layout is left to right and top to bottom.
  The default is DXmLAYOUT_RIGHT_DOWN, or 3. Access is CSG.

DXmNlayoutDirection performs as a read/write value that holds the layout direction of the vertical scroll bars in relation to the text for the DXmCreateScrolledCSText function. In addition, this resource controls the resizing direction for the widget width.

Note

The legal values for DXmNlayoutDirection, if specified in a resource file, are:
  • left_down---layout is right to left and top to bottom.
  • right_down---layout is left to right and top to bottom.

Table 2-2 describes the effect that this resource has on the DXmLAYOUT_LEFT_DOWN and DXmLAYOUT_RIGHT_DOWN values for this function.

Table 2-2 DXmNlayoutDirection Values for the DXmCreateScrolledCSText and DXmCreateCSText Functions
DXmLAYOUT_LEFT_DOWN DXmLAYOUT_RIGHT_DOWN
The default value for XmNscrollLeftSide is TRUE. If XmNresizeWidth is TRUE, the left edge of the widget resizes. The default value for XmNscrollLeftSide is FALSE. If XmNresizeWidth is TRUE, the right edge of the widget resizes.
  The default is DXmLAYOUT_RIGHT_DOWN, or 3. Access is CSG.

2.1.3.2 DXmNlayoutDirection in DECwindows Motif

The following OSF/Motif widgets support DXmNlayoutDirection:

Table 2-3 describes the effect that the DXmNlayoutDirection resource has on these widgets' components.

Table 2-3 DXmNlayoutDirection Effect on Widget Components
Widget Component DXmLAYOUT_LEFT_DOWN DXmLAYOUT_RIGHT_DOWN
CascadeButton / Gadget Cascade graphic appears on the left side, and the menu is brought up on the left. XmALIGNMENT_BEGINNING aligns the right edges of lines and XmALIGNMENT_END aligns the left edges of lines. Cascade graphic appears on the right side, and the menu is brought up on the right. XmALIGNMENT_BEGINNING aligns the left edges of lines and XmALIGNMENT_END aligns the right edges of lines.
Command Prompt string is placed on the right side, with a default of "<". Prompt string is placed on the left side, with a default of ">".
FileSelectionBox Buttons are laid out from right to left, labels are aligned to the right side, scroll bars are aligned to the left side, and text is displayed from right to left. Buttons are laid out from left to right, labels are aligned to the left side, scroll bars are aligned to the right side, and text is displayed from left to right.
Form The word "near" means right when referenced in the OSF/Motif Programmer's Reference for the XmNrubberPositioning, XmNleftAttachment, XmNleftOffset, XmNleftPosition, and XmNleftWidget resources.

The word "far" is defined to mean left when referenced in the OSF/Motif Programmer's Reference for the XmNrightAttachment, XmNrightOffset, XmNrightPosition, and XmNrightWidget resources.

The word "near" is defined to mean left when referenced in the OSF/Motif Programmer's Reference for the XmNrubberPositioning, XmNleftAttachment, XmNleftOffset, XmNleftPosition, and XmNleftWidget resources.

The word "far" is defined to mean right when referenced in the OSF/Motif Programmer's Reference for the XmNrightAttachment, XmNrightOffset, XmNrightPosition, and XmNrightWidget resources.

Label / Gadget XmALIGNMENT_BEGINNING aligns the right edges of lines and XmALIGNMENT_END aligns the left edges of lines. XmALIGNMENT_BEGINNING aligns the left edges of lines and XmALIGNMENT_END aligns the right edges of lines.
Message Box Buttons are laid out from right to left; pixmap is placed at the right side. Buttons are laid out from left to right; pixmap is placed at the left side.
Option Menu Label is aligned on right side and the bar graphic is placed on left side. If the pull-down menu cannot be placed over the button, the menu is displayed to the left side. Label is aligned on the left side and bar graphic is placed on the right side. If the pull-down menu cannot be placed over the button, the menu is displayed to the right side.
PanedWindow The sash is placed on the left side. The sash is placed on the right side.
Popup Menu The hot spot is located at the upper right corner. The hot spot is located at the upper left corner.
Pull-Down Menu If pulled down from a menu bar or a horizontal menu, the right edge of pull-down menu is aligned with the right edge of its parent cascade button. If pulled down from a menu bar or a horizontal menu, the left edge of pull-down menu is aligned with the left edge of its parent cascade button.
Pushbutton/Gadget The accelerator is displayed on the left side. XmALIGNMENT_BEGINNING aligns the right edge of lines and XmALIGNMENT_END aligns the left edge of lines. The accelerator is displayed on the right side. XmALIGNMENT_BEGINNING aligns the left edge of lines and XmALIGNMENT_END aligns the right edge of lines.
RowColumn Children are laid out from right to left, including cascades in a menu bar. Children are laid out from left to right, including cascades in a menu bar.
Scale The text string is placed on the right side. If XmNorientation is XmVERTICAL, and XmNshowValue is TRUE, the value is displayed on the left side of the scale. If XmNorientation is XmHORIZONTAL, the default XmNprocessingDirection is XmMAX_ON_LEFT. The text string is placed on the left side of the scale. If XmNorientation is XmVERTICAL and XmNshowValue is TRUE, the value is displayed on the right side of the scale. If XmNorientation is XmHORIZONTAL, the default XmNprocessingDirection is XmMAX_ON_RIGHT.
scroll bar If XmNorientation is XmHORIZONTAL, the default XmNprocessingDirection is XmMAX_ON_LEFT. If XmNorientation is XmHORIZONTAL, the default XmNprocessingDirection is XmMAX_ON_RIGHT.
ScrolledWindow The default XmNscrollbarPlacement is XmBOTTOM_LEFT. The default XmNscrollbarPlacement is XmBOTTOM_RIGHT.
SelectionBox The buttons are laid out from right to left, and labels are aligned on the right side. The buttons are laid out from left to right, and labels are aligned on the left side.
ToggleButton / Gadget The accelerator is displayed on the left side of the label, and the toggle graphic is placed on the right side of the label. XmALIGNMENT_BEGINNING aligns the right edges of lines, and XmALIGNMENT_END aligns the left edges of lines. The accelerator is displayed on the right side of the label, and the toggle graphic is placed on the left side of the label. XmALIGNMENT_BEGINNING aligns the left edges of lines, and XmALIGNMENT_END aligns the right edges of lines.

2.1.4 XmStringDirectionCreate Routine

The XmStringDirectionCreate routine creates a compound string that specifies in which direction your system displays characters within a string or within a segment of a compound string. The data type you use to specify the direction is XmStringDirection.

In addition to specifying the left-to-right or right-to-left values for the XmStringDirection data type, a DECwindows extension allows you to specify that the application revert to the previous direction before displaying the next character in the string.

The functions of the XmStringDirection data types are summarized in the following table:
XmStringDirection Data Type Description
XmSTRING_DIRECTION_L_TO_R Sets the string direction left to right.
XmSTRING_DIRECTION_R_TO_L Sets the string direction right to left.
XmSTRING_DIRECTION_REVERT Reverts to the previous string direction (DECwindows extension).

2.2 DECwindows Toolkit Routines

The balance of this chapter describes, in alphabetical order, the Toolkit routines Digital has added to supplement those provided by the OSF/Motif Toolkit. These routines fall into the following general categories:

The DECwindows Motif Guide to Application Programming contains complete information about the DECwindows-specific widgets, including guidelines (with examples) for using many of the routines described in this manual.


DXmActivateWidget

Allows the application to simulate push button activation.

Format


void DXmActivateWidget(widget) 
      Widget  widget; 


Arguments

widget

A pointer to the widget data structure.

Description

The DXmActivateWidget routine allows an application to generate the same highlighting and callbacks that would occur if the user clicked on a push button. Using this routine in your application enables you to maintain a consistent user interface. For example, your application could allow a user to choose a function by either pressing a push button or, if the DXmActivateWidget routine has been called, by selecting a menu option that activates the corresponding push button.

The DXmActivateWidget routine only supports push buttons.


DXmChildren

Returns a list of the widget's children.

Format


WidgetList DXmChildren (widget) 
            Widget  widget; 


Return Value

A list of the widget's children.

Arguments

widget

The identifier (widget ID) of the widget.

Description

The DXmChildren routine returns a list of the widget's children. Note that children must request geometry management changes from their parent and that a parent widget can resize its children. You can use this routine to learn the length of a widget_list.

DXmColorMixGetNewColor

Retrieves (returns) the color mixing widget's current new color red, green, and blue values.

Format


void DXmColorMixGetNewColor(cmw, red, green, blue) 
      DXmColorMixWidget  cmw; 
      unsigned short     *red; 
      unsigned short     *green; 
      unsigned short     *blue; 


Arguments

cmw

The widget identifier of the color mixing widget.

red

A pointer to the returned new color red value.

green

A pointer to the returned new color green value.

blue

A pointer to the returned new color blue value.

Description

DXmColorMixGetNewColor allows the calling application or routine to quickly obtain the current color value from the color mixing widget. Note that if your application uses the default color mixing subwidget, the application will perform this operation faster if you call this routine instead of the Intrinsic routine XtGetValues. (See the X Window System Toolkit manual for more information about using the Intrinsic routines.)
Routine Description
DXmColorMixSetNewColor Sets the new color red, green, and blue values in the color mixing widget
DXmCreateColorMix Creates the color mixing widget without a dialog box
DXmCreateColorMixDialog Creates the color mixing widget with a dialog box

DXmColorMixSetNewColor

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

Format


void DXmColorMixSetNewColor(cmw, red, green, blue) 
      DXmColorMixWidget  cmw; 
      unsigned short     red; 
      unsigned short     green; 
      unsigned short     blue; 


Arguments

cmw

The identifier (widget ID) of the color mixing widget.

red

The new color red value. The value is expressed as an X color value (0 to 65535).

green

The new color green value. The value is expressed as an X color value

blue

The new color blue value. The value is expressed as an X color value (0 to 65535).

Description

The DXmColorMixSetNewColor routine allows the application or a user-supplied color mixer subwidget to pass the current color value to the color mixing widget. Note that your application will perform this operation faster if you call this routine instead of the Intrinsic routine XtSetValues. (See the X Window System Toolkit manual for more information about using the Intrinsic routines.)
Routine Description
DXmColorMixGetNewColor Retrieves (returns) the current color value from the color mixing widget
DXmCreateColorMix Creates the color mixing widget without a dialog box
DXmCreateColorMixDialog Creates the color mixing widget with a dialog box

DXmCreateColorMix

Creates a color mixing widget, without a pop-up dialog box.
Widget Class Hierarchy

Core Resource Set
\
Composite Resource Set
\
Constraint Resource Set
\
XmManager Resource Set
\
XmBulletinBoard Resource Set
\
DXmColorMix Resource Set

Format


Widget DXmCreateColorMix(parent, name, arglist, argcount) 
        Widget    parent; 
        String    name; 
        ArgList   arglist; 
        Cardinal  argcount; 


Return Value

The identifier (widget ID) of the created color mixing widget.

Arguments

parent

The identifier (widget ID) of the parent widget.

name

The name of the created widget.

arglist

The application argument list.

argcount

The number of arguments in the application argument list.

Description

The DXmCreateColorMix routine uses the same arguments and resources as the DXmCreateColorMixDialog routine to create a color mixing widget, but does not include a pop-up dialog box. Note, however, that if color resources are limited, your application should use the pop-up color mixing widget instead. See the DXmCreateColorMixDialog routine for complete information.


Previous Next Contents Index