MenuButton(3w) — OLIT Widget Set
NAME
MenuButton − menu button widget and gadget
SYNOPSIS
#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/MenuButton.h>
. . .
Widget my_menubutton, my_parent;
String my_name;
ArgList args;
Cardinal num_args;
my_menubutton = XtCreate( my_name, menubuttonWidgetClass,
my_parent, args, num_args);
OR
my_menubutton = XtCreate( my_name, menubuttonGadgetClass,
my_parent, args, num_args);
. . .
Widget menupane;
XtSetArg( args[0], XtNmenuPane, (XtArgVal) &menupane);
XtGetValues( my_menubutton, args, 1);
Widget a_menu_item;
WidgetClass item_class;
String item_name;
a_menu_item = XtCreate( item_name, item_class, menupane, args, num_args);
DESCRIPTION
The MenuButton widget 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
menu placement, not enough space 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
_
Activation Type Expected Results
=
OL_MENUKEY
Popup the MenuButton’s submenu
item.
_
OL_MENUDEFAULTKEY
If the MenuButton is
menu’s default.
_
OL_SELECTKEY
See the above discussion
Display of Keyboard Mnemonic
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
.LP 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
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
SUBSTRUCTURE
Menu Component
Name: menu
Class: Menu
Application 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)
∗XtNvPad Dimension 4 I
∗XtNvSpace Dimension 4 I
∗ See the Menu and ControlArea widgets for more information on these resources.
Table 1 MenuButton Resource Summary
MenuButton Resource Set
Name Type Default Access
XtNaccelerator String NULL SGI
XtNacceleratorText String Dynamic SGI
XtNancestorSensitive Boolean TRUE GO
XtNbackground Pixel XtDefaultBackground SGI
XtNbackgroundPixmap ∗ Pixmap (none)
XtNconsumeEvent XtCallbackList NULL SGI
XtNdefault Boolean FALSE SGI
XtNdepth ∗ int (parent’s)
XtNdestroyCallback XtCallbackList NULL SI
XtNfont XFontStruct∗ (OPEN LOOK
XtNfontColor Pixel XtDefaultForeground∗ SGI
XtNforeground Pixel XtDefaultForeground SGI
XtNheight Dimension (calculated) SGI
XtNinputFocusColor Pixel Red SGI
XtNlabel String (class name)
XtNlabelJustify OlDefine OL_Left SGI
XtNMappedWhenManaged ∗ Boolean TRUE
XtNmenuMark OlDefine (calculated) SGI
XtNmenuPane Widget (none) G
XtNmnemonic unsigned char NULL
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 timeO = other access
∗ Not available to MenuButton gadgets.
† see resources(3W)
XtNdefault
class:XtCDefault type:Boolean default:FALSEaccess:SGI
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:XtCFont type:XFontStruct∗ default:OPEN LOOK Fontaccess:SI
class:XtCFonttype:XFontStruct∗default:OPEN LOOK Fontaccess:SI
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:XtCFontColor type:Pixel default:Blackaccess:SGI
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:XtCForeground type:Pixel default:Blackaccess:SGI
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 CoreResources(3W).
XtNlabel
class:XtCLabel type:String default:(class name)access:SGI
Action: points to the text for the Label of the MenuButton widget.
XtNlabelJustify
class:XtCLabelJustify type:OlDefine default:OL_Leftaccess:SGI
class:XtCLabelJustifytype:OlDefinedefault:OL_Leftaccess:SGI
Action: controls justification of label within widget.
Values: OL_LEFT, OL_CENTER
XtNmenuMark
class:XtCMenuMark type:OlDefine default:(calculated)access:SGI
Action: specifies the direction of the menu arrow.
Values: OL_DOWN, OL_RIGHT
XtNmenuPane
class:XtCMenuPane type:Widget default:(none)access:G
Action: is the widget to which menu items can be attached.
This resource is available once the MenuButton widget has been created.
XtNrecomputeSize
class:XtCRecomputeSize type:Boolean default:TRUEaccess:SGI
class:XtCRecomputeSizetype:Booleandefault:TRUEaccess:SGI
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:XtCScale type:Int default:12access:SGI
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
=
any TRUE any just
_
> needed FALSE OL_LEFT
_ _
OL_CENTER centered
_ _ _
< needed any truncated
=
XtNheight XtNrecomputeSize XtNlabelJustify label
=
any TRUE any just
_ _ _
> 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-white 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 — 19 July 91