Selection - Vircadia API Docs

Description

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

The Selection API provides a means of grouping together and highlighting avatars and entities in named lists.

Example

Outline an entity when it is grabbed by the mouse or a controller.

// Create an entity and copy the following script into the entity's "Script URL" field.
// Move the entity behind another entity to see the occluded outline.
(function () {
    var LIST_NAME = "SelectionExample",
        ITEM_TYPE = "entity",
        HIGHLIGHT_STYLE = {
            outlineUnoccludedColor: { red: 0, green: 180, blue: 239 },
            outlineUnoccludedAlpha: 0.5,
            outlineOccludedColor: { red: 239, green: 180, blue: 0 },
            outlineOccludedAlpha: 0.5,
            outlineWidth: 4
        };

    Selection.enableListHighlight(LIST_NAME, HIGHLIGHT_STYLE);

    this.startNearGrab = function (entityID) {
        Selection.addToSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
    };

    this.startDistanceGrab = function (entityID) {
        Selection.addToSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
    };

    this.releaseGrab = function (entityID) {
        Selection.removeFromSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
    };

    Script.scriptEnding.connect(function () {
        Selection.removeListFromMap(LIST_NAME);
    });
});

Methods

Name	Return Value	Summary
`addToSelectedItemsList`	boolean	Adds an item to a selection list. The list is created if it doesn't exist.
`clearSelectedItemsList`	boolean	Removes all items from a selection list.
`disableListHighlight`	boolean	Disables highlighting for a selection list. Note: This function implicitly calls disableListToScene.
`disableListToScene`	boolean	Disables scene selection for a selection list.
`enableListHighlight`	boolean	Enables highlighting for a selection list. All items in or subsequently added to the list are displayed with the highlight effect specified. The method can be called multiple times with different values in the style to modify the highlighting. Note: This function implicitly calls enableListToScene.
`enableListToScene`	boolean	Enables scene selection for a selection list. All items in or subsequently added to the list are sent to a scene selection in the rendering engine for debugging purposes.
`getHighlightedListNames`	Array.<string>	Gets the names of all current selection lists that have highlighting enabled.
`getListHighlightStyle`	Selection.HighlightStyle	Gets the current highlighting style for a selection list.
`getListNames`	Array.<string>	Gets the names of all current selection lists.
`getSelectedItemsList`	Selection.SelectedItemsList	Gets the list of avatars and entities in a selection list.
`printList`	None	Prints the list of avatars and entities in a selection to the program log (but not the Script Log window).
`removeFromSelectedItemsList`	boolean	Removes an item from a selection list.
`removeListFromMap`	boolean	Deletes a selection list.

Signals

Name	Summary
`selectedItemsListChanged`	Triggered when a selection list's content changes or the list is deleted.

Type Definitions

HighlightStyle
Type: object

The highlighting style of a selection list.

Properties

Name	Type	Summary
outlineUnoccludedColor	Color	Unoccluded outline color. Default Value: 255,178,51
outlineOccludedColor	Color	Occluded outline color. Default Value: 255,178,51
fillUnoccludedColor	Color	Unoccluded fill color. Default Value: 51,178,255
fillOccludedColor	Color	Occluded fill color. Default Value: 51,178,255
outlineUnoccludedAlpha	number	Unoccluded outline alpha, range `0.0` – `1.0`. Default Value: 0.9
outlineOccludedAlpha	number	Occluded outline alpha, range `0.0` – `1.0`. Default Value: 0.9
fillUnoccludedAlpha	number	Unoccluded fill alpha, range `0.0` – `1.0`. Default Value: 0.0
fillOccludedAlpha	number	Occluded fill alpha, range `0.0` – `1.0`. Default Value: 0.0
outlineWidth	number	Width of the outline, in pixels. Default Value: 2
isOutlineSmooth	boolean	`true` to fade the outside edge of the outline, `false` to have a sharp edge. Default Value: false

ItemType
Type: string

The type of a specific item in a selection list.

Value	Description
`"avatar"`	The item is an avatar.
`"entity"`	The item is an entity.

SelectedItemsList
Type: object

A selection list.

Properties

Name	Type	Summary
avatars	Array.<Uuid>	The IDs of the avatars in the selection list.
entities	Array.<Uuid>	The IDs of the entities in the selection list.

Method Details

(static) addToSelectedItemsList( listName, itemType, itemID ) → {boolean}
Returns: true if the item was successfully added or already existed in the list, otherwise false.

Adds an item to a selection list. The list is created if it doesn't exist.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list to add the item to.
`itemType`	Selection.ItemType	The type of item being added.
`itemID`	Uuid	The ID of the item to add.

(static) clearSelectedItemsList( listName ) → {boolean}
Returns: true always.

Removes all items from a selection list.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list.

(static) disableListHighlight( listName ) → {boolean}
Returns: true always.

Disables highlighting for a selection list.

Note: This function implicitly calls disableListToScene.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list.

(static) disableListToScene( listName ) → {boolean}
Returns: true always.

Disables scene selection for a selection list.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list.

(static) enableListHighlight( listName, highlightStyle ) → {boolean}
Returns: true always.

Enables highlighting for a selection list. All items in or subsequently added to the list are displayed with the highlight effect specified. The method can be called multiple times with different values in the style to modify the highlighting.

Note: This function implicitly calls enableListToScene.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list.
`highlightStyle`	Selection.HighlightStyle	The highlight style.

(static) enableListToScene( listName ) → {boolean}
Returns: true always.

Enables scene selection for a selection list. All items in or subsequently added to the list are sent to a scene selection in the rendering engine for debugging purposes.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list.

(static) getHighlightedListNames( ) → {Array.<string>} Returns: The names of the selection lists that currently have highlighting enabled.
Gets the names of all current selection lists that have highlighting enabled.

(static) getListHighlightStyle( listName ) → {Selection.HighlightStyle}
Returns: The highlight style of the selection list if the list exists and highlighting is enabled, otherwise an empty object.

Gets the current highlighting style for a selection list.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list.

(static) getListNames( ) → {Array.<string>} Returns: The names of all current selection lists.
Gets the names of all current selection lists. Example List all the current selection lists. `print("Selection lists: " + Selection.getListNames());`

(static) getListNames( ) → {Array.<string>}
Returns: The names of all current selection lists.

Gets the names of all current selection lists.

Example

List all the current selection lists.

print("Selection lists: " + Selection.getListNames());

(static) getSelectedItemsList( listName ) → {Selection.SelectedItemsList}
Returns: The content of the selection list if the list exists, otherwise an empty object.

Gets the list of avatars and entities in a selection list.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list.

(static) printList( listName )

Prints the list of avatars and entities in a selection to the program log (but not the Script Log window).

Parameters

Name	Type	Description
`listName`	string	The name of the selection list.

(static) removeFromSelectedItemsList( listName, itemType, itemID ) → {boolean}
Returns: true if the item was successfully removed or was not in the list, otherwise false.

Removes an item from a selection list.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list to remove the item from.
`itemType`	Selection.ItemType	The type of item being removed.
`itemID`	Uuid	The ID of the item to remove.

(static) removeListFromMap( listName ) → {boolean}
Returns: true if the selection existed and was successfully removed, otherwise false.

Deletes a selection list.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list to delete.

Signal Details

selectedItemsListChanged( listName )
Returns: Signal

Triggered when a selection list's content changes or the list is deleted.

Parameters

Name	Type	Description
`listName`	string	The name of the selection list that changed.