Menu

Available in: Interface Scripts Client Entity Scripts

The Menu API provides access to the menu that is displayed at the top of the window on a user's desktop and in the tablet when the "MENU" button is pressed.

Groupings

A "grouping" provides a way to group a set of menus or menu items together so that they can all be set visible or invisible as a group. There are two available groups: "Advanced" and "Developer". These groupings can be toggled in the "Settings" menu. If a menu item doesn't belong to a group it is always displayed.
Methods

Signals

Type Definitions

Methods

addMenu(menuName, groupingopt)
Add a new top-level menu.
Parameters:
Name Type Attributes Description
menuName string Name that will be displayed for the menu. Nested menus can be described using the ">" symbol.
grouping string <optional>
Name of the grouping, if any, to add this menu to.
Examples

Add a menu and a nested submenu.

Menu.addMenu("Test Menu");
Menu.addMenu("Test Menu > Test Sub Menu");

Add a menu to the Settings menu that is only visible if Settings > Advanced is enabled.

Menu.addMenu("Settings > Test Grouping Menu", "Advanced");
addMenuItem(properties)
Add a new menu item to a menu.
Parameters:
Name Type Description
properties Menu.MenuItemProperties Properties of the menu item to create.
Example

Add a menu item using Menu.MenuItemProperties.

Menu.addMenuItem({
  menuName:     "Developer",
  menuItemName: "Test",
  afterItem:    "Log",
  shortcutKey:  "Ctrl+Shift+T",
  grouping:     "Advanced"
});
addMenuItem(menuName, menuItem, shortcutKeyopt)
Add a new menu item to a menu. The new item is added at the end of the menu.
Parameters:
Name Type Attributes Description
menuName string Name of the menu to add a menu item to.
menuItem string Name of the menu item. This is what will be displayed in the menu.
shortcutKey string <optional>
A shortcut key that can be used to trigger the menu item.
Example

Add a menu item to the end of the "Developer" menu.

Menu.addMenuItem("Developer", "Test", "Ctrl+Shift+T");
addSeparator(menuName, separatorName)
Add a separator with an unclickable label below it. The separator will be placed at the bottom of the menu. If you want to add a separator at a specific point in the menu, use Menu.addMenuItem with Menu.MenuItemProperties instead.
Parameters:
Name Type Description
menuName string Name of the menu to add a separator to.
separatorName string Name of the separator that will be displayed as the label below the separator line.
Example

Add a separator.

Menu.addSeparator("Developer","Test Separator");
isMenuEnabled(menuName) → {boolean}
Check whether a menu or menu item is enabled. If disabled, the item is grayed out and unusable. Menus are enabled by default.
Parameters:
Name Type Description
menuName string The name of the menu or menu item to check.
Returns:
true if the menu is enabled, otherwise false.
Type: boolean
Example

Report with the Settings > Advanced Menus menu item is enabled.

print(Menu.isMenuEnabled("Settings > Advanced Menus")); // true or false
isOptionChecked(menuOption) → {boolean}
Check whether a checkable menu item is checked.
Parameters:
Name Type Description
menuOption string The name of the menu item.
Returns:
true if the option is checked, otherwise false.
Type: boolean
Example

Report whether the Settings > Advanced menu item is turned on.

print(Menu.isOptionChecked("Advanced Menus")); // true or false
menuExists(menuName) → {boolean}
Check whether a top-level menu exists.
Parameters:
Name Type Description
menuName string Name of the menu to check for existence.
Returns:
true if the menu exists, otherwise false.
Type: boolean
Example

Check if the "Developer" menu exists.

if (Menu.menuExists("Developer")) {
  print("Developer menu exists.");
}
menuItemExists(menuName, menuItem) → {boolean}
Check if a menu item exists.
Parameters:
Name Type Description
menuName string Name of the menu that the menu item is in.
menuItem string Name of the menu item to check for existence of.
Returns:
true if the menu item exists, otherwise false.
Type: boolean
Example

Determine if the Developer > Stats menu exists.

if (Menu.menuItemExists("Developer", "Stats")) {
  print("Developer > Stats menu item exists.");
}
removeMenu(menuName)
Remove a top-level menu.
Parameters:
Name Type Description
menuName string Name of the menu to remove.
Example

Remove a menu and nested submenu.

Menu.removeMenu("Test Menu > Test Sub Menu");
Menu.removeMenu("Test Menu");
removeMenuItem(menuName, menuItem)
Remove a menu item from a menu.
Parameters:
Name Type Description
menuName string Name of the menu to remove a menu item from.
menuItem string Name of the menu item to remove. Menu.removeMenuItem("Developer", "Test");
removeSeparator(menuName, separatorName)
Remove a separator from a menu.
Parameters:
Name Type Description
menuName string Name of the menu to remove the separator from.
separatorName string Name of the separator to remove.
Example

Remove a separator.

Menu.removeSeparator("Developer","Test Separator");
setIsOptionChecked(menuOption, isChecked)
Set a checkable menu item as checked or unchecked.
Parameters:
Name Type Description
menuOption string The name of the menu item to modify.
isChecked boolean If true, the menu item will be checked, otherwise it will not be checked.
Example

Turn on Settings > Advanced Menus.

Menu.setIsOptionChecked("Advanced Menus", true);
print(Menu.isOptionChecked("Advanced Menus")); // true
setMenuEnabled(menuName, isEnabled)
Set a menu or menu item to be enabled or disabled. If disabled, the item is grayed out and unusable.
Parameters:
Name Type Description
menuName string The name of the menu or menu item to modify.
isEnabled boolean If true, the menu will be enabled, otherwise it will be disabled.
Example

Disable the Settings > Advanced Menus menu item.

Menu.setMenuEnabled("Settings > Advanced Menus", false);
print(Menu.isMenuEnabled("Settings > Advanced Menus")); // false
triggerOption(menuOption)
Trigger the menu item as if the user clicked on it.
Parameters:
Name Type Description
menuOption string The name of the menu item to trigger.
Example

Open the help window.

Menu.triggerOption('Help...');

Signals

menuItemEvent(menuItem) → {Signal}
Triggered when a menu item is clicked (or triggered by Menu.triggerOption).
Parameters:
Name Type Description
menuItem string Name of the menu item that was clicked.
Returns:
Type: Signal
Example

Detect menu item events.

function onMenuItemEvent(menuItem) {
  print("You clicked on " + menuItem);
}

Menu.menuItemEvent.connect(onMenuItemEvent);
   

Type Definitions

MenuItemProperties
A set of properties that can be passed to Menu.addMenuItem to create a new menu item. If none of position, beforeItem, afterItem, or grouping are specified, the menu item will be placed at the end of the menu.
Type: object
Properties:
Name Type Attributes Default Description
menuName string Name of the menu. Nested menus can be described using the ">" symbol.
menuItemName string Name of the menu item.
isCheckable boolean <optional>
false Whether or not the menu item is checkable.
isChecked boolean <optional>
false Whether or not the menu item is checked.
isSeparator boolean <optional>
false Whether or not the menu item is a separator.
shortcutKey string <optional>
A shortcut key that triggers the menu item.
shortcutKeyEvent KeyEvent <optional>
A KeyEvent that specifies a key that triggers the menu item.
position number <optional>
The position to place the new menu item. An integer number with 0 being the first menu item.
beforeItem string <optional>
The name of the menu item to place this menu item before.
afterItem string <optional>
The name of the menu item to place this menu item after.
grouping string <optional>
The name of grouping to add this menu item to.