• 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 "*" and \u2022 are equivalent. To insert or remove a check mark, one can also use the [menuItem check] command directly.

with the -mark option.

• 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, "*" and \u2022 are equivalent. To insert or remove a check mark, one can also use the [menuItem check] command directly.

     # Put a Unicode mark: 03A3 is the code-point of the Greek capital 
     # letter sigma.
     menuItem set $iconMenu 1 -unimark \u03A3

• the -mark option lets you specify a symbol to use as a mark before the menu item: the symbol is any character in MacRoman encoding. If you want to insert a Unicode character, use the -unimark option instead. To insert or remove a check mark, one can also use the [menuItem check] command directly.

• the -unimark option lets you specify a symbol to use as a mark before the menu item: this symbol can be any Unicode character designated with the \u escape sequence. The -mark and the -unimark options are mutually exclusive: the -unimark option has precedence over the -mark option.

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

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

-nocase

Causes comparisons to be handled in a case-insensitive manner.

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:

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. 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? ?-not?

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 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 signifcation:

-all

Return a list of all the matches rather than only the first one.

-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.

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

     menuItem append $iconMenu "item 5" -enabled 0

     menuItem set $iconMenu 11 -indent 1

Both the integer((+|-)integer)? and the end((+|-)integer)?

• Menu item indices
• Menu item options
• Menu item shortcuts
• Examples

by its text. The first item is at index 0. The syntax is:

item is inserted at the end of the menu. The first item is at index 0. The syntax is:

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

Menu item shortcuts

Examples

     menuItem set $iconMenu 0 -style 1
     menuItem set $iconMenu 1 -mark *
     menuItem set $iconMenu 2 -icon "ques"

     menuItem set $iconMenu 3 -enabled 0

     menuItem set $iconMenu 10 -indent 1

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

     menuItem set $iconMenu 1 -hidden 0

     menuItem insert $iconMenu 0 "-40 degrees F" -ignoreMeta 1

     menuItem delete $iconMenu 0

     menuItem check $iconMenu 3 1

     menuItem set $iconMenu 3 -style 2

     menuItem set $iconMenu 1 -submenu $testSubmenu

     menuItem set $iconMenu 1 -parentChoosable 1

     menuItem set $iconMenu 1 -submenu ""

(add your comments here...)

     menuItem check menu index (0|1)

This file documents the new [menuItem] command in version 8.2a1d4 of AlphaX. This is an experimental command proposed as a part of the bindings reform. It is open to discussion.

• Menu item options

     menuItem append menu text ?option value...?

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

     menuItem index menu text ?-all? 

specify the -all option in order to get a list of all the

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

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

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

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:

• the -header option takes the values 0 or 1. When it is set to 1, any text in the item is ignored.

• the -ignoreMeta option lets you set or unset the ignoreMeta attribute. Set its value to 1 to ignore the dash (-) metacharacter in this menu item. Dashes at the beginning of a menu item title traditionally signify that the menu item is a separator. However, in some cases you might want to display the dash in the title (for example, if you wanted the menu item to read -40 degrees F.)

• 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 text of a menu item is a single dash, the item is automatically drawn as a separator: this is another way of creating a menu separator.

     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"

If the item is not found, the command raises an error.

     menuItem index menu text ?-all?

     menuItem index menu ?-all? text ?-all?

• The [index] subcommand
• The [insert] subcommand
• The [set] subcommand

• Menu item attributes
• Menu item shortcuts
• Examples

The [index] subcommand

This subcommand returns the index of a menu item specified by its text. The first item is at index 1. The syntax is:

     menuItem index menu ?-all? text 

In a properly designed menu, all the items should be different. It is possible though that, in some circumstances, several items have the same text: this could happen when the menu is built at runtime out of a list of arbitrary data which are not necessarily unique. In that case, one can specify the -all option in order to get the list of all the matching indices.

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 1. The syntax is:

 
     menuItem insert menu index text ?attribute (0|1)...?

The [set] subcommand

Menu item attributes

Menu item shortcuts

Examples

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.

-hidden

The menu item is not drawn when displaying the menu. The item is also not included in command-key matching unless the -dynamic attribute is set.

-ignoreMeta

Ignore the dash (-) metacharacter in this menu item. Dashes at the beginning of a menu item title traditionally signify that the menu item is a separator. However, in some cases you might want to display the dash in the title (for example, if you wanted the menu item to read -40 degrees F.)

