Class
# ApplicationMenuItem
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Warning
This item was deprecated in version 2021r3. Please use `DesktopApplicationMenuItem` as a replacement.
## Description
Used to place menu items in the Application menu on macOS. A menu item subclassed from ApplicationMenuItem is automatically moved to the Application menu for macOS builds. On all other target platforms, the menu item appears where you put it in the Menu Editor. You cannot place menu items directly in the Apple or application menus in the Menu Editor.
## Properties
table-centered_columns_3_and_4
| Name | Type | Read-Only | Shared |
|------------------------------------------------------------------------|------------------------------------|-----------|--------|
| `AutoEnabled` | `Boolean` | | |
| `Enabled` | `Boolean` | | |
| `Handle` | `Integer` | ✓ | |
| `HasAltKey` | `Boolean` | ✓ | |
| `HasCheckmark` | `Boolean` | | |
| `HasMacControlKey` | `Boolean` | ✓ | |
| `HasMacOptionKey` | `Boolean` | ✓ | |
| `HasSecondaryModifierKey` | `Boolean` | ✓ | |
| `HasStandardModifierKey` | `Boolean` | ✓ | |
| `Icon` | `Picture` | | |
| `Index` | `Integer` | ✓ | |
| `LastRowIndex` | `Integer` | ✓ | |
| `Name` | `String` | | |
| `Shortcut` | `String` | | |
| `ShortcutKey` | `String` | ✓ | |
| `Tag` | `Variant` | | |
| `Value` | `String` | | |
| `Visible` | `Boolean` | | |
## Methods
table-centered_column_4
| Name | Parameters | Returns | Shared |
|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|--------------------------------------|--------|
| `AddMenu` | Item As `MenuItem` | | |
| `AddMenuAt` | Index As `Integer`, Item As `MenuItem` | | |
| `Child` | Name As `String` | `MenuItem` | |
| `Clone` | | `MenuItem` | |
| `Close` | | | |
| `Constructor` | Text As `String`, \[Tag As `Variant` = `Nil`\] | | |
| `Count` | | `Integer` | |
| `MenuAt` | Index As `Integer` | `MenuItem` | |
| `Popup` | \[x As `Integer`, y As `Integer`\] | `MenuItem` | |
| `Remove` | Child As `MenuItem` | | |
| `RemoveMenuAt` | Index As `Integer` | | |
## Events
table-centered_column_4
| Name | Parameters | Returns |
|----------------------------------------------|------------|------------------------------------|
| `Action` | | `Boolean` |
| `EnableMenu` | | |
## Property descriptions
forsearch
ApplicationMenuItem.AutoEnabled
**AutoEnabled** As `Boolean`
If set to `True`, the **MenuItem** is enabled by default, as long as the `App` object or frontmost window has a menu handler for the menuitem.
There is no need to put code in the `EnableMenu` event handler to explicitly enable an autoenabled menu item. AutoEnabled is `True` by default. When you create dynamic menus by creating a new class based on **MenuItem**, AutoEnabled is also `True` by default. See the example on dynamic menus on the `MenuItem` page.
forsearch
ApplicationMenuItem.Enabled
**Enabled** As `Boolean`
Indicates whether or not the menu item is enabled.
For MenuItems that belong to an App or Window menu, this property should only be set to True in the EnableMenuItems event handler.
You can set it for MenuItems created for use by `contextual menus` or for use with the `Popup` method.
This example is in the EnableMenuItems event handler and it enables a menu.
``` xojo
FilePageSetup.Enabled = True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ApplicationMenuItem.Handle
**Handle** As `Integer`
Provides access to the appropriate underlying platform menu implementation.
This property is read-only.
If the requested handle type doesn't make sense for the platform the application is running on, a PlatformNotSupportedException is raised.
**MenuItem.HandleType** enumeration:
- CocoaNSMenuItem: Returns the underlying NSMenuItem. If there is a submenu, the NSMenu can be got through NSMenuItem's submenu method.
- WindowsParentHMENU: Returns the HMENU of the MenuItem if it is a submenu, otherwise it returns the parent's HMENU
- WindowsCommandID: Returns the unique menu item identifier for the MenuItem, used by various Win32 APIs such as GetMenuItemInfo
forsearch
ApplicationMenuItem.HasAltKey
**HasAltKey** As `Boolean`
The Alt key on Windows and Linux keyboards. 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 `MenuItem`. This property is for Windows and Linux only.
This property is read-only.
Use `MenuItem` to change this value at runtime.
forsearch
ApplicationMenuItem.HasCheckmark
**HasCheckmark** As `Boolean`
Indicates whether or not the menu item is checked.
forsearch
ApplicationMenuItem.HasMacControlKey
**HasMacControlKey** As `Boolean`
The Control key on Mac. This property is Mac-only. If selected, the Control key must be held down while pressing the value of the `ShortcutKey` property in order to trigger the event handler of the `MenuItem`.
This property is read-only.
Use `MenuItem` to change this value at runtime.
forsearch
ApplicationMenuItem.HasMacOptionKey
**HasMacOptionKey** As `Boolean`
The Option key on Mac. This property is Mac-only. If selected, the Option key must be held down while pressing the value of the `ShortcutKey` property to trigger the event handler of the `MenuItem`.
This property is read-only.
Use `MenuItem` to change this value at runtime.
forsearch
ApplicationMenuItem.HasSecondaryModifierKey
**HasSecondaryModifierKey** As `Boolean`
The Shift key on all platforms. If `True`, the Shift key must be held down while pressing the value of the Key property to trigger the event handler of the `MenuItem`.
This property is read-only.
Use `MenuItem` to change this value at runtime.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ApplicationMenuItem.HasStandardModifierKey
**HasStandardModifierKey** As `Boolean`
The Control key on Windows and Linux and the Command key on Mac. If this property is selected, the MenuModifier key must be held down while pressing the key specified by the `ShortcutKey` property to trigger the event handler for the `MenuItem`.
This property is read-only.
Use `MenuItem` to change this value at runtime.
forsearch
ApplicationMenuItem.Icon
**Icon** As `Picture`
A picture that is assigned to the **MenuItem**.
On macOS and Linux, the picture appears in its original size. Resize the icon externally before adding it to the project. On Windows, the icon is resized so that its size matches the height of the item's Text. In most cases icons that are 16x16 points look best.
Recent versions of Linux (that use recent version of the GNOME desktop manager), default to not showing menu icons. You can change the OS setting to display menu icons using terminal [](http://gnomeshell.wordpress.com/2011/09/11/show-and-hide-the-menu-icons/):
> gsettings set org.gnome.desktop.interface menus-have-icons true
The following code is in the `Open` event of the main window. The image appears to the left of the menu item's text.
``` xojo
EditFind.Icon = RedApple
```
forsearch
ApplicationMenuItem.Index
**Index** As `Integer`
The number of the selected MenuItem when it is part of an array.
This property is read-only.
forsearch
ApplicationMenuItem.LastRowIndex
**LastRowIndex** As `Integer`
The index of the last child menu item owned by this menu.
This property is read-only.
forsearch
ApplicationMenuItem.Name
**Name** As `String`
The name of the menu item. Set this property using the Menu Editor.
This example sets the name of a menuitem.
``` xojo
EditMenu.Item(2).Name = "Delete"
```
forsearch
ApplicationMenuItem.Shortcut
**Shortcut** As `String`
The keyboard shortcut for the **MenuItem**.
Use this property to set the shortcut in code. You can also specify a shortcut in the Inspector for the MenuItem.
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 set 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.
``` xojo
SpecialMyMenuItem.Shortcut = "Ctrl-Tab"
```
For macOS, use "Cmd" instead of "Ctrl." Or set the `HasStandardModifierKey` property to `True` in the IDE and pass the string literal for the desired keyboard shortcut.
forsearch
ApplicationMenuItem.ShortcutKey
**ShortcutKey** As `String`
The shortcut key for the menu item. If this key and the selected modifier keys are held down, the event handler for the menu item will be executed as if the `MenuItem` itself were chosen via the mouse pointer.
This property is read-only.
When you use the Inspector for 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 `Shortcut` 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).
To set the shortcut in code, use the `MenuItem` property. If the shortcut key is more than one character and it is being set 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.
``` xojo
SpecialMyMenuItem.Shortcut = "Ctrl-Tab"
```
For macOS, use "Cmd" instead of "Ctrl." Or set the `HasStandardModifierKey` property to `True` in the IDE and pass the string literal for the desired keyboard shortcut.
forsearch
ApplicationMenuItem.Tag
**Tag** As `Variant`
A “hidden” value associated with the menu item.
The tag is accessible via code when the user chooses the menu item but, unlike the Text property, is not displayed in the menu. It works like the RowTag property of a `PopupMenu` control.
This example is in the Open event of the main window.
``` xojo
EditFind.Tag = "Search"
```
forsearch
ApplicationMenuItem.Value
**Value** As `String`
The value (text) of the menu item.
This example is in the Open event of the main window.
``` xojo
EditFind.Text = "Find..."
```
forsearch
ApplicationMenuItem.Visible
**Visible** As `Boolean`
Indicates whether or not the menu item is visible. The default is `True`. If `False`, the menu item does not appear and no blank space is for it is in the menu.
This property does nothing on Windows so use `MenuItem` instead.
This code is in the Open event of the main window:
``` xojo
EditFind.Visible = False
```
## Method descriptions
forsearch
ApplicationMenuItem.AddMenu
**AddMenu**(Item As `MenuItem`)
Adds the passed MenuItem to the menu. You can add a Separator by passing the class constant MenuItem.TextSeparator. Used to build a dynamic menu.
The following code creates a contextual menu in the ConstructContextualMenu event of any `Window` or `RectControl`. This event passes in the parameter base as MenuItem.
``` xojo
base.AddMenu(New MenuItem("Import"))
base.AddMenu(New MenuItem("Export"))
base.AddMenu(New MenuItem(MenuItem.TextSeparator))
base.AddMenu(New MenuItem("Cut"))
base.AddMenu(New MenuItem("Copy"))
base.AddMenu(New MenuItem("Paste"))
Return True ' display the contextual menu
```
The following code creates a hierarchical menu that is added to the main menubar. It is in the Open event of the App or the window. It's easiest to create menus and menuitems using the built-in Menu Editor and enable the MenuItems using the AutoEnable property. Use code for cases such as dynamic menus and contextual menus.
``` xojo
Var m, mNew As MenuItem
m = Self.MenuBar
mNew = New MenuItem
mNew.Value = "View"
mNew.Name = "View"
mNew.AddMenu(New MenuItem("As Icons"))
mNew.AddMenu(New MenuItem("As List"))
mNew.AddMenu(New MenuItem("As Columns"))
mNew.AddMenu(New MenuItem( "-" ))
Var submenu As New MenuItem("Sort By")
submenu.AddMenu(New MenuItem("Name"))
submenu.AddMenu(New MenuItem("Kind"))
submenu.AddMenu(New MenuItem("Size"))
mNew.AddMenu(submenu)
m.AddMenu(mNew)
```
forsearch
ApplicationMenuItem.AddMenuAt
**AddMenuAt**(Index As `Integer`, Item As `MenuItem`)
Adds *Item* as a MenuItem at the position indicated by *Index*. Index is zero-based.
You can add a Separator by passing the class constant MenuItem.TextSeparator.
The following example adds a new item in the Edit menu with the text "Paste Special..." just below the Paste item.
``` xojo
Var editPasteSpecial As New MenuItem
editPasteSpecial.Text = "Paste Special..."
EditMenu.AddMenuAt(5, editPasteSpecial)
```
forsearch
ApplicationMenuItem.Child
**Child**(Name As `String`) As `MenuItem`
Looks up menu items by Name and returns a MenuItem. Returns `Nil` if a child is not found.
The following example gets the text of the Edit \> Cut menuitem.
``` xojo
Var c As MenuItem
c = EditMenu.Child("EditCut")
MessageBox(c.Value)
```
forsearch
ApplicationMenuItem.Clone
**Clone** As `MenuItem`
Makes a copy of the `MenuItem` and its `children` if any. Mac does not permit duplicate MenuItems, so you will need to create clones of any MenuItems that are now being used in two or more locations.
Whenever you need to use the same `MenuItem` in different places, use the Clone method to create a new copy of the `MenuItem` and its children, if any.
``` xojo
Var mi As New MenuItem("My menu item")
Var myClone As MenuItem
myClone = mi.Clone ' Creates an independent copy of "mi"
```
forsearch
ApplicationMenuItem.Close
**Close**
Removes dynamically created menu items.
This example closes a menu item that was previously created.
``` xojo
EditSelectAll.Close
```
forsearch
ApplicationMenuItem.Constructor
**Constructor**(Text as `String`, \[Tag as `Variant` = `Nil`\])
Note
`Constructors` are special methods called when you create an object with the `New` keyword and pass in the parameters above.
Creates a new MenuItem that uses the passed string as its Text property and optionally adds the passed Tag.
This example inserts a new item in the Edit menu with the text "Paste Special..." just below the Paste item.
``` xojo
Var editPasteSpecial As New MenuItem
editPasteSpecial.Text = "Paste Special..."
EditMenu.AddMenuAt(5, editPasteSpecial)
```
Using this constructor, you can rewrite the code above more concisely:
``` xojo
Var editPasteSpecial As New MenuItem("Paste Special...")
EditMenu.AddMenuAt(5, editPasteSpecial)
```
This example illustrates how you can manipulate the menu bar at run time. By adding this example to the open even of a window it will add a new menu to menubar when the window opens.
``` xojo
Var m As MenuItem
Var mNew As MenuItem
m = Self.MenuBar
mNew = New MenuItem
mNew.Text = "MyMenuText"
mNew.Name = "MyMenuName"
Var submenu As New MenuItem("MySub")
submenu.AddMenu(New MenuItem("Submenu One"))
submenu.AddMenu(New MenuItem("Submenu Two"))
submenu.AddMenu(New MenuItem("Submenu three"))
mNew.AddMenu(submenu)
m.AddMenu(mNew)
```
forsearch
ApplicationMenuItem.Count
**Count** As `Integer`
Returns as an `Integer` the number of children a menu owns.
For a menu item, it returns the number of submenu items, if any. If there are no submenu items, it returns zero.
forsearch
ApplicationMenuItem.MenuAt
**MenuAt**(Index As `Integer`) As `MenuItem`
Item returns as a MenuItem the item indicated by its index (zero-based).
If the passed index is out of range, an `OutOfBoundsException` is raised.
The following example gets the MenuItem corresponding to the Cut item on the Edit menu by position:
``` xojo
Var c As MenuItem
c = EditMenu.MenuAt(2)
MessageBox(c.Value)
```
forsearch
ApplicationMenuItem.Popup
**Popup**(\[x As `Integer`, y As `Integer`\]) As `MenuItem`
Displays the MenuItem as a contextual menu.
If no parameters are passed, the contextual menu appears at the location of the mouse pointer. If you pass the optional parameters, the contextual menu appears at the passed location. The coordinates are global, not just in the object that handles the MouseDown event.
Popup returns the selected item as a **MenuItem**. The selected item's Action event will be fired. If the selected item is handled by a MenuHandler that returns `True`, then PopUp will return `Nil`.
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.
``` xojo
Var popMenu As MenuItem
popMenu = EditMenu.Clone
Var selectedMenu As MenuItem
selectedMenu = popMenu.Popup
```
forsearch
ApplicationMenuItem.Remove
**Remove**(Child As `MenuItem`)
Removes the MenuItem specified by the *name*.
This code removes the Select All menu item from the Edit menu.
``` xojo
EditMenu.Remove(3)
```
forsearch
ApplicationMenuItem.RemoveMenuAt
**RemoveMenuAt**(Index As `Integer`)
Removes the MenuItem specified by its position (index).
This example removes the Select All menu item from the Edit menu.
``` xojo
EditMenu.RemoveMenuAt(3)
```
## Event descriptions
forsearch
ApplicationMenuItem.Action
**Action** As `Boolean`
Called when a MenuItem is selected. Return `True` to prevent the menu event from proceeding any further in the chain of menu handlers.
Refer to the `MenuItem` page for an example of how a menu that is created dynamically can use the Action event.
forsearch
ApplicationMenuItem.EnableMenu
**EnableMenu**
Called when a user selects a menu. You can use this to enable/disable/hide menus based on the context of your app.
## Notes
To use ApplicationMenuItem, create the menu item under the menu that you want to use for the Windows and Linux builds of the application and then use the Inspector to change its super class to ApplicationMenuItem. Otherwise, set up the menu item normally.
## Compatibility
All project types on all supported operating systems.
## See also
`MenuItem` parent class; `MenuItem`, `PrefsMenuItem`, `QuitMenuItem` classes.