Savage

API Reference

Element.after(el)⚓➭

Inserts given element after the current one.

Parameters

  1. el Element element to insert

Returns: Element parent

Element.animate(attrs, ms, [easing], [callback])⚓➭

Animate given attributes of the element.

Parameters

  1. attrs object key-value pairs of destination attributes
  2. ms number duration
  3. easing optional function easing function from mina or custom
  4. callback optional function  

Returns: Element the element

Element.append(el)⚓➭

Appends given element to current one.

Parameters

  1. el Element Set element to append

Returns: Element parent

Element.asPX(attr, [value])⚓➭

Return given attribute of the element as a px value. (Not %, em, etc)

Parameters

  1. attr string attribute name
  2. value optional string attribute value

Returns: Element result of query selection

Element.attr(…)⚓➭

Gets or sets given attributes of the element

Parameters

  1. params object key-value pairs of attributes you want to set

or

Parameters

  1. param string name of the attribute

Returns: Element

or

Returns: string value of attribute

Usage

el.attr({
    fill: "#fc0",
    stroke: "#000",
    strokeWidth: 2, // CamelCase...
    "fill-opacity": 0.5 // or dash-separated names
});
console.log(el.attr("fill")); // “#fc0”

Element.before(el)⚓➭

Inserts given element before the current one.

Parameters

  1. el Element element to insert

Returns: Element parent

Element.click(handler)⚓➭

Adds event handler for click for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.clone()⚓➭

Creates clone of the element and inserts it after the element.

Returns: Element the clone

Element.data(key, [value])⚓➭

Adds or retrieves given value asociated with given key. See also Element.removeData

Parameters

  1. key string key to store data
  2. value optional any value to store

Returns: object Element

or, if value is not specified:

Returns: any value

Usage

for (var i = 0, i < 5, i++) {
    paper.circle(10 + 15 * i, 10, 10)
         .attr({fill: "#000"})
         .data("i", i)
         .click(function () {
            alert(this.data("i"));
         });
}

Element.dblclick(handler)⚓➭

Adds event handler for double click for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.drag(onmove, onstart, onend, [mcontext], [scontext], [econtext])⚓➭

Adds event handlers for drag of the element.

Parameters

  1. onmove function handler for moving
  2. onstart function handler for drag start
  3. onend function handler for drag end
  4. mcontext optional object context for moving handler
  5. scontext optional object context for drag start handler
  6. econtext optional object context for drag end handler

Additionaly following drag events will be triggered: drag.start.<id> on start, drag.end.<id> on end and drag.move.<id> on every move. When element will be dragged over another element drag.over.<id> will be fired as well.

Start event and start handler will be called in specified context or in context of the element with following parameters:

  1. xnumberx position of the mouse
  2. ynumbery position of the mouse
  3. eventobjectDOM event object

Move event and move handler will be called in specified context or in context of the element with following parameters:

  1. dxnumbershift by x from the start point
  2. dynumbershift by y from the start point
  3. xnumberx position of the mouse
  4. ynumbery position of the mouse
  5. eventobjectDOM event object

End event and end handler will be called in specified context or in context of the element with following parameters:

  1. eventobjectDOM event object

Returns: object Element

Adds event handlers for drag of the element.

Parameters

  1. onmove function handler for moving
  2. onstart function handler for drag start
  3. onend function handler for drag end
  4. mcontext optional object context for moving handler
  5. scontext optional object context for drag start handler
  6. econtext optional object context for drag end handler

Additionaly following drag events will be triggered: drag.start.<id> on start, drag.end.<id> on end and drag.move.<id> on every move. When element will be dragged over another element drag.over.<id> will be fired as well.

Start event and start handler will be called in specified context or in context of the element with following parameters:

  1. xnumberx position of the mouse
  2. ynumbery position of the mouse
  3. eventobjectDOM event object

Move event and move handler will be called in specified context or in context of the element with following parameters:

  1. dxnumbershift by x from the start point
  2. dynumbershift by y from the start point
  3. xnumberx position of the mouse
  4. ynumbery position of the mouse
  5. eventobjectDOM event object

End event and end handler will be called in specified context or in context of the element with following parameters:

  1. eventobjectDOM event object

Returns: object Element

Element.getBBox()⚓➭

Returns bounding box descriptor for the given element.

Returns: object bounding box descriptor:

  1. {
    1. cx:numberx of the center,
    2. cy:numberx of the center,
    3. h:numberheight,
    4. height:numberheight,
    5. path:stringpath command for the box,
    6. r0:numberradius of the circle that will enclose the box,
    7. r1:numberradius of the smallest circle that can be enclosed,
    8. r2:numberradius of the biggest circle that can be enclosed,
    9. vb:stringbox as a viewbox command,
    10. w:numberwidth,
    11. width:numberwidth,
    12. x2:numberx of the right side,
    13. x:numberx of the left side,
    14. y2:numbery of the right side,
    15. y:numbery of the left side
  2. }

