Raster

Extends [Item](Item%20eab4980134ff44238bc91e6d4a28d6f9.md)

The Raster item represents an image in a Paper.js project.

Constructors

  • Raster([source[, position]])

    Creates a new raster item from the passed argument, and places it in the active layer. source can either be a DOM Image, a Canvas, or a string describing the URL to load the image from, or the ID of a DOM element to get the image from (either a DOM Image or a Canvas).

    • Parameters:

    • source: HTMLImageElementHTMLCanvasElementString — the source of the raster — optional

    • position: Point — the center position at which the raster item is placed — optional

    • Returns:

    • Raster

    Example:Creating a raster using a url

    var url = 'http://assets.paperjs.org/images/marilyn.jpg';
    var raster = new Raster(url);
    
    // If you create a Raster using a url, you can use the onLoad
    // handler to do something once it is loaded:
    raster.onLoad = function() {
        console.log('The image has loaded.');
    };

    Example:Creating a raster using the id of a DOM Image:

    // Create a raster using the id of the image:
    var raster = new Raster('art');

    Example:Creating a raster using a DOM Image:

    // Find the element using its id:
    var imageElement = document.getElementById('art');
    
    // Create the raster:
    var raster = new Raster(imageElement);
  • Raster(size[, position])

    Creates a new empty raster of the given size, and places it in the active layer.

    • Parameters:

    • size: Size — the size of the raster

    • position: Point — the center position at which the raster item is placed — optional

    • Returns:

    • Raster

    Example:Creating an empty raster and fill it with random pixels:

    var width = 100;
    var height = 100;
    
    // Create an empty raster placed at view center.
    var raster = new Raster(new Size(width, height), view.center);
    
    // For all of its pixels...
    for (var i = 0; i < width; i++) {
        for (var j = 0; j < height; j++) {
            // ...set a random color.
            raster.setPixel(i, j, Color.random());
        }
    }
  • Raster(object)

    Creates a new raster from an object description, and places it in the active layer.

    • Parameters:

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

    • Returns:

    • Raster

    Example:

    var raster = new Raster({
        source: 'http://assets.paperjs.org/images/marilyn.jpg',
        position: view.center
    });
    
    raster.scale(0.5);
    raster.rotate(10);

