typedef struct MenuBar MenuBar; typedef struct Menu Menu; typedef struct MenuItem MenuItem; typedef void (*MenuAction)(MenuItem *mi); struct MenuBar { Control * ctrl; /* associated control */ Font * font; /* for displaying all text */ int align; /* text alignment,direction */ int num_menus; /* list of menus */ Menu ** menus; }; struct Menu { MenuBar * parent; /* enclosing menubar */ char * text; /* name of the menu */ int num_items; /* list of menu items */ MenuItem ** items; int lasthit; /* which item was chosen */ Font * font; /* for displaying items */ }; struct MenuItem { Menu * parent; /* enclosing menu */ char * text; /* menu item name */ int shortcut; /* shortcut key */ int state; /* enabled? checked? */ Menu * submenu; /* pop-up menu */ MenuAction action; /* user-defined action */ void * data; /* user-defined data */ int value; /* user-defined value */ Font * font; /* for displaying this item */ Colour fg; /* for displaying text */ };
MenuBar * new_menu_bar(Window *win); void del_menu_bar(MenuBar *mb); Menu * new_menu(MenuBar *mb, char *name); Menu * new_sub_menu(Menu *parent, char *name); void del_menu(Menu *m); MenuItem *new_menu_item(Menu *m, char *name, int key, MenuAction fn); void del_menu_item(MenuItem *mi); void check_menu_item(MenuItem *mi); void uncheck_menu_item(MenuItem *mi); int menu_item_is_checked(MenuItem *mi); void enable_menu_item(MenuItem *mi); void disable_menu_item(MenuItem *mi); int menu_item_is_enabled(MenuItem *mi); void set_menu_item_value(MenuItem *mi, int value); int get_menu_item_value(MenuItem *mi); void set_menu_item_foreground(MenuItem *mi, Colour col); Colour get_menu_item_foreground(MenuItem *mi); void set_menu_item_font(MenuItem *mi, Font *font); Font * get_menu_item_font(MenuItem *mi); void set_menu_foreground(Menu *m, Colour col); Colour get_menu_foreground(Menu *m); void set_menu_font(Menu *m, Font *font); Font * get_menu_font(Menu *m); void set_menu_bar_font(MenuBar *mb, Font *font); Font * get_menu_bar_font(MenuBar *mb);
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 menu bar can be associated with a window by calling new_menu_bar after that window has been created. This function will return NULL if it fails for some reason. Calling del_menu_bar will destroy the menu bar and all associated menus and menu items, also removing the menu bar from the window. Destroying a window will automatically call this function.
After creating a menubar, the new_menu 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 new_sub_menu function can also be used to create menus. The parent parameter specifies a menu to which the new sub-menu will be added. The name of the sub-menu will appear in the parent menu, and selecting this name will make the sub-menu appear. The del_menu function can be used to delete a menu from a menu bar, and destroy all of its menu items.
After the creation of a menu, menu items can be added to it using new_menu_item. 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 'separator' line to appear in the pull-down menu. This can be used to logically group items in a menu.
The function pointer fn given as a parameter to new_menu_item is called when that menu item is selected by the user. When this call-back function is called, a pointer to the menu item is passed as a parameter to fn.
Use del_menu_item to delete one menu item and remove it from its menu.
The check_menu_item function places a check-mark beside a menu item within its menu, while the uncheck_menu_item function removes any such check-mark. The menu_item_is_checked function returns non-zero if the menu item has a check-mark next to it, zero if it does not. Menu items initially have no check-mark.
Menu items are enabled for mouse selection by default. They can be disabled using disabled_menu_item, and re-enabled using enable_menu_item. Whether a menu item is currently enabled can be determined using menu_item_is_enabled. Separator menu items are disabled when created.
Each menu item can have an integer value associated with it, by set_menu_item_value. The value can be retrieved using get_menu_item_value.
A menu item can also have its own font and foreground colour, which are used when the font's text is to be displayed. The functions set_menu_item_foreground and get_menu_item_foreground access the text colour.
The functions set_menu_item_font and get_menu_item_font are used to access a menu item's text font. By default, a menu item does not have its own font, in which case the menu bar's font is used for displaying text, which is Unifont by default. Setting the menu bar's font using set_menu_bar_font is all that is needed to change all menu items' displayed text to a single font.
Menus can also have a text font, accessed with set_menu_font and get_menu_font. A menu's font is only used when displaying its name in a menu bar or as a submenu name within another menu. If it has no font, the menu bar's font is used. Similarly, its text colour is accessed with set_menu_foreground and get_menu_foreground, and is only used for displaying the menu's name.