Selection - Vecta API

new Vecta.Selection([shapes])

Vecta selection objects are essentially an array of shapes on a drawing where you can perform shape operations.

Name	Type	Attributes	Description
`shapes`	Vecta.Shape\|Vecta.Shape[]	`optional`	A single shape or an array of shapes to be added to the selection

Examples:

var select = new Vecta.Selection(); //Create an empty selection

Methods

.add(shapes) Returns: Vecta.Selection

Add shapes into the selection object.

Name	Type	Description
`shapes`	Vecta.Shape\|Vecta.Shape[]	A single shape or an array of shapes

Examples:

var select = new Vecta.Selection(), //Create an empty selection
    rect = new Vecta.activePage.drawRect(0, 0, 50, 50); //Draw a rect

select.add(rect); //Add a rectangle shape into the selection

.box() Returns: object

Get the selection object bounding box.

Returns:

{x: number, y: number, width: number, height: number}

Examples:

var rect = new Vecta.activePage.drawRect(0, 0, 50, 50), //Draw a rect
    select = new Vecta.Selection(rect); //Create a new selection object with a single shape

console.log(select.box()); //{x: 0, y: 0, width: 50, height: 50}

.clear() Returns: Vecta.Selection

Clear or remove all shapes from selection object.

Examples:

var rect = new Vecta.activePage.drawRect(0, 0, 50, 50), //Draw a rect
    select = new Vecta.Selection(rect); //Create a new selection object with a single shape

select.clear(); //Remove all shapes from selection object

.difference() Returns: Promise.<Vecta.Shape[]>

Perform difference operation on shapes in the selection object.

Locked shapes will NOT be differenced. Upon completion, differenced shapes will be returned, and the selection object will be modified to contain differenced shapes and locked shapes.

Returns:

Returns a thenable promise containing the shapes that is differenced.

Examples:

var select = new Vecta.Selection([path1, path2]); //Create a new selection object with two paths

select.difference().then(function (shapes) {
    console.log('Number of shapes differenced = ' + shapes.length);
});

.exist(id) Returns: boolean

Perform checking on shape exist in the selection object.

Name	Type	Description
`id`	string	Shape id

Returns:

Returns true if exist in selection object, false otherwise.

.flatten() Returns: Promise.<Vecta.Shape[]>

Perform flatten operation on shapes in the selection object

Locked shapes will NOT be flatten. Upon completion, flattened shapes will be returned, and the selection object will be modified to contain flattened shapes and locked shapes.

Returns:

Returns a thenable promise containing the shapes that is flatten.

Examples:

var select = new Vecta.Selection([path1, path2]); //Create a new selection object with two paths

select.flatten().then(function (shapes) {
    console.log('Number of shapes flatten = ' + shapes.length);
});

.flipHoriz() Returns: Vecta.Selection

Flip shapes in the selection object horizontally

Examples:

var select = new Vecta.Selection(), //Create an empty selection
    rect = new Vecta.activePage.drawRect(0, 0, 50, 50); //Draw a rect

select.flipHoriz(); //Flip shape horizontally

.flipVerti() Returns: Vecta.Selection

Flip shapes in the selection object vertically

Examples:

var select = new Vecta.Selection(), //Create an empty selection
    rect = new Vecta.activePage.drawRect(0, 0, 50, 50); //Draw a rect

select.flipVerti(); //Flip shape vertically

.fragment() Returns: Promise.<Vecta.Shape[]>

Perform fragment operation on shapes in the selection object.

Locked shapes will NOT be fragmented. Upon completion, fragmented shapes will be returned, and the selection object will be modified to contain fragmented shapes and locked shapes.

Returns:

Returns a thenable promise containing the shapes that is fragmented.

Examples:

var select = new Vecta.Selection([path1, path2]); //Create a new selection object with two paths

select.fragmented().then(function (shapes) {
    console.log('Number of shapes from fragment operation = ' + shapes.length);
});

.group() Returns: Vecta.Shape

Group shapes from the selection object into a single shape.

If a shape is a child shape of another group or is locked, it will not be grouped into the new shape.

Returns:

Returns the grouped shape if successful or null if not.

Examples:

var rect1 = new Vecta.activePage.drawRect(0, 0, 50, 50), //Draw a rect
    rect2 = new Vecta.activePage.drawRect(50, 50, 50, 50), //Draw another rect
    select = new Vecta.Selection([rect1, rect2]); //Create a new selection object with two shapes

select.group(); //Group the 2 shapes in the selection object

.intersect() Returns: Promise.<Vecta.Shape[]>

Perform intersect operation on shapes in the selection object

Locked shapes will NOT be intersected. Upon completion, intersected shapes will be returned, and the selection object will be modified to contain intersected shapes and locked shapes.

Returns:

Returns a thenable promise containing the shapes that is intersected.

Examples:

var select = new Vecta.Selection([path1, path2]); //Create a new selection object with two paths

select.intersect().then(function (shapes) {
    console.log('Number of shapes intersected = ' + shapes.length);
});

.join() Returns: Promise.<Vecta.Shape[]>

Join shapes in the selection object.

Join operations only applies to unclosed paths, where the begin and end points are located at the same coordinates, otherwise paths will not be joined.

Returns:

Returns a thenable promise containing the shape after joined.

Examples:

var select = new Vecta.Selection([path1, path2]); //Create a new selection object with two paths

select.join().then(function (joined) {
  console.log(joined); //All shape is now joined into 1
});

.length() Returns: number

Get the number of shapes in the selection object.

Returns:

The number of shapes in the selection object.

Examples:

var select = new Vecta.Selection(); //Create an empty selection

console.log(select.length); //0

.outline() Returns: Promise.<Vecta.Shape[]>

Outline text to path in the selection object.

Only shapes that is unlocked will be outlined. Upon completion, outlined shapes will be returned, and the selection object will be modified to contain outlined shapes and locked shapes.

Returns:

Returns a thenable promise containing the shapes that is outlined to path.

Examples:

var rect = Vecta.activePage.drawRect(0, 0, 50, 50).text('Testing'), //Create rectangle and set text
    select = new Vecta.Selection(rect); //Create a new selection object with rect

select.outline(); //Outline the text

.remove(shape_or_id) Returns: Vecta.Selection

Remove a single shape from the selection object.

Name	Type	Description
`shape_or_id`	Vecta.Shape\|string	The shape object or id to remove.

.toPath() Returns: Promise.<Vecta.Shape[]>

Convert shapes to path in the selection object.

Paths (already converted) and images will NOT be converted.

Upon completion, converted shapes will be returned, and the selection object will be modified to contain converted shapes and locked shapes.

Returns:

Returns a thenable promise containing the shapes that is converted to path.

Examples:

var select = new Vecta.Selection([rect1, rect2]); //Create a new selection object with two shapes

select.toPath(); //Convert both rectangle to paths

.trim() Returns: Promise.<Vecta.Shape[]>

Trim shapes in the selection object.

Locked shapes will NOT be trimmed. Upon completion, trimmed shapes will be returned, and the selection object will be modified to contain trimmed shapes and locked shapes.

Returns:

Returns a thenable promise containing the shapes that is trimmed.

Examples:

var select = new Vecta.Selection([path1, path2]); //Create a new selection object with two paths

select.trim().then(function (shapes) {
    console.log('Number of shapes from trim operation = ' + shapes.length);
});

.ungroup() Returns: Vecta.Shape[]

Ungroup shapes from the current selection into multiple shapes.

Returns:

Returns the ungrouped shapes.

Examples:

var rect1 = new Vecta.activePage.drawRect(0, 0, 50, 50), //Draw a rect
    rect2 = new Vecta.activePage.drawRect(50, 50, 50, 50), //Draw another rect
    select = new Vecta.Selection([rect1, rect2]), //Create a new selection object with two shapes
    grouped = select.group(); //Group the 2 shapes in the selection object

select.clear().add(grouped).ungroup(); //update the selection and ungroup the 2 shapes

.union() Returns: Promise.<Vecta.Shape[]>

Perform union operation on shapes in the selection object.

Locked shapes will NOT be unioned. Upon completion, unioned shapes will be returned, and the selection object will be modified to contain unioned shapes and locked shapes.

Returns:

Returns a thenable promise containing the shapes that is unioned.

Examples:

var select = new Vecta.Selection([path1, path2]); //Create a new selection object with two paths

select.union().then(function (shapes) {
    if (shapes.length === 1) { console.log('All shapes unioned into a single one'); }
});