XmCreateOptionMenu(3X)

NAME
     XmCreateOptionMenu --A RowColumn widget convenience creation function

SYNOPSIS
     #include <Xm/RowColumn.h>

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


VERSION
     This page documents version 1.2 of the Motif library.

DESCRIPTION
     XmCreateOptionMenu  creates  an  instance of a RowColumn widget of type Xm-
     MENU_OPTION and returns the associated widget ID.

     It is provided as a convenience function for creating  a  RowColumn  widget
     configured to operate as an OptionMenu and is not implemented as a separate
     widget class.

     The  OptionMenu widget is a specialized RowColumn manager composed of a la-
     bel, a selection area, and a single Pulldown MenuPane.  When an application
     creates an OptionMenu widget, it supplies the label string and the Pulldown
     MenuPane.  In order to succeed, there must be a valid XmNsubMenuId resource
     set when calling this function.  When the OptionMenu is created, the  Pull-
     down  MenuPane must have been created as a child of the OptionMenu's parent
     and must be specified.  The LabelGadget and the selection area (a  Cascade-
     ButtonGadget) are created by the OptionMenu.

     The  OptionMenu's  Pulldown  MenuPane must not contain any ToggleButtons or
     ToggleButtonGadgets.  The results of including CascadeButtons  or  Cascade-
     ButtonGadgets in the OptionMenu's Pulldown MenuPane are undefined.

     An  OptionMenu is laid out with the label displayed on one side of the wid-
     get and the selection area on the other side when XmNorientation is XmHORI-
     ZONTAL.  If the value is XmVERTICAL, the label is above the selection area.
     The selection area has a dual purpose; it displays the label  of  the  last
     item  selected  from  the associated Pulldown MenuPane, and it provides the
     means for posting the Pulldown MenuPane.

     The OptionMenu typically does not display any 3-D visuals around itself  or
     the internal LabelGadget.  By default, the internal CascadeButtonGadget has
     a  visible 3-D shadow.  The application may change this by getting the Cas-
     cadeButtonGadget ID using XmOptionButtonGadget, and then calling  XtSetVal-
     ues using the standard visual-related resources.

     The Pulldown MenuPane is posted by moving the mouse pointer over the selec-
     tion  area  and  pressing  a mouse button defined by OptionMenu's RowColumn
     parent.  The Pulldown MenuPane is posted and positioned so  that  the  last
     selected  item is directly over the selection area.  The mouse is then used
     to arm the desired menu item.  When the mouse button is released, the armed
     menu item is selected and the label within the selection area is changed to
     match that of the selected item.  By default, BSelect is used  to  interact
     with  an OptionMenu.  The default can be changed via the RowColumn resource
     XmNmenuPost.

     The OptionMenu also operates by using the keyboard interface mechanism.  If
     the application has established a mnemonic with the OptionMenu, typing  Alt
     with  the mnemonic causes the Pulldown MenuPane to be posted with traversal
     enabled.  The standard traversal keys can then be used to move  within  the
     MenuPane.   Selection can occur as the result of pressing the Return key or
     typing a mnemonic or accelerator for one of the menu items.

     An application may use the XmNmenuHistory resource to indicate  which  item
     in  the  Pulldown MenuPane should be treated as the current choice and have
     its label displayed in the selection area.  By default, the first  item  in
     the Pulldown MenuPane is used.


     parent Specifies the parent widget ID

     name   Specifies the name of the created widget

     arglistSpecifies the argument list

     argcount
            Specifies  the  number of attribute/value pairs in the argument list
            (arglist)


     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"


     For  a  complete  definition of RowColumn and its associated resources, see
     XmRowColumn(3X).

RETURN VALUE
     Returns the RowColumn widget ID.

RELATED INFORMATION
     XmCascadeButtonGadget(3X), XmCreatePulldownMenu(3X), XmCreateSimpleOption-
     Menu(3X), XmLabelGadget(3X), XmOptionButtonGadget(3X), XmOptionLabelGad-
     get(3X), XmRowColumn(3X), and XmVaCreateSimpleOptionMenu(3X).

                                                          XmCreateOptionMenu(3X)