Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XmtMenu(3)		   Library Functions Manual		    XmtMenu(3)

       XmtMenu - easy-to-create	menus.

       Include File:
	      #include _Xmt/Menu.h_


       Class Name:

       Class Pointer:

       Class Hierarchy:
	      Core -> XmManager	-> XmRowColumn -> XmtMenu

       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 gram-
       mar  and	 converts it to	an array of these XmtMenuItem structures. Xmt-
       MenuItem	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 automat-
       ically  create Menu widget children to display each of these sub-menus.
       Thus, it	is possible to create an entire	pulldown menu system by	creat-
       ing only	the menu bar, and letting the Menu widget do the rest.

       The Menu	widget has four	constructor functions, each with somewhat dif-
       ferent behavior.	XmtCreateMenubar() creates a Menu widget configured as
       a menubar. XmtCreateMenuPane() creates a	menu pane in a menu shell wid-
       get (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.


       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	 |
	      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.

	      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	termi-
	      nated  with  a XmtMenuItem structure that	has the	value XmtMenu-
	      ItemEnd in its type field. (This is analogous to a  NULL	termi-
	      nated array of strings, for example.)

	      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	expla-
       nation 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 Xmt-
       MenuItems structure are arranged	in  most-commonly-used	to  least-com-
       monly  used order, so that for most menu	items you need only initialize
       the first few fields you	care about, and	leave  the  others  uninitial-
       ized.  If  your array of	structures is declared static, then uninitial-
       ized 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 XmtReg-
       isterMenuItemsConverter(), then you  can	 specify  the  contents	 of  a
       menubar or any of its menu panes	with a single string resource in a re-
       source 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-sen-
       sitive  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 Chap-
       ter 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 `:'

	      `Title' |	`Button' | `Toggle' | `Submenu'	| `Line' |

	      `On' | `Off' | `Help' | `Tearoff'	| `Pixmap'

	      string-with-mnemonic [ `|' string-with-mnemonic ]

	      `[' { modifier `+' | `-' } keysym	`]'

	      `Ctrl' | `Shift' | `Meta'	| `Alt'	| `Lock'

	      single-letter-or-digit | identifier | string

	      `->' identifier

	      `$' identifier

	      `{' callback { callback }	`}'

	      identifier `(' [ arglist ] `)' `;'


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


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


       The Menu	widget defines no new action procedures.

       Chapter 20, Easy	Menu Creation,
       XmtCreateMenuPane(), XmtCreateMenubar(),	XmtCreateOptionMenu(),
       XmtCreatePopupMenu(), XmtMenuActivateProcedure(), XmtMenuGetMenuItem(),
       XmtMenuInactivateProcedure(), XmtMenuItemGetState(),
       XmtMenuItemGetSubmenu(),	XmtMenuItemGetWidget(),
       XmtMenuItemSetSensitivity(), XmtMenuItemSetState().

Xmt				  Motif	Tools			    XmtMenu(3)


Want to link to this manual page? Use this URL:

home | help