Paper.jsTypogram

CompoundPath

Extends Item, PathItem

A compound path is a complex path that is made up of one or more simple sub-paths. It can have the nonzero fill rule, or the evenodd rule applied. Both rules use mathematical equations to determine if any region is outside or inside the final shape. The evenodd rule is more predictable: Every other region within a such a compound path is a hole, regardless of path direction.

All the paths in a compound path take on the style of the compound path and can be accessed through its item.children list.

Constructors

  • CompoundPath(object)

    Creates a new compound path item from an object description and places it at the top of the active layer.

    • Parameters:

      • object: Object — an object containing properties to be set on the path

    • Returns:

      • CompoundPath — the newly created path

    Example:

    var path = new CompoundPath({
    children: [
        new Path.Circle({
            center: new Point(50, 50),
            radius: 30
        }),
        new Path.Circle({
            center: new Point(50, 50),
            radius: 10
        })
    ],
    fillColor: 'black',
    selected: true
});

  • CompoundPath(pathData)

    Creates a new compound path item from SVG path-data and places it at the top of the active layer.

    • Parameters:

      • pathData: String — the SVG path-data that describes the geometry of this path

    • Returns:

      • CompoundPath — the newly created path

    Example:

    var pathData = 'M20,50c0,-16.56854 13.43146,-30 30,-30c16.56854,0 30,13.43146 30,30c0,16.56854 -13.43146,30 -30,30c-16.56854,0 -30,-13.43146 -30,-30z M50,60c5.52285,0 10,-4.47715 10,-10c0,-5.52285 -4.47715,-10 -10,-10c-5.52285,0 -10,4.47715 -10,10c0,5.52285 4.47715,10 10,10z';
var path = new CompoundPath(pathData);
path.fillColor = 'black';

Properties

  • closed

    Specifies whether the compound-path is fully closed, meaning all its contained sub-paths are closed path.

    • Type:

      • Boolean

    • See also:

      • path.closed

  • firstSegment

    The first Segment contained within the compound-path, a short-cut to calling path.firstSegment on item.firstChild.

    Read only.

    • Type:

      • Segment

  • lastSegment

    The last Segment contained within the compound-path, a short-cut to calling path.lastSegment on item.lastChild.

    Read only.

    • Type:

      • Segment

  • curves

    All the curves contained within the compound-path, from all its child Path items.

    Read only.

    • Type:

      • Array of Curve objects

  • firstCurve

    The first Curve contained within the compound-path, a short-cut to calling path.firstCurve on item.firstChild.

    Read only.

    • Type:

      • Curve

  • lastCurve

    The last Curve contained within the compound-path, a short-cut to calling path.lastCurve on item.lastChild.

    Read only.

    • Type:

      • Curve

  • area

    The area that the compound-path’s geometry is covering, calculated by getting the path.area of each sub-path and it adding up. Note that self-intersecting paths and sub-paths of different orientation can result in areas that cancel each other out.

    Read only.

    • Type:

      • Number

  • length

    The total length of all sub-paths in this compound-path, calculated by getting the path.length of each sub-path and it adding up.

    Read only.

    • Type:

      • Number

Properties inherited from Item

  • id

    The unique id of the item.

    Read only.

    • Type:

    • Number

  • className

    The class name of the item as a string.

    • Values:

    • 'Group', 'Layer', 'Path', 'CompoundPath', 'Shape', 'Raster', 'SymbolItem', 'PointText'

    • Type:

    • String

    name

    The name of the item. If the item has a name, it can be accessed by name through its parent’s children list.

    • Type:

    • String

    Example:

    var path = new Path.Circle({
    center: [80, 50],
    radius: 35
});
// Set the name of the path:
path.name = 'example';

// Create a group and add path to it as a child:
var group = new Group();
group.addChild(path);

