NAME
SimpleMenu widget − menu container widget.
SYNOPSIS
Public Headers:<X11/StringDefs.h> <X11/Xaw/SimpleMenu.h>
Private Header:<X11/Xaw/SimpleMenP.h>
Class Name:SimpleMenu
Class Pointer:simpleMenuWidgetClass
Instantiation:widget = XtCreatePopupShell(name, simpleMenuWidgetClass,...);
CLASS HIERARCHY
Core → Composite → Shell → OverrideShell → SimpleMenu
DESCRIPTION
The SimpleMenu widget is a container for menu entries. It is a direct subclass of shell, and is usually created with XtCreatePopupShell(). This is the only part of the menu that actually contains a window, since each menu pane is a gadget. SimpleMenu "glues" the individual menu entries together into one menu.
RESOURCES
The resources associated with the SimpleMenu widget control aspects that will affect the entire menu.
| Name (XtN...) | Class Type | Default | Description | |||
| XtNaccelerators | AcceleratorTable | NULL | List of event-to-action bindings to be executed by this widget, even though the event occurred in another widget. | |||
| XtNancestor− Sensitive |
Boolean | True | (D) Sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive. | |||
| XtNallowShellResize | Boolean | True | Whether the menu can be resized. | |||
| XtNbackground | Pixel | XtDefault− Background |
Window background color. | |||
| XtNbackground− Pixmap |
Pixmap | XtUnspecified− Pixmap |
Window background pixmap. | |||
| XtNbackingStore | BackingStore | See below. | See below. | |||
| XtNborderColor | Pixel | XtDefault− Foreground |
Window border color. | |||
| XtNborderPixmap | Pixmap | XtUnspecified− Pixmap |
Window border pixmap. | |||
| XtNborderWidth | Dimension | 1 | Width of button border. | |||
| XtNbottomMargin | Dimension | 0 | See below. | |||
| XtNchildren | WidgetList | NULL | (R) List of all this composite widget’s current children. | |||
| XtNcreatePopup− | ||||||
| ChildProc | Function | NULL | Procedure to call after the menu pops up. | |||
| XtNcolormap | Colormap | Parent’s colormap. | Colormap that this widget will use. | |||
| XtNcursor | Cursor | None | Pointer cursor. | |||
| XtNdepth | int | Parent’s depth. | (C) Depth of this widget’s window. | |||
| XtNdestroy− Callback |
XtCallbackList | NULL | Callbacks for XtDestroyWidget(). | |||
| XtNgeometry | String | NULL | Geometry specification for menu. | |||
| XtNheight | Dimension | Enough space for all entries. | Menu height. | |||
| XtNlabel | String | Name of widget. | See below. | |||
| XtNlabelClass | Pointer | SmeBSBObjectClass | See below. | |||
| XtNmappedWhen− Managed |
Boolean | True | Whether XtMapWidget() is automatic. | |||
| XtNmenuOnScreen | Boolean | True | See below. | |||
| XtNnumChildren | Cardinal | 0 | (R) The number of children in this composite widget. | |||
| XtNoverrideRedirect | Boolean | True | See below. | |||
| XtNpopdownCallback | Callback | NULL | See below. | |||
| XtNpopupCallback | Callback | NULL | See below. | |||
| XtNpopupOnEntry | Widget | Label (or first entry) | (A) See below. | |||
| XtNrowHeight | Dimension | 0 | See below. | |||
| XtNsaveUnder | Boolean | False | See below. | |||
| XtNscreen | Screen | Parent’s screen. | (R) Screen on which this widget is displayed. | |||
| XtNsensitive | Boolean | True | Whether widget receives input. | |||
| XtNtopMargin | Dimension | 0 | See below. | |||
| XtNtranslations | TranslationTable | NULL | Event-to-action translations. | |||
| XtNvisual | Visual | CopyFromParent | Visual type. | |||
| XtNwidth | Dimension | Width of widest entry. | Menu width. | |||
| XtNx | Position | 0 | x-coordinate in pixels. | |||
| XtNy | Position | 0 | y-coordinate in pixels. | |||
XtNbackingStore
Determines what type of backing store will be used for the menu. Legal values for this resource are NotUseful, WhenMapped, and Always. These values are the backing-store integers defined in <X11/X.h>.
If default is specified (the default behavior) the server will use whatever it thinks is appropriate.
XtNbottomMargin
XtNtopMargin
The amount of space between the top or bottom of the menu and the menu entry closest to that edge.
XtNcursor
The shape of the mouse pointer whenever it is in this widget.
XtNgeometry
If this resource is specified, it overrides the x, y, width and height of this widget. The format of this string is [<width>x<height>][{+ -} <xoffset> {+ -}<yoffset>].
XtNlabel
This label will be placed at the top of the SimpleMenu and cannot be highlighted. The name of the label object is menuLabel. Using this name, it is possible to modify the label’s attributes through the resource database. When the label is created, the XtNlabel is hard-coded to the value of XtNlabel, and XtNjustify is hard-coded as XtJustifyCenter.
XtNlabelClass
Specifies the type of Sme object created as the menu label.
XtNmenuOnScreen
If the menu is automatically positioned under the cursor with the XawPositionSimpleMenu action, and if this resource is True, then the menu is always fully visible on the screen.
XtNoverrideRedirect
Determines the value of the override_redirect attribute of the SimpleMenu’s window. The override_redirect attribute of a window determines whether a window manager may interpose itself between this window and the root window of the display. For more information, see the Inter-Client Communications Conventions Manual.
XtNpopdownCallback
XtNpopupCallback
These callback functions are called by the Xt Intrinsics whenever the shell is popped up or down. (See X Toolkit Intrinsics − C Language Interface for details.)
XtNpopupOnEntry
The XawPositionSimpleMenu action pops up the SimpleMenu with its label (or first entry) directly under the pointer, by default. To pop up 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 without moving the pointer.
XtNrowHeight
If this resource is 0 (the default), then each menu entry is given its desired height. If this resource has any other value, then all menu entries are forced to be XtNrowHeight pixels high.
XtNsaveUnder
If this is True, then save unders will be active on the menu’s window.
TRANSLATIONS AND ACTIONS
The following default translation bindings are used by the SimpleMenu widget: <EnterWindow>: highlight() <LeaveWindow>: unhighlight() <BtnMotion>: highlight() <BtnUp>: MenuPopdown() notify() unhighlight() With these bindings, 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.
The SimpleMenu widget supports the following actions:
•Switching the entry under the mouse pointer between the foreground and background colors with highlight and unhighlight.
•Processing menu entry callbacks with notify.
The actions supported by SimpleMenu are listed below:
highlight()
Highlights the menu entry that is currently under the pointer. Only an item that is highlighted is notified when the notify action is invoked. The look of a highlighted entry is determined by the menu entry.
unhighlight()
Unhighlights the currently highlighted menu item and returns it to its normal look.
notify()
Notifies the currently highlighted menu entry that it has been selected. It is the responsibility of the menu entry to take the appropriate action.
MenuPopdown(menu)
Built-in action to pop down a menu widget.
POSITIONING THE SIMPLEMENU
If the SimpleMenu widget is to be used as a pulldown menu, then either the MenuButton widget or some other outside means should be used to place the menu when it is popped up.
If popup menus are desired you must add the XawPositionSimpleMenu and XtMenuPopup() actions to the translation table of the widget that will be popping up the menu. XawPositionSimpleMenu is a global action procedure. It is registered by the SimpleMenu widget either when the first such action is created or when the convenience routine XawSimpleMenuAddGlobalActions() is called.
For example, these are the translations needed to pop up some of xterm’s menus: !Ctrl<Btn1Down>: XawPositionSimpleMenu(xterm) XtMenuPopup(xterm) !Ctrl<Btn2Down>: XawPositionSimpleMenu(modes) XtMenuPopup(modes) Note that the ! excludes unspecified modifiers.
XawPositionSimpleMenu(menu)
The XawPositionSimpleMenu routine searches for the menu name passed to it using XtNameToWidget(), starting with the widget invoking the action as the reference widget. If unsuccessful, this routine continues to search up the widget tree, using each of the invoking widget’s ancestors as the reference widget. If still unsuccessful, the routine prints a warning message and gives up. XawPositionSimpleMenu positions the menu directly under the pointer. The menu is placed so that the pointer is centered on the entry named by the popupOnEntry resource. If the XtNmenuOnScreen resource is True, then the menu is always fully visible on the screen.
PUBLIC FUNCTIONS
•The XawPositionSimpleMenu action routine can often be invoked before any menus have been created. This can occur when an application uses dynamic menu creation. In these cases an application needs to register this global action routine by calling XawSimpleMenuAddGlobalActions(): void XawSimpleMenuAddGlobalActions(app_con)
XtAppContext app_con; where app_con specifies the application context in which this action should be registered.
This function need only be called once per application and must be called before any widget that uses XawPositionSimpleMenu action is realized.
•To get the currently highlighted menu entry, use XawSimpleMenuGetActiveEntry(): Widget XawSimpleMenuGetActiveEntry(w)
XtAppContext w; where w specifies the SimpleMenu widget. This function returns either the menu entry that is currently highlighted or NULL if no entry is highlighted.
•To clear the SimpleMenu widget’s internal information about the currently highlighted menu entry, use XawSimpleMenuClearActiveEntry(): Widget XawSimpleMenuClearActiveEntry(w)
XtAppContext w; where w specifies the SimpleMenu widget. This function unsets all internal references to the currently highlighted menu entry. It does not unhighlight or otherwise alter the appearance of the active entry. This function is primarily for use by implementors of menu entries.
SEE ALSO
MenuButton, Sme, SmeBSB, SmeLine.