# SimpleMenu Widget

    Application Header file	<X11/Xaw/SimpleMenu.h>

    Class Header file	<X11/Xaw/SimpleMenP.h>

    Class		simpleMenuWidgetClass

    Class Name	SimpleMenu

    Superclass	OverrideShell

The SimpleMenu widget is a container for the menu entries. It is a direct subclass of shell, and is should be created with `XtCreatePopupShell`, not XtCreateManagedWidget. 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.

## Resources

The resources associated with the SimpleMenu widget control aspects that will affect the entire menu.

Name | Class | Type | Notes | Default Value
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

`backingStore`

- 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.

`bottomMargin`

`topMargin`

- The amount of space between the top or bottom of the menu and the menu entry closest to that edge.

`cursor`

- The shape of the mouse pointer whenever it is in this widget.

geometry

- If this resource is specified it will override the x, y, width and height of this widget. The format of this string is [<width>x<height>][{+ -} <xoffset> {+ -}<yoffset>].

`label`

- This label will be placed at the top of the SimpleMenu, and may not 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 `label` is hard coded to the value of `label`, and `justify` is hard coded as `XtJustifyCenter`.

`labelClass`

- Specifies the type of Sme object created as the menu label.

`menuOnScreen`

- If the menu is automatically positioned under the cursor with the `XawPositionSimpleMenu` action, and this resource is `True`, then the menu will always be fully visible on the screen.

overrideRedirect

- 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 Interclient Communications Conventions Manual.

popdownCallback

popupCallback

- These callback functions are called by the Xt Intrinsics whenever the shell is popped up or down (See (xT for details).

`popupOnEntry`

- The `XawPositionSimpleMenu` 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.

`rowHeight`

- 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 `rowHeight` pixels high.

saveUnder

- If this is `True` then save unders will be active on the menu's window.

## SimpleMenu Actions

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 following are the default translation bindings used by the SimpleMenu widget:

    	<EnterWindow>:	highlight( )
    	<LeaveWindow>:	unhighlight( )
    	<BtnMotion>:	highlight( )
    	<BtnUp>:	MenuPopdown( ) notify( ) unhighlight( )

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 full list of actions supported by SimpleMenu is:

`highlight`()

- Highlight the menu entry that is currently under the pointer. Only a item that is highlighted will be 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 menu entry that is currently highlighted that is has been selected. It is the responsibility of the menu entry to take the appropriate action.

`MenuPopdown`(menu)

- This action is defined in (xT.

## Positioning the SimpleMenu

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.

If popup menus are desired it will be necessary to add the `XawPositionSimpleMenu` and `MenuPopup` actions to the translation table of the widget that will be popping up the menu. The `MenuPopup` action is described in (xT. `XawPositionSimpleMenu` is a global action procedure registered by the SimpleMenu widget when the first one is created or the convenience routine XawSimpleMenuAddGlobalActions is called.

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 `xterm's` menus:

    	!Ctrl<Btn1Down>: XawPositionSimpleMenu(xterm) MenuPopup(xterm)
    	!Ctrl<Btn2Down>: XawPositionSimpleMenu(modes) MenuPopup(modes)

`XawPositionSimpleMenu`(menu)

- The `XawPositionSimpleMenu` routine will search for the menu name passed to it using `XtNameToWidget` 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. `XawPositionSimpleMenu` 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 `popupOnEntry` resource. If the `menuOnScreen` resource is `True` then the menu will always be fully visible on the screen.

## Convenience Routines

### Registering the Global Action Routines

The `XawPositionSimpleMenu` 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 XawSimpleMenuAddGlobalActions:

      void XawSimpleMenuAddGlobalActions
      XtAppContext app_con

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.

### Getting and Clearing the Current Menu Entry

To get the currently highlighted menu entry use XawSimpleMenuGetActiveEntry:

      Widget XawSimpleMenuGetActiveEntry
      Widget w

w

- Specifies the SimpleMenu widget.

This function returns 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
      Widget w

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.