From AlphaWiki

Commands: The [menuItem] command

This file documents the new [menuItem] command in version 8.2a1d4 of AlphaX.


The [menuItem] command lets you manipulate menu items in Alpha's menus. Menus can be created and manipulated using the new [menuRef] command (see the MenuRefCommand page on this wiki). Both commands could constitute a replacement for the old [Menu] command.


The formal syntax of the [menuItem] command is:

menuItem subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, various options can be additionnally specified. In all these subcommands, the menu argument designates a unique menu token generated by Alpha each time a menu is created: such a token is typically obtained from the [menuRef create] command, but note that, for backward compatibility, tokens are also generated when menus are created with the old [Menu] command. As a consequence, the [menuItem] command also applies to menu items in menus which where not created with the [menuRef create] command, provided you know the associated token.

The [append] subcommand

This subcommand lets you append a new menu item. It returns the index of the item in the menu items list. The syntax is:

     menuItem append menu text ?option value...?

The possible options are described in the Menu item options section below.

The [check] subcommand

This subcommand lets you add or remove a check mark from a menu item. The syntax is:

     menuItem check menu index (0|1)

You can also add or remove a check mark using the [menuItem set] command with the -mark option.

The [delete] subcommand

This subcommand deletes an item from a menu. The syntax is:

     menuItem delete menu index

If you specify 0 or an index number greater than the last item in the menu, the command does not delete any item from the menu.

The [index] subcommand

This subcommand returns the index of a menu item. The first item is at index 0. The syntax is:

     menuItem index menu text ?-(exact|glob|regexp)? ?-all? ?-inline? ?-nocase? ?-not?

The -exact, -glob, and -regexp options let you specify how the text is to be matched against the menu items:

The text argument is a literal string that is compared for exact equality against each menu item.
The text argument is a glob-style pattern which is matched against each menu item using the same rules as the [string match] Tcl command.
The text argument is treated as a regular expression.

If no matching style option is specified, the default is -glob.

The other options have the following signifcation:

Return a list of all the matches rather than only the first one.
Causes comparisons to be handled in a case-insensitive manner.
The matching value is returned instead of its index (or an empty string if no value matches.) If -all is also specified, then the result of the command is the list of all values that matched.
This negates the sense of the match, returning the index of the first non-matching value in the list.

If no matching item is found, the command returns the value -1 if the option -all is not specified, or an empty list otherwise.

The [insert] subcommand

This subcommand lets you insert a new menu item with text at a specified index. If the index is greater than the number of items in the menu, the item is inserted at the end of the menu. The first item is at index 0. The syntax is:

     menuItem insert menu index text ?option value...?

The possible options are described in the Menu item options section below.

The [set] subcommand

This subcommand lets you get or set several properties attached to a menu item. The syntax can take two forms:

     menuItem set menu index option
     menuItem set menu index 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 possible options are described in the Menu item options section below.

Menu item indices

The menu item indices are 0-based: the first item is at index 0 and the last item is at index count-1 where count is the number of items in the menu.

In the subcommands accepting an index argument ([check], [delete], [insert], and [set]), this argument can be expressed either as an integer or using the end keyword to designate the last item of the menu, as with the usual Tcl list commands. Both the integer((+|-)integer)? and the end((+|-)integer)? formats are supported for the index argument.

Be aware, when using the end keyword, that this designates the last element of the complete list of items, that is to say the list returned by the [menuRef items] command, and it is not necessarily the one you see displayed when opening the menu since some items can be hidden or dynamic.

Menu item options

The [menuItem append], [menuItem insert] and '''[menuItem set]''' commands accept many options to set their attributes and parameters. All these properties are specified by an option starting with a dash. Here is the list of the menu item options:

"c"corresponds to the Command key
"s"corresponds to the Shift key
"o"corresponds to the Option key
"z"corresponds to the Control key

Note that this option does not concern menu shortcuts: menu item key equivalents are defined through the bindings mechanism (see the BindingCommand page).


Note that not all combinations are supported by the Menu Manager or by the System font.

Menu item shortcuts

Starting with version 8.2a1d1, keyboard shortcuts (if they exist) are automatically attached to menu items.

Keyboard shortcuts can be defined with the new [binding] command (see the BindingCommand page on this wiki): a key binding is associated with a Tcl proc. If the same Tcl proc is also attached to a menu item (using [menuItem set -command]), then the binding is displayed in the menu as the menu item key equivalent.

