oracular (3) XmCreateOptionMenu.3.gz

NAME

       XmCreateOptionMenu  —  A  RowColumn  widget  convenience creation function "XmCreateOptionMenu" "creation
       functions" "XmCreateOptionMenu"

SYNOPSIS

       #include <Xm/RowColumn.h>
       Widget XmCreateOptionMenu(
       Widget parent,
       String name,
       ArgList arglist,
       Cardinal argcount);

DESCRIPTION

       XmCreateOptionMenu creates an instance of a RowColumn  widget  of  type  XmMENU_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 label, a  selection  area,  and  a
       single Pulldown menu pane. When an application creates an OptionMenu widget, it supplies the label string
       and the Pulldown menu pane.  In order for  the  operation  to  be  successful,  there  must  be  a  valid
       XmNsubMenuId  resource  set  when  this  function  is  called.  The LabelGadget and the selection area (a
       CascadeButtonGadget) are created by the OptionMenu.

       The OptionMenu's Pulldown menu pane must not  contain  any  ToggleButtons  or  ToggleButtonGadgets.   The
       results  of  including  CascadeButtons or CascadeButtonGadgets in the OptionMenu's Pulldown menu pane are
       undefined.

       An OptionMenu is laid out with the label displayed on one side of the widget and the  selection  area  on
       the  other  side  when  XmNorientation  is  XmHORIZONTAL.   The  layout  of the label with respect to the
       selection area depends on the XmNlayoutDirection resource in the horizontal orientation.  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 menu pane, and it provides the means for
       posting the Pulldown menu pane.

       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  CascadeButtonGadget  ID  using XmOptionButtonGadget, and then calling XtSetValues using the
       standard visual-related resources.

       The Pulldown menu pane is posted when the mouse pointer is moved over the  selection  area  and  a  mouse
       button that is defined by OptionMenu's RowColumn parent is pressed.  The Pulldown menu pane 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 with the RowColumn resource XmNmenuPost.

       The OptionMenu also operates with the keyboard interface mechanism.  If the application has established a
       mnemonic with the OptionMenu, pressing <Alt> with the mnemonic causes the Pulldown menu pane to be posted
       with  traversal  enabled.   The  standard  traversal  keys can then be used to move within the menu pane.
       Pressing <Return> or typing a mnemonic or accelerator for one of the menu items selects that item.

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

       parent    Specifies the parent widget ID

       name      Specifies the name of the created widget

       arglist   Specifies 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.  These widgets (or gadgets) and the associated OptionMenu areas are

       Option Menu Label Gadget
                 OptionLabel

       Option Menu Cascade Button
                 OptionButton

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

RETURN

       Returns the RowColumn widget ID.

RELATED

       XmCascadeButtonGadget(3),    XmCreatePulldownMenu(3),    XmCreateSimpleOptionMenu(3),   XmLabelGadget(3),
       XmOptionButtonGadget(3), XmOptionLabelGadget(3), XmRowColumn(3), and XmVaCreateSimpleOptionMenu(3).

                                                                                           XmCreateOptionMenu(3)