// The path can be accessed by name:
group.children['example'].fillColor = 'red';

  • style

    The path style of the item.

    • Type:

    • Style

    Example:Applying several styles to an item in one go, by passing an object to its style property:

    var circle = new Path.Circle({
    center: [80, 50],
    radius: 30
});
circle.style = {
    fillColor: 'blue',
    strokeColor: 'red',
    strokeWidth: 5
};

    Example:Copying the style of another item:

    var path = new Path.Circle({
    center: [50, 50],
    radius: 30,
    fillColor: 'red'
});

var path2 = new Path.Circle({
    center: new Point(180, 50),
    radius: 20
});

// Copy the path style of path:
path2.style = path.style;

    Example:Applying the same style object to multiple items:

    var myStyle = {
    fillColor: 'red',
    strokeColor: 'blue',
    strokeWidth: 4
};

var path = new Path.Circle({
    center: [50, 50],
    radius: 30
});
path.style = myStyle;

var path2 = new Path.Circle({
    center: new Point(150, 50),
    radius: 20
});
path2.style = myStyle;

  • locked

    Specifies whether the item is locked. When set to true, item interactions with the mouse are disabled.

    • Default:

    • false

    • Type:

    • Boolean

    Example:

    var unlockedItem = new Path.Circle({
    center: view.center - [35, 0],
    radius: 30,
    fillColor: 'springgreen',
    onMouseDown: function() {
        this.fillColor = Color.random();
    }
});

var lockedItem = new Path.Circle({
    center: view.center + [35, 0],
    radius: 30,
    fillColor: 'crimson',
    locked: true,
    // This event won't be triggered because the item is locked.
    onMouseDown: function() {
        this.fillColor = Color.random();
    }
});

new PointText({
    content: 'Click on both circles to see which one is locked.',
    point: view.center - [0, 35],
    justification: 'center'
});

  • visible

    Specifies whether the item is visible. When set to false, the item won’t be drawn.

    • Default:

    • true

    • Type:

    • Boolean

    Example:Hiding an item:

    var path = new Path.Circle({
    center: [50, 50],
    radius: 20,
    fillColor: 'red'
});

// Hide the path:
path.visible = false;

  • blendMode

    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.

    • Values:

    • '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'

    • Default:

    • 'normal'

    • Type:

    • String

    Example:Setting an item's blend mode:

    // Create a white rectangle in the background
// with the same dimensions as the view:
var background = new Path.Rectangle(view.bounds);
background.fillColor = 'white';

var circle = new Path.Circle({
    center: [80, 50],
    radius: 35,
    fillColor: 'red'
});

var circle2 = new Path.Circle({
    center: new Point(120, 50),
    radius: 35,
    fillColor: 'blue'
});

// Set the blend mode of circle2:
circle2.blendMode = 'multiply';

  • opacity

    The opacity of the item as a value between 0 and 1.

    • Default:

    • 1

    • Type:

    • Number

    Example:Making an item 50% transparent:

    var circle = new Path.Circle({
    center: [80, 50],
    radius: 35,
    fillColor: 'red'
});

var circle2 = new Path.Circle({
    center: new Point(120, 50),
    radius: 35,
    fillColor: 'blue',
    strokeColor: 'green',
    strokeWidth: 10
});

// Make circle2 50% transparent:
circle2.opacity = 0.5;

  • selected

    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.

    • Default:

    • false

    • Type:

    • Boolean

    • See also:

    • project.selectedItems

    • segment.selected

    • curve.selected

    • point.selected

    Example:Selecting an item:

    var path = new Path.Circle({
    center: [80, 50],
    radius: 35
});
path.selected = true; // Select the path

  • clipMask

    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.

    • Default:

    • false

    • Type:

    • Boolean

  • data

    A plain javascript object which can be used to store arbitrary data on the item.

    • Type:

    • Object

    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

  • position

    The item’s position within the parent item’s coordinate system. By default, this is the rectangle.center of the item’s bounds rectangle.

    • Type:

    • Point

    Example:Changing the position of a path:

    // Create a circle at position { x: 10, y: 10 }
var circle = new Path.Circle({
    center: new Point(10, 10),
    radius: 10,
    fillColor: 'red'
});

// Move the circle to { x: 20, y: 20 }
circle.position = new Point(20, 20);

