NAME

XmRowColumn — the RowColumn widget class. 

SYNOPSIS

#include <Xm/RowColumn.h>

DESCRIPTION

The RowColumn widget is a general-purpose RowColumn manager capable of containing any widget type as a child.  In general, it requires no special knowledge about how its children function and provides nothing beyond support for several different layout styles.  However, it can be configured as a menu, in which case, it expects only certain children, and it configures to a particular layout.  The menus supported are:  MenuBar, Pulldown or Popup MenuPanes, and OptionMenu. 

The type of layout performed is controlled by how the application has set the various layout resources.  It can be configured to lay out its children in either rows or columns.  In addition, the application can specify whether the children should be packed tightly together (not into organized rows and columns), or whether each child should be placed in an identically-sized box (producing a symmetrical look), or whether specific layout should be done (the current x and y positions of the children control their location). 

In addition, the application has control over both the spacing that occurs between each row and column and the margin spacing present between the edges of the RowColumn widget and any children that are placed against it. 

In most cases, the RowColumn widget has no 3-D visuals associated with it; if an application wishes to have a 3-D shadow placed around this widget, it can create the RowColumn as a child of a Frame widget. 

Classes

RowColumn inherits behavior and resources from Core, Composite, Constraint, and XmManager classes. 

The class pointer is xmRowColumnWidgetClass. 

The class name is XmRowColumn. 

New Resources

The following table defines a set of widget resources used by the programmer to specify data.  The programmer can also set the resource values for the inherited classes to set attributes for this widget.  To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters.  To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lower case or upper case, but include any underscores between words).  The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 

XmNadjustLast
Extends the last row of children to the bottom edge of RowColumn (when XmOrientation is XmHORIZONTAL) or extends the last column to the right edge of RowColumn (when XmOrientation is XmVERTICAL).  This feature is disabled by setting XmNadjustLast to False. 

XmNadjustMargin
Specifies whether the inner minor margins of all items contained within the RowColumn widget are forced to the same value.  The inner minor margin corresponds to the XmNmarginLeft, XmNmarginRight, XmNmarginTop and XmNmarginBottom resources supported by XmLabel and XmLabelGadget. 

A horizontal orientation causes XmNmarginTop and XmNmarginBottom for all items in a particular row to be forced to the same value; the value is the largest margin specified for one of the Label items. 

A vertical orientation causes XmNmarginLeft and XmNmarginRight for all items in a particular column to be forced to the same value; the value is the largest margin specified for one of the Label items. 

This keeps all text within each row or column lined up with all other text in its row or column.  If the XmNrowColumnType is either XmMENU_POPUP or XmMENU_PULLDOWN and this resource is True, only button children have their margins adjusted. 

XmNentryAlignment
Specifies the alignment type for Label or LabelGadget children when XmNisAligned is enabled.  The following are textual alignment types:

•XmALIGNMENT_BEGINNING — the default. 

•XmALIGNMENT_CENTER. 

•XmALIGNMENT_END. 

See the description of XmNalignment in the XmLabel(3Xm) man page for an explanation of these actions. 

XmNentryBorder
Imposes a uniform border width upon all RowColumn’s children. The default value is 0, which disables the feature.

XmNentryCallback
Disables the activation callbacks for all ToggleButton, PushButton, and CascadeButton widgets and gadgets contained within the RowColumn widget.  If the application supplies this resource, the activation callbacks are then revectored to this callback.  This allows an application to supply a single callback routine for handling all items contained in a RowColumn widget.  The application must supply this resource when this widget is created.

If the application does not supply this resource, then the activation callbacks for each item in the RowColumn widget work as normal.  The callback reason is XmCR_ACTIVATE and the default value is NULL.  Changing this resource using the XtSetValues is not supported. 

XmNentryClass
Specifies the only widget class that can be added to the RowColumn widget; this resource is meaningful only when the XmNisHomogeneous resource is set to True.  When XmNrowColumnType is set to XmWORK_AREA and XmNradioBehavior is True, then the default value for XmNentryClass is xmToggleButtonGadgetClass.  When XmNrowColumnType is set to XmMENU_BAR, then the value of XmNentryClass is forced to xmCascadeButtonWidgetClass. 

XmNisAligned
Specifies text alignment for each item within the RowColumn widget; this only applies to items which are a subclass of XmLabel or XmLabelGadget.  However, if the item is a Label widget or gadget and its parent is either a Popup MenuPane or a Pulldown MenuPane, then alignment is not be performed; the Label is treated as the title within the MenuPane, and the alignment set by the application is not overridden.  XmNentryAlignment controls the type of textual alignment. 

