commands.md

commands

You can make structural changes to the scenegraph, and perform other complex operations, by programmatically invoking the same commands as XD users have access to in the UI. Because structural changes have many nuanced rules and behaviors in XD, these calls function more like automating the UI than like low-level APIs.

For example, these methods do not take arguments. Instead, set the selection to the objects you want the command to target, then invoke the command. Commands may also change the selection when run - for example, group() selects the newly created Group node.

Example

let commands = require("commands");
selection.items = [shape1, shape2, maskShape];
commands.createMaskGroup();
console.log(selection.items);  // [Group]

• commands
  • .group()
  • .ungroup()
  • .createMaskGroup()
  • .convertToPath()
  • .duplicate()
  • .bringToFront()
  • .bringForward()
  • .sendToBack()
  • .sendBackward()
  • .alignLeft()
  • .alignRight()
  • .alignHorizontalCenter()
  • .alignTop()
  • .alignBottom()
  • .alignVerticalCenter()
  • .distributeHorizontal()
  • .distributeVertical()
  • .alignToPixelGrid()

---

commands.group()

Wraps the selected objects in a Group, leaving the Group selected afterward. Equivalent to Object > Group in the UI.

Kind: static method of commands

Example

let shape1 = new Rectangle();
// ...configure Rectangle size & appearance...
let label = new Text();
// ...configure Text content & appearance...

// Add both nodes to the current edit context first
selection.insertionParent.addChild(shape1);
selection.insertionParent.addChild(label);

// Select both shapes, then run the group() command
selection.items = [shape1, label];
commands.group();
let group = selection.items[0];  // the new Group node is what's selected afterward

---

commands.ungroup()

Ungroups any of the selected objects that are ungroupable containers (Group, SymbolInstance, RepeatGrid, etc.). Equivalent to Object > Ungroup.

Kind: static method of commands

---

commands.createMaskGroup()

Creates a masked Group from the selected objects, using the object that is highest in the z order as the mask shape. The mask shape must be a leaf node or Boolean Group. Equivalent to Object > Mask With Shape.

Kind: static method of commands

Example

let shape1 = new Rectangle(),
    shape2 = new Ellipse();
// ...configure shapes' size & appearance...
let maskShape = new Ellipse();
// ...configure mask shape's size...

// Create a Masked Group: add all nodes to the current edit context, select them, then run the createMaskGroup() command
selection.insertionParent.addChild(shape1);
selection.insertionParent.addChild(shape2);
selection.insertionParent.addChild(maskShape);  // added last: topmost in z order
selection.items = [shape1, shape2, maskShape];  // order of selection array does not matter
commands.createMaskGroup();
let maskedGroup = selection.items[0];

---

commands.convertToPath()

Converts each selected object to a Path with the exact same visual appearance. Only applies to leaf nodes and Boolean Groups. Equivalent to Object > Path > Convert to Path.

Kind: static method of commands

---

commands.duplicate()

Duplicates all selected objects, leaving the duplicates selected afterward.

• If the objects are artboards, the duplicates are positioned to not overlap any more artboards, and are placed at the top of the artboard z order.
• If normal objects, each duplicate is in the exact same position as the original, and just above it in the z order (duplicates of a multiple selection will not be contiguous in the z order if the originals were not).

Interactions triggered from the selected objects are only duplicated if the user is currently in the Prototype workspace. Equivalent to Edit > Duplicate.

Kind: static method of commands

---

commands.bringToFront()

Brings selected objects to the front of the z order. Equivalent to Object > Arrange > Bring to Front.

Kind: static method of commands

---

commands.bringForward()

Brings each selected object one step closer to the front of the z order. Equivalent to Object > Arrange > Bring Forward.

Kind: static method of commands

---

commands.sendToBack()

Sends selected objects to the back of the z order. Equivalent to Object > Arrange > Send to Back.

Kind: static method of commands

---

commands.sendBackward()

Sends each selected object one step closer to the back of the z order. Equivalent to Object > Arrange > Send Backward.

Kind: static method of commands

---

commands.alignLeft()

Aligns all selected objects flush left. Equivalent to Object > Align > Left.

Kind: static method of commands

---

commands.alignRight()

Aligns all selected objects flush right. Equivalent to Object > Align > Right.

Kind: static method of commands

---

commands.alignHorizontalCenter()

Aligns all selected objects along their horizontal centerlines. Equivalent to Object > Align > Center (Horizontally).

Kind: static method of commands

---

commands.alignTop()

Aligns all selected objects flush top. Equivalent to Object > Align > Top.

Kind: static method of commands

---

commands.alignBottom()

Aligns all selected objects flush bottom. Equivalent to Object > Align > Bottom.

Kind: static method of commands

---

commands.alignVerticalCenter()

Aligns all selected objects along their vertical centerlines. Equivalent to Object > Align > Center (Vertically).

Kind: static method of commands

---

commands.distributeHorizontal()

Distributes all selected objects evenly along the X axis. Equivalent to Object > Distribute > Horizontally.

Kind: static method of commands

---

commands.distributeVertical()

Distributes all selected objects evenly along the Y axis. Equivalent to Object > Distribute > Vertically.

Kind: static method of commands

---

commands.alignToPixelGrid()

Shifts all selected objects and their content so they align crisply with the pixel grid. Equivalent to Object > Align to Pixel Grid.

Kind: static method of commands