Selection

Available in: Interface Scripts Client Entity Scripts

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

Signals

Type Definitions

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

addToSelectedItemsList(listName, itemType, id) → {boolean}
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.
Returns:
true if the item was successfully added, otherwise false.
Type: boolean
clearSelectedItemsList(listName) → {boolean}
Remove all items from a selection.
Parameters:
Name Type Description
listName string The name of the selection list.
Returns:
true if the item was successfully cleared, otherwise false.
Type: boolean
disableListHighlight(listName) → {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.
Parameters:
Name Type Description
listName string The name of the selection list.
Returns:
true if the selection was successfully disabled for highlight, otherwise false.
Type: boolean
disableListToScene(listName) → {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.
Parameters:
Name Type Description
listName string The name of the selection list.
Returns:
true if the selection was successfully disabled on the scene, false otherwise.
Type: boolean
enableListHighlight(listName, highlightStyle) → {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.
Parameters:
Name Type Description
listName string The name of the selection list.
highlightStyle Selection.HighlightStyle The highlight style.
Returns:
true if the selection was successfully enabled for highlight.
Type: boolean
enableListToScene(listName) → {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.
Parameters:
Name Type Description
listName string The name of the selection list.
Returns:
true if the selection was successfully enabled on the scene, otherwise false.
Type: boolean
getHighlightedListNames() → {Array.<string>}
Get the names of the highlighted selection lists.
Returns:
An array of names of the selection list currently highlight enabled.
Type: Array.<string>
getListHighlightStyle(listName) → {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.
Parameters:
Name Type Description
listName string The name of the selection list.
Returns:
highlight style
Type: Selection.HighlightStyle
getListNames() → {Array.<list>}
Get the names of all the selection lists.
Returns:
An array of names of all the selection lists.
Type: Array.<list>
getSelectedItemsList(listName) → {Selection.SelectedItemsList}
Get the list of avatars, entities, and overlays stored in a selection list.
Parameters:
Name Type Description
listName string The name of the selection list.
Returns:
The content of a selection list. If the list name doesn't exist, the function returns an empty object with no properties.
Type: Selection.SelectedItemsList
printList(listName)
Print out the list of avatars, entities, and overlays in a selection to the debug log (not the script log).
Parameters:
Name Type Description
listName string The name of the selection list.
removeFromSelectedItemsList(listName, itemType, id) → {boolean}
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.
Returns:
true if the item was successfully removed, otherwise false. is returned if the list doesn't contain any data.
Type: boolean
removeListFromMap(listName) → {boolean}
Delete a named selection list.
Parameters:
Name Type Description
listName string The name of the selection list.
Returns:
true if the selection existed and was successfully removed, otherwise false.
Type: boolean

Signals

selectedItemsListChanged(listName) → {Signal}
Triggered when a list's content changes.
Parameters:
Name Type Description
listName string The name of the selection list that changed.
Returns:
Type: Signal

Type Definitions

HighlightStyle
Type: object
Properties:
Name Type Description
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
Value Description
"avatar"
"entity"
"overlay"
Type: string
SelectedItemsList
Type: object
Properties:
Name Type Description
avatars Array.<Uuid> The IDs of the avatars in the selection.
entities Array.<Uuid> The IDs of the entities in the selection.
overlays Array.<Uuid> The IDs of the overlays in the selection.