-header

The menu item is a menu section header: this item is disabled and not selectable.

This file documents the new [menuItem] command introduced in version 8.2a1d1 of AlphaX. This is an experimental command proposed as a part of the bindings reform. It is open to discussion.

• 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.

 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. 

-hidden

The menu item is not drawn when displaying the menu. The item is also not

included in command-key matching unless the -dynamic attribute is set.

-ignoreMeta

Ignore the dash (-) metacharacter in this menu item. Dashes at the

beginning of a menu item title traditionally signify that the menu item is a separator. However, in some cases you might want to display the dash in the title (for example, if you wanted the menu item to read -40 degrees F.)

-header

The menu item is a menu section header: this item is disabled and not

selectable.

Some of these attributes can be modified later using the [menuItem set] command.

Starting with version 8.2a1d1, keyboard shortcuts (if they exist) are

Keyboard shortcuts can be defined with the new [binding] command

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:

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

     menuItem set $iconMenu $idx -modifiers "o"

     menuItem set $iconMenu $idx -modifiers "z"

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

Some of these attributes can be modified later using the [menuItem set] command.

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

-hidden

The menu item is not drawn when displaying the menu. The item is also not included in command-key matching unless the -dynamic attribute is set.

-ignoreMeta

Ignore the dash (-) metacharacter in this menu item. Dashes at the beginning of a menu item title traditionally signify that the menu item is a separator. However, in some cases you might want to display the dash in the title (for example, if you wanted the menu item to read -40 degrees F.)

-header

The menu item is a menu section header: this item is disabled and not selectable.

• the -text option lets you specify the text of the menu item. The command does not perform any transformation on the text (such as prettifying, menu forms).

• Menu item shortcuts
• Examples

menuItem subcommand ?options?

     menuItem append menu text ?attribute (0|1)...?

     menuItem check menu

     menuItem delete menu index

     menuItem insert menu index text ?attribute (0|1)...?

     menuItem set menu index option
     menuItem set menu index option value ?option value...?

• the -action option lets you specify an action attached to the menu item. The value of this option is a token previously obtained with the [action create] command (see the ActionCommand page on this wiki). When the menu item will be selected, this action will be executed rather than the proc attached to the menu itself. If no action has been specified, the menu proc is executed instead.
• the -commandKey option lets you specify a keyboard equivalent !! !! for the menu item. By default the key is used in association with the !! !! Command key but this can be modified with the -modifiers option. !! !! The command key can also be interpreted either as a character code (this is !! !! the default behavior), or as a virtual key code (see the -virtual !! !! option).
• the -dynamic option lets you specify whether the menu item is 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. Usually one assigns them the same command key but it is also possible to have dynamic items without a command key equivalent. Each item of a dynamic group must be assigned a key modifier (see the -modifiers option). See also the -notAlternate option to start a new dynamic group.

• the -glyph option lets you specify a glyph to represent a !! !! particular key from the keyboard when it corresponds to a key shortcut and !! !! is not a single letter. The value of this option is a decimal number: see !! !! the Menu item glyphs section below for the possible !! !! values.

• the -icon option lets you specify an icon to attach to the menu item. Its value is a four character code corresponding to a registered icon reference: see the IconrefCommand documentation on this wiki. One can also find a list of predefined icons in the Icon codes section of the Toolbar Command page.

• the -modifiers option lets you specify the modifier keys associated with dynamic items: it defines the modifier keys which must be used to select items 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 c, o, s and z letters:

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

• the -notAlternate option lets you specify that the menu item is not part of the same dynamic group as the previous item (see the -dynamic option). You should set this flag for the first menu item in a new dynamic group.
• the -parentChoosable option lets you specify whether the menu item is selectable or not when a submenu is attached to it. The values for this option are 0 or 1. By default it is not selectable (value 0).
• 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.
• the -style option lets you specify the style of the menu item. Its value is an additive value combining the following base-2 numbers:

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

• the -virtual option tells whether a keyboard shortcut !! !! attached to a menu item is to be interpreted as a character code or a !! !! virtual key code (the values for this option are 0 and 1 respectively).

Here is the list of the available attributes and their signification when the value is set to 1:

-hidden

The menu item is not drawn when displaying the menu. The item is also not

included in command-key matching unless the -dynamic attribute is set.

-ignoreMeta

Ignore the dash (-) metacharacter in this menu item. Dashes at the