XmNisHomogeneous
Indicates if the RowColumn widget should enforce exact homogeneity among the items it contains; if True, then only the widgets which are of the class indicated by XmNentryClass are allowed as children of the RowColumn widget.  This is most often used when creating a MenuBar or a RadioBox widget. 

Attempting to insert a child which is not a member of the specified class generates a warning message.  The default value is False, except when creating a MenuBar or a RadioBox, when the default is True. 

XmNlabelString
Points to a text string which displays the label to the left of the selection area when XmNrowColumnType is set to XmMENU_OPTION.  This resource is not meaningful for all other RowColumn types.  If the application wishes to change the label after creation, it must get the LabelGadget ID (XmOptionLabelGadget) and call XtSetValues on the LabelGadget directly.  The default value is no label. 

XmNmapCallback
Specifies a widget-specific callback function that is invoked when the window associated with the RowColumn widget is about to be mapped.  The callback reason is XmCRMap. 

XmNmarginHeight
Specifies the amount of blank space between the top edge of the RowColumn widget and the first item in each column, and the bottom edge of the RowColumn widget and the last item in each column. The default value is three pixels.

XmNmarginWidth
Specifies the amount of blank space between the left edge of the RowColumn widget and the first item in each row, and the right edge of the RowColumn widget and the last item in each row. The default value is three pixels.

XmNmenuAccelerator
This resource is only useful when the RowColumn widget has been configured to operate as a Popup MenuPane or a MenuBar. The format of this resource is similar to the left side specification of a translation string, with the limitation that it must specify a key event. For a Popup MenuPane, when the accelerator is typed by the user, the Popup MenuPane is posted. For a MenuBar, when the accelerator is typed by the user, the first item in the MenuBar is highlighted, and traversal is enabled in the MenuBar. The default for a Popup MenuPane is <Key>F4.  The default for a MenuBar is <Key>F10.  The accelerator can be disabled by setting the XmNpopupEnabled resource to False. 

XmNmenuHelpWidget
Specifies the widget ID for the CascadeButton which is treated as the Help widget if XmNrowColumnType is set to XmMENU_BAR.  The MenuBar always places the Help widget at the lower right corner.  If the RowColumn widget is of any type other than XmMENU_BAR, then this resource is not meaningful. 

XmNmenuHistory
Specifies the widget ID of the last menu entry to be activated.  It is also useful for specifying the current selection for an OptionMenu.  If XmNrowColumnType is set to XmMENU_OPTION, then the specified menu item is positioned under the cursor when the menu is displayed. 

If the RowColumn widget has the XmNradioBehavior resource set to True, then the widget field associated with this resource contains the widget ID of the last ToggleButton or ToggleButtonGadget to change from unselected to selected.  The default value is the widget ID of the first child in the widget. 

XmNmnemonic
This resource is only useful when XmNrowColumnType is set to XmMENU_OPTION.  Specifies a single character which, when typed by the user, posts the associated Pulldown MenuPane.  The character is underlined if it appears in the OptionMenu label, giving the user a visual cue that the character has special functionality associated with it.  The default is no mnemonic. 

XmNnumColumns
Specifies the number of minor dimension extensions that are made to accommodate the entries; this attribute is only meaningful when XmNpacking is set to XmPACK_COLUMN. 

For vertically-oriented RowColumn widgets, this attribute indicates how many columns are built; the number of entries per column are adjusted to maintain this number of columns, if possible. 

For horizontally-oriented RowColumn widgets, this attribute indicates how many rows are built. 

The default value is one. 

XmNorientation
Determines whether RowColumn layouts are row major or column major.  In a column major layout, the children of the RowColumn are laid out in columns top to bottom within the widget.  In a row major layout the children of the RowColumn are laid out in rows.  XmVERTICAL resource value selects a column major layout.  XmHORIZONTAL resource value selects a row major layout. 

The default value is XmVERTICAL, except when creating a MenuBar, when the default is XmHORIZONTAL. 

XmNpacking
Specifies how to pack the items contained within a RowColumn widget.  This can be set to XmPACK_TIGHT, XmPACK_COLUMN or XmPACK_NONE.  When a RowColumn widget packs the items it contains, it determines its major dimension using the value of the XmNorientation resource. 

