The [menuRef] command.
Introduction
The menuRef command lets you create and manipulate menus in
Alpha. The menu items can be manipulated using the new [menuItem]
command.
Synopsis
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 additionally specified.
The [cancel] subcommand
This subcommand cancels a menu tracking session. The syntax is:
menuRef cancel
It dismisses the currently opened menus and ends all menu
tracking. If no menu was opened, the command returns silently.
The [clear] subcommand
This subcommand removes all the items from a menu. The syntax is:
menuRef clear token
To remove only one item from a menu list, use the [menuItem remove] command.
The [count] subcommand
This subcommand returns the number of menu items in a menu. The syntax is:
menuRef count token
The [create] subcommand
This subcommand creates a new menu. The complete syntax is:
menuRef create ?options?
The command returns a token used in the other
subcommands (as well as with the [menuItem] command) to uniquely
identify the menu.
The available options are described in the
Menu options section below.
The [delete] subcommand
This subcommand lets you delete a menu. The syntax is:
menuRef delete token
After deletion, the token associated with this menu is not valid anymore
and is removed from the list returned by the [menuRef list] command.
The [insert] subcommand
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).
The [items] subcommand
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.
The [list] subcommand
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:
menuRef list ?-name str?
Not all menus have a name: a name can be declared with the -name
option in the [menuRef create] or [menuRef set] commands. The -name
option of the [menuRef list] command can then be specified in order
to find the corresponding menu token.
The [parent] subcommand
This subcommand returns the token of the menu's supermenu. The syntax is:
menuRef parent token
It concerns submenus which have been inserted in some menu. If the menu is
inserted directly in the menu bar, the command returns "menubar". If the
menu is not inserted in any menu, the command raises an error.
The [remove] subcommand
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.
The [set] subcommand
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 described in the
Menu options section below.
Menu options
Here is the description of the various options which can be passed
to the [menuRef create] or the [menuRef set] commands:
- the -attributes option lets you specify some attributes for
the menu.
The value passed in the -attributes option is additive. It is the
sum of base-2 constants. Currently, the only value of interest is:
| Value | Name | Description |
| 1 | Shows State Column | whether column space is allocated for the mark character |
The default value is 0.
- the -command option lets you specify the name of the Tcl proc
to execute when an item is selected in this menu (unless the item has a
proc of itself). Alpha will invoke this command with two arguments: the
token of the menu and the text of the selected item.
- the -icon option lets you specify a token corresponding to a
registered image reference in order to set the title of the menu to be an
icon. The image token is obtained using the [imageRef] command. Note that
the -icon and the -title options are mutually exclusive.
- the -keyMatching option lets you enable or disable key
matching for the entire menu. By default, this option is set to 1 and key
matching is performed when the menu is opened: this means that, for each
menu item, Alpha will check if there is a binding associated with the
action attached to the menu item. To speed things up, you can disable key
matching in menus where you do not want items to have a keyboard shortcut,
or if you know that no items have a shortcut (for instance, in the menus
representing a fileset). Key matching can also be controlled for each
individual menu item with the -showKey option.
- the -name option lets you declare an
internal name for the menu. This option is provided only for compatibility
reasons: the old menu syntax (in AlphaTcl on pre OS X systems) identified
menus by name. This name is still used by Alpha to identify menus defined
by packages and designed to be inserted in the menu bar when that package
is activated. This name does not appear anywhere in the interface: the
visible name of a menu is set using the -title option.
- the -title option lets you specify the title of the menu. The
-icon and the -title options are mutually exclusive.
- the -updateProc option lets you
specify a Tcl procedure to evaluate before a menu is opened. This can be
useful when the contents of a menu has to be adjusted before it is
displayed: depending on the context, one might want to enable or disable
some items, add or remove items, or even rebuild the menu entirely. When
the procedure declared by this option is invoked, the token of the menu is
passed as a single argument. Note that the procedure is only invoked once
per menu tracking session for a given menu, even if that menu is closed and
opened multiple times by the user. In order to remove such a procedure, use
the [menuRef set] command and pass an empty string for
this option.
Built-in menus
There are several built-in menus provided by Alpha. They are also
identified by a token. Currently, the following menus are available:
| Token | Description |
| application | the Alpha application menu |
| dock | the menu containing custom items in the dock tile |
| contextual | the contextual menu triggered by a control-click |
| help | the Help menu |
| services | the Services submenu |
These menus cannot be deleted or removed using the [menuRef delete] and
[menuRef remove] commands but their contents can be modified at
will. The other commands work as expected, using the built-in token. For instance:
menuRef count help
Examples
See a series of sample instructions in the [menuItem] command's
documentation.
Last updated 2019-10-17 13:29:39