'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olMenuButton @(#)olMenuButton	40.2 of 1/8/90
.SO BP.HEADER \" This header enables use of .BP macro for PostScript graphics
.ig
Modified by lmh 10/18/89
..
.ds cW MENUBUTTON
.ds rW MenuButton
.ds nW MenuButton
.ds wW menubutton
.ds bW \fB\*(rW\fP
.ds iW \fI\*(rW\fP
.ds oS \*(cW
.nr oN 0
.nr X
.if \nX=0 .ds x} ""MENUBUTTON WIDGET/GADGET" 3W "\&"
.if \nX=1 .ds x} ""MENUBUTTON WIDGET/GADGET" 3W
.if \nX=2 .ds x} ""MENUBUTTON WIDGET/GADGET" "" "\&"
.if \nX=3 .ds x} ""MENUBUTTON "" "" "\&"
.TH \*(x}
.SH "WIDGET CLASS NAME"
\*(bW
.SH "GADGET CLASS NAME"
\*(bW
.SH "SYNOPSIS"
.nf
\s-1\f4#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <\*(nW.h>\f1\s+1\f1
.fi
.nf
.P
\s-1\f4static Widget stack, menupane, w;
.P
\s-1\f4Arg args[1];
.P
\s-1\f4stack = XtCreateWidget(\f2name\f4, \*(wWWidgetClass, ...);
OR   stack = XtCreateWidget(\f2name\f4, \*(wWGadgetClass, ...);
XtSetArg(args[0], XtNmenuPane, &menupane);
XtGetValues(stack, args, 1);
.P
\s-1\f4w = XtCreateWidget(\f2name\f4, \f2widget-class\f4, menupane, ...);
.fi
.SH "DESCRIPTION"
The \*(bW widget provides the features of menu default
selection and menu previewing as well as the features of the
\f3Menu\f1
widget.
.sp
\f3\*(rW Components\f1
.P
Each menu button has the following parts:
.sp 
\(em  Label
.sp
\(em  Border
.br
.ne3i
.BP PSART/ps.button1
.P
.ce
\f3Figure 1.\f1  Menu Button 
.P
Each menu button also has the components of a
\f3Menu\f1
widget.
These are not shown in Figure 1.
.sp
\f3All Features of the Menu Widget\f1
.P
The \*(bW widget includes all the features of the
\f3Menu\f1
widget;
the features of that widget apply here.
.sp
\f3Selecting the Default Item\f1
.P
As an interface to a menu,
each \*(bW widget has a Default Item.
If the power-user option is on, this Default Item is selected 
by clicking SELECT over the \*(bW widget.
If the Default Item is inactive
(its
\f4XtNsensitive\f1
resource is
\f4FALSE\f1),
or busy
(its
\f4XtNbusy\f1
resource is
\f4TRUE\f1),
the system beeps.
(If the power-user option is off, clicking SELECT brings up a pop-up
menu.  The power-user option is set in the property sheet of the
Workspace Manager.  See the \f2AT&T OPEN LOOK\(tm GUI User's Guide\f1 for more
information on setting the power-user option.)
.P
Since the Default Item may be the \*(bW widget itself,
selecting it really selects
\f2its\f1
Default Item;
this recurses through the menu tree until a non-\*(bW widget is
found as the Default Item.
The Default Item may be the pushpin in a menu.
.P
If a pushpin is the Default Item,
the menu is brought up as a
\f2pinned menu\f1.
.sp
\f3Previewing the Default Item\f1
.P
If the menu button is not in a
\f2pop-up menu\f1 and the power-user option is on,
pressing SELECT,
or moving the
\f2pointer\f1
into the menu button while SELECT is pressed,
displays the
\f2highlighted\f1
label of the Default Item in place of the menu button's label.
Releasing SELECT restores the original colors and label,
and selects the Default Item as described above.
Moving the pointer off the menu button before releasing
also restores the original colors and label,
but does not select the Default Item. (If the power-user option is off,
pressing SELECT and releasing it displays a stayup menu.  See \f3Selecting
the Default Item\f1 above for comments about the power-user option.) 
.P
This Default Item is the one in the menu directly under the
menu button,
not necessarily the Default Item at the end of the menu tree,
that is activated when the Default Item is selected
(see above).
.sp
\f3Popping Up the Menu\(emNot in a Menu\f1
.P
When the \*(bW widget is in a control area,
pressing or clicking MENU when the pointer is within or
on the Border pops up the menu button's menu 
in the direction of the menu mark.
.sp
\f3Popping Up the Menu\(emAs a Menu Button in a Menu\f1
.P
When the \*(bW widget is in a
\f2stay-up menu\f1,
pressing or clicking MENU when the pointer is within or
on the Border pops up the menu button's menu 
in the direction of the menu mark.
When the \*(bW widget is in a pop-up menu,
moving the pointer into the menu mark region pops up the menu in the
direction of the menu mark.
The position is computed when the movement into the menu mark
region is first detected,
but rapid pointer motion and internal delays in popping up the
menu may let the pointer wander. 
.P
Moving the pointer out of the \*(bW widget, but not
directly into the newly popped up menu, causes that menu to be
popped down.
This occurs even if the pointer is moved into and out of the
newly popped up menu in the interim.
.sp
\f3Menu Placement When There is No Room\f1
.P
If the right or bottom edge of the screen is too close
to allow the menu placement described above,
the menu pops up aligned with the edge of the screen and the
pointer is shifted horizontally to keep it four points
from the left edge of the menu items.
If the left edge of the screen is too close,
the menu pops up four points from the edge and the
pointer is shifted to lie on the edge.
The pointer does not jump back after the menu is
dismissed.
.bp
\f3\*(rW Coloration\f1
.P
Figure 2 illustrates the resources that affect the coloration
of the \*(bW widget.
Events that occur outside the Border (but within the
\*(bW widget) are still in the domain of the menu button.
.br
.ne3.5i
.BP PSART/ps.button2
.P
.ce
\f3Figure 2.\f1  Menu Button Coloration
.P
.SH "SUBSTRUCTURE"
.sp
\f3Menu Component\f1
.P
.nf
Name: menu
Class: Menu
.fi
.ds cO
.TS
expand,allbox;
cB s s s s
l1Bp-2 l1Bp-2 l1Bp-2 l1Bp-2 l1Bp-2
l1p-2 l1p-2 l1p-2 l1p-2 l1p-2.
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
XtNpushpin	XtCPushpin	OlDefine	OL_NONE	I
XtNpushpinDefault	XtCPushpinDefault	Boolean	FALSE	I
*XtNsameSize	XtCSameSize	OlDefine	OL_COLUMNS	I
.TE
.bp
.TS
expand,allbox;
cB s s s s
l1Bp-2 l1Bp-2 l1Bp-2 l1Bp-2 l1Bp-2
l1p-2 l1p-2 l1p-2 l1p-2 l1p-2.
Application Resources (cont.)
Name	Class	Type	Default	Access
_
XtNtitle	XtCTitle	String	(widget's name)	I
*XtNvPad	XtCVPad	Dimension	4	I
*XtNvSpace	XtCVSpace	Dimension	4	I
.TE
.sp -0.5
\s-1* See the \f3Menu\f1 and \f3ControlArea\f1 widgets
for more information on these resources. \s+1
.sp
.SH "RESOURCES"
.ds cO
.TS 
expand,allbox;
cB s s s s.
\*(bW Resource Set\\\\*(cO
.T&
lBp-2 lBp-2 lBp-2 lBp-2 lBp-2.
Name	Class	Type	Default	Access
_
.ds cO " (cont'd)
.T&
lp-2 lp-2 lp-2 lp-2 lp-2.
XtNancestorSensitive	XtCAncestorSenstitive	Boolean	TRUE	G*
XtNbackground	XtCBackground	Pixel	White	SGI\(dg
\(dd XtNbackgroundPixmap	XtCPixmap	Pixmap	(none)	SGI\(dg
XtNdefault	XtCDefault	Boolean	FALSE	SGI
\(dd XtNdepth	XtCDepth	int	(parent's)	GI
XtNdestroyCallback	XtCCallback	XtCallbackList	NULL	SI
XtNfont	XtCFont	XFontStruct *	(OPEN LOOK font)	SI
XtNfontColor	XtCFontColor	Pixel	Black*	SGI
XtNforeground	XtCForeground	Pixel	Black	SGI\(dg
XtNheight	XtCHeight	Dimension	(calculated)	SGI
XtNlabel	XtCLabel	String	(class name)	SGI
XtNlabelJustify	XtCLabelJustify	OlDefine	OL_Left	SGI
\(dd XtNmappedWhenManaged	XtCMappedWhenManaged	Boolean	TRUE	SGI
XtNmenuMark	XtCMenuMark	OlDefine	(calculated)	SGI
XtNmenuPane	XtCMenuPane	Widget	(none)	G
XtNrecomputeSize	XtCRecomputeSize	Boolean	TRUE	SGI
XtNsensitive	XtCSensitive	Boolean	TRUE	GI*
XtNuserData	XtCUserData	XtPointer	NULL	SGI
XtNwidth	XtCWidth	Dimension	(calculated)	SGI
XtNx	XtCPosition	Position	0	SGI
XtNy	XtCPosition	Position	0	SGI
.TE
\s-1\(dd These resources are not available to \fBMenuButton\fP gadgets.\s+1
.sp
\f3XtNdefault\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
If this resource is
\f4TRUE\f1,
the Border is doubled to two lines
to show that the menu button contains the default choice of
several buttons.
.bp
\f3XtNfont\f1
.PP
Range of Values:
.br
.in +5
(any valid return from \f4XLoadQueryFont()\f1)
.in -5
.P
Default:
.br
.in +5
(chosen to match the scale and screen resolution)
.in -5
.PP
This resource identifies the font to be used to display the
Label.
.P
The default value points to a cached font structure;
an application should not expect to get this value with a call to
\f4XtGetValues()\f1
and use it reliably thereafter.
.sp
\f3XtNfontColor\f1
.PP
Range of Values:
.br
.in +5
(any \f4Pixel \f1value valid for the current display)/(any name from the \f4rgb.txt \f1file)
.in -5
.PP
This resource specifies the color for the font.
If not set,
the color from the
\f4XtNforeground\f1
resource,
if available,
is used for the font.
.P
See the note about the interaction of this resource with other
color resources under the description of the
\f4XtNbackground\f1
resource in \f3CORE RESOURCES(3W)\f1.
.sp
\f3XtNforeground\f1
.P
This resource defines the foreground color for the widget.
.P
See the note about the interaction of this resource with other
color resources under the description of the
\f4XtNbackground\f1
resource in \f3CORE RESOURCES(3W)\f1.
.sp
\f3XtNlabel\f1
.P
This resource is a pointer to the text for the Label of the
\*(bW widget.
.sp
\f3XtNlabelJustify\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4OL_LEFT/"left"
OL_CENTER/"center"\f1
.in -5
.fi
.PP
This resource dictates whether the Label should be 
left-justified or centered within the widget width.
.sp
\f3XtNmenuMark\f1
.P
Range of Values:
.br
.in +5
.nf
OL_DOWN
OL_RIGHT
.in -5
.fi
.P
This resource specifies the direction of the menu arrow.
.bp
\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
\f3XtNrecomputeSize\f1
.PP
Range of Values:
.br
.in +5
.nf
\f4TRUE
FALSE\f1
.in -5
.fi
.PP
This resource indicates whether the \*(bW widget should
calculate its size and automatically set the
\f4XtNheight\f1
and
\f4XtNwidth\f1
resources.
If set to
\f4TRUE\f1,
the \*(bW widget will do normal size calculations that may
cause its geometry to change.
If set to
\f4FALSE\f1,
the \*(bW widget will leave its size alone;
this may cause truncation of the visible image being shown by
the \*(bW widget if the fixed size is too small,
or may cause padding if the fixed size is too large.
The location of the padding is determined by the
\f4XtNlabelJustify\f1
resource.
.sp .5
\f3Label Appearance\f1
.P
The
\f4XtNwidth\f1,
\f4XtNheight\f1,
\f4XtNrecomputeSize\f1,
and
\f4XtNlabelJustify\f1
resources interact to produce a truncated, clipped, centered, or
left-justified label as shown in Figure 3.
.br
.bp
.ne2.5i
.BP PSART/ps.button3
.P
.ce
\f3Figure 3.\f1  Label Appearance
.sp
When the label is centered or left-justified,
the extra space is filled with the background color of the
\*(bW widget,
as determined by the
\f4XtNbackground\f1
and
\f4XtNbackgroundPixmap\f1
resources.
.P
When a text label is truncated,
the truncation occurs at a character boundary and a solid-white
triangle is inserted to show that part of the label is missing.
The triangle,
of course,
requires that more of the label be truncated than would
otherwise be necessary.
If the width of the button is too small to show even one
character with the triangle,
only the triangle is shown.
If the width is so small that the entire triangle cannot be
shown,
the triangle is clipped on the right.