XmPACK_TIGHT indicates that given the current major dimension (e.g. vertical if XmNorientation is XmVERTICAL), entries are placed one after the other until the RowColumn widget must wrap.  RowColumn wraps when there is no room left for a complete child in that dimension.  Wrapping occurs by beginning a new row or column in the next available space.  Wrapping continues, as often as necessary, until all of the children are laid out.  In the vertical dimension (columns), boxes are set to the same width; in the horizontal dimension (rows), boxes are set to the same depth.  Each entry’s position in the major dimension is left unaltered (e.g., XmNy is left unchanged when XmNorientation is XmVERTICAL); its position in the minor dimension is set to the same value as the greatest entry in that particular row or column.  The position in the minor dimension of any particular row or column is independent of all other rows or columns. 

XmPACK_COLUMN indicates that all entries are placed in identically sized boxes.  The box is based on the largest height and width values of all the children widgets.  The value of the XmNnumColumns resource determines how many boxes are placed in the major dimension, before extending in the minor dimension. 

XmPACK_NONE indicates that no packing is performed.  The x and y attributes of each entry are left alone, and the RowColumn widget attempts to become large enough to enclose all entries. 

The default value is XmPACK_TIGHT except when building an OptionMenu or a RadioBox, where the default is XmPACK_COLUMN. 

XmNpopupEnabled
Allows the menu system to enable keyboard input (accelerators and mnemonics) defined for the Popup MenuPane and any of its submenus. The Popup MenuPane needs to be informed whenever its accessibility to the user changes because posting of the Popup MenuPane is controlled by the application. The default value for this resource is True (keyboard input — accelerators and mnemonics — defined for the Popup MenuPane and any of its submenus is enabled).

XmNradioAlwaysOne
Forces the active ToggleButton or ToggleButtonGadget to be automatically selected after having been unselected (if no other toggle was activated), if True. If False, the active toggle may be unselected. The default value is True.  This resource is only important when XmNradioBehavior is True. 

The application always has the freedom to add and subtract toggles from RowColumn regardless of the selected/unselected state of the toggle.  The application also has the freedom to manage and unmanage toggle children of RowColumn at any time regardless of state.  Because of these freedoms, there are cases in which it is possible for the application to create a RowColumn which has XmNradioAlwaysOne set to True and none of the toggle children selected. 

XmNradioBehavior
Specifies a Boolean value that when True, indicates that the RowColumn widget should enforce a RadioBox-type behavior on all of its children which are ToggleButtons or ToggleButtonGadgets.

Two ToggleButton and ToggleButtonGadget resources are forced to specified values at creation time:  XmNindicator is forced to XmONE_OF_MANY and XmNvisibleWhenOff is forced to True. 

RadioBox behavior dictates that when one toggle is selected and another toggle is selected, the first toggle is unselected automatically.  The default value is False, except when creating a RadioBox, when the default is True. 

XmNresizeHeight
Requests a new height if necessary, when set to True.  When set to False, the widget does not request a new height regardless of any changes to the widget or its children.

XmNresizeWidth
Requests a new width if necessary, when set to True.  When set to False, the widget does not request a new width regardless of any changes to the widget or its children.

XmNrowColumnType
Specifies the type of RowColumn widget which is to be created. It is a non-standard resource that cannot be changed after it is set. If an application uses any of the convenience routines, except XmCreateRowColumn, then this resource is automatically forced to the appropriate value by the convenience routine.  If an application uses the Xt Intrinsics API to create its RowColumn widgets, then it must specify this resource itself.  The set of possible settings for this resource are:

•XmWORK_AREA — the default. 

•XmMENU_BAR. 

•XmMENU_PULLDOWN. 

•XmMENU_POPUP. 

•XmMENU_OPTION. 

This resource cannot be changed after the RowColumn widget is created.  Any changes attempted through XtSetValues are ignored. 

XmNspacing
Specifies the horizontal and vertical spacing between items contained within the RowColumn widget. The default value is one pixel, except for a horizontal MenuBar, which defaults to 0 pixels.

XmNsubMenuId
Specifies the widget ID for the Pulldown MenuPane to be associated with an OptionMenu.  This resource is only useful when XmNrowColumnType is set to XmMENU_OPTION.  This resource must be specified at creation time for an OptionMenu to function properly; it is unused for all other RowColumn types.  The default value is NULL. 

XmNunmapCallback
Specifies a list of callbacks that is called after the window associated with the RowColumn widget has been unmapped.  The callback reason is XmCR_Unmap.  The default value is NULL. 

XmNwhichButton
Specifies the mouse button to which a menu system is sensitive. The default for XmMENU_POPUP is Button3.  The default for XmMENU_OPTION and XmMENU_BAR is Button1.  This resource is not useful for RowColumn widgets of type XmWORK_AREA and XmMENU_PULLDOWN. 

XmNmenuCursor
Sets a variable which controls the cursor which is used whenever this application posts a menu.  This resource can only be specified once at application startup time, either by placing it within a defaults file or by using the -xrm command line argument. 

