Object

MenuItem Class

An individual menu item.

Events
Action
EnableMenu

Properties
AutoEnable | Icon | Tag
BalloonHelp | Index | Text
Checked | KeyboardShortCut | Visible
DisabledBalloonHelp | Name |
Enabled | Submenu |

Methods
Append | Insert
Child | Item
Close | Popup
Count | Remove
Enable |

# Notes

MenuItem objects are used to access the properties of menu items. You can change the menu item text using the Text property. You can find out if a menu item is checked, or check or uncheck a menu item with the Checked property. You can also enable or disable a menu item using the Enabled property. The Enabled property should be set only from within an EnableMenuitems event handler. Setting it from anywhere else has no effect.

MenuItem has a constructor that lets you set the Text and optionally the Tag of the new MenuItem. Pass the value of the Text property and optionally the Tag when instantiating the MenuItem.

Three other classes handle specialized menu items. QuitMenuItem is designed to manage the File . Quit (File . Exit on Windows and Linux) menu of a built application; it is enabled by default and automatically calls the Quit method. The PrefsMenuItem class is designed to handle the Preferences menu item. In Mac OS X, this menu item is supposed to be located under the application's menu, but on other operating systems, this menu does not exist. A menu item derived from the PrefsMenuItem class automatically appears under the application's menu under Mac OS X; on other operating systems is appears where you put it in the Menu Editor. The AppleMenuItem class is designed for creating menu items that appear under the Apple menu on Mac OS "classic" systems. Any menu subclassed from AppleMenuItem will move to the Apple menu for your Mac OS "classic" build but stay where it is for your other builds.

MenuItems can be created on the fly using the New operator. See the New operator for more information.

Specifying the keyboard shortcut in the Menu Editor

When you use the Properties pane in the Menu Editor, you specify the menu item's shortcut key by assigning a key to the Key property and (normally) at least one modifier key. The Menu Editor translates your settings into the value for the KeyboardShortcut property.

You can use either a printable key or the following non-printable keys as shortcut keys: F1-F15, Tab, Enter, Space, Del (Delete), Return, Bksp (Backspace), Esc, Clear, PageUp, PageDown, Left, Right, Up, Down, Help, and Ins (Insert). If the shortcut key is more than one character and it is being sent via code, the modifier key is not implied and must be explicitly defined. For example, the following line sets the Tab key as the shortcut key and uses the Ctrl key as the modifier.

SpecialMyMenuItem.KeyboardShortcut="Ctrl-Tab"

When you are setting a non-printable key in the IDE, you can just enter its name from the list above and select the desired modifier key from the following list.

The Key property entry and the entries for the modifier keys are described in the table below.

Name | Description
--- | ---
AlternateMenuModifier | The Shift key on all platforms. If selected, the Shift key must be held down while pressing the value of the Key property to trigger the event handler of the MenuItem.
Key | The shortcut key for the menu item. If this key and the selected modifier keys set is held down, the event handler for the menu item will be executed as if the menu item itself were chosen via the mouse pointer.
MacControlKey | The Control key on Macintosh. This property is Macintosh-only. If selected, the Control key must be held down while pressing the value of the Key property in order to trigger the event handler of the menuitem.
MacOptionKey | The Option key on Macintosh. This property is Macintosh-only. If selected, the Option key must be held down while pressing the value of the Key property to trigger the event handler of the menu item.
MenuModifier | The Control key on Windows and Linux and the Command key on Macintosh. If this property is selected, the MenuModifier key must be held down while pressing the key specified by the Key property to trigger the event handler for the menu item.
PCAltKey | If selected, the Alt key is must be held down while pressing the value of the Key property in order to trigger the event handler for the menu item. This property is for Windows and Linux only.

# Examples

The following example changes the text of the EditPaste menu item to "Paste Special…":

EditPaste.text="Paste Special…"

The following example inserts a new item in the Edit menu with the text "Paste Special..." just below the Paste item.

Dim EditPasteSpecial as New MenuItem
EditPasteSpecial.text="Paste Special..."
Editmenu.Insert(5,EditPasteSpecial)

Using the constructor, you can write:

Dim EditPasteSpecial as New MenuItem("Paste Special...")
Editmenu.Insert(5,EditPasteSpecial)

The following example adds a Select All menu item to the Edit menu.

Dim EditSelectAll as New MenuItem
EditSelectAll.text="Select All..."
Editmenu.Append(EditSelectAll)

The following example gets the MenuItem corresponding to the Cut item on the Edit menu.

Dim c as MenuItem
c=EditMenu.child("EditCut")
MsgBox c.text

The following example gets the MenuItem corresponding to the Cut item on the Edit menu by position:

Dim c as MenuItem
c=EditMenu.item(2)
MsgBox c.text

The following example removes the fourth dynamically created menu item from a menu item array named WindowItem:

WindowItem(3).Close

The following example assigns a value to the Tag property of a menu item:

SearchFind.Tag="UserSearch"

The following example displays the Edit menu as a contextual menu. The code is in the MouseDown event handler of a RectControl. You can get the text of the selected item by accessing the Text property of the returned MenuItem.

If IsContextualClick Then
Dim m as MenuItem
m=EditMenu.Popup
End if

Note that you can also create and display contextual menus using the ConstructContextualMenu and ContextualMenuAction event handlers of the Window and RectControl classes.

# See Also

AppleMenuItem, PrefsMenuItem, QuitMenuItem classes; IsContextualClick, EnableMenuItems functions, New operator.