'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olMenuShell @(#)olMenuShell	40.3 of 1/8/90
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ig
Modified by lmh 10/18/89 and 10/23/89
..
.ds cW MENU
.ds rW Menu
.ds nW Menu
.ds wW menu
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""MENU WIDGET" "" "\&"
.if \nX=1 .ds x} ""MENU WIDGET" ""
.if \nX=2 .ds x} ""MENU WIDGET" "" "\&"
.if \nX=3 .ds x} ""MENU "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
\*(bW\fBShell\fP
.SH "SYNOPSIS"
.nf
\s-1\f4#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <\*(nW.h>\f1\s+1\f1
.fi
.P
.nf
\s-1\f4static Widget menu, menupane, w;
.P
\s-1\f4Arg args[1];
.P
.nf
\s-1\f4menu = XtCreatePopupShell(\f2name\f4, \*(wWShellWidgetClass, ...);
XtSetArg(args[0], XtNmenuPane, &menupane);
XtGetValues(menu, args, 1);
.P
\s-1\f4w = XtCreateWidget(\f2name\f4, \f2widget-class\f4, menupane, ...);\s+1\f1
.fi
.SH "DESCRIPTION"
.sp
\f3Menu versus MenuButton\f1
.P
The \*(bW widget is used to create a menu not
associated with either a menu button or an abbreviated menu button.
For example, a \*(bW widget can be attached to a button, such as an
\f3OblongButton\f1
widget,
but this does not make the button into a menu button. 
However,
all the features of the \*(bW widget (except those related to
menu creation) also pertain to the MenuButton menu.
.sp
\f3\*(rW Components\f1
.P
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.
.P
The application chooses the label for the Title and whether a
menu has a Pushpin.
.sp
\f3Sub-class of the Shell Widget\f1
.P
The \*(bW widget is a sub-class of the
\f3Shell\f1
widget.
Therefore,
as the SYNOPSIS shows,
the
\f4XtCreatePopupShell()\f1
routine is used to create a menu instead of the normal
\f4XtCreateWidget()\f1.
.sp
\f3Menu Pane\f1
.P
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 \*(bW 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 \*(bW widget.
.bp
\f3Connecting a Menu to a Widget\f1
.P
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 \*(bW 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.
.sp
\f3Popup Control\f1
.P
Pressing MENU when the pointer is over the parent of the
\*(bW widget causes the menu to be popped up.
The menu is presented as a pop-up menu,
where the Items are available for a
\f2press-drag-release\f1
type of selection (see below).
Clicking MENU when the pointer is over the parent of the
\*(bW 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
\f2click-move-click\f1
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
\f2release\f1.
.sp
\f3Use of the Pushpin\f1
.P
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.
.sp
\fBThe Default Item\fP
.P
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.
.sp
\f3Components Shown when Popped Up\f1
.P
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.
.br
.ne3.5i
.BP PSART/ps.menu1
.P
.ce
\f3Figure 1.\f1  Menu Components
.sp
\f3Popup Position\f1
.P
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.
.P
For the pop-up position when the menu is from a menu button,
see \f3MENUBUTTON WIDGET/GADGET(3W)\f1.
.sp
\f3Press-Drag-Release vs Click-Move-Click Selection Control\f1
.P
The \*(bW 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.
.P
These selection methods apply to all menu items EXCEPT menu buttons.  For
example, in
Figure 1 above, \f(HBLocate Owner\f1 can be selected using the methods
described here.  For the other items in Figure 1 (which are menu 
buttons), see \f3MENUBUTTON 
WIDGET/GADGET(3W)\f1 for the explanation of menu button selection
behavior.
.sp
\f3Converting a Stay-up Menu to a Pop-up Menu\f1
.P
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.
.sp 0.75
\f3Highlighting of Menu Items\f1
.P
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 \*(bW widget arranges for its children to respond in this
way.
No highlighting occurs when the click-move-click type of
selection control is used.
.sp 0.75
\f3\*(rW Coloration\f1
.P
Figure 2 illustrates the resources that affect the coloration
of the \*(bW widget.
.br
.ne3.5i
.BP PSART/ps.menu2
.P
.ce
\f3Figure 2.\f1  Menu Coloration
.bp
.SH "SUBSTRUCTURE"
.P
\f3Menu Pane component\f1
.P
.TS H
expand, allbox;
cB s s s s.
Application Resources\\\\*(cO
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.TH
.ds cO " (cont'd)
.T&
lp-2 lp-2 lp-2 lp-2 lp-2.
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
.TE
.sp 
.SH "RESOURCES"
.TS H
allbox;
cB s s s s
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2
lp-2 lp-2 lp-2 lp-2 lp-2.
\*(bW Resource Set
Name	Class	Type	Default	Access
_
.TH
XtNallowShellResize	XtCAllowShellResize	Boolean	TRUE	SGI
XtNancestorSensitive	XtCSenstitive	Boolean	TRUE	G*
XtNbackground	XtCBackground	Pixel	White	SGI\(dg
XtNbackgroundPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNcreatePopupChildProc	XtCCreatePopupChildProc	XtCreatePopupChildProc	NULL	SGI
XtNdepth	XtCDepth	int	(parent's)	GI
XtNdestroyCallback	XtCCallback	XtCallbackList	NULL	SI
.ig
XtNgeometry	XtCGeometry	String	NULL	GI
..
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
.TE
.bp
.TS 
allbox;
cB s s s s
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2
lp-2 lp-2 lp-2 lp-2 lp-2.
\*(bW 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
.ig
XtNx	XtCPosition	Position	0	SGI
XtNy	XtCPosition	Position	0	SGI
..
.TE
\f3XtNmenuAugment\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
If this resource is
\f4TRUE\f1,
the \*(bW widget will augment its parent's event handling so
that the pressing or clicking of MENU automatically pops up the
menu.
If
\f4FALSE\f1,
the application is responsible for detecting when the menu
should be popped up,
and for calling the routine
\f4OlMenuPost(menu_widget)\f1
to pop up the menu.
This routine takes one argument,
the widget ID returned when the menu was created.
.sp
\f3XtNmenuPane\f1
.P
This is the widget where menu items can be attached;
its value is available once the \*(bW widget has been created.
.sp
\f3XtNpushpin\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4OL_NONE/"none"
OL_OUT/"out"\f1
.in -5
.fi
.PP
This resource controls whether the \*(bW widget has a pushpin.
If set to
\f4OL_NONE\f1,
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
\f4OL_OUT\f1,
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.
.P
(This resource is also available in other widgets,
but with three allowed values,
including
\f4OL_IN\f1.
This third value is not allowed for the \*(bW widget.)
.sp
\f3XtNpushpinDefault\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
Setting this resource to
\f4TRUE\f1
makes the Pushpin the Default
Item.
.P
\f(HBNote:\f1
.br
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.
.sp
\f3XtNtitle\f1
.P
This resource gives the Title of the \*(bW widget.