Example:  myProg -xrm "∗menuCursor: arrow"

The menu cursor can also be selected programmatically by using the function XmSetMenuCursor.  The following is a list of acceptable cursor names.  If the application does not specify a cursor or if an invalid name is supplied, then the default cursor (an arrow pointing up and to the right) is used. 

Inherited Resources

RowColumn inherits behavior and resources from the following named superclasses.  For a complete description of these resources, refer to the man page for that superclass. 

Callback Information

The following structure is returned with each callback:

typedef struct
{
intreason;
XEvent∗ event;
Widgetwidget;
char∗ data;
char∗ callbackstruct;
} XmRowColumnCallbackStruct;

reasonIndicates why the callback was invoked. 

eventPoints to the XEvent that triggered the callback. 

The following fields apply only when the callback reason is XmCR_ACTIVATE; for all other callback reasons, these fields are set to NULL.  The XmCR_ACTIVATE callback reason is only generated when the application has supplied an entry callback, which overrides any activation callbacks registered with the individual RowColumn items. 

widgetIs set to the widget ID of the RowColumn item which has been activated. 

dataContains the client-data value supplied by the application when the RowColumn item’s activation callback was registered. 

callbackstructPoints to the callback structure generated by the RowColumn item’s activation callback. 

Behavior

A RowColumn widget’s behavior depends on its type (MenuBar, Popup MenuPane, etc.) and the type of menu system in which it resides (Pulldown, Popup, or Option).  The specific mouse button depends on the XmNwhichButton resource. 

Default MenuBar

<Btn1Down>:
If the button event occurs within one of the MenuBar buttons, then the MenuBar is armed (if not already armed) and the submenu associated with the selected button is posted.  By moving the mouse, the user is then able to access the MenuPanes attached to the MenuBar.

If the button event does not occur within one of the MenuBar buttons and if the MenuBar is already armed, it is disarmed, and any visible MenuPanes are unposted; if the MenuBar is not already armed, then nothing occurs. 

<Btn1Up>:
If the MenuBar is armed, then this event unposts all visible MenuPanes and then disarms the menubar.

Default OptionMenu

<Btn1Down>:
When this event occurs within the selection area, the Pulldown MenuPane is posted.  If this event occurs outside of the selection area and if the MenuPane is already posted, then the Pulldown MenuPane is unposted.

<Btn1Up>:
When this event occurs while the Pulldown MenuPane is posted, then it is unposted.

<Return>:
If this key is pressed while the focus is set to the selection area, then the Pulldown MenuPane is posted.

Default Pulldown MenuPane from a Popup MenuPane

<Btn3Down>:
When this event occurs, the menu system disables traversal mode, and re-enters drag mode.  Depending upon where the button down event occurs, certain portions of the visible set of MenuPanes are unposted.

<Btn3Up>:
When this event occurs within a gadget child of the MenuPane, the indicated child is activated. If the child is not a CascadeButton (widget or gadget), then this also results in all visible MenuPanes being unposted.  If the child is a CascadeButton (widget or gadget), then this results in the associated submenu being posted and traversal being enabled. When this event occurs outside of a gadget child, then all visible MenuPanes are unposted.

<Return>:
If this key is pressed while the focus is set to a gadget child of the MenuPane, then the indicated child is activated. If the child is not a CascadeButton (widget or gadget), then this also results in all visible MenuPanes being unposted. If the child is a CascadeButton (widget or gadget), then this results in the associated submenu being posted and traversal being enabled.

<Escape>:
This event unposts all visible MenuPanes.

<Right>:
If the current focus item is a CascadeButtonGadget, then this posts the associated Pulldown MenuPane and highlights the first accessible item within the Pulldown MenuPane.

<Left>:
If this occurs within a MenuPane which is a submenu of another MenuPane, then this causes the last MenuPane to be unposted and the focus to move to the previous MenuPane.

<Up>:
This moves the focus to the previous menu item; the previous menu item is defined as the widget which was created prior to the one which currently has the focus.  Wrapping occurs, if necessary.

<Down>:
This moves the focus to the next menu item; the next menu item is defined as the widget which was created after the one which currently has the focus.  Wrapping occurs, if necessary.

Default Pulldown MenuPane from a MenuBar or from an OptionMenu

<Btn1Down>:
When this event occurs, the menu system disables traversal mode and re-enters drag mode.  Depending upon where the button down event occurs, certain portions of the visible set of MenuPanes are unposted.

<Btn1Up>:
When this event occurs within a gadget child of the MenuPane, the indicated child is activated. If the child is not a CascadeButton (widget or gadget), then this also results in all visible MenuPanes being unposted.  If the child is a CascadeButton (widget or gadget), then this results in the associated submenu being posted and traversal being enabled. When this event occurs outside of a gadget child, then all visible MenuPanes are unposted.

<Return>:
If this key is pressed while the focus is set to a gadget child of the MenuPane, then the indicated child is activated. If the child is not a CascadeButton (widget or gadget), then this also results in all visible MenuPanes being unposted. If the child is a CascadeButton (widget or gadget), then this results in the associated submenu being posted and traversal being enabled.

<Escape>:
This event unposts all visible MenuPanes.

<Right>:
If the current focus item is a CascadeButtonGadget, then this posts the associated Pulldown MenuPane and highlights the first accessible item within the Pulldown MenuPane. If the current focus item is not a CascadeButton, then the visible set of MenuPanes are unposted, and the top level Pulldown MenuPane associated with the next MenuBar item is posted.

<Left>:
If this is occurs within a MenuPane which is a submenu of another MenuPane, then this event causes the last MenuPane to be unposted and the focus to move to the previous MenuPane. If this is occurs within a MenuPane which is connected directly to the MenuBar, then the visible set of MenuPanes are unposted, and the top level Pulldown MenuPane associated with the previous menubar item is posted.

<Up>:
This moves the focus to the previous menu item; the previous menu item is defined as the widget which was created prior to the one which currently has the focus.  Wrapping occurs, if necessary.

<Down>:
This moves the focus to the next menu item; the next menu item is defined as the widget which was created after the one which currently has the focus.  Wrapping occurs, if necessary.

WorkArea

<Btn1Down>
If the button press occurred in a gadget child, it is dispatched to it.

<Btn1Up>
If the button press occurred in a gadget child, it is dispatched to it.

Default Translations

The following are the default translations for an OptionMenu:
<BtnDown>:PopupBtnDown()
<BtnUp>:PopupBtnUp()
<Key>Return:MenuGadgetReturn()
The following are the default translations for a Popup MenuPane:
<BtnDown>:PopupBtnDown()
<BtnUp>:PopupBtnUp()
<Key>Return:MenuGadgetReturn()
<Key>Escape:MenuGadgetEscape()
<Unmap>:MenuUnmap()
<FocusIn>:MenuFocusIn()
<FocusOut>:MenuFocusOut()
<EnterWindow>: MenuEnter()
<Key>Left:MenuGadgetTraverseLeft()
<Key>Right:MenuGadgetTraverseRight()
<Key>Up:MenuGadgetTraverseUp()
<Key>Down:MenuGadgetTraverseDown()
The following are the default translations are for a Pulldown MenuPane:
<BtnDown>:PulldownBtnDown()
<BtnUp>:PulldownBtnUp()
<Key>Return:MenuGadgetReturn()
<Key>Escape:MenuGadgetEscape()
<Unmap>:MenuUnmap()
<FocusIn>:MenuFocusIn()
<FocusOut>:MenuFocusOut()
<EnterWindow>: MenuEnter()
<Key>Left:MenuGadgetTraverseLeft()
<Key>Right:MenuGadgetTraverseRight()
<Key>Up:MenuGadgetTraverseUp()
<Key>Down:MenuGadgetTraverseDown()
The following are the default translations for a MenuBar:
<BtnDown>:MenuBarBtnDown()
<BtnUp>:MenuBarBtnUp()
<Unmap>:MenuUnmap()
<FocusIn>:MenuFocusIn()
<FocusOut>:MenuFocusOut()
<EnterWindow>: MenuEnter()
The following are the default translations for a WorkArea:
<Btn1Down>:WorkAreaBtnDown()
<Btn1Up>:WorkAreaBtnUp()

Keyboard Traversal

For information on keyboard traversal in a WorkArea, see the man page for XmManager(3Xm) and its sections on behavior and default translations. 

RELATED INFORMATION

Composite(3Xm), Constraint(3Xm), Core(3Xm), XmCreateRowColumn(3Xm), XmCreateMenuBar(3Xm), XmCreateOptionMenu(3Xm), XmCreatePopupMenu(3Xm), XmCreatePulldownMenu(3Xm), XmCreateRadioBox(3Xm), XmGetMenuCursor(3Xm), XmLabel(3Xm), XmManager(3Xm), XmOptionButtonGadget(3Xm), XmOptionLabelGadget(3Xm), XmSetMenuCursor(3Xm), XmMenuPosition(3Xm), and XmUpdateDisplay(3Xm). 

7th Edition