Menu

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar 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 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.

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