XmQTmenuSystem — A widget holding this trait can serve as a menu system
#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)(, , , Boolean (*XmMenuSystemVerifyProc), , void (*XmMenuSystemControlTraversalProc), , Boolean (*XmMenuSystemPopdownProc), , void (*XmMenuSystemDisarmProc), void (*XmMenuSystemEntryCallbackProc), , , Boolean (*XmMenuSystemUpdateHistoryProc), , , void (*XmMenuSystemPositionProc), , void (*XmMenuSystemUpdateBindingsProc), , void (*XmMenuSystemRecordPostFromWidgetProc), , , Widget (*XmMenuSystemPopupPostedProc), int (*XmMenuSystemWidgetProc));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:
status
childFocus
reparentToTearOffShell
buttonPopdown
getLastSelectTopLevel
entryCallback
verifyButton
controlTraversal
getPopupPosted
tearOffArm
popdownEveryone
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.
int type(rowColumnWidget);The type trait method returns the kind of menu system (for example, a Pulldown menu) that widget rowColumnWidget is 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.
int status(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. |
void cascade(rowColumnWidget, cascadeButtonWidget, 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. |
Boolean verifyButton(rowColumnWidget, 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.
void controlTraversal(rowColumnWidget, 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. |
void menuBarCleanup(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 XmCascadeButtonGadget both call the menuBarCleanup trait method.
| menuBarWidget | Specifies the menubar widget (typically, an XmRowColumn widget) that needs to be cleaned up. |
Boolean popdown(rowColumnWidget, event);The popdown trait method pops down all the Popup menus associated with the rowColumnWidget. This trait method is similar to the buttonPopdown trait method. Your widget should call popdown if 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.
Boolean buttonPopdown(rowColumnWidget, event);The buttonPopdown trait method pops down all the Popup menus associated with the rowColumnWidget. This trait method is similar to the buttonPopdown trait method. Your widget should call popdown if 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.
void reparentToTearOffShell(rowColumnWidget, event);When a user tears off a tear-off menu, the rowColumnWidget holding the menu needs to be reparented. In other words, the rowColumnWidget that 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. |
void reparentToMenuShell(rowColumnWidget, 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. |
void arm(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. |
void disarm(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. |
void tearOffArm(rowColumnWidget);Your child button widget should call the tearOffArm trait method when both of the following are true:
If your child's parent was a TearOff Menu container and it has already been torn off
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 tearOffArm trait method itself calls the menuArm trait method. Upon completion of the menuArm trait method the tearOffArm trait method sets up modal grabs.
| rowColumnWidget | Specifies the menu widget to arm. |
void entryCallback(rowColumnWidget, childButtonWidget, 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. |
Boolean updateHistory(rowColumnWidget, childButtonWidget, 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.
void getLastSelectTopLevel(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. |
void positionMenu(popupMenuPaneWidget, 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_root values 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. |
void updateBindings(widget, 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. |
void recordPostFromWidget(rowColumnWidget, cascadeButtonWidget, 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 cascadeButtonWidget is 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. |
void popdownEveryone(menuShellWidget, 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. |
void childFocus(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. |
Widget getPopupPosted(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.
XmRowColumn(3), XmCascadeButton(3), XmPushButton(3), XmDrawnButton(3), XmArrowButton(3), XmPushButtonGadget(3), XmArrowButtonGadget(3) and XmMenuPosition(3).