FreeBSD Manual Pages
XmtMenu(3) Library Functions Manual XmtMenu(3) 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 ar- ray 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 con- verter 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 spec- ify 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 differ- ent 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 at- tached 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 XmtMenu- Item structure that has the value XmtMenuItemEnd in its type field. (This is analogous to a NULL terminated array of strings, for exam- ple.) 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 speci- fied 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 explana- tion 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 wid- get 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 struc- tures 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 XmtRegisterMenu- ItemsConverter(), 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 brack- ets are optional. Note that the grammar is case-sensitive and that all key- words begin with a capital letter. This means that keywords will not con- flict with item or submenu names, which, by convention, begin with a lower- case 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 syntacti- cal 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. SEE ALSO Chapter 20, Easy Menu Creation, XmtCreateMenuPane(), XmtCreateMenubar(), XmtCreateOptionMenu(), XmtCreatePopupMenu(), XmtMenuActivateProcedure(), XmtMenuGetMenuItem(), XmtMenuInactivateProcedure(), XmtMenuItemGetState(), XmtMenuItemGetSubmenu(), XmtMenuItemGetWidget(), XmtMenuItemSetSensitivity(), XmtMenuItemSetState(). Xmt Motif Tools XmtMenu(3)
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmtMenu&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>