MenuShell(3w) — OLIT Widget Set
NAME
MenuShell − menu shell widget
SYNOPSIS
#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/Menu.h>
. . .
Widget my_menu, my_parent;
String my_name;
ArgList args;
Cardinal num_args;
my_menu = XtCreatePopupShell( my_name, menuShellWidgetClass,
my_parent, args, num_args);
. . .
Widget menupane;
XtSetArg( args[0], XtNmenuPane, (XtArgVal) &menupane);
XtGetValues( my_menu, 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
Menu Shell versus MenuButton
The MenuShell widget is used to create a menu not associated with either a MenuButton or an AbbrevMenuButton. For example, a Menu widget can be attached to a button, such as an OblongButton widget, but this does not make the button into a menu button. However, all the features of the Menu widget (except those related to menu creation) also pertain to the MenuButton menu.
Components
A menu contains a set of Items that are presented to the end user for his or her selection. These are specified by the application as widgets attached to the menu. One of these items is a default item. (A menu always has exactly one default item.) The items are laid out in a control area. A menu also has a title, a title separator, a border or window Border, and an optional pushpin. Sometimes it also has a drop shadow.
The application chooses the label for the Title and whether a menu has a Pushpin.
MenuShell Subwidgets
The MenuShell contains one subwidget, a “menupane”, which is acontainer for the components of the menu This widget is provided automatically, and accessible through the XtNmenupane resource.
Figure 1 MenuShell Subwidgets
MenuShell
|
|
menu (XtNmenuPane)
Subclass of Shell Widget
The MenuShell widget is a sub-class of Shell widget, so the XtCreatePopupShell() routine is used to create it instead of the more common XtCreateWidget().
Menu Pane
The menu pane is not described as a separate widget here; the only interface to it for the application programmer is as a parent widget to which the widgets comprising the menu items are attached. The menu items are not attached directly to the MenuShell widget, since a shell widget can take only one child. The SYNOPSIS shows how the widget ID of the Menu Pane is obtained from the Menu widget.
Associating a Menu with a Widget
A menu can be associated with any widget, including Primitive widgets. The connection is made by creating the menu widget as a child of the other widget. Of course, being a shell widget, the MenuShell widget is not a normal widget-child of its parent, but a pop-up child. If the application allows it, the menu augments the parent’s event list so that the popping-up of the menu is handled automatically.
Popup Control
Pressing MENU when the pointer is over the parent of the Menu widget causes the menu to be popped up. The menu is presented as a pop-up menu, where the Items are available for a press-drag-release type of selection (see below).
Clicking MENU when the pointer is over the parent of the Menu widget also causes the menu to be popped up, but the menu is presented as a stay-up menu, where the Items are available for a click-move-click type of selection, instead (see below).
A "slow click" (a press with a noticeable delay before the release) may show the menu as a pop-up on the press, then as a stay-up on the release.
Use of the Pushpin
The pushpin is presented to the end user like any of the items to be selected from the menu, except that it is always the top-most item, and is presented visually as an "adornment" of the header, next to the title (if present). The end user selects the pushpin, pushing it in to cause the menu to remain on the display as an OPEN LOOK window or pinned menu, and pulling it out to make the menu a stay-up menu. To the end user, a pinned menu behaves indistinguishably from a command window.
The Default Item
If none of the menu items are explicitly set as the default item, the menu picks the first menu item to be the default item. If the menu contains a pushpin and no other menu item is explicitly set as the default item, the pushpin is chosen as the default item.
Components
A pop-up or stay-up menu shows the title, border, pushpin (if available), items, and drop shadow. The title is left out if the menu is from either a menu button or an abbreviated menu button. A pinned menu shows the window border, title, pushpin, items, but no drop shadow.
Figure 2 MenuShell Components
Popup Position
If the menu is not from a menu button, the menu pops up so that the Default Item is vertically centered four points to the right of the pointer. If the right or bottom edge of the screen is too close to allow this placement, the menu pops up with the Drop Shadow aligned with the edge of the screen, and the mouse pointer is shifted horizontally to keep it four points from the left edge of the Default Item.
For the pop-up position when the menu is from a menu button, see MenuButton(3w).
Programmatic Menu Popup and Popdown
Four convenience routines are provided to programmatically control the mapping and unmapping of menus.
void OlMenuPopup(menu, emanate, item_index, state, set_position, x, y, position_proc)
Widget menu;
Widget emanate;
Cardinal item_index
OlDefine state;
Boolean set_position;
Position x;
Position y;
OlMenuPositionProc position_proc;
menuA menuShellWidget id obtained by creating a menu explicitly.
emanateThis field specifies the object that the menu is currently associated with and it is supplied to the position_proc when the menu positioning is done. If this field is NULL, the menu’s parent object is used as the emanate object for later positioning calculations.
item_indexIf emanate is a flattened widget this parameter specifies the particular item.
state
Range of values:
OL_PINNED_MENU
OL_PRESS_DRAG_MENU
OL_STAYUP_MENU
This specifies the state the menu should be in when it visibly appears on the screen.
set_positionA Flag indicating whether the following two arguments (x and y) are used to help position the menu. If the flag is NULL the current Pointer Location is used to initialize x and y.
x yThese coordinates are used by the positioning routine. Typically, these values represent the pointer with respect to the RootWindow. For example, xevent->xbutton.x_root and xevent->xbutton.y_root. However, if the menu’s state is OL_PINNED_MENU, these coordinates represent the desired upper-left hand corner of the pinned menu.
position_procProcedure called to determine the menu’s position if the menu’s state is either OL_PINNED_MENU or OL_STAYUP_MENU. If the menu’s state is OL_PINNED_MENU, the position_proc value is ignored. If this procedure is NULL, the default positioning routine (i.e., the one associated with the emanate widget or the menu’s parent) is used. The type of this procedure is:
void (∗OlMenuPositionProc)(menu, emanate, item_index, state, mx, my, px, py)
Widget menu;
Widget emanate;
Cardinal item_index
OlDefine state;
Position ∗ mx;
Position ∗ my;
Position ∗ px;
Position ∗ px;
menuMenuShellWidget id to be positioned.
emanateMenu’s emanate widget.
item_indexEmanate item_index or OL_NO_ITEM
statemenu’s state, either OL_PRESS_DRAG_MENU or OL_STAYUP_MENU
mxPointer containing the menu’s current x location. If the position routine wants to move the menu, it should change this value. The position routine should
myPointer containing the menu’s current y location. If the position routine wants to move the menu, it should change this value. The position routine should not move the menu explicitly.
pxRepresents the x location supplied to the OlMenuPopup routine. If the position routine changes this value, the pointer is warped to the new x location.
pyRepresents the y location supplied to the OlMenuPopup routine. If the position routine changes this value, the pointer is warped to the new y location.
void OlMenuPost(menu)
Widget menu;
A convenience routine that is equivalent to OlMenuPopup(menu, NULL, OL_STAYUP_MENU, FALSE, 0, 0, (OlMenuPositionProc)NULL).
void OlMenuPopdown(menu, dismiss_pinned)
Boolean dismiss_pinned;
This routine pops down a menu. If a menu is pinned, a value of TRUE for dismiss_pinned is required to dismiss it. If a menu does not have a pushpin or the menu is not pinned, the dismiss_pinned field is ignored.
void OlMenuUnpost(menu)
Widget menu;
A convenience routine that is equivalent to OlMenuPopdown(menu, FALSE).
Keyboard Traversal
Keyboard Traversal
By default, all menus will allow traversal among the traversable controls added to the widget.
Popping up a Menu via the keyboard is done by traversing to a MenuButton, using NEXT_FIELD, PREV_FIELD, MOVEUP, MOVEDOWN, MOVERIGHT, or LEFT, and pressing the MENUKEY key. If a menu is attached to a control other than a MenuButton, it can be popped up by traversing to that control and pressing the MENUKEY.
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:
—CANCEL dismisses the menu and returns focus to the originating control
—NEXTWINDOW moves to the next window in the application
—PREVWINDOW moves to the previous window in the applica
—NEXTAPP moves to the first window in the next application
—PREVAPP moves to the first window in the previous application
Keyboard Operation
If input focus is on a MenuButton within a Menu, pressing the MENUKEY will post the cascading menu associated with the MenuButton, and input focus will be on the first menu item with traversal enabled.
The DEFAULTACTION key will activate the default control in the MenuShell
widget as if the user clicked the SELECT button on the control.
The MENUDEFAULTKEY can be used by the user to change the default control in the Menu widget. When the user presses the MENUDEFAULTKEY, the control which has input focus will become the default control.
The TOGGLEPUSHPIN key changes the state of the pushpin in the window header. If the pushpin is in, TOGGLEPUSHPIN will pull the pin out and dismiss the window. If the pushpin is out, TOGGLEPUSHPIN will stick the pin in.
Table 1 MenuShell Activation Types
MenuShell Activation Types
_
Activation Type Expected Results
=
OL_CANCEL
Dismiss this menu and
_
OL_DEFAULTACTION
Calls OlActivateWidget for the
activation_type as OL_SELECTKEY.
_
OL_TOGGLEPUSHPIN
Same semantics as TOGGLEPUSHPIN
Selection Control
The MenuShell arranges for its children to respond to either the press-drag-release or the click-move-click type of selection.
With the press-drag-release type of control, the user keeps MENU pressed and moves the pointer to the item of choice; releasing MENU selects the Item and pops the menu down. If the pointer is not over an Item when MENU is released, the menu simply pops down.
With the click-move-click type of control, the user moves the pointer to the item of choice (MENU has already been released to end a click); clicking SELECT or MENU selects the item and pops the menu down. If the pointer is not over an item when SELECT or MENU is clicked, the menu simply pops down.
These selection methods apply to all menu items EXCEPT menu buttons. For example, in Locate Owner can be selected using the methods described here. For the other items in (which are menu buttons), see MenuButton(3W). for the explanation of menu button selection behavior.
Converting Stay-up to Pop-up Menu
Pressing MENU in a stay-up menu converts it to a pop-up menu. Thus the click-move-click selection control becomes a press-drag-release selection control.
Highlighting Items
In the press-drag-release type of selection control, each menu Item highlights while the pointer is over it. The form of the highlighting depends on the type of widget making up the item. Again, the MenuShell widget arranges for its children to respond in this way. No highlighting occurs when the click-move-click type of selection control is used.
Coloration
of the MenuShell widget.
Figure 3 Menu Coloration
Keyboard Traversal
keyboard traversal
By default, all menus will allow traversal among the traversable controls added to the widget.
Popping up a menu via the keyboard is done by traversing to a MenuButton, using NEXT_FIELD, PREV_FIELD, MOVEUP, MOVEDOWN, MOVERIGHT, or LEFT, and pressing the MENUKEY key. If a Menu is attached to a control besides a MenuButton, it can be popped up by traversing to that control and pressing the MENUKEY.
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:
—CANCEL dismisses the menu and returns focus to the originating control
—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
If input focus is on a MenuButton within a menu, pressing the MENUKEY will post the cascading menu associated with the MenuButton, and input focus will be on the first menu item with traversal enabled.
The DEFAULTACTION key will activate the default control in the Menu widget as if the user clicked the SELECT button on the control.
The MENUDEFAULTKEY can be used by the user to change the default control in the Menu widget. When the user presses the MENUDEFAULTKEY, the control which has input focus will become the default control.
The TOGGLEPUSHPIN key changes the state of the pushpin in the window header. If the pushpin is in, TOGGLEPUSHPIN will pull the pin out and dismiss the window. If the pushpin is out, TOGGLEPUSHPIN will stick the pin in.
Table 2 MenuShell Activation Types
MenuShell Activation Types
_
Activation Type Expected Results
=
OL_CANCEL
Dismiss this menu and
_
OL_DEFAULTACTION
Calls OlActivateWidget for the
activation_type as OL_SELECTKEY.
_
OL_TOGGLEPUSHPIN
Same semantics as TOGGLEPUSHPIN
RESOURCES
SUBSTRUCTURE
Menu Pane component
Table 3 MenuPane Resource Set
Menu Pane 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
XtNsameSize OlDefine OL_COLUMNS I
XtNvPad Dimension 4 I
XtNvSpace Dimension 4 I
Access:S = XtSetValues G = XtGetValues
I = init timeO = other access
† see resources(3W)
MenuPane
Table 4 Menu Components Resource Set
Menu Resource Set
Name Type Default Access
XtNallowShellResize Boolean TRUE SGI
XtNancestorSensitive Boolean TRUE G
XtNbackground Pixel XtDefaultBackground SGI
XtNbackgroundPixmap Pixmap (none) SGI
XtNconsumeEvent XtCallbackList NULL SGI
XtNcreatePopupChildProc XtCreatePopupChildProc NULL SGI
XtNdepth int (parent’s) GI
XtNdestroyCallback XtCallbackList NULL SI
XtNfocusWidget Widget NULL SGI
XtNheight Dimension (calculated) SGI
XtNheightInc int -1 SGI
XtNinput Boolean FALSE G
XtNmaxAspectX Position -1 SGI
XtNmaxAspectY Position -1 SGI
XtNmaxHeight Dimension OL_IGNORE SGI
XtNmaxWidth Dimension OL_IGNORE SGI
XtNmenuAugment Boolean TRUE GI
XtNmenuPane Widget (none) G
XtNminAspectX Position -1 SGI
XtNminAspectY Position -1 SGI
XtNminHeight Dimension OL_IGNORE SGI
XtNminWidth Dimension OL_IGNORE SGI
XtNpopdownCallback XtCallbackList NULL SI
XtNpopupCallback XtCallbackList NULL SI
XtNpushpin OlDefine OL_NONE GI
XtNpushpinDefault Boolean FALSE GI
XtNsaveUnder Boolean FALSE SGI
XtNsensitive Boolean TRUE GIO
XtNtitle String (widget’s name)
XtNuserData XtPointer NULL SGI
XtNwidth Dimension (calculated) SGI
XtNwidthInc int -1 SGI
Access:S = XtSetValues G = XtGetValues
I = init timeO = other access
† see resources(3W)
XtNfocusWidget
class:XtNfocusWidgettype:Widgetdefault:NULLNULL’u’access:SGISGI’u’
Action: This is the ID of the widget to get focus the next time this shell takes focus. Therefore, as a user traverses objects via the keyboard or explicitly sets focus to an object (e.g.clicking SELECT), the value of the XtNfocusWidget resource is updated to reflect this as the object with focus.
XtNmenuAugment
class:XtCMenuAugmenttype:Booleandefault:TRUETRUE’u’access:GIGI’u’
Action: determines who pops up the menu.
Values: TRUE – the Menu widget will augment its parent’s event handling so that the pressing or clicking of MENU automatically pops up the menu. FALSE – the application is responsible for detecting when the menu should be popped up, and for calling the routine OlMenuPost(menu_widget) to pop up the menu. This routine takes one argument, the widget ID returned when the menu was created.
XtNmenuPane
class:XtCMenuPanetype:Widgetdefault:(none)(none)’u’access:GG’u’
Action: gives the widget to which menu items are attached.
The value of this resource is available after the Menu widget has been created.
XtNpushpin
class:XtCPushpintype:OlDefinedefault:OL_NONEOL_NONE’u’access:GIGI’u’
Action: controls whether the Menu widget has a pushpin.
Values: OL_NONE – no pushpin will be included in the list of menu items, which means the user cannot pin the menu to keep it around. OL_OUT – a pushpin will be included as an item the user can select; if the end user selects the pushpin, the menu will be made into an OPEN LOOK window. Note that the pushpin item is always at the top of the menu list.
This resource is also available in other widgets, but with another allowed values, OL_IN, which is not allowed for the Menu widget.
XtNpushpinDefault
class:XtCPushpinDefaulttype:Booleandefault:FALSEFALSE’u’access:GIGI’u’
Action: determines whether pushpin is the default item.
Values: TRUE, FALSE
Note: If a menu has a pushpin and none of the menu pane items have been designated as the default, the pushpin automatically becomes the menu’s Default Item.
XtNtitle
class:XtCTitletype:Stringdefault:(widget’s name)(widget’s name)’u’access:SGISGI’u’
Action: gives the title of the Menu widget.
SEE ALSO
Version 3.0 — Last change: 19 July 91