typedef control menubar; typedef control menu; typedef control menuitem; typedef void (*actionfn)(menubar m); typedef void (*menufn)(menuitem m);
menubar newmenubar(actionfn adjust_menus); menu newmenu(char *name); menu newsubmenu(menu parent, char *name); menuitem newmenuitem(char *name, int key, menufn fn); void addto(menu m); /* add menuitems to this menu */ void check(menuitem m); /* put check-mark next to this */ void uncheck(menuitem m); /* remove any check-mark */ int ischecked(menuitem m); /* is this item checked? */ void enable(menuitem m); /* allow user to select this item */ void disable(menuitem m); /* 'grey out' this item */ int isenabled(menuitem m); /* is this item enabled for use? */
A menubar is a horizontal bar in which the names of menus appear. A menu refers to a pull-down menu which contains menuitems.
A menubar can be associated with a window by calling newmenubar after that window has been created. This function will return NULL if it fails for some reason.
Each menubar has a call-back function associated with it. This call-back, adjust_menus, is called when the user is about to select an option from one of the menus attached to the menubar. This call-back can be used to ensure that the state of the menuitems correctly reflects the state of the program. Normally the adjust_menus parameter can be set to NULL.
After creating a menubar, the newmenu function is used to create menus, which are attached to the menubar. Each menu has a name which is displayed in the menubar, for example "File" might be the name of the menu which controls file operations.
The submenu function can also be used to create menus. The parent parameter specifies a menu to join this new submenu to. The name of the submenu will appear in the parent menu, and selecting this name will make the submenu appear. If the parent is NULL, the menu will be appended to the current menubar.
After the creation of a menu, several menuitems can be added to it using newmenuitem. The name of the item is a string which is displayed in the menu. Next to that name a short-cut key can be displayed. If key is non-zero it specifies an ASCII character which can be typed in combination with some other keyboard key to activate this menu item. For instance, if the key were given as 'Q', on a Windows platform the menu item would appear with "Ctrl+Q" next to its name, signifying that pressing the control key and the letter 'Q' together would trigger this menu item. Other platforms would display their own normal menu key-combinations.
A menuitem created with a name which is a hyphen "-" will cause a 'seperator' line to appear in the pull-down menu. This can be used to logically group items in a menu.
The function fn used in the call to newmenuitem is called when that item is selected by the user. When the function fn is called, the menuitem itself is passed as a parameter. This allows the use of getvalue or getdata to find information associated with the menuitem. (See the section on Controls for more details.)
The addto function can be used to add more menuitems to an existing menu, for instance, after adding a submenu to a parent menu, you may wish to add more menuitems to that parent menu. Usually this is not needed since, by default, menuitems are placed on the most recently created menu or submenu.
The check function places a check-mark beside a menuitem in a menu, while the uncheck function removes any such check-mark. The ischecked function returns non-zero if the menuitem has a check-mark next to it, zero if it does not.
The enable function can be used to enable a menuitem which has been disabled through the use of the disable function. A disabled menuitem will appear in grey text and the user will be unable to select it. The isenabled function returns non-zero if the menuitem is currently enabled, zero if it is disabled.
Menuitems are initially unchecked, and enabled.