beginning of a menu item title traditionally signify that the menu item is a separator. However, in some cases you might want to display the dash in the title (for example, if you wanted the menu item to read -40 degrees F.)

-header

The menu item is a menu section header: this item is disabled and not

selectable.

Menu item shortcuts

Starting with version 8.1a5d4, key shortcuts (if they exist) are automatically attached to menu items.

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

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 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" -disabled 1
     # Create dynamic items
     set idx [menuItem append $iconMenu "dynamic 1" -dynamic 1]
     set idx [menuItem append $iconMenu "dynamic 2" -dynamic 1]
     menuItem set $iconMenu $idx -modifiers 2
     set idx [menuItem append $iconMenu "dynamic 3" -notAlternate 1 -dynamic 1]
     set idx [menuItem append $iconMenu "dynamic 4" -dynamic 1]
     menuItem set $iconMenu $idx -modifiers 4

     # Change some properties (1=bold)
     menuItem set $iconMenu 1 -style 1
     menuItem set $iconMenu 2 -mark *
     menuItem set $iconMenu 3 -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 4 -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
     menuItem set $iconMenu 2 -hidden 1

     # Show it again
     menuItem set $iconMenu 2 -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 1 "-40 degrees F" -ignoreMeta 1

     # Delete this first item
     menuItem delete $iconMenu 1

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

     # Change the style (2=italic)
     menuItem set $iconMenu 4 -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 2 -submenu $testSubmenu

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

     # Detach the submenu from the menu item
     menuItem set $iconMenu 2 -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    

(add your comments here...)

	 menuItem append menu text ?attribute (0|1)...?

	 menuItem check menu

	 menuItem delete menu index

	 menuItem insert menu index text ?attribute (0|1)...?

	 menuItem set menu index option
	 menuItem set menu index option value ?option value...?

• the -commandKey option lets you specify a keyboard equivalent for the menu item. By default the key is used in association with the Command key but this can be modified with the -modifiers option. The command key can also be interpreted either as a character code (this is the default behavior), or as a virtual key code (see the -virtual option).

• the -virtual option tells whether a keyboard shortcut attached to a menu item is to be interpreted as a charaacter code or a virtual key code (the values for this option are 0 and 1 respectively).

-virtual

When comparing this item's keyboard equivalent against a keyboard event, use the item's virtual keycode equivalent rather than its character code equivalent.

keyboard equivalent matching, depending on whether the -virtual

	 menuItem set menu index -virtual 0

to clear the -virtual item attribute.

	 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" -disabled 1
	 # Create dynamic items
	 set idx [menuItem append $iconMenu "dynamic 1" -dynamic 1]
	 menuItem set $iconMenu $idx
	 set idx [menuItem append $iconMenu "dynamic 2" -dynamic 1]
	 menuItem set $iconMenu $idx -modifiers 2
	 set idx [menuItem append $iconMenu "dynamic 3" -notAlternate 1 -dynamic 1]
	 menuItem set $iconMenu $idx -commandKey 66
	 set idx [menuItem append $iconMenu "dynamic 4" -dynamic 1]
	 menuItem set $iconMenu $idx -modifiers 4 -commandKey 66

	 # Change some properties (1=bold)
	 menuItem set $iconMenu 1 -style 1
	 menuItem set $iconMenu 2 -mark *
	 menuItem set $iconMenu 3 -icon Beet

	 # 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"

	 # 104 is the up arrow key
	 menuItem set $iconMenu 4 -enabled 0 -glyph 104

	 # 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
	 menuItem set $iconMenu 2 -hidden 1

	 # Show it again
	 menuItem set $iconMenu 2 -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 1 "-40 degrees F" -ignoreMeta 1

	 # Delete this first item
	 menuItem delete $iconMenu 1

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

	 # Change the style (2=italic)
	 menuItem set $iconMenu 4 -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 2 -submenu $testSubmenu

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

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

	 # Bind the first item to ctrl-opt-cmd-a
	 menuItem set $testMenu 1 -virtual 0 -commandKey 65 -modifiers 6

	 # Bind the second item to opt-cmd-F5
	 #    virtual keycode for F5 is 96
	 #    glyph for F5 is 115
	 menuItem set $testMenu 2 -virtual 1 -commandKey 96 -glyph 115 -modifiers 2

	 # 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    

     # Result: menu1 menu2 etc.

     # Bind the first item to ctrl-opt-cmd-a
     menuItem set $testMenu 1 -virtualKey 0 -commandKey 65 -modifiers 6

     # Bind the second item to opt-cmd-F5
     #    virtual keycode for F5 is 96
     #    glyph for F5 is 115
     menuItem set $testMenu 2 -virtualKey 1 -commandKey 96 -glyph 115 -modifiers 2

