Manual pages › OPEN LOOK widgets (3W)
olMenuShell(3W)
MenuShell
From the original Amiga UNIX 2.1 manual. Some things it mentions may not be in this release.
WIDGET CLASS NAME · SYNOPSIS · DESCRIPTION · SUBSTRUCTURE
WIDGET CLASS NAME
MenuShell
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
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. 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.
Amiga Unix Last change: 1
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.
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.
Amiga Unix Last change: 2
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 WIDGET/GADGET(3W).
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-moveclick 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 WIDGET/GADGET(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-dragrelease selection control.
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 selec-
tion control is used.
Menu Coloration Figure 2 illustrates the resources that
affect the coloration of the Menu widget.
Amiga Unix Last change: 3
Figure 2. Menu Coloration
Amiga Unix Last change: 4
SUBSTRUCTURE
Menu Pane component
___________________________________________________________________
____________________Application_Resources\*(cO_____________________
Name Class Type Default Access
___________________________________________________________________
Amiga Unix Last change: 5
() MISC. REFERENCE MANUAL PAGES ()
___________________________________________________________________
_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_____|
| XtNvSpace | XtCVSpace | Dimension| 4 | I |
|______________|_______________|___________|______________|________|
RESOURCES________________________________________________________________________________________________
Menu Resource Set
____________________________________________________________________________________________________
_Name______________________Class_____________________Type_____________________Default________Access_
Amiga Unix Last change: 1
() MISC. REFERENCE MANUAL PAGES ()
____________________________________________________________________________________________________
_XtNallowShellResize_______XtCAllowShellResize_______Boolean__________________TRUE___________SGI____
XtNancestorSensitive XtCSenstitive Boolean TRUE G*
____________________________________________________________________________________________________
_XtNbackground_____________XtCBackground_____________Pixel____________________White__________SGI-___
XtNbackgroundPixmap XtCPixmap Pixmap (none) SGI-
____________________________________________________________________________________________________
_XtNcreatePopupChildProc___XtCCreatePopupChildProc___XtCreatePopupChildProc___NULL___________SGI____
XtNdepth XtCDepth int (parent's) GI
____________________________________________________________________________________________________
_XtNdestroyCallback________XtCCallback_______________XtCallbackList___________NULL___________SI_____
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 |
|________________________|_________________________|________________________|______________|________|
|_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____|
Amiga Unix Last change: 1
() MISC. REFERENCE MANUAL PAGES ()
______________________________________________________________________________
|______________________________Menu_Resource_Set______________________________|
| Name | Class | Type | Default | Access|
|__________________|___________________|___________|_________________|________|
| 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 |
|__________________|___________________|___________|_________________|________|
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 the menu. If 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 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:
OL_NONE/"none"
OL_OUT/"out"
This resource controls whether the Menu widget has a pushpin. If set to 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. If set to 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 three allowed values, including OL_IN. This third value is not allowed for the Menu widget.)
XtNpushpinDefault
Amiga Unix Last change: 2
() MISC. REFERENCE MANUAL PAGES ()
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.
Amiga Unix Last change: 3