XmQTmenuSystem(3X) UNIX System V 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,
Page 1 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
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:
⊕ status
⊕ childFocus
⊕ reparentToTearOffShell
⊕ buttonPopdown
⊕ getLastSelectTopLevel
Page 2 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
⊕ 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.
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: XmWORKAREA, XmMENUBAR,
XmMENUPULLDOWN, XmMENUPOPUP, or XmMENUOPTION.
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
Page 3 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
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);
Page 4 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
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.
Page 5 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
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);
Page 6 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
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 XmMENUBAR.
The disarm Trait Method
void disarm(
Page 7 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
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 XmMENUBAR.
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:
⊕ 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
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 callvalue);
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
Page 8 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
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 setvalues 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.
Page 9 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
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
Page 10 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
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.
Page 11 (printed 1/22/99)
XmQTmenuSystem(3X) UNIX System V XmQTmenuSystem(3X)
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).
Page 12 (printed 1/22/99)