Element.getPointAtLength(length)⚓➭

Return coordinates of the point located at the given length on the given path. Only works for element of “path” type.

Parameters

  1. length number  

Returns: object representation of the point:

  1. {
    1. x:numberx coordinate
    2. y:numbery coordinate
    3. alpha:numberangle of derivative
  2. }

Element.getSubpath(from, to)⚓➭

Return subpath of a given element from given length to given length. Only works for element of “path” type.

Parameters

  1. from number position of the start of the segment
  2. to number position of the end of the segment

Returns: string pathstring for the segment

Element.getTotalLength()⚓➭

Returns length of the path in pixels. Only works for element of “path” type.

Returns: number length.

Element.hover(f_in, f_out, [icontext], [ocontext])⚓➭

Adds event handlers for hover for the element.

Parameters

  1. f_in function handler for hover in
  2. f_out function handler for hover out
  3. icontext optional object context for hover in handler
  4. ocontext optional object context for hover out handler

Returns: object Element

Element.inAnim()⚓➭

Returns an array of animations element currently in

Returns: object in format

  1. {
    1. animobjectanimation object,
    2. curStatusnumber0..1 — status of the animation: 0 — just started, 1 — just finished,
    3. statusfunctiongets or sets the status of the animation,
    4. stopfunctionstops the animation
  2. }

Element.innerSVG()⚓➭

Returns SVG code of the element. Equivalent to innerHTML in HTML context.

Returns: string SVG code of the element.

Element.insertAfter(el)⚓➭

Inserts the element after the given one.

Parameters

  1. el Element element next to whom insert to

Returns: Element parent

Element.insertBefore(el)⚓➭

Inserts the element after the given one.

Parameters

  1. el Element element next to whom insert to

Returns: Element parent

Element.marker(x, y, width, height, refX, refY)⚓➭

Creates <marker> element from the current element. To create a marker you have to specify the bounding rect and reference point:

Parameters

  1. x number  
  2. y number  
  3. width number  
  4. height number  
  5. refX number  
  6. refY number  

Returns: Element <marker> element

You can use pattern later on as an argument for marker-start or marker-end attributes.

Element.mousedown(handler)⚓➭

Adds event handler for mousedown for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.mousemove(handler)⚓➭

Adds event handler for mousemove for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.mouseout(handler)⚓➭

Adds event handler for mouseout for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.mouseover(handler)⚓➭

Adds event handler for mouseover for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.mouseup(handler)⚓➭

Adds event handler for mouseup for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.parent()⚓➭

Returns parent of the element

Returns: Element parent

Element.pattern(x, y, width, height)⚓➭

Creates <pattern> element from the current element. To create a pattern you have to specify the pattern rect:

Parameters

  1. x string number  
  2. y string number  
  3. width string number  
  4. height string number  

Returns: Element <pattern> element

You can use pattern later on as an argument for fill attribute: 

var p = paper.path("M10-5-10,15M15,0,0,15M0-5-20,15").attr({
        fill: "none",
        stroke: "#bada55",
        strokeWidth: 5
    }).pattern(0, 0, 10, 10),
    c = paper.circle(200, 200, 100);
c.attr({
    fill: p
});

Element.prepend(el)⚓➭

Prepends given element to current one.

Parameters

  1. el Element element to prepend

Returns: Element parent

Element.remove()⚓➭

Removes element from the DOM

Returns: Element removed element

Element.removeData([key])⚓➭

Removes value associated with an element by given key. If key is not provided, removes all the data of the element.

Parameters

  1. key optional string key

Returns: object Element

Element.select(query)⚓➭

Applies CSS selector with the element as a parent and returns the result as an Element.

Parameters

  1. query string CSS selector

Returns: Element result of query selection

Element.selectAll(query)⚓➭

Applies CSS selector with the element as a parent and returns the result as a set or array of elements.

Parameters

  1. query string CSS selector

Returns: Set array result of query selection

Element.stop()⚓➭

Stops all the animations of the current element.

Returns: Element the element

Element.toString()⚓➭

Returns SVG code of the element. Equivalent to outerHTML in HTML context.

Returns: string SVG code of the element.

Returns SVG code of the Paper.

Returns: string SVG code of the Paper.

Element.touchcancel(handler)⚓➭

Adds event handler for touchcancel for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.touchend(handler)⚓➭

Adds event handler for touchend for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.touchmove(handler)⚓➭

Adds event handler for touchmove for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.touchstart(handler)⚓➭

Adds event handler for touchstart for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.transform(tstr)⚓➭

Gets or sets transformation of the element

Parameters

  1. tstr string transform string in Savage or SVG format

Returns: Element

or