If necessary, the automatic attachment of bindings to menu items can be disabled:


Here are a few basic examples which can be executed one by one in the Tcl shell in AlphaX:

     proc testMenuRefProc {menu item} {
     	alertnote "Item $item of menu $menu was selected!"

     # Create a menu
     set testMenu [menuRef create -title Test -command testMenuRefProc]

     # Create a menu with the Burning Icon
     set iconMenu [menuRef create -icon "burn" -command testMenuRefProc]

     # Get the list of newly created menus
     menuRef list
     # Result: menu1 menu2 etc.

     # Insert the menus
     menuRef insert $testMenu
     menuRef insert $iconMenu

     # Populate the "Icon" menu
     menuItem append $iconMenu "item 1"
     menuItem append $iconMenu "item 2"
     menuItem append $iconMenu "item 3"
     menuItem append $iconMenu "item 4"
     menuItem append $iconMenu "item 5" -enabled 0
     # Create dynamic items
     menuItem append $iconMenu "dynamic 1" -dynamic 1
     menuItem append $iconMenu "dynamic 2" -dynamic 1 -modifiers "o"
     menuItem append $iconMenu "dynamic 3" -notAlternate 1 -dynamic 1
     menuItem append $iconMenu "dynamic 4" -dynamic 1 -modifiers "z"

     # Change some properties (1=bold)
     menuItem set $iconMenu 0 -style 1
     # Put a Unicode mark: 03A3 is the code-point of the Greek capital 
     # letter sigma.
     menuItem set $iconMenu 1 -unimark \u03A3
     menuItem set $iconMenu 2 -icon "ques"

     # Query properties
     menuItem set $iconMenu 6 -dynamic

     # Populate the "Test" menu
     menuItem append $testMenu "test item 1"
     menuItem append $testMenu "test item 2"
     menuItem append $testMenu "test item 3"
     menuItem append $testMenu "test item 4"

     # Disable an item
     menuItem set $iconMenu 3 -enabled 0

     # Add a separator and a section header
     menuItem append $iconMenu "" -separator 1
     menuItem append $iconMenu "Section header" -header 1

     # Get the list of items
     menuItem list $iconMenu

     # Count the items
     menuItem count $iconMenu

     # Indent the section header item
     menuItem set $iconMenu 11 -indent 1

     # Hide the second item (its index is 1)
     menuItem set $iconMenu 1 -hidden 1

     # Show it again
     menuItem set $iconMenu 1 -hidden 0

     # Insert an item at the top of the menu (the -ignoreMeta option causes the
     # dash not to generate a separator)
     menuItem insert $iconMenu 0 "-40 degrees F" -ignoreMeta 1

     # Delete this first item
     menuItem delete $iconMenu 0

     # Put a checkmark in front of an item
     menuItem check $iconMenu 3 1

     # Change the style (2=italic)
     menuItem set $iconMenu 3 -style 2

     # Hilite the test menu
     menuRef hilite $testMenu 1
     # Unhilite it
     menuRef hilite $testMenu 0

     # Remove the test menu
     menuRef remove $testMenu
     # Re-insert it before the icon menu
     menuRef insert $testMenu -before $iconMenu

     # Create a new menu which will be later used as a submenu
     set testSubmenu [menuRef create -title TestSub -command testMenuRefProc]

     # Populate the "Test" menu
     menuItem append $testSubmenu "subitem 1"
     menuItem append $testSubmenu "subitem 2"
     menuItem append $testSubmenu "subitem 3"
     menuItem append $testSubmenu "subitem 4"

     # Make it a submenu of the second item in the icon menu
     menuItem set $iconMenu 1 -submenu $testSubmenu

     # Make the submenu title itself selectable
     menuItem set $iconMenu 1 -parentChoosable 1

     # Detach the submenu from the menu item
     menuItem set $iconMenu 1 -submenu ""

     # Suppose you have an icon file named Kandinsky.icns in the Application
     # Support folder. First register the icon (under the KAND type for
     # instance). and then apply it to the menu.
     set icnsFile [file join $SUPPORT(user) Images Kandinsky.icns]
     iconref register -file $icnsFile KAND
     menuRef set $iconMenu -icon KAND

     # Delete the Test menu
     menuRef delete $testMenu    

More sample instructions concerning menu shortcuts can be found on the Binding Command page on this wiki.

(add your comments here...)

Retrieved from
Page last modified on October 24, 2009, at 07:43 AM