WIDGET CLASS NAME

MenuShell

SYNOPSIS

#include <Intrinsic.h>
#include <StringDefs.h>
#include <OpenLook.h>
#include <Menu.h>

static Widget menu, menupane, w;

Arg args[1];

menu = XtCreatePopupShell(name, menuShellWidgetClass, ...);
XtSetArg(args[0], XtNmenuPane, &menupane);
XtGetValues(menu, args, 1);

w = XtCreateWidget(name, widget-class, menupane, ...);

DESCRIPTION

Menu versus MenuButton

The Menu widget is used to create a menu not associated with either a menu button or an abbreviated menu button.  For example, a Menu widget can be attached to a button, such as an OblongButton widget, but this does not make the button into a menu button.  However, all the features of the Menu widget (except those related to menu creation) also pertain to the MenuButton menu.  Menu Components

A menu contains a set of Items that are presented to the end user for his or her selection.  These are specified by the application as widgets attached to the menu.  One of these Items is a Default Item.  (A menu always has exactly one Default Item.)  The Items are laid out in a Control Area.  A menu also has a Title, a Title Separator, a Border or Window Border, and an optional Pushpin.  Sometimes it also has a Drop Shadow.  See the diagram Menu Components. 

The application chooses the label for the Title and whether a menu has a Pushpin.  Sub-class of the Shell Widget

The Menu widget is a sub-class of the Shell widget.  Therefore, as the SYNOPSIS shows, the XtCreatePopupShell() routine is used to create a menu instead of the normal XtCreateWidget().  Menu Pane

The Menu Pane is not described as a separate widget in these requirements; the only interface to it for the application programmer is as a parent widget to which the widgets comprising the menu items are attached.  The menu items are not attached directly to the Menu widget, since a shell widget can take only one child.  The SYNOPSIS shows how the widget ID of the Menu Pane is obtained from the Menu widget.  Connecting a Menu to a Widget

A menu can be connected to any widget, including primitive widgets.  The connection is made by creating the menu widget as a child of the other widget.  Of course, being a shell widget, the Menu widget is not a normal widget-child of its parent, but a pop-up child.  If the application allows it, the menu augments the parent’s event list so that the popping-up of the menu is handled automatically. 

Pressing MENU when the pointer is over the parent of the Menu widget causes the menu to be popped up.  The menu is presented as a pop-up menu, where the Items are available for a press-drag-release type of selection (see below).  Clicking MENU when the pointer is over the parent of the Menu widget also causes the menu to be popped up, but the menu is presented as a stay-up menu, where the Items are available for a click-move-click type of selection, instead (see below).  A "slow click" (a press with a noticeable delay before the release) may show the menu as a pop-up on the press, then as a stay-up on the release.  Use of the Pushpin

The Pushpin is presented to the end user like any of the items to be selected from the menu, except that it is always the top-most item, and is presented visually as an "adornment" of the header, next to the Title (if present).  The end user selects the Pushpin, pushing it in to cause the menu to remain on the display as an OPEN LOOK window or pinned menu, and pulling it out to make the menu a stay-up menu.  To the end user, a pinned menu behaves indistinguishably from a command window.  The Default Item

If none of the menu items are explicitly set as the default item, the menu picks the first menu item to be the default item.  If the menu contains a pushpin and no other menu item is explicitly set as the default item, the pushpin is chosen as the default item.  Components Shown when Popped Up

A pop-up or stay-up menu shows the Title, Border, Pushpin (if available), Items, and Drop Shadow.  The Title is left out if the menu is from either a menu button or an abbreviated menu button.  A pinned menu shows the Window Border, Title, Pushpin, Items, but no Drop Shadow. 

Popup Position

If the menu is not from a menu button, the menu pops up so that the Default Item is vertically centered four points to the right of the pointer.  If the right or bottom edge of the screen is too close to allow this placement, the menu pops up with the Drop Shadow aligned with the edge of the screen, and the mouse pointer is shifted horizontally to keep it four points from the left edge of the Default Item. 

For the pop-up position when the menu is from a menu button, see MENUBUTTON WIDGET/GADGET(3W).  Press-Drag-Release vs Click-Move-Click Selection Control

The Menu arranges for its children to respond to either the press-drag-release or the click-move-click type of selection.  With the press-drag-release type of control, the user keeps MENU pressed and moves the pointer to the Item of choice; releasing MENU selects the Item and pops the menu down.  If the pointer is not over an Item when MENU is released, the menu simply pops down.  With the click-move-click type of control, the user moves the pointer to the Item of choice (MENU has already been released to end a click); clicking SELECT or MENU selects the Item and pops the menu down.  If the pointer is not over an Item when SELECT or MENU is clicked, the menu simply pops down. 

