MenuShell UNIX System V MenuShell
NAME
MenuShell - used to create a menu not associated with a menu button
SYNOPSIS
#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <Menu.h>
static Widget menu, menupane, w;
Arg args[1];
menu = XtCreatePopupShell(name, menuShellWidgetClass, ...);
XtSetArg(args[0], XtNmenuPane, &menupane);
XtGetValues(menu, args, 1);
w = XtCreateWidget(name, widget-class, menupane, ...);
DESCRIPTION
___________________________________________________
| Default Window Decorations |
|__________________|________________|______________|
| Resource | Type | Default|
|__________________|________________|______________|
|__________________|________________|______________|
| XtNmenuButton | Boolean | FALSE |
|__________________|________________|______________|
| XtNpushpin | OlDefine | OL_NONE|
|__________________|________________|______________|
| XtNresizeCorners | Boolean | FALSE |
|__________________|________________|______________|
| XtNwindowHeader | Boolean | TRUE |
|__________________|________________|______________|
Menu versus MenuButton
The Menu widget is used to create a menu not associated with either a
menu button or an abbreviated menu button. 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.
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. See Figure 1.
10/89 Page 1
MenuShell UNIX System V MenuShell
The application chooses the label for the Title and whether a menu has a
Pushpin.
Sub-class of the Shell Widget
The Menu widget is a sub-class of the Shell widget. Therefore, as the
SYNOPSIS shows, the XtCreatePopupShell() routine is used to create a menu
instead of the normal XtCreateWidget().
Menu Pane
The Menu Pane is not described as a separate widget in these
requirements; 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 Menu 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.
Connecting a Menu to a Widget
A menu can be connected to 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 Menu 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.
Page 2 10/89
MenuShell UNIX System V MenuShell
Components Shown when Popped Up
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 1. Menu 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 itemindex
OlDefine state;
Boolean setposition;
Position x;
Position y;
OlMenuPositionProc positionproc;
menu A menuShellWidget id obtained by creating a menu explicitly.
emanate This 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_index
If emanate is a flattened widget this parameter specifies the
particular item.
state
Range of values:
OLPINNEDMENU
OLPRESSDRAGMENU
OLSTAYUPMENU
This specifies the state the menu should be in when it visibly
appears on the screen.
10/89 Page 3
MenuShell UNIX System V MenuShell
set_position
A 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 y These coordinates are used by the positioning routine.
Typically, these values represent the pointer with respect to
the RootWindow. For example, xevent->xbutton.xroot and
xevent->xbutton.yroot. However, if the menu's state is
OL_PINNED_MENU, these coordinates represent the desired upper-
left hand corner of the pinned menu.
position_proc
Procedure 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 itemindex
OlDefine state;
Position *, mx;
Position *, my;
Position *, px;
Position *, px;
menu MenuShellWidget id to be positioned.
emanate Menu's emanate widget.
item_index
Emanate item_index or OL_NO_ITEM
state menu's state, either OL_PRESS_DRAG_MENU or OL_STAYUP_MENU
mx Pointer 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
my Pointer 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.
Page 4 10/89
MenuShell UNIX System V MenuShell
px Represents the x location supplied to the OlMenuPopup routine.
If the position routine changes this value, the pointer is
warped to the new x location.
py Represents 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,
OLSTAYUPMENU, FALSE, 0, 0, (OlMenuPositionProc)NULL.
void OlMenuPopdown(menu, dismiss_pinned)
Widget menu;
Boolean dismisspinned;
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).
Press-Drag-Release vs Click-Move-Click Selection Control
The Menu 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 Figure 1 above, Locate Owner can be selected using the
methods described here. For the other items in Figure 1 (which are menu
buttons), see MenuButton (3W) for the explanation of menu button
selection behavior.
Converting a Stay-up Menu to a 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.
10/89 Page 5
MenuShell UNIX System V MenuShell
Highlighting of Menu 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 Menu widget
arranges for its children to respond in this way. No highlighting occurs
when the click-move-click type of selection control is used.
Menu Coloration
Figure 2 illustrates the resources that affect the coloration of the Menu
widget.
Figure 2. Menu Coloration
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 with in 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.
Page 6 10/89
MenuShell UNIX System V MenuShell
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.
___________________________________________________
| MenuShell Activation Types |
|_________________|________________________________|
| Activation Type | Expected Results |
|||
| OL_CANCEL | Dismiss this menu and any |
| | other menus cascading off of |
| | it. |
|_________________|________________________________|
| OL_DEFAULTACTION| Calls OlActivateWidget for the|
| | default item with the |
| | activation_type as |
| | OL_SELECTKEY. |
|_________________|________________________________|
| OL_TOGGLEPUSHPIN| Same semantics as |
| | TOGGLEPUSHPIN above. |
|_________________|________________________________|
SUBSTRUCTURE
Menu Pane component
____________________________________________________________________
| 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
____________________________________________________________________
XtNsameSize XtCSameSize OlDefine OL_COLUMNS I
____________________________________________________________________
XtNvPad XtCVPad Dimension 4 I
10/89 Page 7
MenuShell UNIX System V MenuShell
____________________________________________________________________
| Application Resources |
|______________|_______________|___________|______________|_________|
| Name | Class | Type | Default | Access |
|______________|_______________|___________|______________|_________|
|______________|_______________|___________|______________|_________|
| XtNvSpace | XtCVSpace | Dimension| 4 | I |
|______________|_______________|___________|______________|_________|
RESOURCES
_______________________________________________________________________________________________
| Menu Resource Set |
|_______________________|_______________________|______________________|_______________|_______|
| Name | Class | Type | Default | Access|
|_______________________|_______________________|______________________|_______________|_______|
_______________________________________________________________________________________________
XtNallowShellResize XtCAllowShellResize Boolean TRUE SGI
_______________________________________________________________________________________________
XtNancestorSensitive XtCSenstitive Boolean TRUE G*
_______________________________________________________________________________________________
XtNbackground XtCBackground Pixel White SGI†
_______________________________________________________________________________________________
XtNbackgroundPixmap XtCPixmap Pixmap (none) SGI†
_______________________________________________________________________________________________
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SGI
_______________________________________________________________________________________________
XtNcreatePopupChildProc XtCCreatePopupChildProc XtCreatePopupChildProc NULL SGI
_______________________________________________________________________________________________
XtNdepth XtCDepth int (parent's) GI
_______________________________________________________________________________________________
XtNdestroyCallback XtCCallback XtCallbackList NULL SI
_______________________________________________________________________________________________
XtNfocusWidget XtCFocusWidget Widget NULL SGI
_______________________________________________________________________________________________
XtNheight XtCHeight Dimension (calculated) SGI
_______________________________________________________________________________________________
XtNheightInc XtCHeightInc int -1 SGI
_______________________________________________________________________________________________
XtNinput XtCInput Boolean FALSE G
_______________________________________________________________________________________________
XtNmaxAspectX XtCMaxAspectX Position -1 SGI
_______________________________________________________________________________________________
XtNmaxAspectY XtCMaxAspectY Position -1 SGI
_______________________________________________________________________________________________
XtNmaxHeight XtCMaxHeight Dimension OL_IGNORE SGI
_______________________________________________________________________________________________
XtNmaxWidth XtCMaxWidth Dimension OL_IGNORE SGI
_______________________________________________________________________________________________
XtNmenuAugment XtCMenuAugment Boolean TRUE GI
_______________________________________________________________________________________________
XtNmenuPane XtCMenuPane Widget (none) G
_______________________________________________________________________________________________
Page 8 10/89
MenuShell UNIX System V MenuShell
_______________________________________________________________________________________________
| Menu Resource Set |
|_______________________|_______________________|______________________|_______________|_______|
| Name | Class | Type | Default | Access|
|_______________________|_______________________|______________________|_______________|_______|
| XtNminAspectX | XtCMinAspectX | Position | -1 | SGI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNminAspectY | XtCMinAspectY | Position | -1 | SGI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNminHeight | XtCMinHeight | Dimension | OL_IGNORE | SGI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNminWidth | XtCMinWidth | Dimension | OL_IGNORE | SGI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNpopdownCallback | XtCCallback | XtCallbackList | NULL | SI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNpopupCallback | XtCCallback | XtCallbackList | NULL | SI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNpushpin | XtCPushpin | OlDefine | OL_NONE | GI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNpushpinDefault | XtCPushpinDefault | Boolean | FALSE | GI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNsaveUnder | XtCSaveUnder | Boolean | FALSE | SGI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI* |
|_______________________|_______________________|______________________|_______________|_______|
| XtNtitle | XtCTitle | String | (widget's name)
| SGI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNuserData | XtCUserData | XtPointer | NULL | SGI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNwidth | XtCWidth | Dimension | (calculated) | SGI |
|_______________________|_______________________|______________________|_______________|_______|
| XtNwidthInc | XtCWidthInc | int | -1 | SGI |
|_______________________|_______________________|______________________|_______________|_______|
XtNfocusWidget
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
Range of Values:
TRUE
FALSE
If this resource is TRUE, the Menu widget will augment its parent's event
handling so that the pressing or clicking of MENU automatically pops up
10/89 Page 9
MenuShell UNIX System V MenuShell
the menu. If FALSE, the application is responsible for detecting when
the menu should be popped up. (Please see the earlier section on
"Programmatic Menu Popup and Popdown.")
XtNmenuPane
This is the widget where menu items can be attached; its value is
available once the Menu widget has been created.
XtNpushpin
Range of Values:
OLNONE/"none"
OLOUT/"out"
This resource controls whether the Menu widget has a pushpin. If set to
OLNONE, no pushpin will be included in the list of menu items, which
means the user cannot pin the menu to keep it around. If set to OLOUT,
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 three allowed
values, including OLIN. This third value is not allowed for the Menu
widget.)
XtNpushpinDefault
Range of Values:
TRUE
FALSE
Setting this resource to TRUE makes the Pushpin the Default Item.
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
This resource gives the Title of the Menu widget.
Page 10 10/89