Returns: object transformation descriptor:

  1. {
    1. stringstringtransform string,
    2. globalMatrixMatrixmatrix of all transformations applied to element or its parents,
    3. localMatrixMatrixmatrix of transformations applied only to the element,
    4. diffMatrixMatrixmatrix of difference between global and local transformations,
    5. globalstringglobal transformation as string,
    6. localstringlocal transformation as string,
    7. toStringfunctionreturns string property
  2. }

Element.unclick(handler)⚓➭

Removes event handler for click for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.undblclick(handler)⚓➭

Removes event handler for double click for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.undrag()⚓➭

Removes all drag event handlers from given element.

Element.unhover(f_in, f_out)⚓➭

Removes event handlers for hover for the element.

Parameters

  1. f_in function handler for hover in
  2. f_out function handler for hover out

Returns: object Element

Element.unmousedown(handler)⚓➭

Removes event handler for mousedown for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.unmousemove(handler)⚓➭

Removes event handler for mousemove for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.unmouseout(handler)⚓➭

Removes event handler for mouseout for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.unmouseover(handler)⚓➭

Removes event handler for mouseover for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.unmouseup(handler)⚓➭

Removes event handler for mouseup for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.untouchcancel(handler)⚓➭

Removes event handler for touchcancel for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.untouchend(handler)⚓➭

Removes event handler for touchend for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.untouchmove(handler)⚓➭

Removes event handler for touchmove for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.untouchstart(handler)⚓➭

Removes event handler for touchstart for the element.

Parameters

  1. handler function handler for the event

Returns: object Element

Element.use()⚓➭

Creates <use> element linked to the current element.

Returns: Element <use> element

Matrix.add(a, b, c, d, e, f, matrix)⚓➭

Adds given matrix to existing one.

Parameters

  1. a number  
  2. b number  
  3. c number  
  4. d number  
  5. e number  
  6. f number  
  7. matrix object Matrix

Matrix.clone()⚓➭

Returns copy of the matrix

Returns: object Matrix

Matrix.invert()⚓➭

Returns inverted version of the matrix

Returns: object Matrix

Matrix.rotate(a, x, y)⚓➭

Rotates the matrix

Parameters

  1. a number  
  2. x number  
  3. y number  

Matrix.scale(x, [y], [cx], [cy])⚓➭

Scales the matrix

Parameters

  1. x number  
  2. y optional number  
  3. cx optional number  
  4. cy optional number  

Matrix.split()⚓➭

Splits matrix into primitive transformations

Returns: object in format:

  1. dxnumbertranslation by x
  2. dynumbertranslation by y
  3. scalexnumberscale by x
  4. scaleynumberscale by y
  5. shearnumbershear
  6. rotatenumberrotation in deg
  7. isSimplebooleancould it be represented via simple transformations

Matrix.toTransformString()⚓➭

Return transform string that represents given matrix

Returns: string transform string

Matrix.translate(x, y)⚓➭

Translate the matrix

Parameters

  1. x number  
  2. y number  

Matrix.x(x, y)⚓➭

Return x coordinate for given point after transformation described by the matrix. See also Matrix.y

Parameters

  1. x number  
  2. y number  

Returns: number x

Matrix.y(x, y)⚓➭

Return y coordinate for given point after transformation described by the matrix. See also Matrix.x

Parameters

  1. x number  
  2. y number  

Returns: number y

Paper.circle(x, y, r)⚓➭

Draws a circle.

Parameters

  1. x number x coordinate of the centre
  2. y number y coordinate of the centre
  3. r number radius

Returns: object Element object with type “circle”

Usage

var c = paper.circle(50, 50, 40);

Paper.el(name, attr)⚓➭

Creates element on paper with a given name and no attributes.

Parameters

  1. name string tag name
  2. attr object attributes

Returns: Element the element

Usage

var c = paper.circle(10, 10, 10); // is the same as...
var c = paper.el("circle").attr({
    cx: 10,
    cy: 10,
    r: 10
});

Paper.ellipse(x, y, rx, ry)⚓➭

Draws an ellipse.

Parameters

  1. x number x coordinate of the centre
  2. y number y coordinate of the centre
  3. rx number horizontal radius
  4. ry number vertical radius

Returns: object Element object with type “ellipse”

Usage

var c = paper.ellipse(50, 50, 40, 20);

Paper.filter(filstr)⚓➭

Creates filter element

Parameters

  1. filstr string SVG fragment of filter provided as a string.

Returns: object Element

Note: It is recommended to use filters embedded into page inside empty SVG element.

Usage

var f = paper.filter('<feGaussianBlur stdDeviation="2"/>'),
    c = paper.circle(10, 10, 10).attr({
        filter: f
    });

Paper.g([varargs])⚓➭

Makes a group element.

Parameters

  1. varargs optional … elements

Returns: object Element object with type “g”

Usage

var c1 = paper.circle(),
    c2 = paper.rect(),
    g = paper.g(c2, c1); // note that the order of elements will be different

or 

var c1 = paper.circle(),
    c2 = paper.rect(),
    g = paper.g();
g.add(c2, c1);

