Menu - Vircadia API Docs

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