// Move the circle 100 points to the right and 50 points down
circle.position += new Point(100, 50);

    Example:Changing the x coordinate of an item's position:

    // Create a circle at position { x: 20, y: 20 }
var circle = new Path.Circle({
    center: new Point(20, 20),
    radius: 10,
    fillColor: 'red'
});

// Move the circle 100 points to the right
circle.position.x += 100;

  • pivot

    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.

    • Default:

    • null

    • Type:

    • Point

  • bounds

    The bounding rectangle of the item excluding stroke width.

    • Type:

    • Rectangle

  • strokeBounds

    The bounding rectangle of the item including stroke width.

    • Type:

    • Rectangle

  • handleBounds

    The bounding rectangle of the item including handles.

    • Type:

    • Rectangle

  • internalBounds

    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.

    • Type:

    • Rectangle

  • rotation

    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.

    • Type:

    • Number

  • scaling

    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.

    • Type:

    • Point

  • matrix

    The item’s transformation matrix, defining position and dimensions in relation to its parent item in which it is contained.

    • Type:

    • Matrix

  • globalMatrix

    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.

    • Type:

    • Matrix

  • viewMatrix

    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.

    • Type:

    • Matrix

  • applyMatrix

    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.).

    • Default:

    • true

    • Type:

    • Boolean

Project Hierarchy

  • project

    The project that this item belongs to.

    Read only.

    • Type:

    • Project

  • view

    The view that this item belongs to.

    Read only.

    • Type:

    • View

  • layer

    The layer that this item is contained within.

    Read only.

    • Type:

    • Layer

  • parent

    The item that this item is contained within.

    • Type:

    • Item

    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

  • children

    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).

    • Type:

    • Array of Item objects

    Example:Accessing items in the children array:

    var path = new Path.Circle({
    center: [80, 50],
    radius: 35
});

// Create a group and move the path into it:
var group = new Group();
group.addChild(path);

// Access the path through the group's children array:
group.children[0].fillColor = 'red';

    Example:Accessing children by name:

    var path = new Path.Circle({
    center: [80, 50],
    radius: 35
});
// Set the name of the path:
path.name = 'example';

// Create a group and move the path into it:
var group = new Group();
group.addChild(path);

// The path can be accessed by name:
group.children['example'].fillColor = 'orange';

    Example:Passing an array of items to item.children:

    var path = new Path.Circle({
    center: [80, 50],
    radius: 35
});

var group = new Group();
group.children = [path];

// The path is the first child of the group:
group.firstChild.fillColor = 'green';

  • firstChild

    The first item contained within this item. This is a shortcut for accessing item.children[0].

    Read only.

    • Type:

    • Item

  • lastChild

    The last item contained within this item.This is a shortcut for accessing item.children[item.children.length - 1].

    Read only.

    • Type:

    • Item

  • nextSibling

    The next item on the same level as this item.

    Read only.

    • Type:

    • Item

  • previousSibling

    The previous item on the same level as this item.

    Read only.

    • Type:

    • Item

  • index

    The index of this item within the list of its parent’s children.

    Read only.

    • Type:

    • Number

Stroke Style

  • strokeColor

    The color of the stroke.

    • Type:

    • Color⟋null

    Example:Setting the stroke color of a path:

    // Create a circle shaped path at { x: 80, y: 50 }
// with a radius of 35:
var circle = new Path.Circle({
    center: [80, 50],
    radius: 35
});

// Set its stroke color to RGB red:
circle.strokeColor = new Color(1, 0, 0);

  • strokeWidth

    The width of the stroke.

    • Type:

    • Number

    Example:Setting an item's stroke width:

    // Create a circle shaped path at { x: 80, y: 50 }
// with a radius of 35:
var circle = new Path.Circle({
    center: [80, 50],
    radius: 35,
    strokeColor: 'red'
});

// Set its stroke width to 10:
circle.strokeWidth = 10;

  • strokeCap

    The shape to be used at the beginning and end of open Path items, when they have a stroke.

    • Values:

    • 'round', 'square', 'butt'

    • Default:

    • 'butt'

    • Type:

    • String

    Example:A look at the different stroke caps:

    var line = new Path({
    segments: [[80, 50], [420, 50]],
    strokeColor: 'black',
    strokeWidth: 20,
    selected: true
});

