MenuButton(3W) UNIX System V MenuButton(3W)
NAME
MenuButton - provides a button with a MenuShell attached
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <MenuButton.h>
static Widget stack, menupane, w;
Arg args[1];
stack = XtCreateWidget(name, menubuttonWidgetClass, ...);
OR stack = XtCreateWidget(name, menubuttonGadgetClass, ...);
XtSetArg(args[0], XtNmenuPane, &menupane);
XtGetValues(stack, args, 1);
w = XtCreateWidget(name, widget-class, menupane, ...);
DESCRIPTION
The MenuButton widget provides the features of menu default selection and
menu previewing as well as the features of the Menu widget.
MenuButton Components
Each menu button has the following parts:
- Label
- Border
Figure 1. Menu Button
Each menu button also has the components of a Menu widget. These are not
shown in Figure 1.
All Features of the Menu Widget
The MenuButton widget includes all the features of the Menu widget; the
features of that widget apply here.
Selecting the Default Item
As an interface to a menu, each MenuButton widget has a Default Item. If
the power-user option is on, this Default Item is selected by clicking
SELECT over the MenuButton widget. If the Default Item is inactive (its
XtNsensitive resource is FALSE), or busy (its XtNbusy resource is TRUE),
the system beeps. (If the power-user option is off, clicking SELECT
brings up a pop-up menu. The power-user option is set in the property
sheet of the Workspace Manager. See the OPEN LOOK GUI User's Guide for
more information on setting the power-user option.)
10/89 Page 1
MenuButton(3W) UNIX System V MenuButton(3W)
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-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 pinned
menu.
Previewing the Default Item
If the menu button is not in a pop-up menu and the power-user option is
on, pressing SELECT, or moving the pointer into the menu button while
SELECT is pressed, displays the highlighted label of the Default Item in
place of the menu button's label. Releasing SELECT restores the original
colors and label, and selects the Default Item as described above.
Moving the pointer off the menu button before releasing also restores the
original colors and label, but does not select the Default Item. (If the
power-user option is off, pressing SELECT and releasing it displays a
stayup menu. See Selecting the Default Item above for comments about the
power-user option.)
This Default Item is the one in the menu directly under the menu button,
not necessarily the Default Item at the end of the menu tree, that is
activated when the Default Item is selected (see above).
NOTE:
The previewing feature is not available with keyboard only operation.
This feature functions only when using a mouse to SELECT an item.
Popping Up the Menu-Not in a Menu
When the MenuButton widget is in a control area, pressing or clicking
MENU when the pointer is within or on the Border pops up the menu
button's menu in the direction of the menu mark.
Popping Up the Menu-As a 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 Border pops up the menu
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 When There is No Room
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
Page 2 10/89
MenuButton(3W) UNIX System V MenuButton(3W)
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.
MenuButton 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.
Figure 2 illustrates the resources that affect the coloration 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 2. 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:
10/89 Page 3
MenuButton(3W) UNIX System V MenuButton(3W)
- 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 action of the SELECTKEY depends on whether the user has selected the
power-user option. (The power-user option is set in the property sheet
of the Workspace Manager. See the GUI User's Guide for more information
on setting this option.) While focus is on the MenuButton and the
power-user option is on, pressing the SELECTKEY activates the default
menu item. If the power-user option is off, pressing the SELECTKEY posts
the stayup menu.
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|
| | 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. |
|__________________|________________________________|
Display of Keyboard Mnemonic
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().
Page 4 10/89
MenuButton(3W) UNIX System V MenuButton(3W)
If truncation is necessary, the mnemonic displayed in parenthesis is
truncated as a unit.
Display of Keyboard Accelerators
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).
SUBSTRUCTURE
Menu Component
Name: menu
Class: Menu
_____________________________________________________________________________________
Application Resources
_____________________________________________________________________________________
Name Class Type Default Access
_____________________________________________________________________________________
_____________________________________________________________________________________
*XtNcenter XtCCenter Boolean TRUE I
_____________________________________________________________________________________
*XtNhPad XtCHPad Dimension 4 I
_____________________________________________________________________________________
*XtNhSpace XtCHSpace Dimension 4 I
_____________________________________________________________________________________
*XtNlayoutType XtCLayoutType OlDefine OL_FIXEDROWS I
_____________________________________________________________________________________
*XtNmeasure XtCMeasure int 1 I
_____________________________________________________________________________________
XtNpushpin XtCPushpin OlDefine OL_NONE I
_____________________________________________________________________________________
XtNpushpinDefault XtCPushpinDefault Boolean FALSE I
_____________________________________________________________________________________
*XtNsameSize XtCSameSize OlDefine OL_COLUMNS I
_____________________________________________________________________________________
XtNtitle XtCTitle String (widget's name) I
_____________________________________________________________________________________
*XtNvPad XtCVPad Dimension 4 I
_____________________________________________________________________________________
10/89 Page 5
MenuButton(3W) UNIX System V MenuButton(3W)
| *XtNvSpace | XtCVSpace | Dimension | 4 | I |
|___________________|____________________|____________|__________________|___________|
* See the Menu and ControlArea widgets for more information on these
resources.
RESOURCES
_____________________________________________________________________________________________
MenuButton Resource Set
_____________________________________________________________________________________________
Name Class Type Default Access
_____________________________________________________________________________________________
_____________________________________________________________________________________________
XtNaccelerator XtCAccelerator String NULL SGI
_____________________________________________________________________________________________
XtNacceleratorText XtCAcceleratorText String Dynamic SGI
_____________________________________________________________________________________________
XtNancestorSensitive XtCAncestorSenstitive Boolean TRUE G*
_____________________________________________________________________________________________
XtNbackground XtCBackground Pixel White SGI†
_____________________________________________________________________________________________
‡ XtNbackgroundPixmap XtCPixmap Pixmap (none) SGI†
_____________________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SGI
_____________________________________________________________________________________________
XtNdefault XtCDefault Boolean FALSE SGI
_____________________________________________________________________________________________
‡ XtNdepth XtCDepth int (parent's) GI
_____________________________________________________________________________________________
XtNdestroyCallback XtCCallback XtCallbackList NULL SI
_____________________________________________________________________________________________
XtNfont XtCFont XFontStruct * (OPEN LOOK font) SI
_____________________________________________________________________________________________
XtNfontColor XtCFontColor Pixel Black* SGI
_____________________________________________________________________________________________
XtNforeground XtCForeground Pixel Black SGI†
_____________________________________________________________________________________________
XtNheight XtCHeight Dimension (calculated) SGI
_____________________________________________________________________________________________
XtNinputFocusColor XtCInputFocusColor Pixel Black SGI
_____________________________________________________________________________________________
XtNlabel XtCLabel String (class name) SGI
_____________________________________________________________________________________________
XtNlabelJustify XtCLabelJustify OlDefine OL_LEFT SGI
_____________________________________________________________________________________________
‡ XtNmappedWhenManaged XtCMappedWhenManaged Boolean TRUE SGI
_____________________________________________________________________________________________
XtNmenuMark XtCMenuMark OlDefine (calculated) SGI
_____________________________________________________________________________________________
XtNmenuPane XtCMenuPane Widget (none) G
_____________________________________________________________________________________________
XtNmnemonic XtCMnemonic unsigned char NULL SGI
_____________________________________________________________________________________________
Page 6 10/89
MenuButton(3W) UNIX System V MenuButton(3W)
| XtNrecomputeSize | XtCRecomputeSize | Boolean | TRUE | SGI |
|_______________________|_______________________|________________|__________________|________|
| XtNreferenceName | XtCReferenceName | String | NULL | SGI |
|_______________________|_______________________|________________|__________________|________|
| XtNreferenceWidget | XtCReferenceWidget | Widget | NULL | SGI |
|_______________________|_______________________|________________|__________________|________|
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI* |
|_______________________|_______________________|________________|__________________|________|
| XtNtraversalOn | XtCTraversalOn | Boolean | TRUE | SGI |
|_______________________|_______________________|________________|__________________|________|
| XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_______________________|_______________________|________________|__________________|________|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|_______________________|_______________________|________________|__________________|________|
| XtNx | XtCPosition | Position | 0 | SGI |
|_______________________|_______________________|________________|__________________|________|
| XtNy | XtCPosition | Position | 0 | SGI |
|_______________________|_______________________|________________|__________________|________|
‡ These resources are not available to MenuButton gadgets.
XtNdefault
Range of Values:
TRUE
FALSE
If this resource is TRUE, the Border is doubled to two lines to show that
the menu button contains the default choice of several buttons.
XtNfont
Range of Values:
(any valid return from XLoadQueryFont())
Default:
(chosen to match the scale and screen resolution)
This resource identifies the font to be used to display the Label.
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
Range of Values:
(any Pixel value valid for the current display)/(any name from the
rgb.txt file)
This resource specifies the color for the font. If not set, the color
from the XtNforeground resource, if available, is used for the font.
10/89 Page 7
MenuButton(3W) UNIX System V MenuButton(3W)
See the note about the interaction of this resource with other color
resources under the description of the XtNbackground resource in Core
Resources.
XtNforeground
This resource defines the foreground color for the widget.
See the note about the interaction of this resource with other color
resources under the description of the XtNbackground resource in Core
Resources.
XtNlabel
This resource is a pointer to the text for the Label of the MenuButton
widget.
XtNlabelJustify
Range of Values:
OLLEFT/"left"
OLCENTER/"center"
This resource dictates whether the Label should be left-justified or
centered within the widget width.
XtNmenuMark
Range of Values:
OL_DOWN
OL_RIGHT
This resource specifies the direction of the menu arrow.
XtNmenuPane
This is the widget where menu items can be attached; its value is
available once the MenuButton widget has been created.
XtNrecomputeSize
Range of Values:
TRUE
FALSE
This resource indicates whether the MenuButton widget should calculate
its size and automatically set the XtNheight and XtNwidth resources. If
set to TRUE, the MenuButton widget will do normal size calculations that
may cause its geometry to change. If set to 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.
Page 8 10/89
MenuButton(3W) UNIX System V MenuButton(3W)
Label Appearance
The XtNwidth, XtNheight, XtNrecomputeSize, and XtNlabelJustify resources
interact to produce a truncated, clipped, centered, or left-justified
label as shown in Figure 3.
Figure 3. Label Appearance
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
MenuShell "Programmatic Menu Popup and Popdown"
10/89 Page 9