-disabled

This menu item is disabled

-dynamic

This menu item changes dynamically based on the state of the modifier keys.

-hidden

The menu item is not drawn when displaying the menu. The item is also not included in command-key matching unless the -dynamic attribute is set.

-ignoreMeta

Ignore the dash (-) metacharacter in this menu item. Dashes at the beginning of a menu item title traditionally signify that the menu item is a separator. However, in some cases you might want to display the dash in the title (for example, if you wanted the menu item to read -40 degrees F.)

-notAlternate

This item is not part of the same dynamic group as the previous item.

-header

The menu item is a menu section header: this item is disabled and not selectable.

-separator

The menu item is a separator: any text in the item is ignored.

-parentChoosable

The user can select the parent item of a submenu.

-virtualKey

When comparing this item's keyboard equivalent against a keyboard event, use the item's virtual keycode equivalent rather than its character code equivalent.

Here is a list of the main virtual keycodes with the value of the corresponding glyph:

• The [delete] subcommand
• The [insert] subcommand
• The [set] subcommand

• Menu item attributes
• Menu item glyphs
• Modifier key constants
• Character codes vs. virtual keycodes
• Examples

The [delete] subcommand

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

     menuItem delete menu index

The [insert] subcommand

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...?

Menu item attributes

Menu item glyphs

Modifier key constants

Character codes vs. virtual keycodes

Examples

     # Delete the Test menu
     menuRef delete $testMenu    

(:title The [menuItem] command:)

This file documents the new [menuItem] command introduced in version 8.1 of AlphaX. This is an experimental command proposed as a part of the bindings reform. It is open to discussion.

• Introduction
• Synopsis
  • The [append] subcommand
  • The [check] subcommand
  • The [count] subcommand
  • The [delete] subcommand
  • The [insert] subcommand
  • The [list] subcommand
  • The [set] subcommand
• Menu item attributes
• Menu item glyphs
• Modifier key constants
• Character codes vs. virtual keycodes
• Examples

Introduction

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.

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 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 ?attribute (0|1)...?

The possible attributes are described in the Menu item attributes 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

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

The [count] subcommand

This subcommand returns the number of menu items in a menu. The syntax is:

 
     menuItem count menu

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 [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 1. The syntax is:

 
     menuItem insert menu index text ?attribute (0|1)...?

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

The [list] subcommand

This subcommand returns a list of all the items currently present in the menu, in the index order. The syntax is:

 
     menuItem list menu

This command should not be confused with the [menuRef list] command which returns the current list of menus.

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. Here is the list of the available options:

• the -commandKey option lets you specify a keyboard equivalent for the menu item. By default the key is used in association with the Command key but this can be modified with the -modifiers option. The command key can also be interpreted either as a character code (this is the default behavior), or as a virtual key code (see the -virtualKey option).
• the -dynamic option lets you specify whether the menu item is 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 and assign them the same command key (but it is also possible to have dynamic items without a command key equivalent). Each item of a dynamic group must be assigned a key modifier (see the -modifiers option). See also the -notAlternate option to start a new dynamic group.
• the -enabled option takes the values 0 or 1 to respectively disable or enable the menu item
• the -glyph option lets you specify a glyph to represent a particular key from the keyboard when it corresponds to a key shortcut and is not a single letter. The value of this option is a decimal number: see the Menu item glyphs section below for the possible values.
• 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 four character code corresponding to a registered icon reference: see the IconrefCommand documentation on this wiki.
• the -ignoreMeta option lets you set or unset the ignoreMeta attribute. See the Menu item attributes section below.
• 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 -mark option lets you specify a symbol to use as a mark before the menu item. To insert or remove a check mark, one can also use the [menuItem check] command directly.
• the -modifiers option lets you specify the modifier keys associated with a menu shortcut. The value of this option is an additive value made of the following base-2 constants: see the Modifier key constants section below.
• the -notAlternate option lets you specify that the menu item is not part of the same dynamic group as the previous item (see the -dynamic option). You should set this flag for the first menu item in a new dynamic group.
• the -parentChoosable option lets you specify whether the menu item is selectable or not when a submenu is attached to it. The values for this option are 0 or 1. By default it is not selectable (value 0).
• the -style option lets you specify the style of the menu item. Its value is an additive value combining the following base-2 numbers:

 Not all combinations are supported by the Menu Manager or by the System font. 

• 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 -text option lets you specify the text of the menu item. The command does not perform any transformation on the text (such as prettifying, menu forms).
• the -virtualKey option tells whether a keyboard shortcut attached to a menu item is to be interpreted as a charaacter code or a virtual key code (the values for this option are 0 and 1 respectively).

Menu item attributes

The [menuItem append] and [menuItem insert] commands accept some attributes. All these attributes are specified by an option (starting with a dash) and followed by 0 or 1: they are set to zero by default. Here is the list of the available attributes and their signification:

-disabled This menu item is disabled. l

t)) ((lt -dynamic This menu item changes dynamically based on the state of the modifier keys. l

t)) ((lt -hidden The menu item is not drawn when displaying the menu. The item is also not included in command-key matching unless the -dynamic attribute is set. l t)) ((lt -ignoreMeta Ignore the dash (-) metacharacter in this menu item. Dashes at the beginning of a menu item title traditionally signify that the menu item is a separator. However, in some cases you might want to display the dash in the title (for example, if you wanted the menu item to read -40 degrees F.) l t)) ((lt -notAlternate This item is not part of the same dynamic group as the previous item. l t)) ((lt -header The menu item is a menu section header: this item is disabled and not selectable. l t)) ((lt -separator The menu item is a separator: any text in the item is ignored. l t)) ((lt -parentChoosable The user can select the parent item of a submenu. l t)) ((lt -virtualKey When comparing this item's keyboard equivalent against a keyboard event, use the item's virtual keycode equivalent rather than its character code equivalent. l t)) Some of these attributes can be modified later using the [menuItem set] command.

