selection

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

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.

The selection can only contain items within the current edit context:

  • If the user has drilled down into a container node, the container is the current edit context and only its immediate children can be selected.
  • If the user hasn't drilled into any container, the root of the document is the edit context, and the selection may contain any artboard or any combination of the pasteboard's immediate children and one or more artboards' immediate children. The selection cannot contain both artboards and non-artboards at the same time, however.

Don't assume that all selected items have the same parent node: in the root edit context, the selection can contain items with differing parents (multiple different artboards, as well as the root node).

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.

Kind: object


selection.items : !Array<!SceneNode>

Array representing the current selection. Empty array if nothing is selected (never null). Never includes locked nodes. May include items with different parents (for example, an item in an artboard plus an item on the pasteboard can be selected at the same time). Never mixes artboards with other nodes: a selection is either all artboards or all non-artboards.

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 this can be mutated by the caller without interfering with anything. Mutating the array does not change the selection - only invoking the 'items' setter changes selection.

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.

Kind: instance property of selection
Read only: true


selection.hasArtboards : boolean

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

Kind: instance property of selection
Read only: true


selection.editContext : !SceneNode

The context in which selection and edit operations must occur. If the user hasn't drilled into any container node, this value is the document root, and its scope includes all immediate children of the pasteboard (including Artboards), and all immediate children of all those Artboards.

Kind: instance property of selection
Read only: true


selection.insertionParent : !SceneNode

The preferred parent to insert newly added content into. Takes into account the current edit context as well as the "focused artboard" if in the root context.

Kind: instance property of selection
Read only: true


selection.focusedArtboard : ?Artboard

The artboard the user is currently most focused on (via recent selection or edit operations). May be null, for example if no artboards exist or if the user just deleted an artboard.

Kind: instance property of selection
Read only: true


results matching ""

    No results matching ""