Group
Extends Item
A Group is a collection of items. When you transform a Group, its children are treated as a single unit without changing their relative positions.
Constructors
Creates a new Group item and places it at the top of the active layer.
- children: Array of Item objects — An array of children that will be added to the newly created group — optional
Parameters:
- Group
Returns:
Example:Create a group containing two paths:
Example:Click in the view to add a path to the group, which in turn is rotated every frame:
Creates a new Group item and places it at the top of the active layer.
- object: Object — an object containing the properties to be set on the group
Parameters:
- Group
Returns:
Example:
Properties
Specifies whether the group item is to be clipped. When setting to true
, the first child in the group is automatically defined as the clipping mask.
- Boolean
Type:
Example:
Properties inherited from Item
The unique id of the item.
Read only.
- Number
Type:
The class name of the item as a string.
- 'Group', 'Layer', 'Path', 'CompoundPath', 'Shape', 'Raster', 'SymbolItem', 'PointText'
Values:
- String
Type:
The name of the item. If the item has a name, it can be accessed by name through its parent’s children list.
- String
Type:
Example:
The path style of the item.
- Style
Type:
Example:Applying several styles to an item in one go, by passing an object to its style property:
Example:Copying the style of another item:
Example:Applying the same style object to multiple items:
Specifies whether the item is locked. When set to true
, item interactions with the mouse are disabled.
- false
Default:
- Boolean
Type:
Example:
Specifies whether the item is visible. When set to false
, the item won’t be drawn.
- true
Default:
- Boolean
Type:
Example:Hiding an item:
The blend mode with which the item is composited onto the canvas. Both the standard canvas compositing modes, as well as the new CSS blend modes are supported. If blend-modes cannot be rendered natively, they are emulated. Be aware that emulation can have an impact on performance.
- 'normal', 'multiply', 'screen', 'overlay', 'soft-light', 'hard- light', 'color-dodge', 'color-burn', 'darken', 'lighten', 'difference', 'exclusion', 'hue', 'saturation', 'luminosity', 'color', 'add', 'subtract', 'average', 'pin-light', 'negation', 'source-over', 'source-in', 'source-out', 'source-atop', 'destination-over', 'destination-in', 'destination-out', 'destination-atop', 'lighter', 'darker', 'copy', 'xor'
Values:
- 'normal'
Default:
- String
Type:
Example:Setting an item's blend mode:
The opacity of the item as a value between 0
and 1
.
- 1
Default:
- Number
Type:
Example:Making an item 50% transparent:
Specifies whether the item is selected. This will also return true
for Group items if they are partially selected, e.g. groups containing selected or partially selected paths.
Paper.js draws the visual outlines of selected items on top of your project. This can be useful for debugging, as it allows you to see the construction of paths, position of path curves, individual segment points and bounding boxes of symbol and raster items.
- false
Default:
- Boolean
Type:
Example:Selecting an item:
Specifies whether the item defines a clip mask. This can only be set on paths and compound paths, and only if the item is already contained within a clipping group.
- false
Default:
- Boolean
Type:
A plain javascript object which can be used to store arbitrary data on the item.
- Object
Type:
Example:
var path = new Path();
path.data.remember = 'milk';
Example:
var path = new Path();
path.data.malcolm = new Point(20, 30);
console.log(path.data.malcolm.x); // 20
Example:
var path = new Path();
path.data = {
home: 'Omicron Theta',
found: 2338,
pets: ['Spot']
};
console.log(path.data.pets.length); // 1
Example:
var path = new Path({
data: {
home: 'Omicron Theta',
found: 2338,
pets: ['Spot']
}
});
console.log(path.data.pets.length); // 1
Position and Bounding Boxes
The item’s position within the parent item’s coordinate system. By default, this is the rectangle.center of the item’s bounds rectangle.
- Point
Type:
Example:Changing the position of a path:
Example:Changing the x coordinate of an item's position:
The item’s pivot point specified in the item coordinate system, defining the point around which all transformations are hinging. This is also the reference point for position. By default, it is set to null
, meaning the rectangle.center of the item’s bounds rectangle is used as pivot.
- null
Default:
- Point
Type:
The bounding rectangle of the item including stroke width.
- Rectangle
Type:
The bounding rectangle of the item including handles.
- Rectangle
Type:
The bounding rectangle of the item without any matrix transformations.
Typical use case would be drawing a frame around the object where you want to draw something of the same size, position, rotation, and scaling, like a selection frame.
- Rectangle
Type:
The current rotation angle of the item, as described by its matrix. Please note that this only returns meaningful values for items with applyMatrix set to false
, meaning they do not directly bake transformations into their content.
- Number
Type:
The current scale factor of the item, as described by its matrix. Please note that this only returns meaningful values for items with applyMatrix set to false
, meaning they do not directly bake transformations into their content.
- Point
Type:
The item’s transformation matrix, defining position and dimensions in relation to its parent item in which it is contained.
- Matrix
Type:
The item’s global transformation matrix in relation to the global project coordinate space. Note that the view’s transformations resulting from zooming and panning are not factored in.
Read only.
- Matrix
Type:
The item’s global matrix in relation to the view coordinate space. This means that the view’s transformations resulting from zooming and panning are factored in.
Read only.
- Matrix
Type:
Controls whether the transformations applied to the item (e.g. through transform(matrix), rotate(angle), scale(scale), etc.) are stored in its matrix property, or whether they are directly applied to its contents or children (passed on to the segments in Path items, the children of Group items, etc.).
- true
Default:
- Boolean
Type:
Project Hierarchy
The item that this item is contained within.
- Item
Type:
Example:
var path = new Path();
// New items are placed in the active layer:
console.log(path.parent == project.activeLayer); // true
var group = new Group();
group.addChild(path);
// Now the parent of the path has become the group:
console.log(path.parent == group); // true
Example:Setting the parent of the item to another item
var path = new Path();
// New items are placed in the active layer:
console.log(path.parent == project.activeLayer); // true
var group = new Group();
path.parent = group;
// Now the parent of the path has become the group:
console.log(path.parent == group); // true
// The path is now contained in the children list of group:
console.log(group.children[0] == path); // true
Example:Setting the parent of an item in the constructor
var group = new Group();
var path = new Path({
parent: group
});
// The parent of the path is the group:
console.log(path.parent == group); // true
// The path is contained in the children list of group:
console.log(group.children[0] == path); // true
The children items contained within this item. Items that define a name can also be accessed by name.
Please note: The children array should not be modified directly using array functions. To remove single items from the children list, use item.remove(), to remove all items from the children list, use item.removeChildren(). To add items to the children list, use item.addChild(item) or item.insertChild(index, item).
- Array of Item objects
Type:
Example:Accessing items in the children array:
Example:Accessing children by name:
Example:Passing an array of items to item.children:
The first item contained within this item. This is a shortcut for accessing item.children[0]
.
Read only.
- Item
Type:
The last item contained within this item.This is a shortcut for accessing item.children[item.children.length - 1]
.
Read only.
- Item
Type:
The index of this item within the list of its parent’s children.
Read only.
- Number
Type:
Stroke Style
The width of the stroke.
- Number
Type:
Example:Setting an item's stroke width:
The shape to be used at the beginning and end of open Path items, when they have a stroke.
- 'round', 'square', 'butt'
Values:
- 'butt'
Default:
- String
Type:
Example:A look at the different stroke caps:
The shape to be used at the segments and corners of Path items when they have a stroke.
- 'miter', 'round', 'bevel'
Values:
- 'miter'
Default:
- String
Type:
Example:A look at the different stroke joins:
The dash offset of the stroke.
- 0
Default:
- Number
Type:
Specifies whether the stroke is to be drawn taking the current affine transformation into account (the default behavior), or whether it should appear as a non-scaling stroke.
- true
Default:
- Boolean
Type:
Specifies an array containing the dash and gap lengths of the stroke.
- []
Default:
- Array of Numbers
Type:
Example:
The miter limit of the stroke. When two line segments meet at a sharp angle and miter joins have been specified for item.strokeJoin, it is possible for the miter to extend far beyond the item.strokeWidth of the path. The miterLimit imposes a limit on the ratio of the miter length to the item.strokeWidth.
- 10
Default:
- Number
Type:
Fill Style
The fill-rule with which the shape gets filled. Please note that only modern browsers support fill-rules other than 'nonzero'
.
- 'nonzero', 'evenodd'
Values:
- 'nonzero'
Default:
- String
Type:
Shadow Style
The shadow’s blur radius.
- 0
Default:
- Number
Type:
Selection Style
The color the item is highlighted with when selected. If the item does not specify its own color, the color defined by its layer is used instead.
- Color⟋null
Type:
Event Handlers
Item level handler function to be called on each frame of an animation. The function receives an event object which contains information about the frame event:
- Function⟋null
Type:
- event.count: Number — the number of times the frame event was fired
- event.time: Number — the total amount of time passed since the first frame event in seconds
- event.delta: Number — the time passed in seconds since the last frame event
Options:
- view.onFrame
See also:
Example:Creating an animation:
The function to be called when the mouse button is pushed down on the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false
from the handler.
- Function⟋null
Type:
- view.onMouseDown
See also:
Example:Press the mouse button down on the circle shaped path, to make it red:
Example:Press the mouse on the circle shaped paths to remove them:
The function to be called when the mouse position changes while the mouse is being dragged over the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false
from the handler.
- Function⟋null
Type:
- view.onMouseDrag
See also:
Example:Press and drag the mouse on the blue circle to move it:
The function to be called when the mouse button is released over the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false
from the handler.
- Function⟋null
Type:
- view.onMouseUp
See also:
Example:Release the mouse button over the circle shaped path, to make it red:
The function to be called when the mouse clicks on the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false
from the handler.
- Function⟋null
Type:
- view.onClick
See also:
Example:Click on the circle shaped path, to make it red:
Example:Click on the circle shaped paths to remove them:
The function to be called when the mouse double clicks on the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false
from the handler.
- Function⟋null
Type:
- view.onDoubleClick
See also:
Example:Double click on the circle shaped path, to make it red:
Example:Double click on the circle shaped paths to remove them:
The function to be called repeatedly while the mouse moves over the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false
from the handler.
- Function⟋null
Type:
- view.onMouseMove
See also:
Example:Move over the circle shaped path, to change its opacity:
The function to be called when the mouse moves over the item. This function will only be called again, once the mouse moved outside of the item first. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false
from the handler.
- Function⟋null
Type:
- view.onMouseEnter
See also:
Example:When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set back to black.
Example:When you click the mouse, you create new circle shaped items. When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set back to black.
The function to be called when the mouse moves out of the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false
from the handler.
- Function⟋null
Type:
- view.onMouseLeave
See also:
Example:Move the mouse over the circle shaped path and then move it out of it again to set its fill color to red:
Methods inherited from Item
Sets the properties of the passed object literal on this item to the values defined in the object literal, if the item has property of the given name (or a setter defined for it).
- props: Object
Parameters:
- Item — the item itself
Returns:
Example:Setting properties through an object literal
Clones the item within the same project and places the copy above the item.
- insert: undefined — specifies whether the copy should be inserted into the scene graph. When set to
true
, it is inserted above the original — default: true - deep: undefined — specifies whether the item’s children should also be cloned — default: true
Options:
- options: Object — optional, default: { insert: true, deep: true }
Parameters:
- Item — the newly cloned item
Returns:
Example:Cloning items:
Copies the content of the specified item over to this item.
- source: Item — the item to copy the content from
Parameters:
Copies all attributes of the specified item over to this item. This includes its style, visibility, matrix, pivot, blend-mode, opacity, selection state, data, name, etc.
- source: Item — the item to copy the attributes from
- excludeMatrix: Boolean — whether to exclude the transformation matrix when copying all attributes
Parameters:
Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization.
- resolution: Number — the desired resolution to be used when rasterizing, in pixels per inch (DPI). If not specified, the value of
view.resolution
is used by default. — default: view.resolution - raster: Raster — specifies a raster to be reused when rasterizing. If the raster has the desired size already, then the underlying canvas is reused and no new memory needs to be allocated. If no raster is provided, a new raster item is created and returned instead. — default: null
- insert: Boolean — specifies whether the raster should be inserted into the scene graph. When set to
true
, it is inserted above the rasterized item. — default: true
Options:
- options: Object — the rasterization options — optional, default: {}
Parameters:
- Raster — the reused raster or the newly created raster item
Returns:
Example:Rasterizing an item:
Geometric Tests
Checks whether the item’s geometry contains the given point.
- point: Point — the point to check for
Parameters:
- Boolean
Returns:
Example:Click within and outside the star below Create a star shaped path:
- rect: Rectangle — the rectangle to check against
Parameters:
- Boolean
Returns:
- item: Item — the item to check against
Parameters:
- Boolean
Returns:
Hit-testing, Fetching and Matching Items
Performs a hit-test on the item and its children (if it is a Group or Layer) at the location of the specified point, returning the first found hit.
The options object allows you to control the specifics of the hit- test and may contain a combination of the following values:
- options.tolerance: Number — the tolerance of the hit-test — default: paperScope.settings.hitTolerance
- options.class: Function — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an
instanceof
check is performed: Group, Layer, Path, CompoundPath, Shape, Raster, SymbolItem, PointText, … - options.match: Function — a match function to be called for each found hit result: Return
true
to return the result,false
to keep searching - options.fill: Boolean — hit-test the fill of items — default: true
- options.stroke: Boolean — hit-test the stroke of path items, taking into account the setting of stroke color and width — default: true
- options.segments: Boolean — hit-test for segment.point of Path items — default: true
- options.curves: Boolean — hit-test the curves of path items, without taking the stroke color or width into account
- options.handles: Boolean — hit-test for the handles (segment.handleIn / segment.handleOut) of path segments.
- options.ends: Boolean — only hit-test for the first or last segment points of open path items
- options.position: Boolean — hit-test the item.position of of items, which depends on the setting of item.pivot
- options.center: Boolean — hit-test the rectangle.center of the bounding rectangle of items (item.bounds)
- options.bounds: Boolean — hit-test the corners and side-centers of the bounding rectangle of items (item.bounds)
- options.guides: Boolean — hit-test items that have Item#guide set to
true
- options.selected: Boolean — only hit selected items
Options:
- point: Point — the point where the hit-test should be performed (in global coordinates system).
- options: Object — optional, default: { fill: true, stroke: true, segments: true, tolerance: settings.hitTolerance }
Parameters:
-
HitResult — a hit result object describing what exactly was hit or
null
if nothing was hit
Returns:
Performs a hit-test on the item and its children (if it is a Group or Layer) at the location of the specified point, returning all found hits.
The options object allows you to control the specifics of the hit- test. See hitTest(point[, options]) for a list of all options.
- point: Point — the point where the hit-test should be performed (in global coordinates system).
- options: Object — optional, default: { fill: true, stroke: true, segments: true, tolerance: settings.hitTolerance }
Parameters:
-
Array of HitResult objects — hit result objects for all hits, describing what exactly was hit or
null
if nothing was hit
Returns:
- hitTest(point[, options]);
See also:
Checks whether the item matches the criteria described by the given object, by iterating over all of its properties and matching against their values through matches(name, compare).
See project.getItems(options) for a selection of illustrated examples.
- options: Object⟋Function — the criteria to match against
Parameters:
- Boolean — true if the item matches all the criteria, false otherwise
Returns:
- getItems(options)
See also:
Checks whether the item matches the given criteria. Extended matching is possible by providing a compare function or a regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x-coordinate to match all points with that x-value). Partial matching does work for item.data.
See project.getItems(options) for a selection of illustrated examples.
- name: String — the name of the state to match against
- compare: Object — the value, function or regular expression to compare against
Parameters:
- Boolean — true if the item matches the state, false otherwise
Returns:
- getItems(options)
See also:
Fetch the descendants (children or children of children) of this item that match the properties in the specified object. Extended matching is possible by providing a compare function or regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x- coordinate to match all points with that x-value). Partial matching does work for item.data.
Matching items against a rectangular area is also possible, by setting either options.inside
or options.overlapping
to a rectangle describing the area in which the items either have to be fully or partly contained.
See project.getItems(options) for a selection of illustrated examples.
- options.recursive: Boolean — whether to loop recursively through all children, or stop at the current level — default: true
- options.match: Function — a match function to be called for each item, allowing the definition of more flexible item checks that are not bound to properties. If no other match properties are defined, this function can also be passed instead of the
options
object - options.class: Function — the constructor function of the item type to match against
- options.inside: Rectangle — the rectangle in which the items need to be fully contained
- options.overlapping: Rectangle — the rectangle with which the items need to at least partly overlap
Options:
- options: Object⟋Function — the criteria to match against
Parameters:
- Array of Item objects — the list of matching descendant items
Returns:
- matches(options)
See also:
Fetch the first descendant (child or child of child) of this item that matches the properties in the specified object. Extended matching is possible by providing a compare function or regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x- coordinate to match all points with that x-value). Partial matching does work for item.data. See project.getItems(match) for a selection of illustrated examples.
- options: Object⟋Function — the criteria to match against
Parameters:
- Item — the first descendant item matching the given criteria
Returns:
- getItems(options)
See also:
Importing / Exporting JSON and SVG
Exports (serializes) the item with its content and child items to a JSON data string.
- options.asString: Boolean — whether the JSON is returned as a
Object
or aString
— default: true - options.precision: Number — the amount of fractional digits in numbers used in JSON data — default: 5
Options:
- options: Object — the serialization options — optional
Parameters:
- String — the exported JSON data
Returns:
Imports (deserializes) the stored JSON data into this item. If the data describes an item of the same class or a parent class of the item, the data is imported into the item itself. If not, the imported item is added to this item’s item.children list. Note that not all type of items can have children.
- json: String — the JSON data to import from
Parameters:
- Item
Returns:
Exports the item with its content and child items as an SVG DOM.
- options.bounds: String⟋Rectangle — the bounds of the area to export, either as a string (‘view’, content’), or a Rectangle object:
'view'
uses the view bounds,'content'
uses the stroke bounds of all content — default: ‘view’ - options.matrix: Matrix — the matrix with which to transform the exported content: If
options.bounds
is set to'view'
,paper.view.matrix
is used, for all other settings ofoptions.bounds
the identity matrix is used. — default: paper.view.matrix - options.asString: Boolean — whether a SVG node or a
String
is to be returned — default: false - options.precision: Number — the amount of fractional digits in numbers used in SVG data — default: 5
- options.matchShapes: Boolean — whether path items should tried to be converted to SVG shape items (rect, circle, ellipse, line, polyline, polygon), if their geometries match — default: false
- options.embedImages: Boolean — whether raster images should be embedded as base64 data inlined in the xlink:href attribute, or kept as a link to their external URL. — default: true
Options:
- options: Object — the export options — optional
Parameters:
-
SVGElement⟋String — the item converted to an SVG node or a
String
depending onoption.asString
value
Returns:
Converts the provided SVG content into Paper.js items and adds them to the this item’s children list. Note that the item is not cleared first. You can call item.removeChildren() to do so.
- options.expandShapes: Boolean — whether imported shape items should be expanded to path items — default: false
- options.onLoad: Function — the callback function to call once the SVG content is loaded from the given URL receiving two arguments: the converted
item
and the originalsvg
data as a string. Only required when loading from external resources. - options.onError: Function — the callback function to call if an error occurs during loading. Only required when loading from external resources.
- options.insert: Boolean — whether the imported items should be added to the item that
importSVG()
is called on — default: true - options.applyMatrix: Boolean — whether the imported items should have their transformation matrices applied to their contents or not — default: paperScope.settings.applyMatrix
Options:
- svg: SVGElement⟋String — the SVG content to import, either as a SVG DOM node, a string containing SVG content, or a string describing the URL of the SVG file to fetch.
- options: Object — the import options — optional
Parameters:
- Item — the newly created Paper.js item containing the converted SVG content
Returns:
Imports the provided external SVG file, converts it into Paper.js items and adds them to the this item’s children list. Note that the item is not cleared first. You can call item.removeChildren() to do so.
- svg: SVGElement⟋String — the URL of the SVG file to fetch.
-
onLoad:
Function
— the callback function to call once the SVG content is loaded from the given URL receiving two arguments: the converted
item
and the originalsvg
data as a string. Only required when loading from external files.
Parameters:
- Item — the newly created Paper.js item containing the converted SVG content
Returns:
Hierarchy Operations
Inserts the specified item as a child of this item at the specified index in its children list. You can use this function for groups, compound paths and layers.
- index: Number — the index at which to insert the item
- item: Item — the item to be inserted as a child
Parameters:
-
Item — the inserted item, or
null
if inserting was not possible
Returns:
Adds the specified items as children of this item at the end of the its children list. You can use this function for groups, compound paths and layers.
- items: Array of Item objects — the items to be added as children
Parameters:
-
Array of Item objects — the added items, or
null
if adding was not possible
Returns:
Inserts the specified items as children of this item at the specified index in its children list. You can use this function for groups, compound paths and layers.
- index: Number
- items: Array of Item objects — the items to be appended as children
Parameters:
-
Array of Item objects — the inserted items, or
null
if inserted was not possible
Returns:
Sends this item to the back of all other items within the same parent.
Brings this item to the front of all other items within the same parent.
If this is a group, layer or compound-path with only one child-item, the child-item is moved outside and the parent is erased. Otherwise, the item itself is returned unmodified.
- options:
Parameters:
- Item — the reduced item
Returns:
Removes the item and all its children from the project. The item is not destroyed and can be inserted again after removal.
- Boolean — true if the item was removed, false otherwise
Returns:
Replaces this item with the provided new item which will takes its place in the project hierarchy instead.
- item: Item — the item that will replace this item
Parameters:
- Boolean — true if the item was replaced, false otherwise
Returns:
Removes the children from the specified start
index to and excluding the end
index from the parent’s children array.
- start: Number — the beginning index, inclusive
- end: Number — the ending index, exclusive — optional, default: children.length
Parameters:
- Array of Item objects — an array containing the removed items
Returns:
Reverses the order of the item’s children
Tests
Specifies whether the item has any content or not. The meaning of what content is differs from type to type. For example, a Group with no children, a TextItem with no text content and a Path with no segments all are considered empty.
- recursively: Boolean — whether an item with children should be considered empty if all its descendants are empty — optional, default: false
Parameters:
- Boolean
Returns:
Style Tests
Checks whether the item has a fill.
- Boolean — true if the item has a fill, false otherwise
Returns:
Checks whether the item has a stroke.
- Boolean — true if the item has a stroke, false otherwise
Returns:
Checks whether the item has a shadow.
- Boolean — true if the item has a shadow, false otherwise
Returns:
Hierarchy Tests
Checks if the item contains any children items.
- Boolean — true it has one or more children, false otherwise
Returns:
Checks whether the item and all its parents are inserted into scene graph or not.
- Boolean — true if the item is inserted into the scene graph, false otherwise
Returns:
Checks if this item is above the specified item in the stacking order of the project.
- item: Item — the item to check against
Parameters:
- Boolean — true if it is above the specified item, false otherwise
Returns:
Checks if the item is below the specified item in the stacking order of the project.
- item: Item — the item to check against
Parameters:
- Boolean — true if it is below the specified item, false otherwise
Returns:
Checks whether the specified item is the parent of the item.
- item: Item — the item to check against
Parameters:
- Boolean — true if it is the parent of the item, false otherwise
Returns:
Checks whether the specified item is a child of the item.
- item: Item — the item to check against
Parameters:
- Boolean — true it is a child of the item, false otherwise
Returns:
Checks if the item is contained within the specified item.
- item: Item — the item to check against
Parameters:
- Boolean — true if it is inside the specified item, false otherwise
Returns:
Checks if the item is an ancestor of the specified item.
- item: Item — the item to check against
Parameters:
- Boolean — true if the item is an ancestor of the specified item, false otherwise
Returns:
Checks if the item is an a sibling of the specified item.
- item: Item — the item to check against
Parameters:
- Boolean — true if the item is aa sibling of the specified item, false otherwise
Returns:
Checks whether the item is grouped with the specified item.
- item: Item
Parameters:
- Boolean — true if the items are grouped together, false otherwise
Returns:
Transform Functions
Translates (moves) the item by the given offset views.
- delta: Point — the offset to translate the item by
Parameters:
Rotates the item by a given angle around the given center point.
Angles are oriented clockwise and measured in degrees.
- angle: Number — the rotation angle
- center: Point — optional, default: item.position
Parameters:
- matrix.rotate(angle[, center])
See also:
Example:Rotating an item:
Example:Rotating an item around a specific point:
Scales the item by the given value from its center point, or optionally from a supplied point.
- scale: Number — the scale factor
- center: Point — optional, default: item.position
Parameters:
Example:Scaling an item from its center point:
Example:Scaling an item from a specific point:
Scales the item by the given values from its center point, or optionally from a supplied point.
- hor: Number — the horizontal scale factor
- ver: Number — the vertical scale factor
- center: Point — optional, default: item.position
Parameters:
Example:Scaling an item horizontally by 300%:
Shears the item by the given value from its center point, or optionally by a supplied point.
- shear: Point — the horizontal and vertical shear factors as a point
- center: Point — optional, default: item.position
Parameters:
- matrix.shear(shear[, center])
See also:
Shears the item by the given values from its center point, or optionally by a supplied point.
- hor: Number — the horizontal shear factor
- ver: Number — the vertical shear factor
- center: Point — optional, default: item.position
Parameters:
- matrix.shear(hor, ver[, center])
See also:
Skews the item by the given angles from its center point, or optionally by a supplied point.
- skew: Point — the horizontal and vertical skew angles in degrees
- center: Point — optional, default: item.position
Parameters:
- matrix.shear(skew[, center])
See also:
Skews the item by the given angles from its center point, or optionally by a supplied point.
- hor: Number — the horizontal skew angle in degrees
- ver: Number — the vertical sskew angle in degrees
- center: Point — optional, default: item.position
Parameters:
- matrix.shear(hor, ver[, center])
See also:
Transform the item.
- matrix: Matrix — the matrix by which the item shall be transformed
Parameters:
Transform the item so that its bounds fit within the specified rectangle, without changing its aspect ratio.
- rectangle: Rectangle
- fill: Boolean — optional, default: false
Parameters:
Example:Fitting an item to the bounding rectangle of another item's bounding rectangle:
Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true:
Example:Fitting an item to the bounding rectangle of the view
Event Handling
Attaches an event handler to the item.
- type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’
- function: Function — the function to be called when the event occurs, receiving a MouseEvent or Event object as its sole argument
Parameters:
- Item — this item itself, so calls can be chained
Returns:
Example:Change the fill color of the path to red when the mouse enters its shape and back to black again, when it leaves its shape.
Attaches one or more event handlers to the item.
- object: Object — an object containing one or more of the following properties: frame, mousedown, mouseup, mousedrag, click, doubleclick, mousemove, mouseenter, mouseleave
Parameters:
- Item — this item itself, so calls can be chained
Returns:
Example:Change the fill color of the path to red when the mouse enters its shape and back to black again, when it leaves its shape.
Example:When you click the mouse, you create new circle shaped items. When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set black.
Detach an event handler from the item.
- type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’
- function: Function — the function to be detached
Parameters:
- Item — this item itself, so calls can be chained
Returns:
Detach one or more event handlers to the item.
- object: Object — an object containing one or more of the following properties: frame, mousedown, mouseup, mousedrag, click, doubleclick, mousemove, mouseenter, mouseleave
Parameters:
- Item — this item itself, so calls can be chained
Returns:
Emit an event on the item.
- type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’
- event: Object — an object literal containing properties describing the event
Parameters:
- Boolean — true if the event had listeners, false otherwise
Returns:
Check if the item has one or more event handlers of the specified type.
- type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’
Parameters:
- Boolean — true if the item has one or more event handlers of the specified type, false otherwise
Returns:
Remove On Event
Removes the item when the events specified in the passed options object occur.
- options.move: undefined — {Boolean) remove the item when the next tool.onMouseMove event is fired.
- options.drag: undefined — {Boolena) remove the item when the next tool.onMouseDrag event is fired.
- options.down: undefined — {Boolean) remove the item when the next tool.onMouseDown event is fired.
- options.up: undefined — {Boolean) remove the item when the next tool.onMouseUp event is fired.
Options:
- options: Object
Parameters:
Example:Click and drag below:
Removes the item when the next tool.onMouseDown event is fired.
Example:Click a few times below:
Tweening Functions
Tween item between two states.
- options.duration: Number — the duration of the tweening
- options.easing: Function⟋String — an easing function or the type of the easing: ‘linear’ ‘easeInQuad’ ‘easeOutQuad’ ‘easeInOutQuad’ ‘easeInCubic’ ‘easeOutCubic’ ‘easeInOutCubic’ ‘easeInQuart’ ‘easeOutQuart’ ‘easeInOutQuart’ ‘easeInQuint’ ‘easeOutQuint’ ‘easeInOutQuint’ — default: ‘linear’
- options.start: Boolean — whether to start tweening automatically — default: true
Options:
- from: Object — the state at the start of the tweening
- to: Object — the state at the end of the tweening
- options: Object⟋Number — the options or the duration
Parameters:
- Tween
Returns:
Example:Tween fillColor:
Example:Tween rotation:
Tween item to a state.
- to: Object — the state at the end of the tweening
- options: Object⟋Number — the options or the duration
Parameters:
- Tween
Returns:
- item.tween(from, to, options)
See also:
Example:Tween a nested property with relative values
Tween item.
- options: Object⟋Number — the options or the duration
Parameters:
- Tween
Returns:
- item.tween(from, to, options)
See also:
Example:Start an empty tween and just use the update callback:
Tween item to a state.
- to: Object — the state at the end of the tweening
- options: Object⟋Number — the options or the duration
Parameters:
- Tween
Returns:
- item.tween(to, options)
See also:
Tween item from a state to its state before the tweening.
- from: Object — the state at the start of the tweening
- options: Object⟋Number — the options or the duration
Parameters:
- Tween
Returns:
- item.tween(from, to, options)