Paper.gradient(gradient)⚓➭

Creates a gradient element.

Parameters

  1. gradient string gradient descriptor

Gradient Descriptor

Gradient descriptor consists of <type>(<coords>)<colors>. Type could be linear or radial, which presented as letter “L” or “R”. Any type could be absolute or relative, absolute gradient take it coords relative to the SVG surface, while relative takes them relative to the bounding box of the element it applied to. For absolute coordinates you specify type as an upper case letter (“L” or “R”). For relative use low case letter (“l” or “r”). Coordinates specify vector of gradient for linear as x1, y1, x2, y2. For radial as cx, cy, r and optional fx, fy. Colors are list of dash separated colors. Optionally color could have offset after colon.

Example

var g = paper.gradient("l(0, 0, 1, 1)#000-#f00-#fff");

Linear gradient, relative from top-left corner to bottom-right corner, from black through red to white. 

var g = paper.gradient("L(0, 0, 100, 100)#000-#f00:25%-#fff");

Linear gradient, absolute from (0, 0) to (100, 100), from black through red at 25% to white. 

var g = paper.gradient("r(0.5, 0.5, 0.5)#000-#fff");

Radial gradient, relative from the center of the element with radius 0.5 of the width, from black to white. 

paper.circle(50, 50, 40).attr({
    fill: g
});

Returns: object Element object with type “gradient”

Paper.image(src, x, y, width, height)⚓➭

Embeds an image into the surface.

Parameters

  1. src string URI of the source image
  2. x number x coordinate position
  3. y number y coordinate position
  4. width number width of the image
  5. height number height of the image

Returns: object Raphaël element object with type “image”

Usage

var c = paper.image("apple.png", 10, 10, 80, 80);

Embeds an image into the surface.

Parameters

  1. src string URI of the source image
  2. x number x coordinate position
  3. y number y coordinate position
  4. width number width of the image
  5. height number height of the image

Returns: object Element object with type “image”

Usage

var c = paper.image("apple.png", 10, 10, 80, 80);

Paper.line(x1, y1, x2, y2)⚓➭

Draws a line.

Parameters

  1. x1 number x coordinate position of the start
  2. y1 number y coordinate position of the start
  3. x2 number x coordinate position of the end
  4. y2 number y coordinate position of the end

Returns: object Element object with type “line”

Usage

var t1 = paper.line(50, 50, 100, 100);

Paper.path([pathString])⚓➭

Creates a path element by given path data string.

Parameters

  1. pathString optional string path string in SVG format.

Path string consists of one-letter commands, followed by comma seprarated arguments in numercal form. Example: 

"M10,20L30,40"

Here we can see two commands: “M”, with arguments (10, 20) and “L” with arguments (30, 40). Upper case letter mean command is absolute, lower case—relative.

Here is short list of commands available, for more details see SVG path string format or article about path strings at MDN.

CommandNameParameters
Mmoveto(x y)+
Zclosepath(none)
Llineto(x y)+
Hhorizontal linetox+
Vvertical linetoy+
Ccurveto(x1 y1 x2 y2 x y)+
Ssmooth curveto(x2 y2 x y)+
Qquadratic Bézier curveto(x1 y1 x y)+
Tsmooth quadratic Bézier curveto(x y)+
Aelliptical arc(rx ry x-axis-rotation large-arc-flag sweep-flag x y)+
RCatmull-Rom curveto*x1 y1 (x y)+

  • “Catmull-Rom curveto” is a not standard SVG command and added to make life easier.
    • Note: there is a special case when path consist of just three commands: “M10,10R…z”. In this case path will smoothly connects to its beginning.

    Usage

    var c = paper.path("M10 10L90 90");
// draw a diagonal line:
// move to 10,10, line to 90,90

    Paper.polyline(…)⚓➭

    Draws a polyline.

    Parameters

    1. points array array of points

    or

    Parameters

    1. varargs … points

    Returns: object Element object with type “text”

    Usage

    var p1 = paper.polyline([10, 10, 100, 100]);
var p2 = paper.polyline(10, 10, 100, 100);

    Paper.rect(x, y, width, height, [rx], [ry])⚓➭

    Draws a rectangle.

    Parameters

    1. x number x coordinate of the top left corner
    2. y number y coordinate of the top left corner
    3. width number width
    4. height number height
    5. rx optional number horisontal radius for rounded corners, default is 0
    6. ry optional number vertical radius for rounded corners, default is rx or 0

    Returns: object Element object with type “rect”

    Usage

    // regular rectangle
var c = paper.rect(10, 10, 50, 50);
// rectangle with rounded corners
var c = paper.rect(40, 40, 50, 50, 10);

    Paper.text(x, y, text)⚓➭

    Draws a text string.

    Parameters

    1. x number x coordinate position
    2. y number y coordinate position
    3. text string array The text string to draw or array of <tspan>s

    Returns: object Element object with type “text”

    Usage

    var t1 = paper.text(50, 50, "Savage");
