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:

the -alternate option lets you specify whether the menu item is an alternate for a dynamic item. A dynamic item changes dynamically based on the state of the modifier keys. For example, holding down the command key might change the menu item from Close to Close All. When a menu item has alternate dynamic states, you should group them together sequentially in the menu: the first one is the default item and only the following ones must have the -alternate option set to 1. Usually one assigns them the same command key but it is also possible to have dynamic items without a command key equivalent. The first item of a group is declared using the -dynamic option. Each item of a dynamic group must be assigned a different key modifier (see the -modifiers option).
the -color option lets you specify a color to apply to the menu item. The color is specified by a color token obtained with the [colorRef create] command.
the -command option lets you specify a Tcl proc attached to the menu item. The value of this option is a Tcl proc or a Tcl code snippet. When the menu item is selected, this code will be executed rather than the proc attached to the menu itself. If no command has been specified, the menu proc is executed instead.
the -dynamic option lets you specify that the menu item starts a group of dynamic menu items. The next menu items which are part of the group must be declared with the -alternate option.
the -enabled option takes the values 0 or 1 to respectively disable or enable the menu item
the -hidden option takes the values 0 or 1 to respectively show or hide the menu item
the -icon option lets you specify an icon to attach to the menu item. Its value is a token typically obtained with the [imageRef create] command.
the -indent option lets you specify an indentation for the menu item: the value is an integer indicating the level of indentation (0 means no indentation). The value for the indentation level may be from 0 to 15. If the level is greater than 15, the value is pinned to the maximum. If it is less than 0, an exception is raised. The default level is 0.
the -mark option lets you specify a symbol to use as a mark before the menu item: this symbol can be any Unicode character. It can be specified as a string if it is a simple MacRoman character or using the \u escape sequence for any code-point in the BMP (between 0x0000 and 0xFFFF): for instance, for a bullet, the values "•" and \u2022 are equivalent. To insert or remove a check mark, one can use the [menuItem check] command directly.
the -modifiers option lets you specify the modifier keys associated with dynamic items: it defines the modifier keys which must be used to select an item in a group of dynamic items. The value of this option uses the same syntax as the [binding] command. It is a combination of the letters c, o, s, z with the following meaning:

Letter Description

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 (aka menu shortcuts) are defined through the bindings mechanism (see the [binding] reference file).
the -represented option lets you get or set the represented object associated with a menu item. It is up to the programmer to decide which object is associated with a menu item: this option is just meant as a storage for this information. The value of the option is any string you wish.
the -separator option takes the values 0 or 1. If it is set to 1, the item is a horizontal separator. Note that, by convention, if the title of a menu item is a single dash (and if the -separator option has not been explicitely set to 0), the item is automatically drawn as a separator: this is another way of creating a menu separator.
the -showKey option tells whether a keyboard shortcut attached to a menu item should be displayed or not. See the Menu Item Shortcuts section for more on this subject. This option has no effect if the -keyMatching option has been set to 0 on the entire menu.
the -state option indicates the state of the menu item which can be on, off or mixed corresponding respectively to the values 1, 0 or -1.
the -style option lets you specify the style of the menu item. The value of this option is an additive value containing the following flags:

Description Flag

normal 0

italic 1

bold 2

underline 4

strike through 8

expand 16

condense 32

The condense and expand values are mutually exclusive.
the -submenu option lets you specify a submenu attached to the menu item. Its value is a menu token designating a menu previously created with the [menuRef create] option.
the -tag option lets you set a tag for the menu item. The tag is a unique integer value which can be used to identify the menu item. In particular, it can be used with the [menuItem index] command to find the index of the menu item.
the -title option lets you specify the title (that is to say the text) of the menu item.
the -tip option lets you specify a short string that describes the menu item and which is displayed as a tool tip.
the -view option lets you specify the token of a view created with the [view create] command. The view will be inserted in the menu item. A menu item with a view does not draw its title, state, font, or other standard drawing attributes, and assigns drawing responsibility entirely to the view. Keyboard equivalents and type-select continue to use the key equivalent and title as normal.

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:

for an entire menu with the -keyMatching option, by setting its value to 0 via the [menuRef set] command;
for a particular menu item with the -showKey option, by setting its value to 0 via the [menuItem set] command.

Examples

Here are a few basic examples which can be executed one by one in the Tcl Shell (⌘Y):

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"

# 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 2019-10-17 13:29:30

Letter	Description
`c`	corresponds to the Command key (`⌘`)
`s`	corresponds to the Shift key (`⇧`)
`o`	corresponds to the Option key (`⌥`)
`z`	corresponds to the Control key (`⌃`)

Description	Flag
normal	0
italic	1
bold	2
underline	4
strike through	8
expand	16
condense	32