XmQTmenuSystem(3X)

     NAME
          XmQTmenuSystem - A widget holding this trait can serve as a
          menu system

     SYNOPSIS
          #include <Xm/MenuT.h>

          typedef struct {
                    int                      version;
                    XmMenuSystemTypeProc          type;
                    XmMenuSystemStatusProc        status;
                    XmMenuSystemCascadeProc       cascade;
                    XmMenuSystemVerifyProc        verifyButton;
                    XmMenuSystemControlTraversalProc        controlTraversal;
                    XmMenuSystemMenuBarCleanupProc     menuBarCleanup;
                    XmMenuSystemPopdownProc       popdown;
                    XmMenuSystemPopdownProc       buttonPopdown;
                    XmMenuSystemReparentProc           reparentToTearOffShell;
                    XmMenuSystemReparentProc           reparentToMenuShell;
                    XmMenuSystemArmProc           arm;
                    XmMenuSystemDisarmProc        disarm;
                    XmMenuSystemTearOffArmProc         tearOffArm;
                    XmMenuSystemEntryCallbackProc      entryCallback;
                    XmMenuSystemUpdateHistoryProc      updateHistory;
                    XmMenuSystemGetPostedFromWidgetProc     getLastSelectToplevel;
                    XmMenuSystemPositionProc           position;
                    XmMenuSystemUpdateBindingsProc     updateBindings;
                    XmMenuSystemRecordPostFromWidgetProc    recordPostFromWidget;
                    XmMenuSystemPopdownAllProc         popdownEveryone;
                    XmMenuSystemChildFocusProc         childFocus;
                    XmMenuSystemPopupPostedProc        getPopupPosted;
          } XmMenuSystemTraitRec, *XmMenuSystemTrait;

          #define  XmMenuSystemTypeProc                XmMenuSystemWidgetProc
          #define  XmMenuSystemStatusProc              XmMenuSystemWidgetProc
          #define  XmMenuSystemMenuBarCleanupProc      XmMenuSystemDisarmProc
          #define  XmMenuSystemReparentProc            XmMenuSystemPositionProc
          #define  XmMenuSystemArmProc                 XmMenuSystemDisarmProc
          #define  XmMenuSystemTearOffArmProc          XmMenuSystemDisarmProc
          #define  XmMenuSystemGetPostedFromWidgetProc    XmMenuSystemDisarmProc
          #define  XmMenuSystemPopdownAllProc          XmMenuSystemPositionProc
          #define  XmMenuSystemChildFocusProc          XmMenuSystemDisarmProc
          void (*XmMenuSystemCascadeProc)(
          Widget,
          Widget,
          XEvent*,
          Boolean (*XmMenuSystemVerifyProc)(
          Widget,
          XEvent*,
          void (*XmMenuSystemControlTraversalProc)(
          Widget,
          Boolean,
          Boolean (*XmMenuSystemPopdownProc)(
          Widget,
          XEvent*,
          void (*XmMenuSystemDisarmProc)(
          Widget,
          void (*XmMenuSystemEntryCallbackProc)(
          Widget,
          Widget,
          XtPointer,
          Boolean (*XmMenuSystemUpdateHistoryProc)(
          Widget,
          Widget,
          Boolean,
          void (*XmMenuSystemPositionProc)(
          Widget,
          XEvent*,
          void (*XmMenuSystemUpdateBindingsProc)(
          Widget,
          int,
          void (*XmMenuSystemRecordPostFromWidgetProc)(
          Widget,
          Widget,
          Boolean,
          Widget (*XmMenuSystemPopupPostedProc)(
          Widget,
          int (*XmMenuSystemWidgetProc)(
          Widget);

     VERSION
          This page documents Motif 2.1.

     DESCRIPTION
          A widget holding the XmQTmenuSystem trait can be configured
          as a menu system. In the standard Motif widget set, only the
          XmRowColumn widget holds this trait.

          The XmQTmenuSystem trait provides many trait methods.  If
          you are writing a menu child widget, then you will need to
          call some of these trait methods. For example, the
          ExmMenuButton demonstration widget uses the following trait
          methods of XmQTmenuSystem:

             o  status

             o  childFocus

             o  reparentToTearOffShell

             o  buttonPopdown

             o  getLastSelectTopLevel

             o  entryCallback

             o  verifyButton

             o  controlTraversal

             o  getPopupPosted

             o  tearOffArm

             o  popdownEveryone

             o  popdown

          We do not recommend writing your own menu manager widget.

          All the primitive button widgets and button gadgets in the
          standard Motif widget set call trait methods of
          XmQTmenuSystem.

        The type Trait Method
          int type(
          Widget rowColumnWidget);

          The type trait method returns the kind of menu system (for
          example, a Pulldown menu) that widget rowColumnWidgetis
          managing.

          rowColumnWidget
                    Specifies the parent widget that is managing the
                    menu system.  Typically, rowColumnWidget is the
                    parent widget of the current widget.

          This trait method returns the type of menu. The returned
          type must be one of the following:  XmWORK_AREA, XmMENU_BAR,
          XmMENU_PULLDOWN, XmMENU_POPUP, or XmMENU_OPTION.

        The status Trait Method
          int status(
          Widget rowColumnWidget);

          The status trait method returns the current status of
          certain menu operations.

          rowColumnWidget
                    Specifies the XmRowColumn widget that is managing
                    the menu system.  Typically, rowColumnWidget is
                    the parent widget of the current widget.

          This trait method returns a bit mask symbolizing the current
          status of certain menu operations.  The Xm/XmP.h header file
          provides widget writers with the following macros for
          interpreting the returned mask:

          XmIsTorn(mask)
                    This macro returns a nonzero value if the menu has
                    already been torn off.  Otherwise, this macro
                    returns 0.

          XmIsTearOffShellDescendant(mask)
                    This macro returns a nonzero value if the menu is
                    a descendant of the tear-off shell. Otherwise,
                    this macro returns 0.

          XmPopupPosted(mask)
                    This macro returns a nonzero value if the menu is
                    a Popup menu that has already been posted.
                    Otherwise, this macro returns 0.

          XmIsInDragMode(mask)
                    This macro returns a nonzero value if the menu is
                    in drag mode.  Otherwise, this macro returns 0.

        The cascade Trait Method
          void cascade(
          Widget rowColumnWidget,
          Widget cascadeButtonWidget,
          XEvent *event);

          We do not recommend writing your own cascade button widget;
          however, if you do, then your cascade button widget must
          call the cascade trait method. More specifically, your
          cascade button widget must call cascade immediately prior to
          performing the menu cascade itself.  The cascade trait
          method records the data causing the cascade.  Furthermore,
          the trait method positions the submenu.  Note that this
          trait method does not actually perform the menu cascade
          itself.

          rowColumnWidget
                    Specifies the submenu to post.

          cascadeButtonWidget
                    Specifies the cascade button widget that is about
                    to be cascaded.

          event     Specifies a pointer to the event causing the menu
                    cascade.

        The verifyButton Trait Method
          Boolean verifyButton(
          Widget rowColumnWidget,
          XEvent *event);

          A child button widget calls the verifyButton trait method to
          determine whether event is supposed to cause menu posting.
          The event that is supposed to cause menu posting is defined
          by the XmNmenuPost resource of the parent XmRowColumn
          widget.

          rowColumnWidget
                    Specifies the parent XmRowColumn widget that holds
                    the menu posting event.

          event     Specifies a pointer to the event received by the
                    child button widget that is to be verified.

          This trait method returns True if the event matches the menu
          posting specification defined by the XmNmenuPost resource of
          rowColumnWidget.  Otherwise, it returns False.

        The controlTraversal Trait Method
          void controlTraversal(
          Widget rowColumnWidget,
          Boolean traverse);

          We do not recommend writing your own cascade button widget;
          however, if you do, then your cascade button widget will
          call controlTraversal to control traversal within the
          MenuBar.  This trait method turns menu traversal on or off.

          rowColumnWidget
                    Specifies the RowColumn widget that will handle
                    traversal.

          traverse  This is a Boolean value. Ordinarily, this should
                    be set to False.  Specifying False establishes
                    default Motif traversal behavior within a MenuBar,
                    which is to say that traversal is disabled.
                    Specifying True enables menu traversal within the
                    MenuBar.

        The menuBarCleanup Trait Method
          void menuBarCleanup(
          Widget menuBarWidget);

          A user may invoke the <osfMenuBar> action of
          XmRowColumn(typically, by pressing the F10 function key) to
          activate traversal within the MenuBar.  When the user
          invokes <osfMenuBar> a second time to deactivate menu
          traversal, the XmRowColumn needs to "clean up" the MenuBar.
          This cleanup involves lowering any Pulldown or Popup menus.
          In the standard Motif widget set, XmCascadeButton and
          XmCascadeButtonGadgetboth call the menuBarCleanup trait
          method.

          menuBarWidget
                    Specifies the menubar widget (typically, an
                    XmRowColumn widget) that needs to be cleaned up.

        The popdown Trait Method
          Boolean popdown(
          Widget rowColumnWidget,
          XEvent *event);

          The popdown trait method pops down all the Popup menus
          associated with the rowColumnWidget.  This trait method is
          similar to the buttonPopdowntrait method. Your widget should
          call popdownif rowColumnWidget is in a tear-off shell.

          rowColumnWidget
                    Specifies the parent widget (typically, an
                    XmRowColumn widget) that is managing the Popup
                    menus.

          event     Specifies a pointer to the event causing the
                    popdown.

          This trait method returns True if rowColumnWidget was
          managing any Popup menus. Otherwise, it returns False.

        The buttonPopdown Trait Method
          Boolean buttonPopdown(
          Widget rowColumnWidget,
          XEvent *event);

          The buttonPopdown trait method pops down all the Popup menus
          associated with the rowColumnWidget.  This trait method is
          similar to the buttonPopdowntrait method. Your widget should
          call popdownif rowColumnWidget is not in a tear-off shell.
          The buttonPopdown trait method provides a slight delay
          between the time the user presses the button and the popdown
          occurs.  This delay gives the widget time to draw visuals
          that simulate the button being pressed.

          rowColumnWidget
                    Specifies the Popup menu widget that needs to be
                    popped down.

          event     Specifies the event that caused the popdown.

          This trait method returns True if the rowColumnWidget was
          managing any Popup menus. Otherwise, returns False.

        The reparentToTearOffShell Trait Method
          void reparentToTearOffShell(
          Widget rowColumnWidget,
          XEvent *event);
          When a user tears off a tear-off menu, the rowColumnWidget
          holding the menu needs to be reparented. In other words, the
          rowColumnWidgetthat was a child of the MenuBar must now
          become a child of the tear-off shell. In order to do this,
          the child button widget calls the reparentToTearOffShell
          trait method.

          rowColumnWidget
                    Specifies the menu to reparent.

          event     Specifies a pointer to the event that caused the
                    tear off.

        The reparentToMenuShell Trait Method
          void reparentToMenuShell(
          Widget rowColumnWidget,
          XEvent *event);

          When a user collapses a tear-off shell, the rowColumnWidget
          holding the menu needs to be reparented. That is, the menu
          inside the tear-off shell must become a child of the
          MenuBar. Therefore, when the user collapses a tear-off
          shell, the child button widget (typically, a cascade button
          widget) must call reparentToMenuShell.

          rowColumnWidget
                    Specifies the menu to reparent.

          event     Specifies a pointer to the event causing the
                    tear-off shell to collapse.

        The arm Trait Method
          void arm(
          Widget rowColumnWidget);

          A cascade button widget must call the arm trait method as
          part of its Arm or ArmAndActivate method.  More precisely, a
          cascade button widget must call arm whenever the user posts
          a Pulldown method.

          If rowColumnWidget is not already armed, then the arm trait
          method makes current the calling widget and saves the focus
          widget.  If rowColumnWidget is already armed, then the arm
          trait method does nothing.

          rowColumnWidget
                    Specifies the XmRowColumn widget to arm. The
                    XmRowColumn widget must have the XmNrowColumnType
                    resource set to XmMENU_BAR.

        The disarm Trait Method
          void disarm(
          Widget rowColumnWidget);

          The disarm trait method undoes the changes caused by the arm
          trait method.  A cascade button widget must call disarm
          whenever the user unposts a Pulldown menu.

          The disarm trait method undoes the actions performed by the
          arm trait method.  That is, if rowColumnWidget is armed,
          then the disarm trait method makes current the active item
          that had the focus before the menu was armed.

          rowColumnWidget
                    Specifies the menu widget to disarm.  The
                    XmRowColumn widget must have the XmNrowColumnType
                    resource set to XmMENU_BAR.

        The tearOffArm Trait Method
          void tearOffArm(
          Widget rowColumnWidget);

          Your child button widget should call the tearOffArm trait
          method when both of the following are true:

             o  If your child's parent was a TearOff Menu container
                and it has already been torn off

             o  The user has selected your child widget as the initial
                selection

          The tearOffArm trait method places the menu system into an
          active state by setting up grabs. After doing this, the
          tearOffArmtrait method itself calls the menuArm trait
          method.  Upon completion of the menuArm trait method the
          tearOffArmtrait method sets up modal grabs.

          rowColumnWidget
                    Specifies the menu widget to arm.

        The entryCallback Trait Method
          void entryCallback(
          Widget rowColumnWidget,
          Widget childButtonWidget,
          XtPointer call_value);

          A button widget that supports an activate callback must call
          the entryCallback trait method. More specifically, a button
          widget must call this trait method when the user activates
          the button.  This trait method calls the entry callback of
          rowColumnWidget.  The entry callback of the rowColumnWidget
          is defined by the value of the XmNentryCallback resource.

          rowColumnWidget
                    Specifies the menu widget.

          childButtonWidget
                    Specifies the child menu widget that the user has
                    activated.

          call_value
                    Specifies the client data to pass to the entry
                    callback.

        The updateHistory Trait Method
          Boolean updateHistory(
          Widget rowColumnWidget,
          Widget childButtonWidget,
          Boolean updateOnMemWidgetMatch);

          We do not recommend calling this trait method.

          The childButtonWidget should call this trait method from the
          widget's initialize and set_values methods.  This trait
          method updates the value of the XmNmenuHistory resource of
          the rowColumnWidget.

          rowColumnWidget
                    Specifies the RowColumn widget that is the parent
                    of your button widget.

          childButtonWidget
                    Specifies the button widget calling this trait
                    method.

          updateOnMemWidgetMatch
                    Specifies False.

          This trait method returns True if childButtonWidget is in a
          Pulldown or Option Menu. Otherwise, it returns False.

        The getLastSelectToplevel Trait Method
          void getLastSelectTopLevel(
          Widget rowColumnWidget);

          We do not recommend calling this trait method.

          Menu button widgets need to call this trait method
          immediately prior to arming themselves. That is, a menu
          button widget should call the getLastSelectTopLevel trait
          method from its Arm or ArmAndActivate methods.

          rowColumnWidget
                    Specifies the RowColumn widget that is the parent
                    of your button widget.

        The positionMenu Trait Method
          void positionMenu(
          Widget popupMenuPaneWidget,
          XButtonPressedEvent *buttonevent);

          You may need to call the positionMenu trait method from your
          cascade button widget.  The positionMenu trait method
          positions a Popup MenuPane by using the information in the
          specified event.  The popupMenuPaneWidget uses the x_root
          and y_rootvalues in the specified buttonevent to determine
          the menu position.

          Note that the positionMenu trait method works almost
          identically to the XmMenuPosition. The only difference
          between the two is that XmMenuPosition requires its first
          argument to be an XmRowColumn widget, but positionMenu can
          accept any menu manager.

          popupMenuPaneWidget
                    Specifies the Popup menu to be positioned.
                    Typically, this will be an XmRowColumn widget.

          buttonevent
                    Specifies a pointer to the button event that
                    caused the menu to pop up.

        The updateBindings Trait Method
          void updateBindings(
          Widget widget,
          int mode);

          Your button widget must call the updateBindings trait when
          its accelerator or mnemonic changes.  Calling this trait
          method informs the menu parent widget of any changes to
          accelerators or mnemonics.

          widget    Specifies a widget. Ordinarily, this will be a
                    menu child widget.

          mode      Specifies whether an accelerator or mnemonic has
                    been added, removed, or replaced. You should
                    specify one of the following constants:  XmADD,
                    XmDELETE, or XmREPLACE.

        The recordPostFromWidget Trait Method
          void recordPostFromWidget(
          Widget rowColumnWidget,
          Widget cascadeButtonWidget,
          Boolean attach);

          We do not recommend writing your own cascade button widget,
          but if you do, you will need to call the
          recordPostFromWidget. This trait method signals that a
          MenuPane has either been attached to or detached from a
          cascade button.

          rowColumnWidget
                    Specifies the RowColumn widget containing the
                    Popup Menu.

          cascadeButtonWidget
                    Specifies a cascade button widget.

          attach    This is a Boolean value. If True, the
                    cascadeButtonWidgetis signaling that a MenuPane
                    has been attached to a cascade button widget. If
                    False, the cascadeButtonWidget is signaling that a
                    MenuPane has been detached from a cascade button
                    widget.

        The popdownEveryone Trait Method
          void popdownEveryone(
          Widget menuShellWidget,
          XEvent *event);

          The popdownEveryone trait method pops down all the Popup
          Menus associated with menuShellWidget, from bottom to top.

          menuShellWidget
                    Specifies the menu shell widget.

          event     Specifies a pointer to the event causing the
                    popdown.

        The childFocus Trait Method
          void childFocus(
          Widget menuChildWidget);

          The childFocus trait method gives menuChildWidget the
          keyboard focus. This trait method performs other special
          handling to ensure that traversal ignores the focus change.
          This is needed so that keyboard actions (for example,
          <osfSelect> or <osfHelp>) may be taken during the drag.

          menuChildWidget
                    Specifies the menu child widget.

        The getPopupPosted Trait Method
          Widget getPopupPosted(
          Widget rowColumnWidget);

          Each rowColumnWidget maintains one shell to encompass all of
          its Popup Menus. Use the getPopupPosted trait method to get
          the widget identifier of that shell.
          menuChildWidget
                    Specifies the XmRowColumn widget managing your
                    button widget.

          This trait method returns the widget identifier of the shell
          managing the posted Popup Menu.

     RELATED
          XmRowColumn(3), XmCascadeButton(3), XmPushButton(3),
          XmDrawnButton(3), XmArrowButton(3), XmPushButtonGadget(3),
          XmArrowButtonGadget(3) and XmMenuPosition(3).