var t2 = paper.text(50, 50, ["S","a","v","a","g","e"]);

    Paper.toString()⚓➭

    Returns SVG code of the element. Equivalent to outerHTML in HTML context.

    Returns: string SVG code of the element.

    Returns SVG code of the Paper.

    Returns: string SVG code of the Paper.

    Savage.Matrix(…)⚓➭

    Utility method Returns matrix based on given parameters.

    Parameters

    1. a number  
    2. b number  
    3. c number  
    4. d number  
    5. e number  
    6. f number  

    or

    Parameters

    1. svgMatrix SVGMatrix  

    Returns: object Matrix

    Savage.ajax(…)⚓➭

    Simple implementation of Ajax.

    Parameters

    1. url string URL
    2. postData object string data for post request
    3. callback function callback
    4. scope optional object scope of callback

    or

    Parameters

    1. url string URL
    2. callback function callback
    3. scope optional object scope of callback

    Returns: XMLHttpRequest XMLHttpRequest (just in case)

    Savage.animate(from, to, setter, ms, [easing], [callback])⚓➭

    Runs generic animation of one number into another with a caring function.

    Parameters

    1. from number array number or array of numbers
    2. to number array number or array of numbers
    3. setter function caring function that will take one number argument
    4. ms number duration
    5. easing optional function easing function from mina or custom
    6. callback optional function  

    Returns: object animation object in mina format

    1. {
      1. idstringanimation id, consider it read-only,
      2. durationfunctiongets or sets the duration of the animation,
      3. easingfunctioneasing,
      4. speedfunctiongets or sets the speed of the animation,
      5. statusfunctiongets or sets the status of the animation,
      6. stopfunctionstops the animation
    2. }

    Savage.animation(attr, ms, [easing], [callback])⚓➭

    Creates animation object.

    Parameters

    1. attr object attributes of final destination
    2. ms number animation duration
    3. easing optional function one of easing functions of mina or custom one
    4. callback optional function callback

    Returns: object animation object

    Savage.color(clr)⚓➭

    Parses the color string and returns object with all values for the given color.

    Parameters

    1. clr string color string in one of the supported formats (see Savage.getRGB)

    Returns: object Combined RGB & HSB object in format:

    1. {
      1. rnumberred,
      2. gnumbergreen,
      3. bnumberblue,
      4. hexstringcolor in HTML/CSS format: #••••••,
      5. errorbooleantrue if string cant be parsed,
      6. hnumberhue,
      7. snumbersaturation,
      8. vnumbervalue (brightness),
      9. lnumberlightness
    2. }

    Savage.deg(deg)⚓➭

    Transform angle to degrees

    Parameters

    1. deg number angle in radians

    Returns: number angle in degrees.

    Savage.filter⚓

    Savage.filter.blur(x, [y])⚓➭

    Returns string of the blur filter.

    Parameters

    1. x number amount of horisontal blur in px.
    2. y optional number amount of vertical blur in px.

    Returns: string filter representation

    Usage

    var f = paper.filter(Savage.filter.blur(5, 10)),
    c = paper.circle(10, 10, 10).attr({
        filter: f
    });

    Savage.filter.brightness(amount)⚓➭

    Returns string of the brightness filter.

    Parameters

    1. amount number amount of filter (0..1).

    Returns: string filter representation

    Savage.filter.contrast(amount)⚓➭

    Returns string of the contrast filter.

    Parameters

    1. amount number amount of filter (0..1).

    Returns: string filter representation

    Savage.filter.grayscale(amount)⚓➭

    Returns string of the grayscale filter.

    Parameters

    1. amount number amount of filter (0..1).

    Returns: string filter representation

    Savage.filter.hueRotate(angle)⚓➭

    Returns string of the hue-rotate filter.

    Parameters

    1. angle number angle of rotation.

    Returns: string filter representation

    Savage.filter.invert(amount)⚓➭

    Returns string of the invert filter.

    Parameters

    1. amount number amount of filter (0..1).

    Returns: string filter representation

    Savage.filter.saturate(amount)⚓➭

    Returns string of the saturate filter.

    Parameters

    1. amount number amount of filter (0..1).

    Returns: string filter representation

    Savage.filter.sepia(amount)⚓➭

    Returns string of the sepia filter.

    Parameters

    1. amount number amount of filter (0..1).

    Returns: string filter representation

    Savage.filter.shadow(dx, dy, [blur], [color])⚓➭

    Returns string of the shadow filter.

    Parameters

    1. dx number horisontal shift of the shadow in px.
    2. dy number vertical shift of the shadow in px.
    3. blur optional number amount of blur.
    4. color optional string color of the shadow.

    Returns: string filter representation

    Usage

    var f = paper.filter(Savage.filter.shadow(0, 2, 3)),
    c = paper.circle(10, 10, 10).attr({
        filter: f
    });

    Savage.format(token, json)⚓➭

    Replaces construction of type “{<name>}” to the corresponding argument.

    Parameters

    1. token string string to format
    2. json object object which properties will be used as a replacement

    Returns: string formated string

    Usage

    // this will draw a rectangular shape equivalent to "M10,20h40v50h-40z"