Properties

  • size3245`

    The size of the raster in pixels.

    • Type:

    • Size

  • width

    The width of the raster in pixels.

    • Type:

    • Number

  • height

    The height of the raster in pixels.

    • Type:

    • Number

  • loaded

    The loading state of the raster image.

    Read only.

    • Type:

    • Boolean

  • resolution

    The resolution of the raster at its current size, in PPI (pixels per inch).

    Read only.

    • Type:

    • Size

  • image

    The HTMLImageElement or Canvas element of the raster, if one is associated. Note that for consistency, a onLoad event will be triggered on the raster even if the image has already finished loading before, or if we are setting the raster to a canvas.

    • Type:

    • HTMLImageElementHTMLCanvasElement

  • canvas

    The Canvas object of the raster. If the raster was created from an image, accessing its canvas causes the raster to try and create one and draw the image into it. Depending on security policies, this might fail, in which case null is returned instead.

    • Type:

    • HTMLCanvasElement

  • context

    The Canvas 2D drawing context of the raster.

    • Type:

    • CanvasRenderingContext2D

  • source

    The source of the raster, which can be set using a DOM Image, a Canvas, a data url, a string describing the URL to load the image from, or the ID of a DOM element to get the image from (either a DOM Image or a Canvas). Reading this property will return the url of the source image or a data-url. Note that for consistency, a onLoad event will be triggered on the raster even if the image has already finished loading before.

    • Type:

    • HTMLImageElementHTMLCanvasElementString

    Example:

    var raster = new Raster();
    raster.source = 'http://paperjs.org/about/paper-js.gif';
    raster.position = view.center;

    Example:

    var raster = new Raster({
        source: 'http://paperjs.org/about/paper-js.gif',
        position: view.center
    });
  • crossOrigin

    The crossOrigin value to be used when loading the image resource, in order to support CORS. Note that this needs to be set before setting the source property in order to always work (e.g. when the image is cached in the browser).

    • Type:

    • String

    Example:

    var raster = new Raster({
        crossOrigin: 'anonymous',
        source: 'http://assets.paperjs.org/images/marilyn.jpg',
        position: view.center
    });
    
    console.log(view.element.toDataURL('image/png').substring(0, 32));
  • smoothing

    Specifies if the raster should be smoothed when scaled up or if the pixels should be scaled up by repeating the nearest neighboring pixels.

    • Default:

    • true

    • Type:

    • Boolean

    Example:

    var raster = new Raster({
        source: 'http://assets.paperjs.org/images/marilyn.jpg',
        smoothing: false
    });
    raster.scale(5);

Event Handlers

  • onLoad

    The event handler function to be called when the underlying image has finished loading and is ready to be used. This is also triggered when the image is already loaded, or when a canvas is used instead of an image.

    • Type:

    • Functionnull

    Example:

    var url = 'http://assets.paperjs.org/images/marilyn.jpg';
    var raster = new Raster(url);
    
    // If you create a Raster using a url, you can use the onLoad
    // handler to do something once it is loaded:
    raster.onLoad = function() {
        console.log('The image has finished loading.');
    };
    
    // As with all events in paper.js, you can also use this notation instead
    // to install multiple handlers:
    raster.on('load', function() {
        console.log('Now the image is definitely ready.');
    });
  • onError

    The event handler function to be called when there is an error loading the underlying image.

    • Type:

    • Functionnull

Methods

  • getSubCanvas(rect)

    Extracts a part of the Raster’s content as a sub image, and returns it as a Canvas object.

    • Parameters:

    • rect: Rectangle — the boundaries of the sub image in pixel coordinates

    • Returns:

    • HTMLCanvasElement — the sub image as a Canvas object

  • getSubRaster(rect)

    Extracts a part of the raster item’s content as a new raster item, placed in exactly the same place as the original content.

    • Parameters:

    • rect: Rectangle — the boundaries of the sub raster in pixel coordinates

    • Returns:

    • Raster — the sub raster as a newly created raster item

  • toDataURL()

    Returns a Base 64 encoded data: URL representation of the raster.

    • Returns:

    • String

  • drawImage(image, point)

    Draws an image on the raster.

    • Parameters:

    • image: CanvasImageSource

    • point: Point — the offset of the image as a point in pixel coordinates

  • getAverageColor(object)

    Calculates the average color of the image within the given path, rectangle or point. This can be used for creating raster image effects.

    • Parameters:

    • object: PathRectanglePoint

    • Returns:

    • Color — the average color contained in the area covered by the specified path, rectangle or point

Pixels

  • getPixel(x, y)

    Gets the color of a pixel in the raster.

    • Parameters:

    • x: Number — the x offset of the pixel in pixel coordinates

    • y: Number — the y offset of the pixel in pixel coordinates

    • Returns:

    • Color — the color of the pixel

  • getPixel(point)

    Gets the color of a pixel in the raster.

    • Parameters:

    • point: Point — the offset of the pixel as a point in pixel coordinates

    • Returns:

    • Color — the color of the pixel

  • setPixel(x, y, color)

    Sets the color of the specified pixel to the specified color.

    • Parameters:

    • x: Number — the x offset of the pixel in pixel coordinates

    • y: Number — the y offset of the pixel in pixel coordinates

    • color: Color — the color that the pixel will be set to

  • setPixel(point, color)

    Sets the color of the specified pixel to the specified color.

    • Parameters:

    • point: Point — the offset of the pixel as a point in pixel coordinates

    • color: Color — the color that the pixel will be set to

  • clear()

    Clears the image, if it is backed by a canvas.

Image Data

  • createImageData(size)

    • Parameters:

    • size: Size

    • Returns:

    • ImageData

  • getImageData(rect)

    • Parameters:

    • rect: Rectangle

    • Returns:

    • ImageData

  • setImageData(data, point)

    • Parameters:

    • data: ImageData

    • point: Point

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:

    • Colornull

    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:

    • Colornull

    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:

    • Colornull

    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:

    • Colornull

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:

    • Functionnull

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

    • Functionnull

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

    • Functionnull

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

    • Functionnull

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

    • Functionnull

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

    • Functionnull

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

    • Functionnull

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

    • Functionnull

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

    • Functionnull

    • 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

  • rasterize([resolution[, insert]])

    Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization.

    • Parameters:

    • resolution: Number — the resolution of the raster in pixels per inch (DPI). If not specified, the value of view.resolution is used. — optional, default: view.resolution

    • insert: Boolean — specifies whether the raster should be inserted into the scene graph. When set to true, it is inserted above the original — optional, default: true

    • Returns:

    • Raster — the newly created raster item

    Example:Rasterizing an item:

    var circle = new Path.Circle({
        center: [50, 50],
        radius: 5,
        fillColor: 'red'
    });
    
    // Create a rasterized version of the path:
    var raster = circle.rasterize();
    
    // Move it 100pt to the right:
    raster.position.x += 100;
    
    // Scale the path and the raster by 300%, so we can compare them:
    circle.scale(5);
    raster.scale(5);

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