XmRowColumn(3X)

XmRowColumn --The RowColumn widget class

As shipped in IRIX 6.5.7. Unchanged since IRIX 6.5.

NAME
XmRowColumn --The RowColumn widget class

SYNOPSIS
#include <Xm/RowColumn.h>

VERSION
This page documents version 1.2 of the Motif library.

DESCRIPTION
The RowColumn widget is a general purpose RowColumn manager capable of con-
taining any widget type as a child. In general, it requires no special
knowledge about how its children function and provides nothing beyond sup-
port 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:

* the children are packed tightly together into either rows or columns

* each child is placed in an identically sized box (producing a symmet-
rical look)

* a specific layout (the current x and y positions of the children con-
trol 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 a MenuBar, Pulldown MenuPane, or Popup MenuPane the default for the XmN-
shadowThickness resource is 2. In an OptionMenu or a WorkArea (such as a
RadioBox or CheckBox) this resource is not applicable and its use is unde-
fined. 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 de-
fault for XmNnavigationType is XmTAB_GROUP. In an OptionMenu the default
for XmNnavigationType is XmNONE.

In a MenuBar, Pulldown MenuPane, or Popup MenuPane the XmNtraversalOn re-
source 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 re-
source 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 identi-
fies the names of these widgets (or gadgets) and the associated OptionMenu
areas.

* Option Menu Label Gadget-"OptionLabel"

* Option Menu Cascade Button-"OptionButton"

Tear-off Menus
Pulldown and Popup MenuPanes support tear-off menus, which enable the user
to retain a MenuPane on the display to facilitate subsequent menu selec-
tions. 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 dis-
plays an empty title.

The user can tear-off a MenuPane using the mouse or keyboard. Clicking BS-
elect or pressing KActivate (or KSelect) on the tear-off button, tears off
the MenuPane at the current position. Pressing BDrag on the tear-off but-
ton 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 "TearOffCon-
trol". The name can be used to set resources in a resource file. An ap-
plication can also obtain the tear-off button itself using XmGetTearOffCon-
trol 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, XmNmar-
gin, XmNseparatorType, XmNshadowThickness, and XmNtopShadowColor. Refer to
the XmSeparator man page for a complete description of each of these re-
sources.

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: startupKeyFo-
cus and autoKeyFocus.

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 program-
mer 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 re-
maining letters (in either lowercase or uppercase, but include any under-
scores 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).

XmRowColumn Resource Set
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

XmNadjustLast
Extends the last row of children to the bottom edge of RowColumn
(when XmNorientation is XmHORIZONTAL) or extends the last column
to the right edge of RowColumn (when XmNorientation is XmVERTI-
CAL). 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, XmNmargin-
Right, 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 ei-
ther XmMENU_POPUP or XmMENU_PULLDOWN and this resource is True,
only button children have their margins adjusted.

XmNentryAlignment
Specifies the alignment type for children that are subclasses of
XmLabel or XmLabelGadget when XmNisAligned is enabled. The fol-
lowing are textual alignment types:

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.

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

XmNentryCallback
Disables the XmNactivateCallback and XmNvalueChangedCallback
callbacks for all CascadeButton, DrawnButton, PushButton, and
ToggleButton widgets and gadgets contained within the RowColumn
widget. If the application supplies this resource, the XmNacti-
vateCallback and XmNvalueChangedCallback callbacks are then
revectored to the XmNentryCallback callbacks. This allows an ap-
plication to supply a single callback routine for handling all
items contained in a RowColumn widget. The callback reason is
XmCR_ACTIVATE. If the application does not supply this resource,
the XmNactivateCallback and XmNvalueChangedCallback callbacks for
each item in the RowColumn widget work as normal.

The application must supply this resource when this widget is
created. Changing this resource using the XtSetValues is not
supported.

XmNentryClass
Specifies the only widget class that can be added to the RowCol-
umn widget; this resource is meaningful only when the XmNisHomo-
geneous resource is set to True. Both widget and gadget variants
of the specified class may be added to the widget.

When XmCreateRadioBox is called or when XmNrowColumnType is set
to XmWORK_AREA and XmNradioBehavior is True, the default value of
XmNentryClass is xmToggleButtonGadgetClass. When XmNrowColumn-
Type is set to XmMENU_BAR, the value of XmNentryClass is forced
to xmCascadeButtonWidgetClass.

XmNentryVerticalAlignment
Specifies the type of vertical alignment for children that are
subclasses of XmLabel, XmLabelGadget, and XmText. This resource
is invalid if XmNorientation is XmVERTICAL and XmNpacking is Xm-
PACK_TIGHT because this layout preserves variable heights among
the children. The vertical alignment types include:

* XmALIGNMENT_BASELINE_BOTTOM-causes the bottom baseline of
all children in a row to be aligned. This resource is ap-
plicable only when all children in a row contain textual
data.

* XmALIGNMENT_BASELINE_TOP-causes the top baseline of all
children in a row to be aligned. This resource is applica-
ble only when all children in a row contain textual data.

* XmALIGNMENT_CONTENTS_BOTTOM-causes the bottom of the con-
tents (text or pixmap) of all children in a row to be
aligned.

* XmALIGNMENT_CENTER-causes the center of all children in a
row to be aligned.

* XmALIGNMENT_CONTENTS_TOP-causes the top of the contents
(text or pixmap) of all children in a row to be aligned.

XmNisAligned
Specifies text alignment for each item within the RowColumn wid-
get; this applies only to items that are subclasses 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,
alignment is not 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 whether the RowColumn widget should enforce exact homo-
geneity among the items it contains; if True, only the widgets
that are of the class indicated by XmNentryClass are allowed as
children of the RowColumn widget. This is most often used when
creating a MenuBar. Attempting to insert a child that is not a
member of the specified class generates a warning message.

In a MenuBar the value of XmNisHomogeneous is forced to True. In
an OptionMenu the value is forced to False. When XmCreateRa-
dioBox is called the default value is True. Otherwise, the de-
fault value is False.

XmNlabelString
Points to a text string, which displays the label to one side 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 XtSet-
Values on the LabelGadget directly. The default value is no la-
bel.

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 XmCR_MAP.

XmNmarginHeight
Specifies the amount of blank space between the top edge of the
RowColumn widget and the first item in each column, and the bot-
tom edge of the RowColumn widget and the last item in each col-
umn. The default value is 0 for Pulldown and Popup MenuPanes,
and 3 pixels for other RowColumn types.

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 0 for Pulldown and Popup MenuPanes, and 3 pixels
for other RowColumn types.

XmNmenuAccelerator
This resource is useful only when the RowColumn widget has been
configured to operate as a Popup MenuPane or a MenuBar. The for-
mat 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 KMenu. The default for a
MenuBar is KMenuBar. 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 bottom right corner
(in a lef to right environment) of the MenuBar. If the RowColumn
widget is any type other than XmMENU_BAR, 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 Op-
tionMenu. If XmNrowColumnType is set to XmMENU_OPTION, the spec-
ified menu item is positioned under the cursor when the menu is
displayed.

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.

XmNmenuPost
Specifies an X event description indicating a button event that
posts a menu system. The default for XmMENU_POPUP is BMenu
Press. The default for XmMENU_OPTION, XmMENU_BAR, and Xm-
WORK_AREA is BSelect Press. The XmNmenuPost resource for pull-
downs should be consistent with that of top-level parent menu
(although the event type is ignored). Setting this resource to
BDrag Press will conflict with drag and drop operations, which
use BDrag Press as a default button binding.

XmNmnemonic
This resource is useful only when XmNrowColumnType is set to Xm-
MENU_OPTION. Specifies a keysym for a key that, when pressed by
the user along with the MAlt modifier, posts the associated Pull-
down MenuPane. The first character in the OptionMenu label
string that exactly matches the mnemonic in the character set
specified in XmNmnemonicCharSet is underlined. The user can post
the menu by pressing either the shifted or the unshifted mnemonic
key. The default is no mnemonic.

XmNmnemonicCharSet
Specifies the character set of the mnemonic for an OptionMenu.
The default is XmFONTLIST_DEFAULT_TAG. If the RowColumn widget
is any type other than XmMENU_OPTION, this resource is not mean-
ingful.

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

For vertically oriented RowColumn widgets, this attribute indi-
cates how many columns are built; the number of entries per col-
umn is adjusted to maintain this number of columns, if possible.

For horizontally oriented RowColumn widgets, this attribute indi-
cates 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.

XmNorientation
Determines whether RowColumn layouts are row-major or column-ma-
jor. 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. XmHORI-
ZONTAL resource value selects a row-major layout.

When creating a MenuBar or an OptionMenu, the default is XmHORI-
ZONTAL. Otherwise, the default value is XmVERTICAL. The results
of specifying a value of XmVERTICAL for a MenuBar are undefined.

XmNpackingSpecifies how to pack the items contained within a RowColumn wid-
get. This can be set to XmPACK_TIGHT, XmPACK_COLUMN or Xm-
PACK_NONE. When a RowColumn widget packs the items it contains,
it determines its major dimension using the value of the XmNori-
entation resource.

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 XmNorienta-
tion 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 identi-
cally sized boxes. The box is based on the largest height and
width values of all the children widgets. The value of the XmN-
numColumns 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 ini-
tialized to XmPACK_TIGHT. Otherwise, the value defaults to Xm-
PACK_TIGHT.

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

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

The application can always add and subtract toggles from RowCol-
umn 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 appli-
cation can sometimes create a RowColumn that has XmNradioAl-
waysOne 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.

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

When the value of this resource is True, XmNindicatorType de-
faults 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 be-
havior 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 XmTog-
gleButtonGadgetSetState with a notify argument of True.

When XmCreateRadioBox is called the default value of XmNradioBe-
havior is True. Otherwise, the default value is False.

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 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 Xm-
CreateRowColumn, this resource is automatically forced to the ap-
propriate value by the convenience routine. If an application
uses the Xt Intrinsics API to create its RowColumn widgets, 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.

The value of this resource is used to determine the value of a
number of other resources. The descriptions of RowColumn re-
sources explain this when it is the case. The resource XmNnavi-
gationType, inherited from XmManager, is changed to XmNONE if Xm-
NrowColumnType is XmMENU_OPTION.

XmNspacingSpecifies the horizontal and vertical spacing between items con-
tained within the RowColumn widget. The default value is 3 pix-
els for XmOPTION_MENU and XmWORK_AREA and 0 for other RowColumn
types.

XmNsubMenuId
Specifies the widget ID for the Pulldown MenuPane to be associ-
ated with an OptionMenu. This resource is useful only when XmN-
rowColumnType is set to XmMENU_OPTION. The default value is
NULL.

XmNtearOffMenuActivateCallback
Specifies the callback list that notifies the application when
the tear-off MenuPane is about to be activated. It precedes the
tear-off's map callback.

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 re-
source 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.

XmNtearOffMenuDeactivateCallback
Specifies the callback list that notifies the application when
the tear-off MenuPane is about to be deactivated. It follows the
tear-off's unmap callback.

XmNtearOffModel
Indicates whether tear-off functionality is enabled or disabled
when XmNrowColumnType is set to XmMENU_PULLDOWN or XmMENU_POPUP.
The values are: XmTEAR_OFF_ENABLED or XmTEAR_OFF_DISABLED (de-
fault value). This resource is invalid for type XmMENU_OPTION;
however, it does affect any pulldown submenus within an Option-
Menu. The function XmRepTypeInstallTearOffModelConverter in-
stalls a resource converter for this resource.

XmNunmapCallback
Specifies a list of callbacks that is called after the window as-
sociated with the RowColumn widget has been unmapped. The call-
back reason is XmCR_UNMAP. The default value is NULL.

XmNwhichButton
This resource is obsolete; it has been replaced by XmNmenuPost
and is present for compatibility with older releases of 1/Motif.

XmRowColumn Constraint Resource Set
Name Class Type Default Access
-----------------------------------------------------------------------
XmNpositionIndex XmCPositionIndex short XmLAST_POSITION CSG

XmNpositionIndex
Specifies the position of the widget in its parent's list of
children (the value of the XmNchildren resource). The value is
an integer that is no less than zero and no greater than the num-
ber of children in the list at the time the value is specified.
A value of zero means that the child is placed at the beginning
of the list. The value can also be specified as XmLAST_POSITION
(the default), which means that the child is placed at the end of
the list. Any other value is ignored. XtGetValues returns the
position of the widget in its parent's child list at the time of
the call to XtGetValues.

When a widget is inserted into its parent's child list, the posi-
tions 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, de-
crease 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.

Simple Menu Creation Resource Set
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

XmNbuttonAccelerators
This resource is for use with the simple menu creation routines.
It specifies a list of accelerators for the buttons created. The
list contains one element for each button, separator, and title
created.

XmNbuttonAcceleratorText
This resource is for use with the simple menu creation routines.
It specifies a list of compound strings to display for the accel-
erators for the buttons created. The list contains one element
for each button, separator, and title created.

XmNbuttonCount
This resource is for use with the simple menu creation routines.
It specifies the total number of menu buttons, separators, and
titles to create. The value must not be negative.

XmNbuttonMnemonicCharSets
This resource is for use with the simple menu creation routines.
It specifies a list of character sets with which button mnemonics
are to be displayed. The list contains one element for each but-
ton, separator, and title created. The default is determined dy-
namically depending on the locale of the widget.

XmNbuttonMnemonics
This resource is for use with the simple menu creation routines.
It specifies a list of mnemonics for the buttons created. The
list contains one element for each button, separator, and title
created.

XmNbuttonsThis resource is for use with the simple menu creation routines.
It specifies a list of compound strings to use as labels for the
buttons created. The list contains one element for each button,
separator, and title created.

XmNbuttonSet
This resource is for use with the simple menu creation routines.
It specifies which button of a RadioBox or OptionMenu Pulldown
submenu is initially set. The value is an integer n indicating
the nth ToggleButtonGadget specified for a RadioBox or the nth
PushButtonGadget specified for an OptionMenu Pulldown submenu.
The first button specified is number 0. The value must not be
negative.

XmNbuttonType
This resource is for use with the simple menu creation routines.
It specifies a list of button types associated with the buttons
to be created. The list contains one element for each button,
separator, and title created. If this resource is not specified,
each button in a MenuBar is a CascadeButtonGadget, each button in
a RadioBox or CheckBox is a ToggleButtonGadget, and each button
in any other type of RowColumn widget is a PushButtonGadget.
Each button type is of type XmButtonType, an enumeration with the
following possible values:

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 Menu-
Pane, 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 Menu-
Pane or Pulldown MenuPane.

XmNoptionLabel
This resource is for use with the simple menu creation routines.
It specifies a compound string for the label string to be used on
the left side of an OptionMenu.

XmNoptionMnemonic
This resource is for use with the simple menu creation routines.
It specifies a keysym for a key that, when pressed by the user
along with the MAlt modifier, posts the associated Pulldown Menu-
Pane for an OptionMenu.

XmNpostFromButton
This resource is for use with the simple menu creation routines.
For a Pulldown MenuPane, it specifies the button in the parent to
which the submenu is attached. The menu is then posted from this
button. The value is an integer n indicating the nth CascadeBut-
ton or CascadeButtonGadget specified for the parent of the Pull-
down MenuPane. The first button specified is number 0. The
value must not be negative.

XmNsimpleCallback
This resource is for use with the simple menu creation routines.
It specifies a callback procedure to be called when a button is
activated or when its value changes. This callback function is
added to each button after creation. For a CascadeButtonGadget
or a PushButtonGadget, the callback is added as the button's XmN-
activateCallback, and it is called when the button is activated.
For a ToggleButtonGadget, the callback is added as the button's
XmNvalueChangedCallback, and it is called when the button's value
changes. The button number is passed in the client_data field.

Inherited Resources
RowColumn inherits behavior and resources from the following named super-
classes. For a complete description of each resource, refer to the man
page for that superclass.

XmManager Resource Set
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

Composite Resource Set
Name Class Type Default Access
---------------------------------------------------------------------------------
XmNchildren XmCReadOnly WidgetList NULL G
XmNinsertPosition XmCInsertPosition XtOrderProc default procedure CSG
XmNnumChildren XmCReadOnly Cardinal 0 G

Core Resource Set
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
XmNscreen XmCScreen Screen * dynamic CG
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

Callback Information
A pointer to the following structure is passed to each callback:

typedef struct
{
int reason;
XEvent * event;
Widget widget;
char * data;
char * callbackstruct;
} XmRowColumnCallbackStruct;

reason Indicates why the callback was invoked

event Points 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_AC-
TIVATE callback reason is generated only when the application has supplied
an entry callback, which overrides any activation callbacks registered with
the individual RowColumn items.

widget Is set to the widget ID of the RowColumn item that has been acti-
vated

data Contains the client-data value supplied by the application when
the RowColumn item's activation callback was registered

callbackstruct
Points to the callback structure generated by the RowColumn
item's activation callback

Translations
XmRowColumn translations depend on the value of the XmNrowColumnType re-
source.

If XmNrowColumnType is set to XmWORK_AREA, XmRowColumn inherits transla-
tions from XmManager.

If XmNrowColumnType is set to XmMENU_OPTION, XmRowColumn inherits traver-
sal, KActivate, and KCancel translations from XmManager and has the addi-
tional translations listed below. These translations may not directly cor-
respond 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 di-
rectly 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()

Action Routines
The XmRowColumn action routines are described below:

Help(): Calls the callbacks for XmNhelpCallback if any exist. If there
are no help callbacks for this widget, this action calls the help
callbacks for the nearest ancestor that has them.

ManagerGadgetSelect():
When a gadget child of the menu has the focus, invokes the gadget
child's behavior associated with KSelect. This generally has the
effect of unposting the menu hierarchy and arming and activating
the gadget, except that for a CascadeButtonGadget with a submenu,
it posts the submenu.

MenuBtnDown():
When a gadget child of the menu has the focus, invokes the gadget
child's behavior associated with BSelect Press. This generally
has the effect of unposting any menus posted by the parent menu,
enabling mouse traversal in the menu, and arming the gadget. For
a CascadeButtonGadget with a submenu, it also posts the associ-
ated submenu.

MenuBtnUp():
When a gadget child of the menu has the focus, invokes the gadget
child's behavior associated with BSelect Release. This generally
has the effect of unposting the menu hierarchy and activating the
gadget, except that for a CascadeButtonGadget with a submenu, it
posts the submenu and enables keyboard traversal in the menu.

MenuGadgetEscape():
In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu,
disarms the MenuBar CascadeButton and the MenuBar, and, when the
shell's keyboard focus policy is XmEXPLICIT, restores keyboard
focus to the widget that had the focus before the MenuBar was en-
tered. In other Pulldown MenuPanes, unposts the menu.

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, dis-
misses the menu; otherwise, if one or more submenus are posted, unposts the
last menu pane.

MenuGadgetTraverseDown():
If the current menu item has a submenu and is in a MenuBar, then
this action posts the submenu, disarms the current menu item, and
arms the submenu's first traversable menu item.

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 cor-
ner of the MenuPane, then this action wraps to the tear-off control, if
present, or to the top, leftmost menu item.

MenuGadgetTraverseLeft():
When the current menu item is in a MenuBar, then this action dis-
arms the current item and arms the MenuBar item to the left.
This action wraps within the MenuBar.

In MenuPanes, if the current menu item is not at the left edge of a Menu-
Pane, 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 di-
rectly 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.

MenuGadgetTraverseRight():
If the current menu item is in a MenuBar, then this action dis-
arms the current item and arms the MenuBar item to the right.
This action wraps within the MenuBar.

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 Cascade-
Button 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 sub-
menu that is a descendent of a MenuBar, then this action unposts all sub-
menus 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 traversa-
ble 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.

MenuGadgetTraverseUp():
When the current menu item is in a MenuPane, then this action
disarms the current menu item and arms the item above it. This
action wraps within the MenuPane. When the current menu item is
at the MenuPane's top edge, then this action wraps to the bottom-
most menu item in the column to the left, if one exists. When
the current menu item is at the top, leftmost corner of the Menu-
Pane, then this action wraps to the tear-off control, if present,
or to the bottom, rightmost menu item.

Related Behavior
The following menu functions are available.

KMenuBar: In any non-popup descendant of a MenuBar's parent, excluding the
MenuBar itself, this action enables keyboard traversal and moves
keyboard focus to the first item in the MenuBar. In the MenuBar
or any menu cascaded from it, this action unposts the menu hier-
archy and, when the shell's keyboard focus policy is XmEXPLICIT,
restores focus to the widget that had the focus when the menu
system was entered.

KMenu: Pops up the menu associated with the control that has the key-
board focus. Enables keyboard traversal in the menu. In the
Popup menu system or any menu cascaded from it, this action un-
posts the menu hierarchy and, when the shell's keyboard focus
policy is XmEXPLICIT, restores focus to the widget that had the
focus when the menu system was entered.

Virtual Bindings
The bindings for virtual keys are vendor specific. For information about
bindings for virtual buttons and keys, see VirtualBindings(3X).

RELATED INFORMATION
Composite(3X), Constraint(3X), Core(3X), XmCreateMenuBar(3X), XmCreateOp-
tionMenu(3X), XmCreatePopupMenu(3X), XmCreatePulldownMenu(3X), XmCreateRa-
dioBox(3X), XmCreateRowColumn(3X), XmCreateSimpleCheckBox(3X), XmCreateSim-
pleMenuBar(3X), XmCreateSimpleOptionMenu(3X), XmCreateSimplePopupMenu(3X),
XmCreateSimplePulldownMenu(3X), XmCreateSimpleRadioBox(3X), XmCreate-
WorkArea(3X), XmGetMenuCursor(3X), XmGetPostedFromWidget(3X), XmGetTearOff-
Control, XmLabel(3X), XmManager(3X), XmMenuPosition(3X), XmOptionButtonGad-
get(3X), XmOptionLabelGadget(3X), XmRepTypeInstallTearOffModelConverter,
XmSetMenuCursor(3X), XmUpdateDisplay(3X), XmVaCreateSimpleCheckBox(3X), Xm-
VaCreateSimpleMenuBar(3X), XmVaCreateSimpleOptionMenu(3X), XmVaCreateSim-
plePopupMenu(3X), XmVaCreateSimplePulldownMenu(3X), and XmVaCreateSimpleRa-
dioBox(3X).

XmRowColumn(3X)