paper.path(Savage.format("M{x},{y}h{dim.width}v{dim.height}h{dim['negative width']}z", {
    x: 10,
    y: 20,
    dim: {
        width: 40,
        height: 50,
        "negative width": -40
    }
}));

    Savage.fragment(varargs)⚓➭

    Creates DOM fragment from given list of elements or strings

    Parameters

    1. varargs … SVG string

    Returns: Fragment the Fragment

    Savage.getRGB(colour)⚓➭

    Parses colour string as RGB object

    Parameters

    1. colour string colour string in one of formats:
    • Colour name (“red”, “green”, “cornflowerblue”, etc)
    • #••• — shortened HTML colour: (“#000”, “#fc0”, etc)
    • #•••••• — full length HTML colour: (“#000000”, “#bd2300”)
    • rgb(•••, •••, •••) — red, green and blue channels values: (“rgb(200, 100, 0)”)
    • rgb(•••%, •••%, •••%) — same as above, but in %: (“rgb(100%, 175%, 0%)”)
    • hsb(•••, •••, •••) — hue, saturation and brightness values: (“hsb(0.5, 0.25, 1)”)
    • hsb(•••%, •••%, •••%) — same as above, but in %
    • hsl(•••, •••, •••) — same as hsb
    • hsl(•••%, •••%, •••%) — same as hsb

    Returns: object RGB object in format:

    1. {
      1. rnumberred,
      2. gnumbergreen,
      3. bnumberblue
      4. hexstringcolor in HTML/CSS format: #••••••,
      5. errorbooleantrue if string cant be parsed
    2. }

    Savage.hsb(h, s, b)⚓➭

    Converts HSB values to hex representation of the colour.

    Parameters

    1. h number hue
    2. s number saturation
    3. b number value or brightness

    Returns: string hex representation of the colour.

    Savage.hsb2rgb(h, s, v)⚓➭

    Converts HSB values to RGB object.

    Parameters

    1. h number hue
    2. s number saturation
    3. v number value or brightness

    Returns: object RGB object in format:

    1. {
      1. rnumberred,
      2. gnumbergreen,
      3. bnumberblue,
      4. hexstringcolor in HTML/CSS format: #••••••
    2. }

    Savage.hsl(h, s, l)⚓➭

    Converts HSL values to hex representation of the colour.

    Parameters

    1. h number hue
    2. s number saturation
    3. l number luminosity

    Returns: string hex representation of the colour.

    Savage.hsl2rgb(h, s, l)⚓➭

    Converts HSL values to RGB object.

    Parameters

    1. h number hue
    2. s number saturation
    3. l number luminosity

    Returns: object RGB object in format:

    1. {
      1. rnumberred,
      2. gnumbergreen,
      3. bnumberblue,
      4. hexstringcolor in HTML/CSS format: #••••••
    2. }

    Savage.is(o, type)⚓➭

    Handfull replacement for typeof operator.

    Parameters

    1. o … any object or primitive
    2. type string name of the type, i.e. “string”, “function”, “number”, etc.

    Returns: boolean is given value is of given type

    Savage.load(url, callback, [scope])⚓➭

    Loads external SVG file as a Fragment. For more advanced AJAX see Savage.ajax.

    Parameters

    1. url string URL
    2. callback function callback
    3. scope optional object scope of callback

    Savage.parse(svg)⚓➭

    Parses SVG fragment and converts it into Fragment.

    Parameters

    1. svg string SVG string

    Returns: Fragment the fragment

    Savage.parsePathString(pathString)⚓➭

    Utility method Parses given path string into an array of arrays of path segments.

    Parameters

    1. pathString string array path string or array of segments (in the last case it will be returned straight away)

    Returns: array array of segments.

    Savage.parseTransformString(TString)⚓➭

    Utility method Parses given path string into an array of transformations.

    Parameters

    1. TString string array transform string or array of transformations (in the last case it will be returned straight away)

    Returns: array array of transformations.

    Savage.path⚓

    Savage.path.bezierBBox(…)⚓➭

    Utility method Return bounding box of a given cubic bezier curve

    Parameters

    1. p1x number x of the first point of the curve
    2. p1y number y of the first point of the curve
    3. c1x number x of the first anchor of the curve
    4. c1y number y of the first anchor of the curve
    5. c2x number x of the second anchor of the curve
    6. c2y number y of the second anchor of the curve
    7. p2x number x of the second point of the curve
    8. p2y number y of the second point of the curve

    or

    Parameters

    1. bez array array of six points for bezier curve

    Returns: object point information in format:

    1. {
      1. min: {
        1. x:numberx coordinate of the left point
        2. y:numbery coordinate of the top point
      2. }
      3. max: {
        1. x:numberx coordinate of the right point
        2. y:numbery coordinate of the bottom point
      4. }
    2. }

    Savage.path.findDotsAtSegment(p1x, p1y, c1x, c1y, c2x, c2y, p2x, p2y, t)⚓➭

    Utility method Find dot coordinates on the given cubic bezier curve at the given t.

    Parameters

    1. p1x number x of the first point of the curve
    2. p1y number y of the first point of the curve
    3. c1x number x of the first anchor of the curve
    4. c1y number y of the first anchor of the curve
    5. c2x number x of the second anchor of the curve
    6. c2y number y of the second anchor of the curve
    7. p2x number x of the second point of the curve
    8. p2y number y of the second point of the curve
    9. t number position on the curve (0..1)

    Returns: object point information in format:

    1. {
      1. x:numberx coordinate of the point
      2. y:numbery coordinate of the point
      3. m: {
        1. x:numberx coordinate of the left anchor
        2. y:numbery coordinate of the left anchor
      4. }
      5. n: {
        1. x:numberx coordinate of the right anchor
        2. y:numbery coordinate of the right anchor
      6. }
      7. start: {
        1. x:numberx coordinate of the start of the curve
        2. y:numbery coordinate of the start of the curve
      8. }
      9. end: {
        1. x:numberx coordinate of the end of the curve
        2. y:numbery coordinate of the end of the curve
      10. }
      11. alpha:numberangle of the curve derivative at the point
    2. }

    Savage.path.getBBox(path)⚓➭

    Utility method Return bounding box of a given path

    Parameters

    1. path string path string

    Returns: object bounding box

    1. {
      1. x:numberx coordinate of the left top point of the box
      2. y:numbery coordinate of the left top point of the box
      3. x2:numberx coordinate of the right bottom point of the box
      4. y2:numbery coordinate of the right bottom point of the box
      5. width:numberwidth of the box
      6. height:numberheight of the box
    2. }

    Savage.path.getPointAtLength(path, length)⚓➭

    Return coordinates of the point located at the given length on the given path.

    Parameters

    1. path string SVG path string
    2. length number  

    Returns: object representation of the point:

    1. {
      1. x:numberx coordinate
      2. y:numbery coordinate
      3. alpha:numberangle of derivative
    2. }

    Savage.path.getSubpath(path, from, to)⚓➭

    Return subpath of a given path from given length to given length.

    Parameters

    1. path string SVG path string
    2. from number position of the start of the segment
    3. to number position of the end of the segment

    Returns: string pathstring for the segment

    Savage.path.getTotalLength(path)⚓➭

    Returns length of the given path in pixels.

    Parameters

    1. path string SVG path string.

    Returns: number length.

    Savage.path.intersection(path1, path2)⚓➭

    Utility method Finds intersections of two paths

    Parameters

    1. path1 string path string
    2. path2 string path string

    Returns: array dots of intersection

    1. [
    2. {
      1. x:numberx coordinate of the point
      2. y:numbery coordinate of the point
      3. t1:numbert value for segment of path1
      4. t2:numbert value for segment of path2
      5. segment1:numberorder number for segment of path1
      6. segment2:numberorder number for segment of path2
      7. bez1:arrayeight coordinates representing beziér curve for the segment of path1
      8. bez2:arrayeight coordinates representing beziér curve for the segment of path2
    3. }
    4. ]

    Savage.path.isBBoxIntersect(bbox1, bbox2)⚓➭

    Utility method Returns true if two bounding boxes intersect

    Parameters

    1. bbox1 string first bounding box
    2. bbox2 string second bounding box

    Returns: boolean true if they intersect

    Savage.path.isPointInside(path, x, y)⚓➭

    Utility method Returns true if given point is inside a given closed path.

    Parameters

    1. path string path string
    2. x number x of the point
    3. y number y of the point

    Returns: boolean true, if point is inside the path

    Savage.path.isPointInsideBBox(bbox, x, y)⚓➭

    Utility method Returns true if given point is inside bounding box.

    Parameters

    1. bbox string bounding box
    2. x string x coordinate of the point
    3. y string y coordinate of the point

    Returns: boolean true if point inside

    Savage.path.map(path, matrix)⚓➭

    Transform the path string with given matrix.

    Parameters

    1. path string path string
    2. matrix object see Matrix

    Returns: string transformed path string

    Savage.path.toAbsolute(path)⚓➭

    Utility method Converts path coordinates into absolute values.

    Parameters

    1. path string path string

    Returns: array path string

    Savage.path.toCubic(pathString)⚓➭

    Utility method Converts path to a new path where all segments are cubic bezier curves.

    Parameters

    1. pathString string array path string or array of segments

    Returns: array array of segments.

    Savage.path.toRelative(path)⚓➭

    Utility method Converts path coordinates into relative values.

    Parameters

    1. path string path string

    Returns: array path string

    Savage.rad(deg)⚓➭

    Transform angle to radians

    Parameters

    1. deg number angle in degrees

    Returns: number angle in radians.

    Savage.rgb(r, g, b)⚓➭

    Converts RGB values to hex representation of the colour.

    Parameters

    1. r number red
    2. g number green
    3. b number blue

    Returns: string hex representation of the colour.

    Savage.rgb2hsb(r, g, b)⚓➭

    Converts RGB values to HSB object.

    Parameters

    1. r number red
    2. g number green
    3. b number blue

    Returns: object HSB object in format:

    1. {
      1. hnumberhue
      2. snumbersaturation
      3. bnumberbrightness
    2. }

    Savage.rgb2hsl(r, g, b)⚓➭

    Converts RGB values to HSL object.

    Parameters

    1. r number red
    2. g number green
    3. b number blue

    Returns: object HSL object in format:

    1. {
      1. hnumberhue
      2. snumbersaturation
      3. lnumberluminosity
    2. }

    Savage.select(query)⚓➭

    Wraps DOM element specified by CSS selector as Element

    Parameters

    1. query string CSS selector of the element

    Returns: Element

    Savage.selectAll(query)⚓➭

    Wraps DOM elements specified by CSS selector as set or array of Element

    Parameters

    1. query string CSS selector of the element

    Returns: Element

    Savage.snapTo(values, value, [tolerance])⚓➭

    Snaps given value to given grid.

    Parameters

    1. values array number given array of values or step of the grid
    2. value number value to adjust
    3. tolerance optional number tolerance for snapping. Default is 10.

    Returns: number adjusted value.

    Set.clear()⚓➭

    Removeds all elements from the set

    Set.exclude(element)⚓➭

    Removes given element from the set

    Parameters

    1. element object element to remove

    Returns: boolean true if object was found & removed from the set

    Set.forEach(callback, thisArg)⚓➭

    Executes given function for each element in the set.

    If function returns false it will stop loop running.

    Parameters

    1. callback function function to run
    2. thisArg object context object for the callback

    Returns: object Set object

    Set.pop()⚓➭

    Removes last element and returns it.

    Returns: object element

    Set.push()⚓➭

    Adds each argument to the current set.

    Returns: object original element

    Set.splice(index, count, [insertion…])⚓➭

    Removes given element from the set

    Parameters

    1. index number position of the deletion
    2. count number number of element to remove
    3. insertion… optional object elements to insert

    Returns: object set elements that were deleted

    mina(a, A, b, B, get, set, [easing])⚓➭

    Generic animation of numbers.

    Parameters

    1. a number start “slave” number
    2. A number end “slave” number
    3. b number start “master” number (start time in gereal case)
    4. B number end “master” number (end time in gereal case)
    5. get function getter of “master” number (see mina.time)
    6. set function setter of “slave” number
    7. easing optional function easing function, default is mina.linear

    Returns: object animation descriptor

    1. {
      1. idstringanimation id,
      2. startnumberstart “slave” number,
      3. endnumberend “slave” number,
      4. bnumberstart “master” number,
      5. snumberanimation status (0..1),
      6. durnumberanimation duration,
      7. spdnumberanimation speed,
      8. getfunctiongetter of “master” number (see mina.time),
      9. setfunctionsetter of “slave” number,
      10. easingfunctioneasing function, default is mina.linear,
      11. statusfunctionstatus getter/setter,
      12. speedfunctionspeed getter/setter,
      13. durationfunctionduration getter/setter,
      14. stopfunctionanimation stopper
    2. }

    mina.backin(n)⚓➭

    Backin easing.

    Parameters

    1. n number input 0..1

    Returns: number output 0..1

    mina.backout(n)⚓➭

    Backout easing.

    Parameters

    1. n number input 0..1

    Returns: number output 0..1

    mina.bounce(n)⚓➭

    Bounce easing.

    Parameters

    1. n number input 0..1

    Returns: number output 0..1

    mina.easein(n)⚓➭

    Easein easing.

    Parameters

    1. n number input 0..1

    Returns: number output 0..1

    mina.easeinout(n)⚓➭

    Easeinout easing.

    Parameters

    1. n number input 0..1

    Returns: number output 0..1

    mina.easeout(n)⚓➭

    Easeout easing.

    Parameters

    1. n number input 0..1

    Returns: number output 0..1

    mina.elastic(n)⚓➭

    Elastic easing.

    Parameters

    1. n number input 0..1

    Returns: number output 0..1

    mina.getById(id)⚓➭

    Returns animation by it’s id.

    Parameters

    1. id string animation’s id

    Returns: object See mina

    mina.linear(n)⚓➭

    Default linear easing.

    Parameters

    1. n number input 0..1

    Returns: number output 0..1

    mina.time()⚓➭

    Returns current time. Equal to 

    function () {
    return (new Date).getTime();
}