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 is currently only one available group: "Developer". This grouping 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 Adds a new top-level menu.
addMenuItem None Adds a new menu item to a menu. The menu item is specified using Menu.MenuItemProperties.
addMenuItem None Adds a new menu item to a menu. The new item is added at the end of the menu.
addSeparator None Adds a separator with an unclickable label below it. The separator will be placed at the bottom of the menu. To add a separator at a specific point in the menu, use Menu.addMenuItem with Menu.MenuItemProperties instead.
isMenuEnabled boolean Checks whether a menu or menu item is enabled. If disabled, the item is grayed out and unusable. Menus are enabled by default.
isOptionChecked boolean Checks whether a checkable menu item is checked.
menuExists boolean Checks whether a top-level menu exists.
menuItemExists boolean Checks whether a menu item exists.
removeMenu None Removes a top-level menu.
removeMenuItem None Removes a menu item from a menu.
removeSeparator None Removes a separator from a menu.
setIsOptionChecked None Sets a checkable menu item as checked or unchecked.
setMenuEnabled None Sets a menu or menu item to be enabled or disabled. If disabled, the item is grayed out and unusable.
triggerOption None Triggers a 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 the properties, 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 ">" character.
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 )

Adds a new top-level menu.

Parameters

Name Type Attributes Description
menuName string Name that will be displayed for the menu. Nested menus can be specified using the ">" character.
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 > Developer is enabled.

Menu.addMenu("Settings > Test Grouping Menu", "Developer");
(static) addMenuItem( properties )

Adds a new menu item to a menu. The menu item is specified using Menu.MenuItemProperties.

Parameters

Name Type Description
properties Menu.MenuItemProperties Properties of the menu item to create.
Example

Add a menu item at a particular position in the "Developer" menu.

Menu.addMenuItem({
    menuName:     "Developer",
    menuItemName: "Test",
    afterItem:    "Log",
    shortcutKey:  "Ctrl+Shift+T"
});
(static) addMenuItem( menuName, menuItem, shortcutKeyopt )

Adds 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 the 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 )

Adds a separator with an unclickable label below it. The separator will be placed at the bottom of the menu. 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 the 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.

Checks 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 whether the Settings > Developer Menu item is enabled.

print("Developer Menu item enabled: " + Menu.isMenuEnabled("Settings > Developer Menu"));
(static) isOptionChecked( menuOption ) → {boolean}
Returns: true if the option is checked, otherwise false.

Checks whether a checkable menu item is checked.

Parameters

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

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

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

Checks whether a top-level menu exists.

Parameters

Name Type Description
menuName string Name of the menu to check exists.
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.

Checks whether 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 )

Removes 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 )

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

Remove a menu item from the "Developer" menu.

Menu.removeMenuItem("Developer", "Test");
(static) removeSeparator( menuName, separatorName )

Removes 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 )

Sets 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 > Developer Menu.

Menu.setIsOptionChecked("Developer Menu", true);
print("Developer menu showing: " + Menu.isOptionChecked("Developer Menu"));
(static) setMenuEnabled( menuName, isEnabled )

Sets 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 > Developer Menu item.

Menu.setMenuEnabled("Settings > Developer Menu", false);
print("Developer Menu item enabled: " + Menu.isMenuEnabled("Settings > Developer Menu"));
(static) triggerOption( menuOption )

Triggers a 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 Asset Browser dialog.

Menu.triggerOption('Asset Browser');

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

Detect menu item events.

function onMenuItemEvent(menuItem) {
    print("Menu item clicked: " + menuItem);
}

Menu.menuItemEvent.connect(onMenuItemEvent);