MenuButton(3W)
NAME
MenuButton − menu button widget and gadget
SYNOPSIS
#include <Xol/OpenLook.h>
#include <Xol/MenuButton.h>
. . .
ANCESTRY
Core-Primitive-Button-MenuButton
DESCRIPTION
The MenuButton is used to create a pop-up menu. It appears similar to the OblongButton widget, except that it also has a mark, called a menumark, near the end of the button. When the user presses MENU on the MenuButton, a menu pane pops up. This menu can contain several objects which allow the user to make a selection. The MenuButton provides the features of menu default selection and menu previewing as well as the features of the Menu widget.
Components
Each MenuButton has the following parts:
— label
— border
Figure 1 Menu Button
Each menu button also has the components of a Menu widget.
The MenuButton widget includes all the features of the Menu widget; the features of that widget apply here.
Subwidgets
MenuButton contains one subwidget, a MenuShell provided automatically, and accessible through the XtNmenupane resource.
Figure 2 MenuButton Subwidgets
MenuButton
|
|
MenuShell
(XtNmenuPane)
Selecting the Default Item
As the trigger of a menu, each MenuButton widget has a default item. If the default item is inactive (its XtNsensitive resource is FALSE ), or busy (its XtNbusy resource is TRUE), the system beeps.
Since the default item may be the MenuButton widget itself, selecting it really selects its default item; this recurses through the menu tree until a non- non-MenuButton widget is found as the default item. The default item may be the pushpin in a menu.
If a pushpin is the default item, the menu is brought up as a .pinnedmenu
Popping Up Menu—Not in a Menu
When the MenuButton widget is in a control area, pressing or clicking MENU MenuButton´s menu in the direction of the menu mark.
Popping Up Menu—As Menu Button in a Menu
When the MenuButton widget is in a stay-up menu, pressing or clicking MENU when the pointer is within or on the button’s border pops up the button’s menu in the direction of the menu mark.
When the MenuButton widget is in a pop-up menu, moving the pointer into the menu mark region pops up the menu in the direction of the menu mark. The position is computed when the movement into the menu mark region is first detected, but rapid pointer motion and internal delays in popping up the menu may let the pointer wander.
Moving the pointer out of the MenuButton widget, but not directly into the newly popped up menu, causes that menu to be popped down. This occurs even if the pointer is moved into and out of the newly popped up menu in the interim.
Menu Placement - Not Enough Space
If the right or bottom edge of the screen is too close to allow the menu placement described above, the menu pops up aligned with the edge of the screen and the pointer is shifted horizontally to keep it four points from the left edge of the menu items. If the left edge of the screen is too close, the menu pops up four points from the edge and the pointer is shifted to lie on the edge. The pointer does not jump back after the menu is dismissed.
Coloration
On a monochrome display, the MenuButton widget indicates that it has input focus by inverting the foreground and background colors of the control.
On color displays, when the MenuButton widget receives the input focus, the background color is changed to the input focus color set in the XtNinputFocusColor resource.
EXCEPTIONS:
—If the input focus color is the same as the font color for the control labels, then the coloration of the active control is inverted.
—If the input focus color is the same as the Input Window Header Color and the active control is in the window header, then invert the colors.
—If the input focus color is the same as the window background color, then the MenuButton widget inverts the foreground and background colors when it has input focus. of the MenuButton widget. Events that occur outside the border (but within the MenuButton widget) are still in the domain of the menu button.
Figure 3 Menu Button Coloration
Keyboard Traversal
The default value of the XtNtraversalOn resource is TRUE.
Keyboard traversal within a menu is done using the PREV_FIELD, NEXT_FIELD, MOVEUP, MOVEDOWN, MOVELEFT and MOVERIGHT keys. The PREV_FIELD, MOVEUP, and MOVELEFT keys move the input focus to the previous menu item with keyboard traversal enabled. If the input focus is on the first item of the menu, then pressing one of these keys will wrap to the last item of the menu with keyboard traversal enabled. The NEXT_FIELD, MOVEDOWN, and MOVERIGHT keys move the input focus to the next menu item with keyboard traversal enabled. If the input focus is on the last item of the menu, then pressing one of these keys will wrap to the first item of the menu with keyboard traversal enabled.
To traverse out of the menu, the following keys can be used:
—NEXTWINDOW moves to the next window in the application
—PREVWINDOW moves to the previous window in the application
—NEXTAPP moves to the first window in the next application
—PREVAPP moves to the first window in the previous application
Keyboard Operation
The DEFAULTACTION key will activate the default control in the MenuButton widget as if the user clicked the SELECT button on the control. To dismiss a MenuButton’s submenu while focus is with the submenu, the CANCEL key is used.
The MENUDEFAULTKEY can be used by the user to change the default control in the MenuButton widget. When the user presses the MENUDEFAULTKEY, the control which has input focus will become the default control.
MenuButton/MenuGadget Activation Types
OL_MENUKEY: Popup the MenuButton’s submenu and set focus to the menu’s default
item.
OL_MENUDEFAULTKEY: If the MenuButton is on a menu, this sets the MenuButton to be the
menu’s default.
OL_SELECTKEY: See the above discussion of SELECTKEY.
Keyboard Mnemonic Display
The MenuButton widget displays the mnemonic accelerator for its child as part of its label. If the mnemonic character is in the label, then that character is highlighted according to the value returned by XtNshowMnemonics. If the mnemonic character is not in the label, it is displayed to the right of the label in parenthesis and highlighted according to the value returned by XtNshowMnemonics.
If truncation is necessary, the mnemonic displayed in parenthesis is truncated as a unit.
Keyboard Accelerators Display
The MenuButton widget displays the keyboard accelerator as part of its label. The string in the XtNacceleratorText resource is displayed to the right of the label (or mnemonic) separated by at least one space. The acceleratorText is right justified.
If truncation is necessary, the accelerator is truncated as a unit. The accelerator is truncated before the mnemonic or the label.
MenuButton Gadgets
MenuButton gadgets cannot be parents (i.e. cannot be used as the parent parameter when creating a widget or other gadget.
Gadgets share some Core fields. But since they are not subclasses of Core, they do not have all Core fields. In particular, they don’t have a name field or a translation field (so translations cannot be specified/overridden).
RESOURCES
Menu Component
Name: menu
Class: Menu
Table 1 Menu Component Resources
Name Type Default Access
∗XtNcenter Boolean TRUE I
∗XtNhPad Dimension 4 I
∗XtNhSpace Dimension 4 I
∗XtNlayoutType OlDefine OL_FIXEDROWS I
∗XtNmeasure int 1 I
XtNpushpin OlDefine OL_NONE I
XtNpushpinDefault Boolean FALSE I
∗XtNsameSize OlDefine OL_COLUMNS I
XtNtitle String (widget’s name) I
∗XtNvPad Dimension 4 I
∗XtNvSpace Dimension 4 I
∗ See the Menu and ControlArea widgets for more information on these resources.
Table 2 MenuButton Resource Summary
Name Type Default Access
XtNaccelerator- String NULL SGI
XtNacceleratorText- String Dynamic SGI
XtNancestorSensitive- Boolean TRUE GO
XtNbackground- Pixel XtDefaultBackground SGI
XtNbackgroundPixmap-∗ Pixmap (none) SGI
XtNconsumeEvent- XtCallbackList NULL SGI
XtNdefault Boolean FALSE SGI
XtNdepth-∗ int (parent’s) GI
XtNdestroyCallback- XtCallbackList NULL SI
XtNfont XFontStruct∗ (OPEN LOOK font) SI
XtNfontColor Pixel XtDefaultForeground∗ SGI
XtNforeground- Pixel XtDefaultForeground SGI
XtNheight- Dimension (calculated) SGI
XtNinputFocusColor- Pixel Red SGI
XtNlabel String (class name) SGI
XtNlabelJustify OlDefine OL_Left SGI
XtNMappedWhenManaged-∗ Boolean TRUE SGI
XtNmenuMark OlDefine (calculated) SGI
XtNmenuPane Widget (none) G
XtNmnemonic- unsigned char NULL SGI
XtNrecomputeSize Boolean TRUE SGI
XtNreferenceName- String NULL SGI
XtNreferenceWidget- Widget NULL SGI
XtNscale int 12 ISG
XtNsensitive- Boolean TRUE GIO
XtNuserData- XtPointer NULL SGI
XtNwidth- Dimension (calculated) SGI
XtNx- Position 0 SGI
XtNy- Position 0 SGI
Access: S = XtSetValues G = XtGetValues
I = init time O = other access
∗ Not available to MenuButton gadgets.
† see resources(3W)
XtNdefault
class:XtCDefaulttype:Booleandefault:FALSEFALSE’u’access:SGISGI’u’
Action: indicates default choice of the menu.
Values: TRUE – this button is the default choice for the menu, and the button’s border is doubled to indicate such. FALSE – not the default item.
XtNfont
class:XtCFonttype:XFontStruct∗default:OPEN LOOK FontOPEN LOOK Font’u’access:SISI’u’
Action: identifies the font to be used to display the Label.
Values: any valid return from XLoadQueryFont()
The default value points to a cached font structure; an application should not expect to get this value with a call to XTGetValues() and use it reliably thereafter.
XtNfontColor
class:XtCFontColortype:Pixeldefault:XtDefaultForegroundXtDefaultForeground’u’access:SGISGI’u’
Action: specifies the font color.
Values: any pixel value valid for the current display, or
any name from the rgb.txt file
If not set, the color from the XtNforeground
XtNforeground
class:XtCForegroundtype:Pixeldefault:XtDefaultForegroundXtDefaultForeground’u’access:SGISGI’u’
Action: defines the foreground color for the widget.
Values: any pixel value valid for the current display
any name from the rgb.txt file
See the note about the interaction of this resource with other color resources under the description of the XtNbackground resource in resources(3W)
XtNlabel
class:XtCLabeltype:Stringdefault:(class name)(class name)’u’access:SGISGI’u’
Action: points to the text for the Label of the MenuButton widget.
XtNlabelJustify
class:XtCLabelJustifytype:OlDefinedefault:OL_LeftOL_Left’u’access:SGISGI’u’
Action: controls justification of label within widget.
Values: OL_LEFT, OL_CENTER
XtNmenuMark
class:XtCMenuMarktype:OlDefinedefault:(calculated)(calculated)’u’access:SGISGI’u’
Action: specifies the direction of the menu arrow.
Values: OL_DOWN, OL_RIGHT
XtNmenuPane
class:XtCMenuPanetype:Widgetdefault:(none)(none)’u’access:GG’u’
Action: is the widget to which menu items can be attached.
This resource is available once the MenuButton widget has been created.
XtNrecomputeSize
class:XtCRecomputeSizetype:Booleandefault:TRUETRUE’u’access:SGISGI’u’
Action: indicates whether the MenuButton widget should calculate its size.
Values: TRUE – the MenuButton widget will do normal size calculations that may cause its geometry to change and automatically set the XtNheight and XtNwidth resources. FALSE – the MenuButton widget will leave its size alone; this may cause truncation of the visible image being shown by the MenuButton widget if the fixed size is too small, or may cause padding if the fixed size is too large.
The location of the padding is determined by the XtNlabelJustify resource.
XtNscale
class:XtCScaletype:Intdefault:1212’u’access:SGISGI’u’
Action: determines size of graphical elements, in points
Values: 0 < XtNscale
This resource sets the size of graphical elements (widgets) in a manner similar to other scale resources.
Note that the units of this resource are points (1/72 of an inch) , not pixels.
Note: Only sizes 10, 12, 14, 19 are presently supported. If this resource is set to any other value, one of these is substituted instead.
Label Appearance
The XtNwidth, XtNheight, XtNrecomputeSize, and XtNlabelJustify resources interact to produce a truncated, clipped, centered, or
Figure 4 Label Appearance
| XtNwidth | XtNrecomputeSize | XtNlabelJustify | label appearance | |||
| any | TRUE | any | just fits | |||
| > needed | FALSE | OL_LEFT | left justified | |||
| OL_CENTER | centered | |||||
| < needed | any | truncated | ||||
| XtNheight | XtNrecomputeSize | XtNlabelJustify | label appearance | |||
| any | TRUE | any | just fits | |||
| > needed | FALSE | centered | ||||
| < needed | clipped |
When the label is centered or left-justified, the extra space is filled with the background color of the MenuButton widget, as determined by the XtNbackground and XtNbackgroundPixmap resources. When a text label is truncated, the truncation occurs at a character boundary and a solid-black triangle is inserted to show that part of the label is missing. The triangle, of course, requires that more of the label be truncated than would otherwise be necessary. If the width of the button is too small to show even one character with the triangle, only the triangle is shown. If the width is so small that the entire triangle cannot be shown, the triangle is clipped on the right.
SEE ALSO
Version 3.0.1 — Last change: June 92