Added libXaw

1 files changed, 315 insertions, 0 deletions

diff --git a/libXaw/spec/SimpleMenu b/libXaw/spec/SimpleMenu
new file mode 100644
index 000000000..b59e511c8
--- /dev/null
+++ b/libXaw/spec/SimpleMenu
@@ -0,0 +1,315 @@
+.\" $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.