Menu item glyphs

Here is a table of the decimal constants which can be used with the [menuItem set -glyph] command.

Modifier key constants

Specify modifier keys used with menu item selections. You can use one or more of these mask constants to determine which modifier key(s) must be pressed along with a character key to create a keyboard equivalent for selecting a menu item. You set and obtain these constants by calling the [menuItem set -modifiers] command.

Character codes vs. virtual keycodes

A menu item's keyboard equivalent may be either a character code or a virtual keycode. An item's character code and virtual keycode are stored separately and may contain different values, but only one is used by the Menu Manager at any given time. The character code is always used to draw the item's keyboard equivalent in the menu, but either may be used for keyboard equivalent matching, depending on whether the -virtualKey item attribute is set. To make the menu item stop using the virtual keycode equivalent and use the character code equivalent instead, use

 
     menuItem set menu index -virtualKey 0

to clear the -virtualKey item attribute. Note that zero is a valid virtual keycode.

Examples

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: menu2000 menu2001 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" -disabled 1
     # Create dynamic items
     set idx [menuItem append $iconMenu "dynamic 1" -dynamic 1]
     menuItem set $iconMenu $idx
     set idx [menuItem append $iconMenu "dynamic 2" -dynamic 1]
     menuItem set $iconMenu $idx -modifiers 2
     set idx [menuItem append $iconMenu "dynamic 3" -notAlternate 1 -dynamic 1]
     menuItem set $iconMenu $idx -commandKey 66
     set idx [menuItem append $iconMenu "dynamic 4" -dynamic 1]
     menuItem set $iconMenu $idx -modifiers 4 -commandKey 66

     # Change some properties (1=bold)
     menuItem set $iconMenu 1 -style 1
     menuItem set $iconMenu 2 -mark *
     menuItem set $iconMenu 3 -icon Beet

     # 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"

     # 104 is the up arrow key
     menuItem set $iconMenu 4 -enabled 0 -glyph 104

     # 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
     menuItem set $iconMenu 2 -hidden 1

     # Show it again
     menuItem set $iconMenu 2 -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 1 "-40 degrees F" -ignoreMeta 1

     # Delete this first item
     menuItem delete $iconMenu 1

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

     # Change the style (2=italic)
     menuItem set $iconMenu 4 -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 2 -submenu $testSubmenu

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

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

     # 106 (0x6a) is the F16 key
     menuItem set $testMenu 1 -virtualKey 1
     menuItem set $testMenu 1 -commandKey 96  

     # 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    

(add your comments here...)