= Menus =

Menus allow the user to view or choose from a list of choices and commands. Each menu has one or more menu items associated with it. A menu item may also be a submenu, sometimes called a hierarchical menu.

{{{menu-item (view view-action-mixin view-text-mixin) [class]}}}

An abstract class representing menu items. A menu item can have a view-action which is invoked when the item is selected, and a view-text which is the name of the menu item. Additional initargs:

'':menu-item-updater'' -- intializes the function call to update the menu item, see set-menu-item-updater.

'':menu-item-key'' -- initializes the menu items command key equivalent, see set-menu-item-key.

'':menu-item-check'' -- initializes the check mark of the menu item, see set-menu-item-check.

'':menu-item-style'' -- initializes the font style in which the item text appears, see set-menu-item-style.

''TODO: can also set the font family.''

''TODO: can also have icons.''

''TODO: menu items are not first class objects in Carbon. I guess we'll just return ''nil'' from view-ref. Also will need some hack for getting the item info through command handler so can find the menu-item object.''

{{{(set-menu-item-updater menu-item updater) [method]}}}

Sets the menu item's updater function to ''updater'', which must be either ''nil'' or a funcallable object (function or symbol). If non-''nil'', it is invoked with one argument, the menu item, to allow it to be adjusted in the current program context (e.g. enabled/disabled) before it is displayed.

{{{(menu-item-updater menu-item updater) [method]}}}

Returns the menu item's updater function.

{{{(set-menu-item-key menu-item key) [method]}}}

Sets the keyboard equivalent for the menu item to key (which may be ''nil'' to remove the keyboard equivalent).

{{{(menu-item-key menu-item) [method]}}}

Returns the keyboard equivalent of the menu item.

{{{(set-menu-item-check menu-item check) [method]}}}

Sets the check mark character that appears next to the menu item text. If check is ''nil'', no check mark appears. If check is ''t'', then a standard check-mark symbol is used.  Otherwise it should be a character to be used as the check mark.

{{{(menu-item-check menu-item) [method]}}}

Returns the check mark character that appears next to the menu item text, or ''t'' if the standard check-mark symbol is used, or ''nil'' if no check mark appears.

{{{(set-menu-item-style menu-item style) [method]}}}

Sets the style in which the item text appears, one of :normal or :plain, :bold, :italic, :shadow, :outline, :underline, :condense, and :extend.

{{{(menu-item-style menu-item) [method]}}}

Returns the style in which the item text appears, one of - :normal, :bold, :italic, :shadow, :outline, :underline, :condense, and :extend.

{{{separator-menu-item (menu-item) [class]}}}

A permanently disabled menu item consisting of a long line, used as a separator.

''TODO: window-menu-item (menu-item) [class] ? ''

''TODO: font-menu-item (menu-item) [class] ? ''

{{{menu (menu-item view-nib-mixin) [class]}}}

The class of menus. Additional initargs:

'':menu-items'' -- initializes the menu's menu items, see set-menu-items.

{{{(set-menu-items menu items) [method]}}}

Sets the menu items associated with menu to ''items'', which must be a sequence of menu-item's.

{{{(menu-items menu) [method]}}}

Returns a freshly consed list of menu-item's associated with menu.

{{{(set-menubar menu) [method]}}}

Sets the root menu, also known as the menubar, to menu.

{{{(menubar) [method]}}}

Returns the menu object that is the current menubar.