WIDGET CLASS NAME

MenuButton

GADGET CLASS NAME

MenuButton

SYNOPSIS

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

static Widget stack, menupane, w;

Arg args[1];

stack = XtCreateWidget(name, menubuttonWidgetClass, ...);
OR   stack = XtCreateWidget(name, menubuttonGadgetClass, ...);
XtSetArg(args[0], XtNmenuPane, &menupane);
XtGetValues(stack, args, 1);

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

DESCRIPTION

The MenuButton widget provides the features of menu default selection and menu previewing as well as the features of the Menu widget.  MenuButton Components

Each menu button has the following parts: —  Label —  Border

Each menu button also has the components of a Menu widget.  These are not shown in the diagram Menu Button .  All Features of the Menu Widget

The MenuButton widget includes all the features of the Menu widget; the features of that widget apply here.  Selecting the Default Item

As an interface to a menu, each MenuButton widget has a Default Item.  If the power-user option is on, this Default Item is selected by clicking SELECT over the MenuButton widget.  If the Default Item is inactive (its XtNsensitive resource is FALSE), or busy (its XtNbusy resource is TRUE), the system beeps.  (If the power-user option is off, clicking SELECT brings up a pop-up menu.  The power-user option is set in the property sheet of the Workspace Manager.  See the OPEN LOOK™ GUI User’s Guide for more information on setting the power-user option.) 

Since the Default Item may be the MenuButton widget itself, selecting it really selects its Default Item; this recurses through the menu tree until a non-MenuButton widget is found as the Default Item.  The Default Item may be the pushpin in a menu. 

If a pushpin is the Default Item, the menu is brought up as a pinned menu.  Previewing the Default Item

If the menu button is not in a pop-up menu and the power-user option is on, pressing SELECT, or moving the pointer into the menu button while SELECT is pressed, displays the highlighted label of the Default Item in place of the menu button’s label.  Releasing SELECT restores the original colors and label, and selects the Default Item as described above.  Moving the pointer off the menu button before releasing also restores the original colors and label, but does not select the Default Item. (If the power-user option is off, pressing SELECT and releasing it displays a stayup menu.  See Selecting the Default Item above for comments about the power-user option.) 

This Default Item is the one in the menu directly under the menu button, not necessarily the Default Item at the end of the menu tree, that is activated when the Default Item is selected (see above).  Popping Up the Menu—Not in a Menu

When the MenuButton widget is in a control area, pressing or clicking MENU when the pointer is within or on the Border pops up the menu button’s menu in the direction of the menu mark.  Popping Up the Menu—As a Menu Button in a Menu

When the MenuButton widget is in a stay-up menu, pressing or clicking MENU when the pointer is within or on the Border pops up the menu button’s menu in the direction of the menu mark.  When the MenuButton widget is in a pop-up menu, moving the pointer into the menu mark region pops up the menu in the direction of the menu mark.  The position is computed when the movement into the menu mark region is first detected, but rapid pointer motion and internal delays in popping up the menu may let the pointer wander. 

Moving the pointer out of the MenuButton widget, but not directly into the newly popped up menu, causes that menu to be popped down.  This occurs even if the pointer is moved into and out of the newly popped up menu in the interim.  Menu Placement When There is No Room

If the right or bottom edge of the screen is too close to allow the menu placement described above, the menu pops up aligned with the edge of the screen and the pointer is shifted horizontally to keep it four points from the left edge of the menu items.  If the left edge of the screen is too close, the menu pops up four points from the edge and the pointer is shifted to lie on the edge.  The pointer does not jump back after the menu is dismissed.  MenuButton Coloration

the diagram Menu Button Coloration illustrates the resources that affect the coloration of the MenuButton widget.  Events that occur outside the Border (but within the MenuButton widget) are still in the domain of the menu button. 

SUBSTRUCTURE

Menu Component

Name: menu
Class: Menu

Application Resources
             Name       Type    Default  Access
       ∗XtNcenter    Boolean       TRUE       I
         ∗XtNhPad  Dimension          4       I
       ∗XtNhSpace  Dimension          4       I
      ∗XtNmeasure        int          1       I XtNpushpinDefault    Boolean      FALSE       I
         XtNtitle     String  (widget’s name)       I
         ∗XtNvPad  Dimension          4       I
       ∗XtNvSpace  Dimension          4       I ∗ See the Menu and ControlArea widgets for more information on these resources.

