The [menuItem] command.

Introduction

The menuItem command lets you manipulate menu items in Alpha's menus. The menus can be created and manipulated using the [menuRef] command.

Synopsis

The formal syntax of the [menuItem] command is:
menuItem subcommand ?options?
The possible subcommands are described below. Depending on the subcommand, various options can additionally be 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.

The [append] subcommand

This subcommand lets you append a new menu item. It returns the (0-based) 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 [index] subcommand

This subcommand returns the index of a menu item. The first item is at index 0. The command can take two forms:
    menuItem index menu -tag num
    menuItem index menu text ?-(exact|glob|regexp)? ?-all? ?-inline?
				?-nocase? ?-not?

In the first form, the command returns the index of the first menu item with the given tag. If no such menu item is found in the menu, the returned value is -1. This is useful to find menu items which have been attributed a tag. A menu item can be attributed a tag with the -tag option in the
[menuItem append], [menuItem set] and [menuItem insert] commands.
In the second form, one specifies the text of the item(s) to find and possibly some extra options to tell how the search should be performed. The -exact, -glob, and -regexp options let you specify how the text is to be matched against the menu items:
-exact
The text argument is a literal string that is compared for exact equality against each menu item.
-glob
The text argument is a glob-style pattern which is matched against each menu item using the same rules as with the [string match] Tcl command.
-regexp
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 signification:
-all
Return a list of all the matches rather than only the first one.
-nocase
Causes comparisons to be handled in a case-insensitive manner.
-inline
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.
-not
This negates the sense of the match, returning the index of the first non-matching value in the list.

In the second form, 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 [remove] subcommand

This subcommand removes an item from a menu. The syntax is:
    menuItem remove menu index
If you specify a negative value or an index number past the last item in the menu, the command does nothing.

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
insert, remove, 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.
Here is the list of the menu item options:

Menu item shortcuts

Keyboard shortcuts (aka bindings) are automatically attached to menu items (and drawn in the menu).
Keyboard shortcuts are defined with the
[binding] command: each key binding is associated with a Tcl proc. If the same Tcl proc is also attached to a menu item (using the [menuItem set -command] command), then the binding is automatically displayed in the menu as the menu item key equivalent.
If necessary, the automatic attachment of bindings to menu items can be disabled:

Examples

Here are a few basic examples which can be executed one by one in the Tcl shell in Alpha:
    proc testMenuRefProc {token item} {
    	alertnote "Item $item of menu $token 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 1
    # Create dynamic items
    menuItem append $iconMenu "dynamic 1" 
    menuItem append $iconMenu "dynamic 2" -alternate 1 -modifiers "o"
    menuItem append $iconMenu "dynamic 3" 
    menuItem append $iconMenu "dynamic 4" -alternate 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 -mark \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
    menuItem insert $iconMenu 0 "-40 degrees F" -separator 0

    # Delete this first item
    menuItem remove $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    


Last updated 2017-02-12 12:05:36