XmRowColumn(3X)

XmRowColumn - The RowColumn widget class

As shipped in IRIX 6.5.30. Added in IRIX 6.5.19.

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 how the
children are laid out, as follows:

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

o each child is placed in an identically sized box
(producing a symmetrical look)

o a specific layout (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 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.

o Option Menu Label Gadget - "OptionLabel"

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

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

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 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 children that are
subclasses of XmLabel or XmLabelGadget 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(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 XmNactivateCallback and
XmNvalueChangedCallback callbacks are then revectored
to the XmNentryCallback callbacks. This allows an
application 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 RowColumn widget; this resource is meaningful only
when the XmNisHomogeneous 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
XmNrowColumnType 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 XmPACK_TIGHT because this
layout preserves variable heights among the children.
The vertical alignment types include:

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

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

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

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

o 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 widget; 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 homogeneity 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 XmCreateRadioBox is called the default value is
True. Otherwise, the default 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
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
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 bottom edge of the RowColumn widget and
the last item in each column. 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 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 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 OptionMenu. If
XmNrowColumnType is set to XmMENU_OPTION, 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, 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 XmWORK_AREA is BSelect
Press. The XmNmenuPost resource for pulldowns 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 XmMENU_OPTION. Specifies a keysym for a key
that, when pressed by the user along with the MAlt
modifier, posts the associated Pulldown 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 meaningful.

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

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.

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.

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

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 of
this resource is True (keyboard input - accelerators
and mnemonics - defined for the Popup MenuPane and any
of its submenus is enabled).

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 important only when XmNradioBehavior is True.

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.

XmNradioBehavior
Specifies a Boolean value that when True, indicates
that the RowColumn 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 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.

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 XmCreateRowColumn, 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, 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 resources explain this when it is the
case. The resource XmNnavigationType, inherited from
XmManager, is changed to XmNONE if XmNrowColumnType is
XmMENU_OPTION.

XmNspacing
Specifies the horizontal and vertical spacing between
items contained within the RowColumn widget. The
default value is 3 pixels for XmOPTION_MENU and
XmWORK_AREA and 0 for other RowColumn types.

XmNsubMenuId
Specifies the widget ID for the Pulldown MenuPane to be
associated with an OptionMenu. This resource is useful
only when XmNrowColumnType 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 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.

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 (default
value). This resource is invalid for type
XmMENU_OPTION; however, it does affect any pulldown
submenus within an OptionMenu. The function
XmRepTypeInstallTearOffModelConverter installs a
resource converter for this resource.

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

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 accelerators 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 button, separator, and
title created. The default is determined dynamically
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.

XmNbuttons
This 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 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.

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 MenuPane 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 CascadeButton or
CascadeButtonGadget specified for the parent of the
Pulldown 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
XmNactivateCallback, 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 superclasses. 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_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.

widget
Is set to the widget ID of the RowColumn item that has
been activated

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 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. When the value of the XmDisplay resource
enableMenuInCascade is True, BMenu also performs the BSelect
actions in all types of menu systems. 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()

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
associated 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 entered. 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, dismisses 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 corner 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 disarms 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 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.

MenuGadgetTraverseRight():
If the current menu item is in a MenuBar, then this
action disarms 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
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.

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 bottommost menu item in
the column to the left, if one exists. When the
current menu item is at the top, leftmost corner of the
MenuPane, 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
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.

KMenu:
Pops up the menu associated with the control that has
the keyboard focus. Enables keyboard traversal in the
menu. In the Popup menu system or any menu cascaded
from it, this action unposts 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), XmCreateOptionMenu(3X),
XmCreatePopupMenu(3X), XmCreatePulldownMenu(3X),
XmCreateRadioBox(3X), XmCreateRowColumn(3X),
XmCreateSimpleCheckBox(3X), XmCreateSimpleMenuBar(3X),
XmCreateSimpleOptionMenu(3X), XmCreateSimplePopupMenu(3X),
XmCreateSimplePulldownMenu(3X), XmCreateSimpleRadioBox(3X),
XmCreateWorkArea(3X), XmDisplay(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).