RESOURCES

MenuButton Resource Set
                Name                  Type       Default      Access XtNancestorSensitive               Boolean          TRUE          G∗
       XtNbackground                 Pixel         White     SGI† ‡ XtNbackgroundPixmap                Pixmap        (none)     SGI†
          XtNdefault               Boolean         FALSE         SGI
       ‡ XtNdepth                   int    (parent’s)          GI
  XtNdestroyCallback        XtCallbackList          NULL          SI
             XtNfont         XFontStruct ∗  (OPEN LOOK font)          SI
        XtNfontColor                 Pixel        Black∗         SGI
       XtNforeground                 Pixel         Black     SGI†
           XtNheight             Dimension  (calculated)         SGI
            XtNlabel                String  (class name)         SGI ‡ XtNmappedWhenManaged               Boolean          TRUE         SGI
         XtNmenuMark              OlDefine  (calculated)         SGI
         XtNmenuPane                Widget        (none)           G
    XtNrecomputeSize               Boolean          TRUE         SGI
        XtNsensitive               Boolean          TRUE         GI∗
         XtNuserData             XtPointer          NULL         SGI
            XtNwidth             Dimension  (calculated)         SGI
                XtNx              Position             0         SGI
                XtNy              Position             0         SGI ‡ These resources are not available to MenuButton gadgets. XtNdefault

Range of Values:

TRUE
FALSE

If this resource is TRUE, the Border is doubled to two lines to show that the menu button contains the default choice of several buttons.  XtNfont

Range of Values:

(any valid return from XLoadQueryFont())

Default:

(chosen to match the scale and screen resolution)

This resource identifies the font to be used to display the Label. 

The default value points to a cached font structure; an application should not expect to get this value with a call to XtGetValues() and use it reliably thereafter.  XtNfontColor

Range of Values:

(any Pixel value valid for the current display)/(any name from the rgb.txt file)

This resource specifies the color for the font.  If not set, the color from the XtNforeground resource, if available, is used for the font. 

See the note about the interaction of this resource with other color resources under the description of the XtNbackground resource in CORE RESOURCES(3W).  XtNforeground

This resource defines the foreground color for the widget. 

See the note about the interaction of this resource with other color resources under the description of the XtNbackground resource in CORE RESOURCES(3W).  XtNlabel

This resource is a pointer to the text for the Label of the MenuButton widget.  XtNlabelJustify

Range of Values:

OL_LEFT/"left"
OL_CENTER/"center"

This resource dictates whether the Label should be left-justified or centered within the widget width.  XtNmenuMark

Range of Values:

OL_DOWN
OL_RIGHT

This resource specifies the direction of the menu arrow.  XtNmenuPane

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

Range of Values:

TRUE
FALSE

This resource indicates whether the MenuButton widget should calculate its size and automatically set the XtNheight and XtNwidth resources.  If set to TRUE, the MenuButton widget will do normal size calculations that may cause its geometry to change.  If set to FALSE, the MenuButton widget will leave its size alone; this may cause truncation of the visible image being shown by the MenuButton widget if the fixed size is too small, or may cause padding if the fixed size is too large.  The location of the padding is determined by the XtNlabelJustify resource.  Label Appearance

The XtNwidth, XtNheight, XtNrecomputeSize, and XtNlabelJustify resources interact to produce a truncated, clipped, centered, or left-justified label as shown in the diagram Label Appearance. 

When the label is centered or left-justified, the extra space is filled with the background color of the MenuButton widget, as determined by the XtNbackground and XtNbackgroundPixmap resources. 

When a text label is truncated, the truncation occurs at a character boundary and a solid-white triangle is inserted to show that part of the label is missing.  The triangle, of course, requires that more of the label be truncated than would otherwise be necessary.  If the width of the button is too small to show even one character with the triangle, only the triangle is shown.  If the width is so small that the entire triangle cannot be shown, the triangle is clipped on the right. 

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