Selection

Description

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

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

Example

Outline an entity when it is grabbed by a controller.

// Create a box and copy the following text into the entity's "Script URL" field.
(function () {
    print("Starting highlight script...............");
    var _this = this;
    var prevID = 0;
    var listName = "contextOverlayHighlightList";
    var listType = "entity";

    _this.startNearGrab = function(entityID){
        if (prevID !== entityID) {
            Selection.addToSelectedItemsList(listName, listType, entityID);
            prevID = entityID;
        }
    };

    _this.releaseGrab = function(entityID){
        if (prevID !== 0) {
            Selection.removeFromSelectedItemsList("contextOverlayHighlightList", listType, prevID);
            prevID = 0;
        }
    };

    var cleanup = function(){
        Entities.findEntities(MyAvatar.position, 1000).forEach(function(entity) {
            try {
                Selection.removeListFromMap(listName);
            } catch (e) {
                print("Error cleaning up.");
            }
        });
    };

    Script.scriptEnding.connect(cleanup);
});

Methods

Name Return Value Summary
addToSelectedItemsList boolean Add an item to a selection list.
clearSelectedItemsList boolean Remove all items from a selection.
disableListHighlight boolean Disable highlighting for the selection list. If the selection list doesn't exist or wasn't enabled for highlighting then nothing happens and false is returned.
Note: This function implicitly calls Selection.disableListToScene.
disableListToScene boolean Disable scene selection for the named selection. If the selection list doesn't exist or wasn't enabled on the scene then nothing happens and false is returned.
enableListHighlight boolean Enable highlighting for a selection list. If the selection list doesn't exist, it will be created. All objects in the list will be displayed with the highlight effect specified. The function can be called several times with different values in the style to modify it.
Note: This function implicitly calls Selection.enableListToScene.
enableListToScene boolean Enable scene selection for the selection list. If the Selection doesn't exist, it will be created. All objects in the list will be sent to a scene selection.
getHighlightedListNames Array.<string> Get the names of the highlighted selection lists.
getListHighlightStyle Selection.HighlightStyle Get the highlight style values for the a selection list. If the selection doesn't exist or hasn't been highlight enabled yet, an empty object is returned.
getListNames Array.<list> Get the names of all the selection lists.
getSelectedItemsList Selection.SelectedItemsList Get the list of avatars and entities stored in a selection list.
printList None Print out the list of avatars and entities in a selection to the debug log (not the script log).
removeFromSelectedItemsList boolean Remove an item from a selection list.
removeListFromMap boolean Delete a named selection list.

Signals

Name Summary
selectedItemsListChanged Triggered when a list's content changes.

Type Definitions

HighlightStyle
Type: object

 

Properties

Name Type Summary
outlineUnoccludedColor Color Color of the specified highlight region.
outlineOccludedColor Color ""
fillUnoccludedColor- Color ""
fillOccludedColor- Color ""
outlineUnoccludedAlpha number Alpha value ranging from 0.0 (not visible) to 1.0 (fully opaque) for the specified highlight region.
outlineOccludedAlpha number ""
fillUnoccludedAlpha number ""
fillOccludedAlpha number ""
outlineWidth number Width of the outline, in pixels.
isOutlineSmooth boolean true to enable outline smooth fall-off.
ItemType
Type: string

ValueDescription
"avatar"
"entity"

SelectedItemsList
Type: object

 

Properties

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

Method Details

(static) addToSelectedItemsList( listName, itemType, id ) → {boolean}
Returns: true if the item was successfully added, otherwise false.

Add an item to a selection list.

Parameters

Name Type Description
listName string The name of the selection list to add the item to.
itemType Selection.ItemType The type of the item being added.
id Uuid The ID of the item to add to the selection.
(static) clearSelectedItemsList( listName ) → {boolean}
Returns: true if the item was successfully cleared, otherwise false.

Remove all items from a selection.

Parameters

Name Type Description
listName string The name of the selection list.
(static) disableListHighlight( listName ) → {boolean}
Returns: true if the selection was successfully disabled for highlight, otherwise false.

Disable highlighting for the selection list. If the selection list doesn't exist or wasn't enabled for highlighting then nothing happens and false is returned.
Note: This function implicitly calls Selection.disableListToScene.

Parameters

Name Type Description
listName string The name of the selection list.
(static) disableListToScene( listName ) → {boolean}
Returns: true if the selection was successfully disabled on the scene, false otherwise.

Disable scene selection for the named selection. If the selection list doesn't exist or wasn't enabled on the scene then nothing happens and false is returned.

Parameters

Name Type Description
listName string The name of the selection list.
(static) enableListHighlight( listName, highlightStyle ) → {boolean}
Returns: true if the selection was successfully enabled for highlight.

Enable highlighting for a selection list. If the selection list doesn't exist, it will be created. All objects in the list will be displayed with the highlight effect specified. The function can be called several times with different values in the style to modify it.
Note: This function implicitly calls Selection.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 if the selection was successfully enabled on the scene, otherwise false.

Enable scene selection for the selection list. If the Selection doesn't exist, it will be created. All objects in the list will be sent to a scene selection.

Parameters

Name Type Description
listName string The name of the selection list.
(static) getHighlightedListNames( ) → {Array.<string>}
Returns: An array of names of the selection list currently highlight enabled.

Get the names of the highlighted selection lists.

(static) getListHighlightStyle( listName ) → {Selection.HighlightStyle}
Returns: highlight style

Get the highlight style values for the a selection list. If the selection doesn't exist or hasn't been highlight enabled yet, an empty object is returned.

Parameters

Name Type Description
listName string The name of the selection list.
(static) getListNames( ) → {Array.<list>}
Returns: An array of names of all the selection lists.

Get the names of all the selection lists.

(static) getSelectedItemsList( listName ) → {Selection.SelectedItemsList}
Returns: The content of a selection list. If the list name doesn't exist, the function returns an empty object with no properties.

Get the list of avatars and entities stored in a selection list.

Parameters

Name Type Description
listName string The name of the selection list.
(static) printList( listName )

Print out the list of avatars and entities in a selection to the debug log (not the script log).

Parameters

Name Type Description
listName string The name of the selection list.
(static) removeFromSelectedItemsList( listName, itemType, id ) → {boolean}
Returns: true if the item was successfully removed, otherwise false. is returned if the list doesn't contain any data.

Remove 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 the item being removed.
id Uuid The ID of the item to remove.
(static) removeListFromMap( listName ) → {boolean}
Returns: true if the selection existed and was successfully removed, otherwise false.

Delete a named selection list.

Parameters

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

Signal Details

selectedItemsListChanged( listName )
Returns: Signal

Triggered when a list's content changes.

Parameters

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