From AlphaWiki

Commands: The [menuItem] command

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

• Introduction
• Synopsis
  • The [append] subcommand
  • The [check] subcommand
  • The [delete] subcommand
  • The [index] subcommand
  • The [insert] subcommand
  • The [set] subcommand
• Menu item indices
• Menu item options
• Menu item shortcuts
• 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 ?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:

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

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

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:

• 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 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 -enabled option takes the values 0 or 1 to respectively disable or enable the menu item

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

• 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. One can also find a list of predefined icons in the Icon codes section of the Toolbar Command page.

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

• 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 mechanism (see the BindingCommand page).

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

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

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:

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