selection

The selection object represents the currently selected set of nodes in the UI. You can change the selection to use it as input for commands, or to control what is left selected for the user when your plugin's edit operation completes.

Selected items might not all have the same parent node. For example, the selection could be split between two sibling Group nodes, or half the selection could be inside a Group and half inside its parent. Or the selection could be split between multiple different artboards along with items on the pasteboard (immediate children of the root node).

Your plugin can only modify nodes in the "neighborhood" of the user's selection, a subset of the scenegraph tree called the edit context. You can only set the selection to other nodes within the edit context. The edit context does not update to reflect any changes to the selection until after a plugin operation completes.

Other restrictions on selection

The selection cannot contain both artboards and non-artboards at the same time.
The selection cannot contain both a node and one of its ancestors at the same time.
Items that are locked cannot be in the selection. If the user or your plugin attempts to select any locked items, they are automatically filtered into a separate list (itemsIncludingLocked) which is generally only used by the Unlock command.

Accessing the selection

The current selection state is passed to your command handler function as an argument:

function myCommand(selection, documentRoot) {
    console.log(selection.items.length + " items are selected");
}
module.exports = {
    commands: {
        myCommandId: myCommand
    }
};

You can also access this object from the scenegraph.selection property.

Kind: object

selection
- .items : !Array<!SceneNode>
- .itemsIncludingLocked : !Array<!SceneNode>
- .hasArtwork : boolean
- .hasArtboards : boolean
- .insertionParent : !SceneNode
- .focusedArtboard : ?Artboard
- .editContext : !SceneNode
- .isInEditContext(node) ⇒ boolean

selection.items : `!Array<!SceneNode>`

Array representing the current selection. Empty array if nothing is selected (never null). Items might not all have the same parent node. Never includes locked nodes. Never mixes artboards with other nodes: a selection is either all artboards or all non-artboards. Never includes any ancestors of any other item in the selection.

As a convenience, the setter also accepts a single node or null as valid input. However, the getter always returns an array.

If the user selects nodes one-by-one, by Shift-clicking, this array lists the nodes in the order they were added to the selection. If the user selected by other means, e.g. dragging a marquee, the order has no meaning.

Returns a fresh array each time, so modifying the array returned by the getter does not change the selection -- only invoking the 'items' setter changes selection.

The selection can only contain items which are in the current edit context.

Kind: instance property of selection
Example

console.log("There are " + selection.items.length + " nodes currently selected");
selection.items = [rectangle, ellipse, path];  // select 3 nodes
selection.items = rectangle;  // select 1 node (convenience)
selection.items = null;       // deselect all (convenience)

selection.itemsIncludingLocked : `!Array<!SceneNode>`

Array representing the current selection plus any locked items that the user has attempted to select.

Kind: instance property of selection
Read only: true
Example

let numUnlockedSelected = selection.items.length;
let numLockedSelected = selection.itemsIncludingLocked.length - numUnlockedSelected;
console.log("There are " + numLockedSelected + " locked nodes 'sort of' currently selected");

selection.hasArtwork : `boolean`

True if the selection isn’t empty and consists of one or more non-Artboards. Never true at the same time as hasArtboards.