NAME

XmtMenu - easy-to-create menus.

SYNOPSIS

Include File:

#include <Xmt/Menu.h>

Constructor:

XmtCreateMenubar()
XmtCreateMenuPane()
XmtCreatePopupMenu()
XmtCreateOptionMenu()

Class Name:

XmtMenu

Class Pointer:

xmtMenuWidgetClass

Class Hierarchy:

Core -> XmManager -> XmRowColumn -> XmtMenu

DESCRIPTION

The XmtMenu widget is a subclass of the XmRowColumn widget designed to make it easier to create menus and systems of menus. A Menu widget takes an array of XmtMenuItem structures on its XmtNitems resource and automatically creates the items (push buttons, toggle buttons, cascade buttons, labels, and separators) described by those structures. There is a resource converter that parses an intuitive menu description grammar and converts it to an array of these XmtMenuItem structures. XmtMenuItem structures, whether statically initialized in C or created by the resource converter, can specify other arrays of menu structures which describe the contents of sub-menus. The Menu widget will automatically create Menu widget children to display each of these sub-menus. Thus, it is possible to create an entire pulldown menu system by creating only the menu bar, and letting the Menu widget do the rest.

The Menu widget has four constructor functions, each with somewhat different behavior. XmtCreateMenubar() creates a Menu widget configured as a menubar. XmtCreateMenuPane() creates a menu pane in a menu shell widget (it may share the menu shell with other panes). The resulting pane can be attached to any cascade button. XmtCreatePopupMenu() creates a menu shell and a menu pane to pop up in that shell, and registers an event handler to pop up the menu appropriately. XmtCreateOptionMenu() creates an XmOption Menu and a menu pane to pop up in it. This last constructor is less useful than the others; option menus are generally better handled by the XmtChooser widget.

RESOURCES

XmtMenu inherits the resources of the XmRowColumn class, and defines the following new resources:

Name	Type	Class	Access	Default
XmtNacceleratorFontTag	XtRString	XmtCAcceleratorFontTag	CG	NULL
XmtNitems	XmtRXmtMenuItemList	XmtCItems	CG	NULL
XmtNnumItems	XtRCardinal	XmtCNumItems	CG	-1

XmtNacceleratorFontTag: A string that specifies the font that any accelerator labels should be displayed in. If specified, this string should match a ``font tag'' for one of the fonts an XmFontList that will be used by all the buttons in the menu. Note that the Menu widget does not have such a font list resource itself.
XmtNitems: An array of XmtMenuItem structures, each of which describes one item to appear in the menu. If XmtNnumItems is specified, then this array must contain the specified number of elements. If XmtNnumItems is left unspecified, then this array must be terminated with a XmtMenuItem structure that has the value XmtMenuItemEnd in its type field. (This is analogous to a NULL terminated array of strings, for example.)
XmtNnumItems: If set to something other than its default of -1, this resource specifies the number of elements in the XmtNitems array.

Describing Menus

The Menu widget creates a menu bar or menu pane described by an array of XmtMenuItem structures on the XmtNitems resource. This array may be specified from a resource file using the resource converter described in the next section, or it may be statically initialized from C code.

The XmtMenuItems structure and related types are defined as follows in <Xmt/Menu.h>. See Chapter 22, Easy Menu Creation, for a complete explanation of how to initialize each of the fields of the structure.

/*
 * This structure defines a single menu item. Initialize an array of
 * them in order to define a menubar or menu pane.
 */
