MENU WIDGET() MISC. REFERENCE MANUAL PAGES MENU WIDGET()
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 abbrevi-
ated 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
MENU WIDGET() MISC. REFERENCE MANUAL PAGES 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 visu-
ally 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 indis-
tinguishably 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
MENU WIDGET() MISC. REFERENCE MANUAL PAGES MENU WIDGET()
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 place-
ment, the menu pops up with the Drop Shadow aligned with the
edge of the screen, and the mouse pointer is shifted hor-
izontally 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 selec-
tion. 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 but-
tons. 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 selec-
tion 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.
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
MENU WIDGET() MISC. REFERENCE MANUAL PAGES MENU WIDGET()
Figure 2. Menu Coloration
Amiga Unix Last change: 4
MENU WIDGET() MISC. REFERENCE MANUAL PAGES MENU WIDGET()
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_____________|__OLIGNORE___|__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_____________|__OLIGNORE___|__SGI___|
| XtNminWidth | XtCMinWidth | Dimension | OL_IGNORE | SGI |
|________________________|_________________________|________________________|______________|________|
|_XtNpopdownCallback_____|__XtCCallback____________|__XtCallbackList________|__NULL________|__SI____|
| XtNpopupCallback | XtCCallback | XtCallbackList | NULL | SI |
|________________________|_________________________|________________________|______________|________|
|_XtNpushpin_____________|__XtCPushpin_____________|__OlDefine______________|__OLNONE_____|__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 applica-
tion is responsible for detecting when the menu should be
popped up, and for calling the routine
OlMenuPost(menuwidget) 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:
OLNONE/"none"
OLOUT/"out"
This resource controls whether the Menu widget has a push-
pin. 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
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