// Set the stroke cap of the line to be round:
line.strokeCap = 'round';

// Copy the path and set its stroke cap to be square:
var line2 = line.clone();
line2.position.y += 50;
line2.strokeCap = 'square';

// Make another copy and set its stroke cap to be butt:
var line2 = line.clone();
line2.position.y += 100;
line2.strokeCap = 'butt';

  • strokeJoin

    The shape to be used at the segments and corners of Path items when they have a stroke.

    • Values:

    • 'miter', 'round', 'bevel'

    • Default:

    • 'miter'

    • Type:

    • String

    Example:A look at the different stroke joins:

    var path = new Path({
    segments: [[80, 100], [120, 40], [160, 100]],
    strokeColor: 'black',
    strokeWidth: 20,
    // Select the path, in order to see where the stroke is formed:
    selected: true
});

var path2 = path.clone();
path2.position.x += path2.bounds.width * 1.5;
path2.strokeJoin = 'round';

var path3 = path2.clone();
path3.position.x += path3.bounds.width * 1.5;
path3.strokeJoin = 'bevel';

  • dashOffset

    The dash offset of the stroke.

    • Default:

    • 0

    • Type:

    • Number

  • strokeScaling

    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.

    • Default:

    • true

    • Type:

    • Boolean

  • dashArray

    Specifies an array containing the dash and gap lengths of the stroke.

    • Default:

    • []

    • Type:

    • Array of Numbers

    Example:

    var path = new Path.Circle({
    center: [80, 50],
    radius: 40,
    strokeWidth: 2,
    strokeColor: 'black'
});

// Set the dashed stroke to [10pt dash, 4pt gap]:
path.dashArray = [10, 4];

  • miterLimit

    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.

    • Default:

    • 10

    • Type:

    • Number

Fill Style

  • fillColor

    The fill color of the item.

    • Type:

    • Color⟋null

    Example:Setting the fill color of a path to red:

    // Create a circle shaped path at { x: 80, y: 50 }
// with a radius of 35:
var circle = new Path.Circle({
    center: [80, 50],
    radius: 35
});

// Set the fill color of the circle to RGB red:
circle.fillColor = new Color(1, 0, 0);

  • fillRule

    The fill-rule with which the shape gets filled. Please note that only modern browsers support fill-rules other than 'nonzero'.

    • Values:

    • 'nonzero', 'evenodd'

    • Default:

    • 'nonzero'

    • Type:

    • String

Shadow Style

  • shadowColor

    The shadow color.

    • Type:

    • Color⟋null

    Example:Creating a circle with a black shadow:

    var circle = new Path.Circle({
    center: [80, 50],
    radius: 35,
    fillColor: 'white',
    // Set the shadow color of the circle to RGB black:
    shadowColor: new Color(0, 0, 0),
    // Set the shadow blur radius to 12:
    shadowBlur: 12,
    // Offset the shadow by { x: 5, y: 5 }
    shadowOffset: new Point(5, 5)
});

  • shadowBlur

    The shadow’s blur radius.

    • Default:

    • 0

    • Type:

    • Number

  • shadowOffset

    The shadow’s offset.

    • Default:

    • 0

    • Type:

    • Point

Selection Style

  • selectedColor

    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.

    • Type:

    • Color⟋null

Event Handlers

  • onFrame

    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:

    • Type:

    • Function⟋null

    • Options:

    • 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

    • See also:

    • view.onFrame

    Example:Creating an animation:

    // Create a rectangle shaped path with its top left point at:
// {x: 50, y: 25} and a size of {width: 50, height: 50}
var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50));
path.fillColor = 'black';

path.onFrame = function(event) {
    // Every frame, rotate the path by 3 degrees:
    this.rotate(3);
}

  • onMouseDown

    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.

    • Type:

    • Function⟋null

    • See also:

    • view.onMouseDown

    Example:Press the mouse button down on the circle shaped path, to make it red:

    // Create a circle shaped path at the center of the view:
