path: root/libXaw/spec/SimpleMenu

.\" $Xorg: SimpleMenu,v 1.3 2000/08/17 19:42:27 cpqbld Exp $
.NH 2
SimpleMenu Widget
.XS
	SimpleMenu Widget
.XE
.IN "SimpleMenu widget" "" "@DEF@"
.Ds 0
.TA 2.0i
.ta 2.0i
.sp
Application Header file	<X11/Xaw/SimpleMenu.h>
.IN "SimpleMenu.h" ""
Class Header file	<X11/Xaw/SimpleMenP.h>
.IN "SimpleMenP.h" ""
Class		simpleMenuWidgetClass
.IN "simpleMenuWidgetClass" ""
Class Name	SimpleMenu
.IN "SimpleMenu widget" "class name"
Superclass	OverrideShell
.sp
.De
.LP
The SimpleMenu widget is a container for the menu entries.  It is a
direct subclass of shell, and is should be created with
\fBXtCreatePopupShell\fP, not \fBXtCreateManagedWidget\fP.  This is the
only part of the menu that
actually is associated with a window.  The SimpleMenu serves as the glue to bind
the individual menu entries together into a menu.
.NH 3
Resources
.LP
.IN "SimpleMenu widget" "resources"
.LP
The resources associated with the SimpleMenu widget control aspects
that will affect the entire menu.
.TS H
lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
_
.sp 3p
.TB
Name	Class	Type	Notes	Default Value
.sp 3p
_
.TH
.R
.sp 3p
accelerators	Accelerators	AcceleratorTable		NULL
ancestorSensitive	AncestorSensitive	Boolean	D	True
allowShellResize	AllowShellResize	Boolean		True
background	Background	Pixel		XtDefaultBackground
backgroundPixmap	Pixmap	Pixmap		XtUnspecifiedPixmap
backingStore	BackingStore	BackingStore		see below
borderColor	BorderColor	Pixel		XtDefaultForeground
borderPixmap	Pixmap	Pixmap		XtUnspecifiedPixmap
borderWidth	BorderWidth	Dimension		1
bottomMargin	VerticalMargins	Dimension		0
children	ReadOnly	WidgetList	R	NULL
createPopupChildProc	CreatePopupChildProc	Function		NULL
colormap	Colormap	Colormap		Parent's Colormap
cursor	Cursor	Cursor		None
depth	Depth	int	C	Parent's Depth
destroyCallback	Callback	XtCallbackList		NULL
geometry	Geometry	String		NULL
height	Height	Dimension		Enough space to contain all entries
label	Label	String		NULL
labelClass	LabelClass	Pointer		SmeBSBObjectClass
mappedWhenManaged	MappedWhenManaged	Boolean		True
menuOnScreen	MenuOnScreen	Boolean		True
numChildren	ReadOnly	Cardinal	R	0
overrideRedirect	OverrideRedirect	Boolean		True
popdownCallback	Callback	XtCallbackList		NULL
popupCallback	Callback	XtCallbackList		NULL
popupOnEntry	PopupOnEntry	Widget	A	Label or first entry
rowHeight	RowHeight	Dimension		0
saveUnder	SaveUnder	Boolean		False
screen	Screen	Screen	R	Parent's Screen
sensitive	Sensitive	Boolean		True
topMargin	VerticalMargins	Dimension		0
translations	Translations	TranslationTable		See below
visual	Visual	Visual		CopyFromParent
width	Width	Dimension		Width of widest entry
x	Position	Position		0
y	Position	Position		0
.sp 3p
_
.TE
.Ac
.As
.IP \fBbackingStore\fP 1.5i
.IN "conversions" "BackingStore"
Determines what type of backing store will be used for the menu.  Legal
values for this resource are \fBNotUseful\fP, \fBWhenMapped\fP, and
\fBAlways\fP.  These values are the backing-store integers defined in
<X11/X.h>.
.Rs "notUseful, whenMapped, always, \fPand\fP default"
If \fBdefault\fP is specified (the default behavior) the server will use
whatever it thinks is appropriate.
.Bg
.Gp
.Bc
.Bp
.Bw
.IP \fBbottomMargin\fP 1.5i
.br
.ns
.IP \fBtopMargin\fP 1.5i
The amount of space between the top or bottom of the menu and the menu entry
closest to that edge.
.Ch
.Cm
.IP \fBcursor\fP 1.5i
The shape of the mouse pointer whenever it is in this widget.
.Dp
.Dc
.IP geometry 1.5i
If this resource is specified it will override the x, y, width and
height of this widget.  The format of this string is
[<\fIwidth\fP>x<\fIheight\fP>][{+ -} <\fIxoffset\fP> {+ -}<\fIyoffset\fP>].
.Hw
.IP \fBlabel\fP 1.5i
This label will be placed at the top of the SimpleMenu, and may not be
highlighted.  The name of the
label object is \fBmenuLabel\fP.  Using this name it is possible to
modify the label's attributes through the resource database.  When the label
is created, the \fBlabel\fP is hard coded to the value of \fBlabel\fP, and
\fBjustify\fP is hard coded as \fBXtJustifyCenter\fP.
.IP \fBlabelClass\fP 1.5i
Specifies the type of Sme object created as the menu label.
.Mm
.IP \fBmenuOnScreen\fP 1.5i
If the menu is automatically positioned under the cursor with the
\fBXawPositionSimpleMenu\fP action, and this resource is \fBTrue\fP,
then the menu will always be fully visible on the screen.
.Nc
.IP overrideRedirect 1.5i
Determines the value of the override_redirect attribute of the
SimpleMenu's window.  The override_redirect attribute of a window
determines whether or not a window manager may interpose itself between
this window and the root window of the display.  For more information
see the \fIInterclient Communications Conventions Manual\fP.
.IP popdownCallback 1.5i
.br
.ns
.IP popupCallback 1.5i
These callback functions are called by the Xt Intrinsics whenever the
shell is popped up or down (See \fI\*(xT\fP for details).
.IP \fBpopupOnEntry\fP 1.5i
The \fBXawPositionSimpleMenu\fP action will, by default, popup the
SimpleMenu with its label (or first entry) directly under the
pointer.  To popup the menu under
another entry, set this resource to the menu entry that should be
under the pointer, when the menu is popped up.  This allows the
application to offer the user a default menu entry that can be selected
with out moving the pointer.
.IP \fBrowHeight\fP 1.5i
If this resources is zero (the default) then each menu entry will be
given its desired height.  If this resource has any other value then
all menu entries will be forced to be \fBrowHeight\fP pixels high.
.IP saveUnder 1.5i
If this is \fBTrue\fP then save unders will be active on the menu's window.
.Sc
.Se
.Tr
.Xy
.NH 3
SimpleMenu Actions
.IN "SimpleMenu widget" "actions"
.LP
The SimpleMenu widget supports the following actions:
.IP \(bu 5
Switching the entry under the mouse pointer between
the foreground and background colors with \fBhighlight\fP
and \fBunhighlight\fP
.IP \(bu 5
Processing menu entry callbacks with \fBnotify\fP
.sp
.LP
.IN "SimpleMenu widget" "default translations"
The following are the default translation bindings used
by the SimpleMenu widget:
.LP
.sp
.Ds 0
.TA .5i 2.25i
.ta .5i 2.25i
	<EnterWindow>:	highlight(\|)
	<LeaveWindow>:	unhighlight(\|)
	<BtnMotion>:	highlight(\|)
	<BtnUp>:	MenuPopdown(\|) notify(\|) unhighlight(\|)
.De
.sp
.LP
.IN "SimpleMenu widget" "MenuPopdown routine"
The user can pop down the menu without activating any of the callback
functions by releasing the pointer button when no menu item is
highlighted.
.sp
.LP
The full list of actions supported by SimpleMenu is:
.IP \fBhighlight\fP() 1.5i
Highlight the menu entry that is currently under the pointer.
Only a item that is highlighted will be notified when the \fBnotify\fP
action is invoked.  The look of a highlighted entry is determined by
the menu entry.
.IP \fBunhighlight\fP(\|) 1.5i
Unhighlights the currently highlighted menu item, and returns it to
its normal look.
.IP \fBnotify\fP(\|) 1.5i
Notifies the menu entry that is currently highlighted that is has been
selected.  It is the responsibility of the menu entry to take the
appropriate action.
.IP \fBMenuPopdown\fP(\fImenu\fP)
This action is defined in \fI\*(xT\fP.
.IN "SimpleMenu widget" "MenuPopdown routine"
.NH 3
Positioning the SimpleMenu
.IN "XawPositionSimpleMenu" "" "@DEF@"
.IN "SimpleMenu widget" "positioning" "@DEF@"
.LP
If the SimpleMenu widget is to be used as a pulldown menu then the
MenuButton widget, or some other outside means should be used to place
the menu when it is popped up.
.LP
If popup menus are desired it will be necessary to add the
\fBXawPositionSimpleMenu\fP and \fBMenuPopup\fP actions to the
translation table of the widget that will be popping up the menu.  The
\fBMenuPopup\fP action is described in \fI\*(xT\fP.
\fBXawPositionSimpleMenu\fP is a global action procedure registered by
the SimpleMenu widget when the first one is created or the convenience
routine \fBXawSimpleMenuAddGlobalActions\fP is called.
.LP
Translation writers should be aware that Xt does not register grabs on
``don't care'' modifiers, and therefore the left hand side of the
production should be written to exclude unspecified modifiers.
For example these are the translations needed to popup some of
\fBxterm's\fP menus:
.sp
.LP
.Ds 0
.TA .5i 2.25i
.ta .5i 2.25i
	!Ctrl<Btn1Down>: XawPositionSimpleMenu(xterm) MenuPopup(xterm)
	!Ctrl<Btn2Down>: XawPositionSimpleMenu(modes) MenuPopup(modes)
.De
.sp 1
.LP
.IP \fBXawPositionSimpleMenu\fP(\fImenu\fP) 2.25i
The \fBXawPositionSimpleMenu\fP routine will search for the menu name
passed to it using \fBXtNameToWidget\fP starting with the widget
invoking the action as the reference widget.  If it is unsuccessful it
will continue up the widget tree using each of the invoking widget's
ancestors as the reference widget.  If it is still unsuccessful it will
print a warning message and give up.  \fBXawPositionSimpleMenu\fP will
position the menu directly under the pointer cursor.  The menu will be
placed so that the pointer cursor is centered on the entry named by the
\fBpopupOnEntry\fP resource.  If the \fBmenuOnScreen\fP resource is
\fBTrue\fP then the menu will always be fully visible on the screen.
.NH 3
Convenience Routines
.NH 4
Registering the Global Action Routines
.LP
.IN "XawPositionSimpleMenu" ""
The \fBXawPositionSimpleMenu\fP action routine may often be invoked
before any menus have been created.  This can occur when an
application uses dynamic menu creation.  In these cases an application will
need to register this global action routine by calling
\fBXawSimpleMenuAddGlobalActions\fP:
.IN "XawSimpleMenuAddGlobalActions" "" "@DEF@"
.FD 0
void XawSimpleMenuAddGlobalActions(\fIapp_con\fP)
.br
      XtAppContext \fIapp_con\fP;
.FN
.IP \fIapp_con\fP 1i
Specifies the application context in which this action should be registered.
.LP
This function need only be called once per application and must be
called before any widget that uses \fBXawPositionSimpleMenu\fP action
is realized.
.NH 4
Getting and Clearing the Current Menu Entry
.LP
To get the currently highlighted menu entry use
\fBXawSimpleMenuGetActiveEntry\fP:
.IN "XawSimpleMenuGetActiveEntry" "" "@DEF@"
.FD 0
Widget XawSimpleMenuGetActiveEntry(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the SimpleMenu widget.
.LP
This function returns the menu entry that is
currently highlighted, or NULL if no entry is highlighted.
.LP
.sp
To clear the SimpleMenu widget's internal information about the
currently highlighted menu entry use
\fBXawSimpleMenuClearActiveEntry\fP:
.IN "XawSimpleMenuClearActiveEntry" "" "@DEF@"
.FD 0
Widget XawSimpleMenuClearActiveEntry(\fIw\fP)
.br
      Widget \fIw\fP;
.FN
.IP \fIw\fP 1i
Specifies the SimpleMenu widget.
.LP
This function unsets all internal references to the currently
highlighted menu entry.  It does not \fIunhighlight\fP or otherwise
alter the appearance of the active entry.  This function is primarily
for use by implementors of menu entries.