The [menuRef] command lets you create and manipulate menus in Alpha. Menu items can be manipulated using the new [menuItem] command (see the MenuItemCommand page on this wiki). Both commands could constitute a replacement for the old [Menu] command.
The formal syntax of the [menuRef] command is:
menuRef subcommand ?options?
The possible subcommands are described below. Depending on the subcommand, various options can be additionnally specified.
This subcommand removes all the items from a menu. The syntax is:
menuItem clear token
To remove only one item from a menu list, use the [menuRef delete] command.
This subcommand returns the number of menu items in a menu. The syntax is:
menuItem count token
This subcommand creates a new menu. It accepts a few options. The complete syntax is:
menuRef create ?-attributes val? ?(-icon code|-title name)? ?-command name?
The [menuRef create] command returns a token used in the other subcommands (as well as with the [menuItem] command) to uniquely identify the menu.
Here is the description of the various options:
|1||ExcludesMarkColumn||No column space is allocated for the mark character when this menu is drawn.|
|4||AutoDisable||The menu title is automatically disabled when all items are disabled.|
|16||Hidden||The menu title is not drawn in the menubar, even when the menu is inserted in the menubar. Useful for adding command keys that don't correspond to a visible menu item; menu items with the desired command keys can be added to the menu and inserted in the menubar without making the menu visible.|
|32||CondenseSeparators||If menu item separators are present at the beginning or end of the menu, or if multiple contiguous separators are present, the extra separator items are marked as hidden to avoid extra blank space in the menu. The menu is examined for extra separators whenever the menu size is recalculated.|
This subcommand lets you delete a menu. The syntax is:
menuRef delete token
The token associated with this menu is not valid anymore and is removed from the list returned by the [menuRef list] command.
This subcommand lets you hilite/unhilite a menu. The syntax is:
menuRef hilite token (0|1)
This subcommand lets you insert a menu in the menu bar. The syntax is:
menuRef insert token ?-before token?
The -before option lets you specify the token of another menu before which the menu must be inserted in the menu bar. If unspecified, the menu is appended at the right of the menu bar (yet before the Help menu).
This subcommand returns a list of all the items currently present in the menu, in the index order. The syntax is:
menuRef items token
This command should not be confused with the [menuRef list] command which returns the current list of menus.
This subcommand returns a list of the tokens corresponding to the currently existing menus. Each time a new menu is created, its token is appended at the end of the list, so this list is ordered from the oldest to the newest menu. The syntax is:
This subcommand lets you remove a menu from the menu bar. The syntax is:
menuRef remove token
The menu is removed but not deleted: its token remains valid.
This subcommand lets you get or set some properties of a menu. The syntax can take two forms:
menuRef set token option menuRef set token option value ?option value...?
In the first form the command returns the current value of the specified option. In the second form, it lets you set the value of one or several options.
The available options are exactly the same as with the [menuRef create] command.
There are two special menus provided by the system: the application menu (which starts with the About Alpha item) and the help menu. Both menus can be targetted by the [menuRef] and [menuItem] commands using the "application" and "help" symbolic names in place of the token. For instance:
menuRef count help
The application also provides a symbolic token "contextual" to designate the contextual menu which is displayed when the user control-clicks on a document window (see the ContextualModules page on this wiki).
These menus cannot be deleted or removed using the [menuRef delete] and [menuRef remove] commands.
See a series of sample instructions on the MenuItem Command page on this wiki.
(add your comments here...)