var path = new Path.Circle({
    center: view.center,
    radius: 25,
    fillColor: 'black'
});

// When the mouse is pressed on the item,
// set its fill color to red:
path.onMouseDown = function(event) {
    this.fillColor = 'red';
}

    Example:Press the mouse on the circle shaped paths to remove them:

    // Loop 30 times:
for (var i = 0; i < 30; i++) {
    // Create a circle shaped path at a random position
    // in the view:
    var path = new Path.Circle({
        center: Point.random() * view.size,
        radius: 25,
        fillColor: 'black',
        strokeColor: 'white'
    });

    // When the mouse is pressed on the item, remove it:
    path.onMouseDown = function(event) {
        this.remove();
    }
}

  • onMouseDrag

    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.

    • Type:

    • Function⟋null

    • See also:

    • view.onMouseDrag

    Example:Press and drag the mouse on the blue circle to move it:

    // Create a circle shaped path at the center of the view:
var path = new Path.Circle({
    center: view.center,
    radius: 50,
    fillColor: 'blue'
});

// Install a drag event handler that moves the path along.
path.onMouseDrag = function(event) {
    path.position += event.delta;
}

  • onMouseUp

    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.

    • Type:

    • Function⟋null

    • See also:

    • view.onMouseUp

    Example:Release the mouse button over the circle shaped path, to make it red:

    // Create a circle shaped path at the center of the view:
var path = new Path.Circle({
    center: view.center,
    radius: 25,
    fillColor: 'black'
});

// When the mouse is released over the item,
// set its fill color to red:
path.onMouseUp = function(event) {
    this.fillColor = 'red';
}

  • onClick

    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.

    • Type:

    • Function⟋null

    • See also:

    • view.onClick

    Example:Click on the circle shaped path, to make it red:

    // Create a circle shaped path at the center of the view:
var path = new Path.Circle({
    center: view.center,
    radius: 25,
    fillColor: 'black'
});

// When the mouse is clicked on the item,
// set its fill color to red:
path.onClick = function(event) {
    this.fillColor = 'red';
}

    Example:Click on the circle shaped paths to remove them:

    // Loop 30 times:
for (var i = 0; i < 30; i++) {
    // Create a circle shaped path at a random position
    // in the view:
    var path = new Path.Circle({
        center: Point.random() * view.size,
        radius: 25,
        fillColor: 'black',
        strokeColor: 'white'
    });

    // When the mouse clicks on the item, remove it:
    path.onClick = function(event) {
        this.remove();
    }
}

  • onDoubleClick

    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.

    • Type:

    • Function⟋null

    • See also:

    • view.onDoubleClick

    Example:Double click on the circle shaped path, to make it red:

    // Create a circle shaped path at the center of the view:
var path = new Path.Circle({
    center: view.center,
    radius: 25,
    fillColor: 'black'
});

// When the mouse is double clicked on the item,
// set its fill color to red:
path.onDoubleClick = function(event) {
    this.fillColor = 'red';
}

    Example:Double click on the circle shaped paths to remove them:

    // Loop 30 times:
for (var i = 0; i < 30; i++) {
    // Create a circle shaped path at a random position
    // in the view:
    var path = new Path.Circle({
        center: Point.random() * view.size,
        radius: 25,
        fillColor: 'black',
        strokeColor: 'white'
    });

    // When the mouse is double clicked on the item, remove it:
    path.onDoubleClick = function(event) {
        this.remove();
    }
}

  • onMouseMove

    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.

    • Type:

    • Function⟋null

    • See also:

    • view.onMouseMove

    Example:Move over the circle shaped path, to change its opacity:

    // Create a circle shaped path at the center of the view:
    var path = new Path.Circle({
    center: view.center,
    radius: 25,
    fillColor: 'black'
    });

// When the mouse moves on top of the item, set its opacity
// to a random value between 0 and 1:
path.onMouseMove = function(event) {
    this.opacity = Math.random();
}

  • onMouseEnter

    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.

    • Type:

    • Function⟋null

    • See also:

    • view.onMouseEnter

    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.

    // Create a circle shaped path at the center of the view:
