NAME

AbbrevMenuButton − abbreviated menu button, a button widget with associated menu

SYNOPSIS

#include <X11/Intrinsic.h>
#include <X11/StringDefs.h>
#include <Xol/OpenLook.h>
#include <Xol/AbbrevMenu.h>
 . . .
Widget my_abbrevmenubutton, my_parent;
String my_name;
ArgList args;
Cardinal num_args;

my_abbrevmenubutton =  XtCreate( my_name, abbrevMenuButtonWidgetClass,

my_parent, args, num_args);

 . . . 
Widget menupane;

XtSetArg( args[0], XtNmenuPane, (XtArgVal) &menupane);

XtGetValues( my_abbrevmenubutton, args, 1);
Widget a_menu_item;
WidgetClass item_class;
String item_name;

a_menu_item =  XtCreate( item_name, item_class, menupane, args, num_args);

DESCRIPTION

The AbbrevMenuButton widget provides the end user the same features as the MenuButton widget (menu default selection, menu previewing, menu selection), plus current selection viewing, and the ability to add a new selection by typing in its name. 

Components

Each abbreviated menu button has a submenu.  An application typically identifies an additional component, the Current Selection Widget, where previewing of the default menu choice can be done. 

  Figure 1

Each abbreviated menu button also has the components of a MenuButton widget, except for previewing (done instead in the Current Selection Widget) and menu behavior (since the AbbrevMenuButton widget cannot be used in a menu). 

AbbrevMenuButton Subwidgets

AbbrevMenuButton contains one subwidget, a MenuShell provided automatically, and accessible through the XtNmenupane resource. 

  Figure 2 AbbrevMenuButton Subwidgets AbbrevMenuButton
      |
      |
  MenuShell (XtNmenupane)

Widget Features

The AbbrevMenuButton widget includes all the features of the MenuButton widget, except for the previewing (done instead in the Current Select Widget) and the behavior in a menu (the AbbrevMenuButton widget cannot be used in a menu). 

Current Selection Widget

The Current Selection Widget is created by the application.  Typically, the Current Selection Widget and the AbbrevMenuButton widget are placed together in a composite widget that manages their side-by-side placement.  The AbbrevMenuButton widget uses the Current Selection Widget only for previewing the default item in the menu.  The application is responsible for using it to implement the OPEN LOOK user interface needs of showing the current menu selection and acquiring a new item to add to the menu, as appropriate. 

Coloration

of the AbbrevMenuButton widget. 

  Figure 3 Abbreviated Menu Button Coloration

On a monochrome display, the AbbrevMenuButton widget indicates that it has input focus by inverting the foreground and background colors of the control. 

On color displays, when the AbbrevMenuButton widget receives the input focus, the background color is changed to the input focus color set in the XtNinputFocusColor resource. 

Note:

—If the input focus color is the same as the Input Window Header Color and the active control is in the window header, then invert the colors. 

—If the input focus color is the same as the window background color, then the AbbrevMenuButton widget inverts the foreground and background colors when it has input focus. 

  Table 1 AbbrevMenuButton Activation

Abbreviated  MenuButton Activation Types
_
Activation   Type       Expected   Results
=
 
OL_SELECTKEY See        discussion below
OL_MENUKEY   Popup      the        AbbrevMenuButton

Keyboard Traversal

The default value of the XtNtraversalOn resource is TRUE. 

The action of the SELECTKEY posts the stayup menu. 

The AbbrevMenuButton does not control the keyboard traversal between the AbbrevMenuButton widget and the Current Selection widget.  The Current Selection widget’s traversal resources can be set up to allow for traversal between it and the AbbrevMenuButton, but it is recommended that the XtNtraversalOn resource on the Current Selection widget be FALSE.  Normal menu traversal can always be used to access the Current Selection Widget.  The AbbrevMenuButton does not control the keyboard traversal between the AbbrevMenuButton widget and the Current Selection widget.  The Current Selection widget’s traversal resources can be set up to allow for traversal between it and the AbbrevMenuButton, but it is recommended that the XtNtraversalOn resource on the Current Selection widget be False.  Normal menu traversal can always be used to access the Current Selection widget. 

Keyboard traversal within a menu is done using the PREV_FIELD, NEXT_FIELD, MOVEUP, MOVEDOWN, MOVELEFT and MOVERIGHT keys.  The PREV_FIELD, MOVEUP, and MOVELEFT keys move the input focus to the previous menu item with keyboard traversal enabled.  If the  menu is not pinned, the MOVELEFT key will dismiss the menu. 

If the input focus is on the first item of the menu, then pressing one of these keys will wrap to the last item of the menu with keyboard traversal enabled.  The NEXT_FIELD, MOVEDOWN, and MOVERIGHT keys move the input focus to the next menu item with keyboard traversal enabled. 

If the input focus is on the last item of the menu, then pressing one of these keys will wrap to the first item of the menu with keyboard traversal enabled. 

If input focus is on a MenuButton within a menu, pressing the MENUKEY will post the cascading menu associated with the AbbrevMenuButton, and input focus will be on the first menu item with traversal enabled. 

