diff options
Diffstat (limited to 'libXaw/spec/SimpleMenu')
| -rw-r--r-- | libXaw/spec/SimpleMenu | 315 |
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. |