var path = new Path.Circle({
    center: view.center,
    radius: 25,
    fillColor: 'black'
});

// When the mouse enters the item, set its fill color to red:
path.onMouseEnter = function(event) {
    this.fillColor = 'red';
}

// When the mouse leaves the item, set its fill color to black:
path.onMouseLeave = function(event) {
    this.fillColor = '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.

    function enter(event) {
    this.fillColor = 'red';
}

function leave(event) {
    this.fillColor = 'black';
}

// When the mouse is pressed:
function onMouseDown(event) {
    // Create a circle shaped path at the position of the mouse:
    var path = new Path.Circle(event.point, 25);
    path.fillColor = 'black';

    // When the mouse enters the item, set its fill color to red:
    path.onMouseEnter = enter;

    // When the mouse leaves the item, set its fill color to black:
    path.onMouseLeave = leave;
}

  • onMouseLeave

    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.

    • Type:

    • Function⟋null

    • See also:

    • view.onMouseLeave

    Example:Move the mouse over the circle shaped path and then move it out of it again to set its fill color to red:

    // Create a circle shaped path at the center of the view:
var path = new Path.Circle({
    center: view.center,
    radius: 25,
    fillColor: 'black'
});

// When the mouse leaves the item, set its fill color to red:
path.onMouseLeave = function(event) {
    this.fillColor = 'red';
}

Methods inherited from Item

  • set(props)

    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).

    • Parameters:

    • props: Object

    • Returns:

    • Item — the item itself

    Example:Setting properties through an object literal

    var circle = new Path.Circle({
    center: [80, 50],
    radius: 35
});

circle.set({
    strokeColor: 'red',
    strokeWidth: 10,
    fillColor: 'black',
    selected: true
});

  • clone([options])

    Clones the item within the same project and places the copy above the item.

    • Options:

    • 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

    • Parameters:

    • options: Object — optional, default: { insert: true, deep: true }

    • Returns:

    • Item — the newly cloned item

    Example:Cloning items:

    var circle = new Path.Circle({
    center: [50, 50],
    radius: 10,
    fillColor: 'red'
});

// Make 20 copies of the circle:
for (var i = 0; i < 20; i++) {
    var copy = circle.clone();

    // Distribute the copies horizontally, so we can see them:
    copy.position.x += i * copy.bounds.width;
}

  • copyContent(source)

    Copies the content of the specified item over to this item.

    • Parameters:

    • source: Item — the item to copy the content from

  • copyAttributes(source, excludeMatrix)

    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.

    • Parameters:

    • source: Item — the item to copy the attributes from

    • excludeMatrix: Boolean — whether to exclude the transformation matrix when copying all attributes

Geometric Tests

  • contains(point)

    Checks whether the item’s geometry contains the given point.

    • Parameters:

    • point: Point — the point to check for

    • Returns:

    • Boolean

    Example:Click within and outside the star below Create a star shaped path:

    var path = new Path.Star({
    center: [50, 50],
    points: 12,
    radius1: 20,
    radius2: 40,
    fillColor: 'black'
});

// Whenever the user presses the mouse:
function onMouseDown(event) {
    // If the position of the mouse is within the path,
    // set its fill color to red, otherwise set it to
    // black:
    if (path.contains(event.point)) {
        path.fillColor = 'red';
    } else {
        path.fillColor = 'black';
    }
}

  • isInside(rect)

    • Parameters:

    • rect: Rectangle — the rectangle to check against

    • Returns:

    • Boolean

  • intersects(item)

    • Parameters:

    • item: Item — the item to check against

    • Returns:

    • Boolean

Hit-testing, Fetching and Matching Items

  • hitTest(point[, options])

    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:

    • 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

    • Parameters:

    • 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 }

    • Returns:

    • HitResult — a hit result object describing what exactly was hit or null if nothing was hit

  • hitTestAll(point[, options])

    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.

    • Parameters: