Menu

Description

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.

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts

Methods

Name Return Value Summary
addMenu None Add a new top-level menu.
addMenuItem None Add a new menu item to a menu.
addMenuItem None Add a new menu item to a menu. The new item is added at the end of the menu.
addSeparator None 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.
isMenuEnabled boolean Check whether a menu or menu item is enabled. If disabled, the item is grayed out and unusable. Menus are enabled by default.
isOptionChecked boolean Check whether a checkable menu item is checked.
menuExists boolean Check whether a top-level menu exists.
menuItemExists boolean Check if a menu item exists.
removeMenu None Remove a top-level menu.
removeMenuItem None Remove a menu item from a menu.
removeSeparator None Remove a separator from a menu.
setIsOptionChecked None Set a checkable menu item as checked or unchecked.
setMenuEnabled None Set a menu or menu item to be enabled or disabled. If disabled, the item is grayed out and unusable.
triggerOption None Trigger the menu item as if the user clicked on it.

Signals

Name Summary
menuItemEvent Triggered when a menu item is clicked (or triggered by Menu.triggerOption).

Type Definitions

MenuItemProperties
Type: object

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.

Properties

Name Type Attributes Summary
menuName string Name of the menu. Nested menus can be described using the ">" symbol.
menuItemName string Name of the menu item.
isCheckable boolean <optional>
Whether or not the menu item is checkable.

Default Value: false

isChecked boolean <optional>
Whether or not the menu item is checked.

Default Value: false

isSeparator boolean <optional>
Whether or not the menu item is a separator.

Default Value: false

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.

Method Details

(static) 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");
(static) 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"
});
(static) 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");
(static) 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");
(static) isMenuEnabled( menuName ) → {boolean}
Returns: true if the menu is enabled, otherwise false.

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

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

print(Menu.isMenuEnabled("Settings > Advanced Menus")); // true or false
(static) isOptionChecked( menuOption ) → {boolean}
Returns: true if the option is checked, otherwise false.

Check whether a checkable menu item is checked.

Parameters

Name Type Description
menuOption string The name of the menu item.
Example

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

print(Menu.isOptionChecked("Advanced Menus")); // true or false
(static) menuExists( menuName ) → {boolean}
Returns: true if the menu exists, otherwise false.

Check whether a top-level menu exists.

Parameters

Name Type Description
menuName string Name of the menu to check for existence.
Example

Check if the "Developer" menu exists.

if (Menu.menuExists("Developer")) {
    print("Developer menu exists.");
}
(static) menuItemExists( menuName, menuItem ) → {boolean}
Returns: true if the menu item exists, otherwise false.

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

Determine if the Developer > Stats menu exists.

if (Menu.menuItemExists("Developer", "Stats")) {
    print("Developer > Stats menu item exists.");
}
(static) 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");
(static) 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");
(static) 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");
(static) 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
(static) 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
(static) 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...');

Signal Details

menuItemEvent( menuItem )
Returns: 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.
Example

Detect menu item events.

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

Menu.menuItemEvent.connect(onMenuItemEvent);