These selection methods apply to all menu items EXCEPT menu buttons.  For example, in the diagram Menu Components above, Locate Owner can be selected using the methods described here.  For the other items in the diagram Menu Components (which are menu buttons), see MENUBUTTON WIDGET/GADGET(3W) for the explanation of menu button selection behavior.  Converting a Stay-up Menu to a Pop-up Menu

Pressing MENU in a stay-up menu converts it to a pop-up menu.  Thus the click-move-click selection control becomes a press-drag-release selection control.  Highlighting of Menu Items

In the press-drag-release type of selection control, each menu Item highlights while the pointer is over it.  The form of the highlighting depends on the type of widget making up the Item.  Again, the Menu widget arranges for its children to respond in this way.  No highlighting occurs when the click-move-click type of selection control is used. 
Menu Coloration

The diagram Menu Coloration illustrates the resources that affect the coloration of the Menu widget. 

SUBSTRUCTURE

Menu Pane component

Application Resources
       Name       Type   Default  Access
  XtNcenter    Boolean      TRUE       I
    XtNhPad  Dimension         4       I
  XtNhSpace  Dimension         4       I
 XtNmeasure        int         1       I
    XtNvPad  Dimension         4       I
  XtNvSpace  Dimension         4       I

RESOURCES

Menu Resource Set
                   Name                    Type       Default   Access
    XtNallowShellResize                 Boolean          TRUE      SGI
   XtNancestorSensitive                 Boolean          TRUE       G∗
          XtNbackground                   Pixel         White  SGI†
    XtNbackgroundPixmap                  Pixmap        (none)  SGI† XtNcreatePopupChildProc  XtCreatePopupChildProc          NULL      SGI
               XtNdepth                     int    (parent’s)       GI
     XtNdestroyCallback          XtCallbackList          NULL       SI
                    .ig
            XtNgeometry                  String          NULL       GI
                     ..
              XtNheight               Dimension  (calculated)      SGI
           XtNheightInc                     int            -1      SGI
               XtNinput                 Boolean         FALSE        G
          XtNmaxAspectX                Position            -1      SGI
          XtNmaxAspectY                Position            -1      SGI
         XtNmenuAugment                 Boolean          TRUE       GI
            XtNmenuPane                  Widget        (none)        G
          XtNminAspectX                Position            -1      SGI
          XtNminAspectY                Position            -1      SGI
     XtNpopdownCallback          XtCallbackList          NULL       SI
       XtNpopupCallback          XtCallbackList          NULL       SI
      XtNpushpinDefault                 Boolean         FALSE       GI
           XtNsaveUnder                 Boolean         FALSE      SGI
           XtNsensitive                 Boolean          TRUE      GI∗
               XtNtitle                  String  (widget’s name)      SGI
            XtNuserData               XtPointer          NULL      SGI
               XtNwidth               Dimension  (calculated)      SGI
            XtNwidthInc                     int            -1      SGI
                    .ig
                   XtNx                Position             0      SGI
                   XtNy                Position             0      SGI
                     .. XtNmenuAugment

Range of Values:

TRUE
FALSE

If this resource is TRUE, the Menu widget will augment its parent’s event handling so that the pressing or clicking of MENU automatically pops up the menu.  If FALSE, the application is responsible for detecting when the menu should be popped up, and for calling the routine OlMenuPost(menu_widget) to pop up the menu.  This routine takes one argument, the widget ID returned when the menu was created.  XtNmenuPane

This is the widget where menu items can be attached; its value is available once the Menu widget has been created.  XtNpushpin

Range of Values:

OL_NONE/"none"
OL_OUT/"out"

This resource controls whether the Menu widget has a pushpin.  If set to OL_NONE, no pushpin will be included in the list of menu items, which means the user cannot pin the menu to keep it around.  If set to OL_OUT, a pushpin will be included as an item the user can select; if the end user selects the pushpin, the menu will be made into an OPEN LOOK window.  Note that the pushpin item is always at the top of the menu list. 

(This resource is also available in other widgets, but with three allowed values, including OL_IN.  This third value is not allowed for the Menu widget.)  XtNpushpinDefault

Range of Values:

TRUE
FALSE

Setting this resource to TRUE makes the Pushpin the Default Item. 

Note:
If a menu has a pushpin and none of the menu pane items have been designated as the default, the pushpin automatically becomes the menu’s Default Item. XtNtitle

This resource gives the Title of the Menu widget. 

Sun Release 4.1  —  Last change: 1/8/90