NAME
MenuButton widget − button that pops up a menu.
SYNOPSIS
Public Headers:<X11/StringDefs.h> <X11/Xaw/MenuButton.h>
Private Header:<X11/Xaw/MenuButtoP.h>
Class Name:MenuButton
Class Pointer:menuButtonWidgetClass
Instantiation:widget = XtCreateWidget(name, menuButtonWidgetClass, ...)
CLASS HIERARCHY
Core → Simple → Label → Command → MenuButton
DESCRIPTION
The MenuButton widget is an area, often rectangular, that contains a text or pixmap label. This selectable area is referred to as a button. When the pointer cursor is on the button, the button border is highlighted to indicate that the button is ready for selection. When pointer button 1 is pressed, the MenuButton widget pops up the menu that has been named in the XtNmenuName resource.
RESOURCES
When creating a MenuButton widget instance, the following resources are retrieved from the argument list or from the resource database:
| Name (XtN...) | Type | Default | Description | |||
| XtNaccelerators | AcceleratorTable | NULL | List of event-to-action bindings to be executed by this widget, even though the event occurred in another widget. | |||
| XtNancestor− Sensitive |
Boolean | True | (D) Sensitivity state of the ancestors of this widget: a widget is insensitive if either it or any of its ancestors is insensitive. | |||
| XtNbackground | Pixel | XtDefault− Background |
Window background color. | |||
| XtNbackground− Pixmap |
Pixmap | XtUnspecified− Pixmap |
Window background pixmap. | |||
| XtNbitmap | Pixmap | None | Pixmap to display in place of the label. | |||
| XtNborderColor | Pixel | XtDefault− Foreground |
Window border color. | |||
| XtNborderPixmap | Pixmap | XtUnspecified− Pixmap |
Window border pixmap. | |||
| XtNborderWidth | Dimension | 1 | Width of button border. | |||
| XtNcallback | XtCallbackList | NULL | Callback for button select. | |||
| XtNcolormap | Colormap | Parent’s colormap. | Colormap that this widget will use. | |||
| XtNcornerRound− Percent |
Dimension | 25 | See below. | |||
| XtNcursor | Cursor | None | Pointer cursor. | |||
| XtNdepth | int | Parent’s depth. | (C) Depth of this widget’s window. | |||
| XtNdestroy− Callback |
XtCallbackList | NULL | Callbacks for XtDestroyWidget(). | |||
| XtNencoding | unsigned char | XawTextEncoding8bit | For I18N. | |||
| XtNfont | XFontStruct | XtDefaultFont | Label font. | |||
| XtNforeground | Pixel | XtDefault− Foreground |
Foreground color. | |||
| XtNheight | Dimension | Font height + 2 ∗ XtNinternalHeight |
(A) Button height. | |||
| XtNhighlight− Thickness |
Dimension | 2 (0 if Shaped) | (A) Width of border to be highlighted. | |||
| XtNinsensitive− Border |
Pixmap | Gray pixmap. | Border when not sensitive. | |||
| XtNinternal− Height |
Dimension | 2 | Internal border height for highlighting. | |||
| XtNinternalWidth | Dimension | 4 | Internal border width for highlighting. | |||
| XtNjustify | Justify | XtJustifyCenter | Type of text alignment. | |||
| XtNlabel | String | Name of widget. | Button label. | |||
| (R5) XtNleftBitmap | Bitmap | None | Pixmap before label. | |||
| XtNmappedWhen− Managed |
Boolean | True | Whether XtMapWidget() is automatic. | |||
| XtNmenuName | String | "menu" | Name of menu. | |||
| XtNresize | Boolean | True | Whether to auto-resize in SetValues. | |||
| XtNscreen | Screen | Parent’s screen. | (R) Screen on which this widget is displayed. | |||
| XtNsensitive | Boolean | True | Whether widget receives input. | |||
| XtNshapeStype | ShapeStyle | Rectangle | Type of nonrectangular button. | |||
| XtNtranslations | TranslationTable | See below. | Event-to-action translations. | |||
| XtNwidth | Dimension | XtNlabel width + 2 ∗ XtNinternalWidth |
(A) Button Width. | |||
| XtNx | Position | 0 | x-coordinate in pixels. | |||
| XtNy | Position | 0 | y-coordinate in pixels. | |||
Note that the MenuButton widget supports two callback lists: XtNdestroyCallback and XtNcallback. The notify action executes the callbacks on the XtNcallback list. The call_data argument is unused.
The new resources (not inherited from superclasses) associated with the MenuButton widget are:
XtNmenuName
The name of a popup shell to pop up as a menu. The MenuButton searches for this name using XtNameToWidget(), starting with itself as the reference widget. If unsuccessful, MenuButton continues to search up the widget tree, using each of its ancestors as the reference widget. If still unsuccessful, MenuButton prints a warning message and gives up. When the menu is found, it is popped up with an exclusive Xt grab mode and with a global passive grab of the pointer button that was pressed. The MenuButton widget does not copy the value of this resource into newly allocated memory. The application programmer must pass the resource value in nonvolatile memory.
TRANSLATIONS AND ACTIONS
The following default translation bindings are used by the MenuButton widget: <EnterWindow>: highlight() <LeaveWindow>: reset() <BtnDown>: reset() PopupMenu() With these bindings, the user can cancel the action before releasing the button by moving the pointer out of the MenuButton widget.
The MenuButton widget supports the following actions:
•Switching the button between the foreground and background colors with set and unset.
•Processing application callbacks with notify.
•Switching the internal border between highlighted and unhighlighted states with highlight and unhighlight.
•Popping up a menu with PopupMenu.
The actions supported by MenuButton are listed below:
highlight(condition)
Displays the internal highlight border in the color (XtNforeground or XtNbackground) that contrasts with the interior color of the MenuButton widget. The conditions WhenUnset and Always are understood by this action procedure. If no argument is passed, WhenUnset is assumed.
unhighlight()
Displays the internal highlight border in the color (XtNforeground or XtNbackground) that matches the interior color of the MenuButton widget.
set()
Enters the set state, in which notify is possible, and displays the interior of the button, including the highlight border, in the foreground color. The label or pixmap is displayed in the background color.
unset()
Cancels the set state and displays the interior of the button, including the highlight border, in the background color. The label or pixmap is displayed in the foreground color.
reset()
Cancels any set or highlight action and displays the interior of the button in the background color, with the label or pixmap displayed in the foreground color.
notify()
Executes the callback list specified by XtNcallback, if executed in the set state. The value of the call_data argument is undefined.
PopupMenu()
Pops up the menu specified by the XtNmenuName resource. PopupMenu is registered as a grab action. As a result, clients which pop up menus without using XtMenuPopup() or MenuPopup or PopupMenu in translations will fail to have a grab active. They should make a call to XtRegisterGrabAction() on the appropriate action in the application initialization routine, or use a different translation.
SEE ALSO
Command, Label, SimpleMenu.