To traverse out of the menu, the following keys can be used:

—CANCEL dismisses the menu and returns focus to the AbbrevMenuButton

—NEXTWINDOW moves to the next window in the application

—PREVWINDOW moves to the previous window in the application

—NEXTAPP moves to the first window in the next application

—PREVAPP moves to the first window in the previous application

The DEFAULTACTION key will activate the default control in the AbbrevMenuButton widget as if the user clicked the SELECT button on the control. 

The MENUDEFAULTKEY can be used by the user to change the default control in the AbbrevMenuButton widget.  When the user presses the MENUDEFAULTKEY, the control which has input focus will become the default control. 

Keyboard Mnemonic Display

The AbbrevMenuButton does not display the mnemonic accelerator.  If the AbbrevMenuButton is the child of a Caption widget, the Caption widget can be used to display the mnemonic. 

Display of Keyboard Accelerators

The AbbrevMenuButton does not display the keyboard accelerator.  If the AbbrevMenuButton is a child of a Caption widget, the Caption widget can be used to display the accelerator as part of the label. 

RESOURCES

Menu Resources

  Table 2 Abbreviated Menu Button Resources

Application       Resources
Name              Type      Default      Access
 
XtNcenter         Boolean   TRUE         I
XtNhPad           Dimension 4            I
XtNhSpace         Dimension 4            I
XtNlayoutType     OlDefine  OL_FIXEDROWS I
XtNmeasure        int       1            I
XtNpushpin        OlDefine  OL_NONE      I
XtNpushpinDefault Boolean   FALSE        I
XtNsameSize       OlDefine  OL_COLUMNS   I
XtNtitle          String    (widget’s    name)
XtNvPad           Dimension 4            I
XtNvSpace         Dimension 4            I

Access:S = XtSetValues G = XtGetValues
        I = init timeO = other access
† see resources(3W)
† see ControlArea(3W) and MenuShell(3W) for more information on these resources

Menu Button Resources

  Table 3 AbbrevMenuButton Resource Set

AbbrevMenuButton     Resource       Set
Name                 Type           Default             Access
 
XtNaccelerator       String         NULL                SGI
XtNacceleratorText   String         Dynamic             SGI
XtNancestorSensitive Boolean        TRUE                GO
XtNbackground        Pixel          XtDefaultBackground SGI
XtNbackgroundPixmap  Pixmap         (none)              SGI
XtNconsumeEvent      XtCallbackList NULL                SGI
XtNdestroyCallback   XtCallbackList NULL                SI
XtNforeground        Pixel          XtDefaultForeground SGI
XtNheight            Dimension      (calculated)        SGI
XtNinputFocusColor   Pixel          Red                 SGI
XtNmappedWhenManaged Boolean        TRUE                SGI
XtNmenuPane          Widget         (none)              G
XtNmnemonic          unsigned       char                NULL
XtNpreviewWidget     Widget         NULL                SGI
XtNreferenceName     String         NULL                SGI
XtNreferenceWidget   Widget         NULL                SGI
XtNscale             int            12                  SGI
XtNsensitive         Boolean        TRUE                GIO
XtNtraversalOn       Boolean        TRUE                SGI
XtNuserData          XtPointer      NULL                SGI
XtNwidth             Dimension      (calculated)        SGI
XtNx                 Position       0                   SGI
XtNy                 Position       0                   SGI

Access:S = XtSetValues G = XtGetValues
        I = init timeO = other access
† see resources(3W)

XtNmenuPane

 class:XtCMenuPane type:Widget default:(none)access:G

Action: identifies the widget where menu items can be attached. 

Values: ID of AbbrevMenuButton’s existing menu pane widget

Its value is available once the AbbrevMenuButton widget has been created. 

XtNpreviewWidget

 class:XtCPreviewWidget type:Widget default:NULLaccess:SGI
 class:XtCPreviewWidgettype:Widgetdefault:NULLaccess:SGI

Action: identifies the Current Selection Widget that the AbbrevMenuButton can use for previewing the Default Item. 

Values: ID of existing widget

When the end user presses SELECT over the AbbrevMenuButton widget, the AbbrevMenuButton widget uses the location and size of the Current Selection Widget to display the label of the Default Item.  The preview is constrained to be within the height and width of the Current Selection Widget.  If the Current Selection Widget is not defined or is not mapped, previewing does not take place. 

If the Current Selection Widget is not defined or is not mapped, previewing does not take place. 

NOTE: The previewing feature does not work with keyboard–only operation. 

XtNscale

 class:XtCScale type:Int default:12access:SGI
 class:XtCScaletype:Intdefault:12access:SGI

Action: determines size of graphical elements, in points (1/72-inch). 

Values: 0 < XtNscale

This resource sets the size of graphical elements (widgets) in a manner similar to other scale resources. 

Note: Only sizes 10, 12, 14, 19 are presently supported.  If this resource is set to any other value, one of these is substituted instead. 

SEE ALSO

ControlArea(3w), Menu(3w), resources(3w),

Version 3.0  —  19 July 91