typedef struct _XmtMenuItem {

unsigned type;	/* an XmtMenuItemType + any applicable flags */
String label;	/* the item label, or the name of an icon */
char mnemonic;	/* the mnemonic character for the item */
String accelerator;	/* the accelerator; translation table syntax */
String accelerator_label;	/* how to display the accelerator */
XtCallbackProc callback;	/* callback procedure or list for the item */
XtPointer client_data;	/* data to be registered with the callback */
struct _XmtMenuItem *submenu;	/* the array of items for the submenu */
String symbol_name;	/* name of a symbol to set for this item */
String alt_label;	/* an alternate label for a toggle button */
char alt_mnemonic;	/* alternate mnemonic for a toggle button */
String name;	/* item name for later lookup */
	/* the private fields below are omitted here; leave them uninitialized */

} XmtMenuItem;
/* These are the possible types of menu items */
typedef enum {

XmtMenuItemEnd,	/* used to NULL-terminate the array of items */
XmtMenuItemPushButton,	/* a push button */
XmtMenuItemToggleButton,	/* a toggle button */
XmtMenuItemCascadeButton,	/* a cascade button; has a submenu attached */
XmtMenuItemSeparator,	/* a single-line etched separator */
XmtMenuItemDoubleSeparator,	/* a double-line etched separator */
XmtMenuItemLabel	/* a label widget; good for menu titles */

} XmtMenuItemType;
/* These are flags for menu items. Add these to the type */

#define XmtMenuItemOn	0x10	/* initial state of toggle button is on */
#define XmtMenuItemHelp	0x20	/* cascade button goes to far right of bar */
#define XmtMenuItemTearoff	0x40	/* attached menu pane is a tearoff */
#define XmtMenuItemPixmap	0x80	/* label field is pixmap name, not a str
ing */
#define XmtMenuItemCallbackList	0x100	/* callback field is an XtCallbackList */

Note that the XmtMenuItem structure has both public fields which may be initialized, and private fields which are used internally by the Menu widget and should set or read by the programmer. The fields in an XmtMenuItems structure are arranged in most-commonly-used to least-commonly used order, so that for most menu items you need only initialize the first few fields you care about, and leave the others uninitialized. If your array of structures is declared static, then uninitialized fields will contain NULL, which is their proper value.

The XmtMenu Grammar

The Xmt library provides a String-to-XmtMenuItems converter for use with the Menu widget. If you register this converter by calling XmtRegisterMenuItemsConverter(), then you can specify the contents of a menubar or any of its menu panes with a single string resource in a resource file.

The XmtMenu grammar was designed to be easily readable and intuitive. A BNF definition of the syntax appears below. Items within single quotes are terminal symbols of the grammar-keywords or punctuation that should appear exactly as shown. Items in italics are non-terminals-items that are defined elsewhere in the grammar, or which are implicitly defined. Items within curly braces are repeated zero or more times and items within square brackets are optional. Note that the grammar is case-sensitive and that all keywords begin with a capital letter. This means that keywords will not conflict with item or submenu names, which, by convention, begin with a lowercase letter.

This summary of the grammar is provided here for reference. See Chapter 20, Easy Menu Creation for a semantic explanation of each of the syntactical elements of the grammar, and for examples menu descriptions that use the grammar.

menu::: { item }
item::: [ name ] [ type ] { flags } [ label ] [ accelerator] [ submenu ] [ symbol ] `;' [ name ] [ type ] { flags } [ label ] [ accelerator] [ submenu ] [ symbol ] callbacks [ name ] `-' { `-' } `;' [ name ] `=' { `=' } `;'
name::: identifier `:'
|type::: `Title' | `Button' | `Toggle' | `Submenu' | `Line' | `DoubleLine'
flags::: `On' | `Off' | `Help' | `Tearoff' | `Pixmap'
label::: string-with-mnemonic [ `|' string-with-mnemonic ]
accelerator::: `[' { modifier `+' | `-' } keysym `]'
modifier::: `Ctrl' | `Shift' | `Meta' | `Alt' | `Lock'
keysym::: single-letter-or-digit | identifier | string
submenu::: `->' identifier
symbol::: `$' identifier
callbacks::: callback
`{' callback { callback } `}'
callback::: identifier `(' [ arglist ] `)' `;'

CALLBACKS

The Menu widget defines no new callback lists of its own. It does allow callback procedures and XtCallbackLists to be specified and registered on the menu item children it automatically creates, however.

TRANSLATIONS

The Menu widget inherits its translations from the XmRow Column widget class and does not add any new translations of its own.

ACTIONS

The Menu widget defines no new action procedures.

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO