XmRowColumn - The RowColumn widget class
#include <Xm/RowColumn.h>
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 how the children are laid out, as follows:
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 a MenuBar, Pulldown MenuPane, or Popup MenuPane the default for the XmNshadowThickness resource is 2. In an OptionMenu or a WorkArea (such as a RadioBox or CheckBox) this resource is not applicable and its use is undefined. If an application wishes to place a 3-D shadow around an OptionMenu or WorkArea, it can create the RowColumn as a child of a Frame widget.
In a MenuBar, Pulldown MenuPane, or Popup MenuPane the XmNnavigationType resource is not applicable and its use is undefined. In a WorkArea the default for XmNnavigationType is XmTAB_GROUP. In an OptionMenu the default for XmNnavigationType is XmNONE.
In a MenuBar, Pulldown MenuPane, or Popup MenuPane the XmNtraversalOn resource is not applicable and its use is undefined. In an OptionMenu or WorkArea the default for XmNtraversalOn is True.
If the parent of the RowColumn is a MenuShell, the XmNmappedWhenManaged resource is forced to False when the widget is realized.
The user can specify resources in a resource file for the automatically created widgets and gadgets of an OptionMenu. The following list identifies the names of these widgets (or gadgets) and the associated OptionMenu areas.
Pulldown and Popup MenuPanes support tear-off menus, which enable the user to retain a MenuPane on the display to facilitate subsequent menu selections. A MenuPane that can be torn-off is identified by a tear-off button that spans the width of the MenuPane and displays a dashed line. A torn-off MenuPane contains a window manager system menu icon and a title bar. The window title displays the label of the cascade button that initiated the action when the label type is XmSTRING. If the label contains a pixmap the window title is empty. A tear-off menu from a Popup MenuPane also displays an empty title.
The user can tear-off a MenuPane using the mouse or keyboard. Clicking BSelect or pressing KActivate (or KSelect) on the tear-off button, tears off the MenuPane at the current position. Pressing BDrag on the tear-off button tears off the MenuPane, and allows the user to drag the torn-off menu to a new position designated by releasing the mouse button. Tearing off a MenuPane unposts the current active menu. Only one tear-off copy for each MenuPane is allowed. Subsequent tear-off actions of a torn MenuPane unpost the existing copy first.
The name of the tear-off button of a torn-off menu pane is "TearOffControl". The name can be used to set resources in a resource file. An application can also obtain the tear-off button itself using XmGetTearOffControl and then set resource values by calling XtSetValues.
The tear-off button has Separator-like behavior. Its appearance can be specified using the following tear-off button resources: XmNbackground, XmNbackgroundPixmap, XmNbottomShadowColor, XmNforeground, XmNheight, XmNmargin, XmNseparatorType, XmNshadowThickness, and XmNtopShadowColor. Refer to the XmSeparator man page for a complete description of each of these resources.
RowColumn resources that affect tear-off menu behavior are XmNtearOffModel, XmNtearOffMenuActivateCallback, and XmNtearOffMenuDeactivateCallback.
By default, menus do not tear off; tear off functionality may be enabled by setting the XmNtearOffModel resource to XmTEAR_OFF_ENABLED. There is no resource converter pre-registered for XmNtearOffModel. To allow tear-off functionality to be enabled through the resource database call the function XmRepTypeInstallTearOffModelConverter.
Tear-off menu focus policy follows standard window manager policy. It is recommended that the following mwm resources are set to True: startupKeyFocus and autoKeyFocus.
RowColumn inherits behavior and resources from Core, Composite, Constraint, and XmManager classes.
The class pointer is xmRowColumnWidgetClass.
The class name is XmRowColumn.
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
lowercase or uppercase, 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).
Name | Class | Type | Default | Access |
---|---|---|---|---|
XmNadjustLast | XmCAdjustLast | Boolean | True | CSG |
XmNadjustMargin | XmCAdjustMargin | Boolean | True | CSG |
XmNentryAlignment | XmCAlignment | unsigned char | XmALIGNMENT_BEGINNING | CSG |
XmNentryBorder | XmCEntryBorder | Dimension | 0 | CSG |
XmNentryCallback | XmCCallback | XtCallbackList | NULL | C |
XmNentryClass | XmCEntryClass | WidgetClass | dynamic | CSG |
XmNentryVerticalAlignment | XmCVerticalAlignment | unsigned char | XmALIGNMENT_CENTER | CSG |
XmNisAligned | XmCIsAligned | Boolean | True | CSG |
XmNisHomogeneous | XmCIsHomogeneous | Boolean | dynamic | CG |
XmNlabelString | XmCXmString | XmString | NULL | C |
XmNmapCallback | XmCCallback | XtCallbackList | NULL | C |
XmNmarginHeight | XmCMarginHeight | Dimension | dynamic | CSG |
XmNmarginWidth | XmCMarginWidth | Dimension | dynamic | CSG |
XmNmenuAccelerator | XmCAccelerators | String | dynamic | CSG |
XmNmenuHelpWidget | XmCMenuWidget | Widget | NULL | CSG |
XmNmenuHistory | XmCMenuWidget | Widget | NULL | CSG |
XmNmenuPost | XmCMenuPost | String | NULL | CSG |
XmNmnemonic | XmCMnemonic | KeySym | NULL | CSG |
XmNmnemonicCharSet | XmCMnemonicCharSet | String | XmFONTLIST_DEFAULT_TAG | CSG |
XmNnumColumns | XmCNumColumns | short | 1 | CSG |
XmNorientation | XmCOrientation | unsigned char | dynamic | CSG |
XmNpacking | XmCPacking | unsigned char | dynamic | CSG |
XmNpopupEnabled | XmCPopupEnabled | Boolean | True | CSG |
XmNradioAlwaysOne | XmCRadioAlwaysOne | Boolean | True | CSG |
XmNradioBehavior | XmCRadioBehavior | Boolean | False | CSG |
XmNresizeHeight | XmCResizeHeight | Boolean | True | CSG |
XmNresizeWidth | XmCResizeWidth | Boolean | True | CSG |
XmNrowColumnType | XmCRowColumnType | unsigned char | XmWORK_AREA | CG |
XmNspacing | XmCSpacing | Dimension | dynamic | CSG |
XmNsubMenuId | XmCMenuWidget | Widget | NULL | CSG |
XmNtearOffMenuActivateCallback | XmCCallback | XtCallbackList | NULL | C |
XmNtearOffMenuDeactivateCallback | XmCCallback | XtCallbackList | NULL | C |
XmNtearOffModel | XmCTearOffModel | unsigned char | XmTEAR_OFF_DISABLED | CSG |
XmNunmapCallback | XmCCallback | XtCallbackList | NULL | C |
XmNwhichButton | XmCWhichButton | unsigned int | dynamic | CSG |
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.
XmALIGNMENT_BEGINNING - the default
XmALIGNMENT_CENTER
XmALIGNMENT_END
See the description of XmNalignment in the XmLabel(3X) man page for an explanation of these actions.
The application must supply this resource when this widget is created. Changing this resource using the XtSetValues is not supported.
When XmCreateRadioBox is called or when XmNrowColumnType is set to XmWORK_AREA and XmNradioBehavior is True, the default value of XmNentryClass is xmToggleButtonGadgetClass. When XmNrowColumnType is set to XmMENU_BAR, the value of XmNentryClass is forced to xmCascadeButtonWidgetClass.
In a MenuBar the value of XmNisHomogeneous is forced to True. In an OptionMenu the value is forced to False. When XmCreateRadioBox is called the default value is True. Otherwise, the default value is False.
If the RowColumn widget has the XmNradioBehavior resource set to True, 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.
For vertically oriented RowColumn widgets, this attribute indicates how many columns are built; the number of entries per column is 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 1. In an OptionMenu the value is forced to 1. The value must be greater than 0.
When creating a MenuBar or an OptionMenu, the default is XmHORIZONTAL. Otherwise, the default value is XmVERTICAL. The results of specifying a value of XmVERTICAL for a MenuBar are undefined.
XmPACK_TIGHT indicates that given the current major dimension (for example, 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 (for example, 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.
When XmCreateRadioBox is called or when XmNrowColumnType is set to XmWORK_AREA and XmNradioBehavior is True, the default value of XmNpacking is XmPACK_COLUMN. In an OptionMenu the value is initialized to XmPACK_TIGHT. Otherwise, the value defaults to XmPACK_TIGHT.
The application can always add and subtract toggles from RowColumn regardless of the selected/unselected state of the toggle. The application can also manage and unmanage toggle children of RowColumn at any time regardless of state. Therefore, the application can sometimes create a RowColumn that has XmNradioAlwaysOne set to True and none of the toggle children selected. The result is undefined if the value of this resource is True and the application sets more than one ToggleButton at a time.
When the value of this resource is True, XmNindicatorType defaults to XmONE_OF_MANY for ToggleButton and ToggleButtonGadget children.
RadioBox behavior dictates that when one toggle is selected and the user selects another toggle, the first toggle is unselected automatically. The RowColumn usually does not enforce this behavior if the application, rather than the user, changes the state of a toggle. The RowColumn does enforce this behavior if a toggle child is selected using XmToggleButtonSetState or XmToggleButtonGadgetSetState with a notify argument of True.
When XmCreateRadioBox is called the default value of XmNradioBehavior is True. Otherwise, the default value is False.
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.
The value of this resource is used to determine the value of a number of other resources. The descriptions of RowColumn resources explain this when it is the case. The resource XmNnavigationType, inherited from XmManager, is changed to XmNONE if XmNrowColumnType is XmMENU_OPTION.
Use this resource when your application has shared MenuPanes and when the torn-off menu can have two or more parents that can have opposing sensitivity states for the same menu item. This resource enables the application to track whether a menu item is sensitive or insensitive and to set the state to the original parent's menu item state when the torn-off menu is reposted. The application can use XmGetPostedFromWidget to determine from which parent the menu was torn. The callback reason is XmCR_TEAR_OFF_ACTIVATE. The default is NULL.
Use this resource when your application has shared MenuPanes and when the torn-off menu can have two or more parents that can have opposing sensitivity states for the same menu item. This resource enables the application to track whether a menu item is sensitive or insensitive and to set the state to the original parent's menu item state when the torn-off menu is reposted. The application can use XmGetPostedFromWidget to determine from which parent the menu was torn. The callback reason is XmCR_TEAR_OFF_DEACTIVATE. The default is NULL.
Name | Class | Type | Default | Access |
---|---|---|---|---|
XmNpositionIndex | XmCPositionIndex | short | XmLAST_POSITION | CSG |
When a widget is inserted into its parent's child list, the positions of any existing children that are greater than or equal to the specified widget's XmNpositionIndex are increased by one. The effect of a call to XtSetValues for XmNpositionIndex is to remove the specified widget from its parent's child list, decrease by one the positions of any existing children that are greater than the specified widget's former position in the list, and then insert the specified widget into its parent's child list as described in the preceding sentence.
Name | Class | Type | Default | Access |
---|---|---|---|---|
XmNbuttonAccelerators | XmCButtonAccelerators | StringTable | NULL | C |
XmNbuttonAcceleratorText | XmCButtonAcceleratorText | XmStringTable | NULL | C |
XmNbuttonCount | XmCButtonCount | int | 0 | C |
XmNbuttonMnemonicCharSets | XmCButtonMnemonicCharSets | XmStringCharSetTable | NULL | C |
XmNbuttonMnemonics | XmCButtonMnemonics | XmKeySymTable | NULL | C |
XmNbuttons | XmCButtons | XmStringTable | NULL | C |
XmNbuttonSet | XmCButtonSet | int | -1 | C |
XmNbuttonType | XmCButtonType | XmButtonTypeTable | NULL | C |
XmNoptionLabel | XmCOptionLabel | XmString | NULL | C |
XmNoptionMnemonic | XmCOptionMnemonic | KeySym | NULL | C |
XmNpostFromButton | XmCPostFromButton | int | -1 | C |
XmNsimpleCallback | XmCCallback | XtCallbackProc | NULL | C |
XmCASCADEBUTTON - Specifies a CascadeButtonGadget for a MenuBar, Popup MenuPane, or Pulldown MenuPane.
XmCHECKBUTTON - Specifies a ToggleButtonGadget for a CheckBox, Popup MenuPane, or Pulldown MenuPane.
XmDOUBLE_SEPARATOR - Specifies a SeparatorGadget for a Popup MenuPane, Pulldown MenuPane, or OptionMenu Pulldown submenu. The separator type is XmDOUBLE_LINE.
XmPUSHBUTTON - Specifies a PushButtonGadget for a Popup MenuPane, Pulldown MenuPane, or OptionMenu Pulldown submenu.
XmRADIOBUTTON - Specifies a ToggleButtonGadget for a RadioBox, Popup MenuPane, or Pulldown MenuPane.
XmSEPARATOR - Specifies a SeparatorGadget for a Popup MenuPane, Pulldown MenuPane, or OptionMenu Pulldown submenu.
XmTITLE - Specifies a LabelGadget used as a title for a Popup MenuPane or Pulldown MenuPane.
RowColumn inherits behavior and resources from the following named superclasses. For a complete description of each resource, refer to the man page for that superclass.
Name | Class | Type | Default | Access |
---|---|---|---|---|
XmNbottomShadowColor | XmCBottomShadowColor | Pixel | dynamic | CSG |
XmNbottomShadowPixmap | XmCBottomShadowPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG |
XmNforeground | XmCForeground | Pixel | dynamic | CSG |
XmNhelpCallback | XmCCallback | XtCallbackList | NULL | C |
XmNhighlightColor | XmCHighlightColor | Pixel | dynamic | CSG |
XmNhighlightPixmap | XmCHighlightPixmap | Pixmap | dynamic | CSG |
XmNinitialFocus | XmCInitialFocus | Widget | NULL | CSG |
XmNnavigationType | XmCNavigationType | XmNavigationType | dynamic | CSG |
XmNshadowThickness | XmCShadowThickness | Dimension | dynamic | CSG |
XmNstringDirection | XmCStringDirection | XmStringDirection | dynamic | CG |
XmNtopShadowColor | XmCTopShadowColor | Pixel | dynamic | CSG |
XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | dynamic | CSG |
XmNtraversalOn | XmCTraversalOn | Boolean | dynamic | CSG |
XmNunitType | XmCUnitType | unsigned char | dynamic | CSG |
XmNuserData | XmCUserData | XtPointer | NULL | CSG |
Name | Class | Type | Default | Access |
---|---|---|---|---|
XmNchildren | XmCReadOnly | WidgetList | NULL | G |
XmNinsertPosition | XmCInsertPosition | XtOrderProc | default procedure | CSG |
XmNnumChildren | XmCReadOnly | Cardinal | 0 | G |
Name | Class | Type | Default | Access |
---|---|---|---|---|
XmNaccelerators | XmCAccelerators | XtAccelerators | dynamic | CSG |
XmNancestorSensitive | XmCSensitive | Boolean | dynamic | G |
XmNbackground | XmCBackground | Pixel | dynamic | CSG |
XmNbackgroundPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG |
XmNborderColor | XmCBorderColor | Pixel | XtDefaultForeground | CSG |
XmNborderPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG |
XmNborderWidth | XmCBorderWidth | Dimension | 0 | CSG |
XmNcolormap | XmCColormap | Colormap | dynamic | CG |
XmNdepth | XmCDepth | int | dynamic | CG |
XmNdestroyCallback | XmCCallback | XtCallbackList | NULL | C |
XmNheight | XmCHeight | Dimension | dynamic | CSG |
XmNinitialResourcesPersistent | XmCInitialResourcesPersistent | Boolean | True | C |
XmNmappedWhenManaged | XmCMappedWhenManaged | Boolean | True | CSG |
XmNsensitive | XmCSensitive | Boolean | True | CSG |
XmNtranslations | XmCTranslations | XtTranslations | dynamic | CSG |
XmNwidth | XmCWidth | Dimension | dynamic | CSG |
XmNx | XmCPosition | Position | 0 | CSG |
XmNy | XmCPosition | Position | 0 | CSG |
typedef struct { int reason; XEvent * event; Widget widget; char * data; char * callbackstruct; } XmRowColumnCallbackStruct;
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 generated only when the application has supplied an entry callback, which overrides any activation callbacks registered with the individual RowColumn items.
XmRowColumn translations depend on the value of the XmNrowColumnType resource.
If XmNrowColumnType is set to XmWORK_AREA, XmRowColumn inherits translations from XmManager.
If XmNrowColumnType is set to XmMENU_OPTION, XmRowColumn inherits traversal, KActivate, and KCancel translations from XmManager and has the additional translations listed below. These translations may not directly correspond to a translation table.
BSelect Press: MenuBtnDown() BSelect Release: MenuBtnUp() KSelect: ManagerGadgetSelect() KHelp: Help()
The translations for XmRowColumn if XmNrowColumnType is set to XmMENU_BAR XmMENU_PULLDOWN, or XmMENU_POPUP are listed below. In a Popup menu system, BMenu also performs the BSelect actions. These translations may not directly correspond to a translation table.
BSelect Press: MenuBtnDown() BSelect Release: MenuBtnUp() KActivate: ManagerGadgetSelect() KSelect: ManagerGadgetSelect() MAny KCancel: MenuGadgetEscape() KHelp: Help() KLeft: MenuGadgetTraverseLeft() KRight: MenuGadgetTraverseRight() KUp: MenuGadgetTraverseUp() KDown: MenuGadgetTraverseDown()
The XmRowColumn action routines are described below:
In a Popup MenuPane, unposts the menu and, when the shell's keyboard focus policy is XmEXPLICIT, restores keyboard focus to the widget from which the menu was posted. In a TearOff MenuPane that has no submenus posted, dismisses the menu; otherwise, if one or more submenus are posted, unposts the last menu pane.
If the current menu item is in a MenuPane, then this action disarms the current menu item and arms the item below it. This action wraps within the MenuPane. When the current menu item is at the MenuPane's bottom edge, then this action wraps to the topmost menu item in the column to the right, if one exists. When the current menu item is at the bottom, rightmost corner of the MenuPane, then this action wraps to the tear-off control, if present, or to the top, leftmost menu item.
In MenuPanes, if the current menu item is not at the left edge of a MenuPane, this action disarms the current item and arms the item to its left. If the current menu item is at the left edge of a submenu attached to a MenuBar item, then this action unposts the submenu and traverses to the MenuBar item to the left, wrapping if necessary. If that MenuBar item has a submenu, it posts the submenu and arms the first traversable item in the submenu. If the current menu item is at the left edge of a submenu not directly attached to a MenuBar item, then this action unposts the current submenu only.
In Popup or Torn-off MenuPanes, when the current menu item is at the left edge, this action wraps within the MenuPane. If the current menu item is at the left edge of the MenuPane and not in the top row, this action wraps to the rightmost menu item in the row above. If the current menu item is in the upper, leftmost corner, this action wraps to the tear-off control, if present, or else it wraps to the bottom, rightmost menu item in the MenuPane.
In MenuPanes, if the current menu item is a CascadeButton, then this action posts its associated submenu. If the current menu item is not a CascadeButton and is not at the right edge of a MenuPane, this action disarms the current item and arms the item to its right, wrapping if necessary. If the current menu item is not a CascadeButton and is at the right edge of a submenu that is a descendent of a MenuBar, then this action unposts all submenus and traverses to the MenuBar item to the right. If that MenuBar item has a submenu, it posts the submenu and arms the submenu's first traversable item.
In Popup or Torn-off menus, if the current menu item is not a CascadeButton and is at the right edge of a row (except the bottom row), this action wraps to the leftmost menu item in the row below. If the current menu item is not a CascadeButton and is in the bottom, rightmost corner of a Popup or Pulldown MenuPane, this action wraps to the tear-off control, if present, or else it wraps to the top, leftmost menu item of the MenuPane.
The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3X).
Composite(3X), Constraint(3X), Core(3X), XmCreateMenuBar(3X), XmCreateOptionMenu(3X), XmCreatePopupMenu(3X), XmCreatePulldownMenu(3X), XmCreateRadioBox(3X), XmCreateRowColumn(3X), XmCreateSimpleCheckBox(3X), XmCreateSimpleMenuBar(3X), XmCreateSimpleOptionMenu(3X), XmCreateSimplePopupMenu(3X), XmCreateSimplePulldownMenu(3X), XmCreateSimpleRadioBox(3X), XmCreateWorkArea(3X), XmGetMenuCursor(3X), XmGetPostedFromWidget(3X), XmGetTearOffControl, XmLabel(3X), XmManager(3X), XmMenuPosition(3X), XmOptionButtonGadget(3X), XmOptionLabelGadget(3X), XmRepTypeInstallTearOffModelConverter, XmSetMenuCursor(3X), XmUpdateDisplay(3X), XmVaCreateSimpleCheckBox(3X), XmVaCreateSimpleMenuBar(3X), XmVaCreateSimpleOptionMenu(3X), XmVaCreateSimplePopupMenu(3X), XmVaCreateSimplePulldownMenu(3X), and XmVaCreateSimpleRadioBox(3X).