RedRaphaël API Reference

Animation⚓

Animation.delay⚓➭

* Creates a copy of existing animation object with given delay. *

Parameters

delay number number of ms to pass between animation start and actual animation

Returns: object new altered Animation object

 var anim = Raphael.animation({cx: 10, cy: 20}, 2e3);
 circle1.animate(anim); // run the given animation immediately
 circle2.animate(anim.delay(500)); // run the given animation after 500 ms

Animation.repeat⚓➭

* Creates a copy of existing animation object with given repetition. *

Parameters

repeat number number iterations of animation. For infinite animation pass Infinity

Returns: object new altered Animation object

Element⚓

Element.animate⚓➭

* Creates and starts animation for given element. *

Parameters

params object final attributes for the element, see also Element.attr
ms number number of milliseconds for animation to run
easing optional string easing type. Accept one of Raphael.easing_formulas or CSS format: cubic‐bezier(XX, XX, XX, XX)
callback optional function callback function. Will be called at the end of animation.

animation object animation object, see Raphael.animation

Returns: object original element

Element.animateWith⚓➭

* Acts similar to Element.animate, but ensure that given animation runs in sync with another given element. *

Parameters

el object element to sync with
anim object animation to sync with
params optional object final attributes for the element, see also Element.attr
ms optional number number of milliseconds for animation to run
easing optional string easing type. Accept on of Raphael.easing_formulas or CSS format: cubic‐bezier(XX, XX, XX, XX)
callback optional function callback function. Will be called at the end of animation.

element object element to sync with
anim object animation to sync with
animation optional object animation object, see Raphael.animation

Returns: object original element

Element.click⚓➭

* Adds event handler for click for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.clone⚓➭

Returns: object clone of a given element

Element.data⚓➭

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

Parameters

key string key to store data
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⚓➭

* Adds event handler for double click for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.drag⚓➭

* Adds event handlers for drag of the element.

Parameters

onmove function handler for moving
onstart function handler for drag start
onend function handler for drag end
mcontext optional object context for moving handler
scontext optional object context for drag start handler
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:

xnumberx position of the mouse
ynumbery position of the mouse
eventobjectDOM event object

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

dxnumbershift by x from the start point
dynumbershift by y from the start point
xnumberx position of the mouse
ynumbery position of the mouse
eventobjectDOM event object

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

eventobjectDOM event object

Returns: object Element

Element.getBBox⚓➭

* Return bounding box for a given element *

Parameters

isWithoutTransform boolean flag, true if you want to have bounding box before transformations. Default is false.

Returns: object Bounding box object:

{
1. x:numbertop left corner x
2. y:numbertop left corner y
3. x2:numberbottom right corner x
4. y2:numberbottom right corner y
5. width:numberwidth
6. height:numberheight
}

Element.getData⚓➭

* Retrieves the element data

Returns: object data

Element.glow⚓➭

* Return set of elements that create glow-like effect around given element. See Paper.set.

Note: Glow is not connected to the element. If you change element attributes it won’t adjust itself. *

Parameters

glow optional object parameters object with all properties optional:

{
1. widthnumbersize of the glow, default is 10
2. fillbooleanwill it be filled, default is false
3. opacitynumberopacity, default is 0.5
4. offsetxnumberhorizontal offset, default is 0
5. offsetynumbervertical offset, default is 0
6. colorstringglow colour, default is black
}

Returns: object Paper.set of elements that represents glow

Element.hover⚓➭

* Adds event handlers for hover for the element.

Parameters

f_in function handler for hover in
f_out function handler for hover out
icontext optional object context for hover in handler
ocontext optional object context for hover out handler

Returns: object Element

Element.isPointInside⚓➭

* Determine if given point is inside this element’s shape *

Parameters

x number x coordinate of the point
y number y coordinate of the point

Returns: boolean true if point inside the shape

Element.matrix⚓➭

object

* Keeps Matrix object, which represents element transformation

Element.mousedown⚓➭

* Adds event handler for mousedown for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.mousemove⚓➭

* Adds event handler for mousemove for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.mouseout⚓➭

* Adds event handler for mouseout for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.mouseover⚓➭

* Adds event handler for mouseover for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.mouseup⚓➭

* Adds event handler for mouseup for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.onDragOver⚓➭

* Shortcut for assigning event handler for drag.over.<id> event, where id is id of the element (see Element.id).

Parameters

f function handler for event, first argument would be the element you are dragging over

Element.pause⚓➭

* Stops animation of the element with ability to resume it later on. *

Parameters

anim optional object animation object

Returns: object original element

Element.removeData⚓➭

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

Parameters

key optional string key

Returns: object Element

Element.resume⚓➭

* Resumes animation if it was paused with Element.pause method. *

Parameters

anim optional object animation object

Returns: object original element

Element.setTime⚓➭

* Sets the status of animation of the element in milliseconds. Similar to Element.status method. *

Parameters

anim object animation object
value number number of milliseconds from the beginning of the animation

Returns: object original element if value is specified

Note, that during animation following events are triggered:

On each animation frame event anim.frame.<id>, on start anim.start.<id> and on end anim.finish.<id>.

Element.status⚓➭

* Gets or sets the status of animation of the element. *

Parameters

anim optional object animation object
value optional number 0 – 1. If specified, method works like a setter and sets the status of a given animation to the value. This will cause animation to jump to the given position.

Returns: number status

Returns: array status if anim is not specified. Array of objects in format:

{
1. anim:objectanimation object
2. status:numberstatus
}

Returns: object original element if value is specified

Element.stop⚓➭

* Stops animation of the element. *

Parameters

anim optional object animation object

Returns: object original element

Element.touchcancel⚓➭

* Adds event handler for touchcancel for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.touchend⚓➭

* Adds event handler for touchend for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.touchmove⚓➭

* Adds event handler for touchmove for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.touchstart⚓➭

* Adds event handler for touchstart for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.unclick⚓➭

* Removes event handler for click for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.undblclick⚓➭

* Removes event handler for double click for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.undrag⚓➭

* Removes all drag event handlers from given element.

Element.unhover⚓➭

* Removes event handlers for hover for the element.

Parameters

f_in function handler for hover in
f_out function handler for hover out

Returns: object Element

Element.unmousedown⚓➭

* Removes event handler for mousedown for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.unmousemove⚓➭

* Removes event handler for mousemove for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.unmouseout⚓➭

* Removes event handler for mouseout for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.unmouseover⚓➭

* Removes event handler for mouseover for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.unmouseup⚓➭

* Removes event handler for mouseup for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.untouchcancel⚓➭

* Removes event handler for touchcancel for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.untouchend⚓➭

* Removes event handler for touchend for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.untouchmove⚓➭

* Removes event handler for touchmove for the element.

Parameters

handler function handler for the event

Returns: object Element

Element.untouchstart⚓➭

* Removes event handler for touchstart for the element.

Parameters

handler function handler for the event

Returns: object Element

Matrix⚓

Matrix.add⚓➭

* Adds given matrix to existing one.

Parameters

a number
b number
c number
d number
e number
f number

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⚓➭

* Rotates the matrix

Parameters

a number
x number
y number

Matrix.scale⚓➭

* Scales the matrix

Parameters

x number
y optional number
cx optional number
cy optional number

Matrix.split⚓➭

* Splits matrix into primitive transformations

Returns: object in format:

dxnumbertranslation by x
dynumbertranslation by y
scalexnumberscale by x
scaleynumberscale by y
shearnumbershear
rotatenumberrotation in deg
isSimplebooleancould it be represented via simple transformations

Matrix.toTransformString⚓➭

* Return transform string that represents given matrix

Returns: string transform string

Matrix.translate⚓➭

* Translate the matrix

Parameters

x number
y number

Matrix.x⚓➭

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

Parameters

x number
y number

Returns: number x

Matrix.y⚓➭

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

Parameters

x number
y number

Returns: number y

Paper⚓

Paper.add⚓➭

* Imports elements in JSON array in format {type: type, <attributes>} *

Parameters

json array

Returns: object resulting set of imported elements

Usage

 paper.add([
     {
         type: "circle",
         cx: 10,
         cy: 10,
         r: 5
     },
     {
         type: "rect",
         x: 10,
         y: 10,
         width: 10,
         height: 10,
         fill: "#fc0"
     }
 ]);

Paper.bottom⚓➭

* Points to the bottom element on the paper

Paper.ca⚓➭

object

* Shortcut for Paper.customAttributes

Paper.circle⚓➭

* Draws a circle. *

Parameters

x number x coordinate of the centre
y number y coordinate of the centre
r number radius

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

Usage

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

Paper.customAttributes⚓➭

object

* If you have a set of attributes that you would like to represent as a function of some number you can do it easily with custom attributes:

Usage

 paper.customAttributes.hue = function (num) {
     num = num % 1;
     return {fill: "hsb(" + num + ", 0.75, 1)"};
 };
 // Custom attribute “hue” will change fill
 // to be given hue with fixed saturation and brightness.
 // Now you can use it like this:
 var c = paper.circle(10, 10, 10).attr({hue: .45});
 // or even like this:
 c.animate({hue: 1}, 1e3);

 // You could also create custom attribute
 // with multiple parameters:
 paper.customAttributes.hsb = function (h, s, b) {
     return {fill: "hsb(" + [h, s, b].join(",") + ")"};
 };
 c.attr({hsb: "0.5 .8 1"});
 c.animate({hsb: [1, 0, 0.5]}, 1e3);

Paper.ellipse⚓➭

* Draws an ellipse. *

Parameters

x number x coordinate of the centre
y number y coordinate of the centre
rx number horizontal radius
ry number vertical radius

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

Usage

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

Paper.forEach⚓➭

* Executes given function for each element on the paper

If callback function returns false it will stop loop running. *

Parameters

callback function function to run
thisArg object context object for the callback

Returns: object Paper object

Usage

 paper.forEach(function (el) {
     el.attr({ stroke: "blue" });
 });

Paper.getElementByPoint⚓➭

* Returns you topmost element under given point. *

Returns: object Raphaël element object

Parameters

x number x coordinate from the top left corner of the window
y number y coordinate from the top left corner of the window

Usage

 paper.getElementByPoint(mouseX, mouseY).attr({stroke: "#f00"});

Paper.getElementsByBBox⚓➭

* Returns set of elements that have an intersecting bounding box *

Parameters

bbox object bbox to check with

Returns: object Set

Paper.getElementsByPoint⚓➭

* Returns set of elements that have common point inside *

Parameters

x number x coordinate of the point
y number y coordinate of the point

Returns: object Set

Paper.getFont⚓➭

* Finds font object in the registered fonts by given parameters. You could specify only one word from the font name, like “Myriad” for “Myriad Pro”. *

Parameters

family string font family name or any word from it
weight optional string font weight
style optional string font style
stretch optional string font stretch

Returns: object the font object

Usage

 paper.print(100, 100, "Test string", paper.getFont("Times", 800), 30);

Paper.group⚓➭

* Creates a group *

Parameters

id number id of the group

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

Usage

 var g = paper.group();

Paper.hide⚓➭

* Hides a paper *

Usage

 paper.hide();

Paper.image⚓➭

* Embeds an image into the surface. *

Parameters

src string URI of the source image
x number x coordinate position
y number y coordinate position
width number width of the image
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);

Paper.path⚓➭

* Creates a path element by given path data string.

Parameters

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.

Command	Name	Parameters
M	moveto	(x y)+
Z	closepath	(none)
L	lineto	(x y)+
H	horizontal lineto	x+
V	vertical lineto	y+
C	curveto	(x1 y1 x2 y2 x y)+
S	smooth curveto	(x2 y2 x y)+
Q	quadratic Bézier curveto	(x1 y1 x y)+
T	smooth quadratic Bézier curveto	(x y)+
A	elliptical arc	(rx ry x-axis-rotation large-arc-flag sweep-flag x y)+
R	Catmull-Rom curveto*	x1 y1 (x y)+

“Catmull-Rom curveto” is a not standard SVG command and added in 2.0 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

For example of path strings, check out these icons: http://raphaeljs.com/icons/

Paper.print⚓➭

* Creates path that represent given text written using given font at given position with given size. Result of the method is path element that contains whole text as a separate path. *

Parameters

x number x position of the text
y number y position of the text
string string text to print
font object font object, see Paper.getFont
size optional number size of the font, default is 16
origin optional string could be "baseline" or "middle", default is "middle"
letter_spacing optional number number in range -1..1, default is 0

Returns: object resulting path element, which consist of all letters

Usage

 var txt = r.print(10, 50, "print", r.getFont("Museo"), 30).attr({fill: "#fff"});

Paper.raphael⚓➭

* Points to the Raphael object/function

Paper.rect⚓➭

Draws a rectangle. *

Parameters

x number x coordinate of the top left corner
y number y coordinate of the top left corner
width number width
height number height
r optional number radius for rounded corners, default is 0

Returns: object Raphaël 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.safari⚓➭

* There is an inconvenient rendering bug in Safari (WebKit): sometimes the rendering should be forced. This method should help with dealing with this bug.

Paper.set⚓➭

* Creates array-like object to keep and operate several elements at once. Warning: it doesn’t create any elements for itself in the page, it just groups existing elements. Sets act as pseudo elements — all methods available to an element can be used on a set.

Returns: object array-like object that represents set of elements

Usage

 var st = paper.set();
 st.push(
     paper.circle(10, 10, 5),
     paper.circle(30, 10, 5)
 );
 st.attr({fill: "red"}); // changes the fill of both circles

Paper.setFinish⚓➭

* See Paper.setStart. This method finishes catching and returns resulting set. *

Returns: object set

Paper.setSize⚓➭

* If you need to change dimensions of the canvas call this method *

Parameters

width number new width of the canvas
height number new height of the canvas

Paper.setStart⚓➭

* Creates Paper.set. All elements that will be created after calling this method and before calling Paper.setFinish will be added to the set. *

Usage

 paper.setStart();
 paper.circle(10, 10, 5),
 paper.circle(30, 10, 5)
 var st = paper.setFinish();
 st.attr({fill: "red"}); // changes the fill of both circles

Paper.setViewBox⚓➭

* Sets the view box of the paper. Practically it gives you ability to zoom and pan whole paper surface by specifying new boundaries. *

Parameters

x number new x position, default is 0
y number new y position, default is 0
w number new width of the canvas
h number new height of the canvas
fit boolean true if you want graphics to fit into new boundary box

Paper.show⚓➭

* Shows a hidden paper *

Usage

 paper.show();

Paper.text⚓➭

* Draws a text string. If you need line breaks, put “\n” in the string. *

Parameters

x number x coordinate position
y number y coordinate position
text string The text string to draw

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

Usage

 var t = paper.text(50, 50, "Raphaël\nkicks\nbutt!");

Paper.top⚓➭

* Points to the topmost element on the paper

Raphael⚓➭

* Creates a canvas object on which to draw. You must do this first, as all future calls to drawing methods from this instance will be bound to this canvas.

Parameters

container HTMLElement string DOM element or its ID which is going to be a parent for drawing surface
width number
height number
callback optional function callback function which is going to be executed in the context of newly created paper

x number
y number
width number
height number
callback optional function callback function which is going to be executed in the context of newly created paper

all array (first 3 or 4 elements in the array are equal to [containerID, width, height] or [x, y, width, height]. The rest are element descriptions in format {type: type, <attributes>}). See Paper.add.
callback optional function callback function which is going to be executed in the context of newly created paper

onReadyCallback function function that is going to be called on DOM ready event. You can also subscribe to this event via Eve’s “DOMLoad” event. In this case method returns undefined.

Returns: object Paper

Usage

 // Each of the following examples create a canvas
 // that is 320px wide by 200px high.
 // Canvas is created at the viewport’s 10,50 coordinate.
 var paper = Raphael(10, 50, 320, 200);
 // Canvas is created at the top left corner of the #notepad element
 // (or its top right corner in dir="rtl" elements)
 var paper = Raphael(document.getElementById("notepad"), 320, 200);
 // Same as above
 var paper = Raphael("notepad", 320, 200);
 // Image dump
 var set = Raphael(["notepad", 320, 200, {
     type: "rect",
     x: 10,
     y: 10,
     width: 25,
     height: 25,
     stroke: "#f00"
 }, {
     type: "text",
     x: 30,
     y: 40,
     text: "Dump"
 }]);

Raphael.angle⚓➭

* Returns angle between two or three points

Parameters

x1 number x coord of first point
y1 number y coord of first point
x2 number x coord of second point
y2 number y coord of second point
x3 optional number x coord of third point
y3 optional number y coord of third point

Returns: number angle in degrees.

Raphael.animation⚓➭

* Creates an animation object that can be passed to the Element.animate or Element.animateWith methods. See also Animation.delay and Animation.repeat methods. *

Parameters

params object final attributes for the element, see also Element.attr
ms number number of milliseconds for animation to run
easing optional string easing type. Accept one of Raphael.easing_formulas or CSS format: cubic‐bezier(XX, XX, XX, XX)
callback optional function callback function. Will be called at the end of animation.

Returns: object Animation

Raphael.bezierBBox⚓➭

* Utility method * Return bounding box of a given cubic bezier curve

Parameters

p1x number x of the first point of the curve
p1y number y of the first point of the curve
c1x number x of the first anchor of the curve
c1y number y of the first anchor of the curve
c2x number x of the second anchor of the curve
c2y number y of the second anchor of the curve
p2x number x of the second point of the curve
p2y number y of the second point of the curve

bez array array of six points for bezier curve

Returns: object point information in format:

{
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. }
}

Raphael.ca⚓➭

object

* Shortcut for Raphael.customAttributes

Raphael.clone⚓➭

* Returns a recursively cloned version of an object.

Raphael.color⚓➭

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

Parameters

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

Returns: object Combined RGB & HSB object in format:

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

Raphael.createUUID⚓➭

* Returns RFC4122, version 4 ID

Raphael.customAttributes⚓➭

object

* If you have a set of attributes that you would like to represent as a function of some number across all papers you can do it easily with custom attributes:

Usage

 Raphael.customAttributes.hue = function (num) {
     num = num % 1;
     return {fill: "hsb(" + num + ", 0.75, 1)"};
 };
 // Custom attribute “hue” will change fill
 // to be given hue with fixed saturation and brightness.
 // Now you can use it like this:
 var c = paper.circle(10, 10, 10).attr({hue: .45});
 // or even like this:
 c.animate({hue: 1}, 1e3);

 // You could also create custom attribute
 // with multiple parameters:
 Raphael.customAttributes.hsb = function (h, s, b) {
     return {fill: "hsb(" + [h, s, b].join(",") + ")"};
 };
 c.attr({hsb: "0.5 .8 1"});
 c.animate({hsb: [1, 0, 0.5]}, 1e3);

Raphael.define⚓➭

* Allows a unified definition of composite shapes and other behaviours using simple directives. *

Parameters

definition object the shape definition

Raphael.deg⚓➭

* Transform angle to degrees

Parameters

deg number angle in radians

Returns: number angle in degrees.

Raphael.easing_formulas⚓➭

* Object that contains easing formulas for animation. You could extend it with your own. By default it has following list of easing:

“linear”
“<” or “easeIn” or “ease-in”
“>” or “easeOut” or “ease-out”
“<>” or “easeInOut” or “ease-in-out”
“backIn” or “back-in”
“backOut” or “back-out”
“elastic”
“bounce”

Raphael.el⚓➭

object

* You can add your own method to elements. This is usefull when you want to hack default functionality or want to wrap some common transformation or attributes in one method. In difference to canvas methods, you can redefine element method at any time. Expending element methods wouldn’t affect set.

Usage

 Raphael.el.red = function () {
     this.attr({fill: "#f00"});
 };
 // then use it
 paper.circle(100, 100, 20).red();

Raphael.findDotsAtSegment⚓➭

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

Parameters

p1x number x of the first point of the curve
p1y number y of the first point of the curve
c1x number x of the first anchor of the curve
c1y number y of the first anchor of the curve
c2x number x of the second anchor of the curve
c2y number y of the second anchor of the curve
p2x number x of the second point of the curve
p2y number y of the second point of the curve
t number position on the curve (0..1)

Returns: object point information in format:

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

Raphael.fn⚓➭

object

* You can add your own method to the canvas. For example if you want to draw a pie chart, you can create your own pie chart function and ship it as a Raphaël plugin. To do this you need to extend the Raphael.fn object. You should modify the fn object before a Raphaël instance is created, otherwise it will take no effect. Please note that the ability for namespaced plugins was removed in Raphael 2.0. It is up to the plugin to ensure any namespacing ensures proper context.

Usage

 Raphael.fn.arrow = function (x1, y1, x2, y2, size) {
     return this.path( ... );
 };
 // or create namespace
 Raphael.fn.mystuff = {
     arrow: function () {…},
     star: function () {…},
     // etc…
 };
 var paper = Raphael(10, 10, 630, 480);
 // then use it
 paper.arrow(10, 10, 30, 30, 5).attr({fill: "#f00"});
 paper.mystuff.arrow();
 paper.mystuff.star();

Raphael.format⚓➭

* Simple format function. Replaces construction of type “{<number>}” to the corresponding argument. *

Parameters

token string string to format
… string rest of arguments will be treated as parameters for replacement

Returns: string formated string

Usage

 var x = 10,
     y = 20,
     width = 40,
     height = 50;
 // this will draw a rectangular shape equivalent to "M10,20h40v50h-40z"
 paper.path(Raphael.format("M{0},{1}h{2}v{3}h{4}z", x, y, width, height, -width));

Raphael.fullfill⚓➭

* A little bit more advanced format function than Raphael.format. Replaces construction of type “{<name>}” to the corresponding argument. *

Parameters

token string string to format
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(Raphael.fullfill("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
     }
 }));

Raphael.getColor⚓➭

* On each call returns next colour in the spectrum. To reset it back to red call Raphael.getColor.reset

Parameters

value optional number brightness, default is 0.75

Returns: string hex representation of the colour.

Raphael.getColor.reset⚓➭

* Resets spectrum position for Raphael.getColor back to red.

Raphael.getPointAtLength⚓➭

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

Parameters

path string SVG path string
length number

Returns: object representation of the point:

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

Raphael.getRGB⚓➭

* Parses colour string as RGB object

Parameters

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. rnumberred,
2. gnumbergreen,
3. bnumberblue
4. hexstringcolor in HTML/CSS format: #••••••,
5. errorbooleantrue if string can’t be parsed
}

Raphael.getSubpath⚓➭

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

Parameters

path string SVG path string
from number position of the start of the segment
to number position of the end of the segment

Returns: string pathstring for the segment

Raphael.getTotalLength⚓➭

* Returns length of the given path in pixels. *

Parameters

path string SVG path string.

Returns: number length.

Raphael.hsb⚓➭

* Converts HSB values to hex representation of the colour.

Parameters

h number hue
s number saturation
b number value or brightness

Returns: string hex representation of the colour.

Raphael.hsb2rgb⚓➭

* Converts HSB values to RGB object.

Parameters

h number hue
s number saturation
v number value or brightness

Returns: object RGB object in format:

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

Raphael.hsl⚓➭

* Converts HSL values to hex representation of the colour.

Parameters

h number hue
s number saturation
l number luminosity

Returns: string hex representation of the colour.

Raphael.hsl2rgb⚓➭

* Converts HSL values to RGB object.

Parameters

h number hue
s number saturation
l number luminosity

Returns: object RGB object in format:

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

Raphael.is⚓➭

* Handfull replacement for typeof operator.

Parameters

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

Returns: boolean is given value is of given type

Raphael.isBBoxIntersect⚓➭

* Utility method * Returns true if two bounding boxes intersect

Parameters

bbox1 string first bounding box
bbox2 string second bounding box

Returns: boolean true if they intersect

Raphael.isPointInsideBBox⚓➭

* Utility method * Returns true if given point is inside bounding boxes.

Parameters

bbox string bounding box
x string x coordinate of the point
y string y coordinate of the point

Returns: boolean true if point inside

Raphael.isPointInsidePath⚓➭

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

Parameters

path string path string
x number x of the point
y number y of the point

Returns: boolean true, if point is inside the path

Raphael.mapPath⚓➭

* Transform the path string with given matrix.

Parameters

path string path string
matrix object see Matrix

Returns: string transformed path string

Raphael.matrix⚓➭

* Utility method * Returns matrix based on given parameters.

Parameters

a number
b number
c number
d number
e number
f number

Returns: object Matrix

Raphael.ninja⚓➭

* If you want to leave no trace of Raphaël (Well, Raphaël creates only one global variable Raphael, but anyway.) You can use ninja method. Beware, that in this case plugins could stop working, because they are depending on global variable existance. *

Returns: object Raphael object

Usage

 (function (local_raphael) {
     var paper = local_raphael(10, 10, 320, 200);
     …
 })(Raphael.ninja());

Raphael.parsePathString⚓➭

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

Parameters

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

Returns: array array of segments.

Raphael.parseTransformString⚓➭

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

Parameters

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

Returns: array array of transformations.

Raphael.path2curve⚓➭

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

Parameters

pathString string array path string or array of segments

Returns: array array of segments.

Raphael.pathBBox⚓➭

* Utility method * Return bounding box of a given path

Parameters

path string path string

Returns: object bounding box

{
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
7. cx:numberx coordinate of the center of the box
8. cy:numbery coordinate of the center of the box
}

Raphael.pathIntersection⚓➭

* Utility method * Finds intersections of two paths

Parameters

path1 string path string
path2 string path string

Returns: array dots of intersection

[
{
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
}
]

Raphael.pathToRelative⚓➭

* Utility method * Converts path to relative form

Parameters

pathString string array path string or array of segments

Returns: array array of segments.

Raphael.pick⚓➭

* Returns the first truthy argument.

Raphael.rad⚓➭

* Transform angle to radians

Parameters

deg number angle in degrees

Returns: number angle in radians.

Raphael.registerFont⚓➭

* Adds given font to the registered set of fonts for Raphaël. Should be used as an internal call from within Cufón’s font file. Returns original parameter, so it could be used with chaining.

More about Cufón and how to convert your font form TTF, OTF, etc to JavaScript file.

Parameters

font object the font to register

Returns: object the font you passed in

Usage

 Cufon.registerFont(Raphael.registerFont({…}));

Raphael.rgb⚓➭

* Converts RGB values to hex representation of the colour.

Parameters

r number red
g number green
b number blue

Returns: string hex representation of the colour.

Raphael.rgb2hsb⚓➭

* Converts RGB values to HSB object.

Parameters

r number red
g number green
b number blue

Returns: object HSB object in format:

{
1. hnumberhue
2. snumbersaturation
3. bnumberbrightness
}

Raphael.rgb2hsl⚓➭

* Converts RGB values to HSL object.

Parameters

r number red
g number green
b number blue

Returns: object HSL object in format:

{
1. hnumberhue
2. snumbersaturation
3. lnumberluminosity
}

Raphael.setWindow⚓➭

* Used when you need to draw in <iframe>. Switched window to the iframe one.

Parameters

newwin window new window object

Raphael.snapTo⚓➭

* Snaps given value to given grid.

Parameters

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

Returns: number adjusted value.

Raphael.st⚓➭

object

* You can add your own method to elements and sets. It is wise to add a set method for each element method you added, so you will be able to call the same method on sets too. * See also Raphael.el.

Usage

 Raphael.el.red = function () {
     this.attr({fill: "#f00"});
 };
 Raphael.st.red = function () {
     this.forEach(function (el) {
         el.red();
     });
 };
 // then use it
 paper.set(paper.circle(100, 100, 20), paper.circle(110, 100, 20)).red();

Raphael.svg⚓➭

boolean

* true if browser supports SVG.

Raphael.toMatrix⚓➭

* Utility method * Returns matrix of transformations applied to a given path

Parameters

path string path string
transform string array transformation string

Returns: object Matrix

Raphael.transformPath⚓➭

* Utility method * Returns path transformed by a given transformation

Parameters

path string path string
transform string array transformation string

Returns: string path

Raphael.type⚓➭

string

* Can be “SVG”, “VML” or empty, depending on browser support.

Raphael.vml⚓➭

boolean

* true if browser supports VML.

Set⚓

Set.clear⚓➭

* Removeds all elements from the set

Set.exclude⚓➭

* Removes given element from the set *

Parameters

element object element to remove

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

Set.forEach⚓➭

* Executes given function for each element in the set.

If function returns false it will stop loop running. *

Parameters

callback function function to run
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⚓➭

* Removes given element from the set *

Parameters

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

Returns: object set elements that were deleted

eve⚓➭

Fires event with given name, given scope and other parameters.

Arguments

name string name of the event, dot (.) or slash (/) separated
scope object context for the event handlers
varargs ... the rest of arguments will be sent to event handlers

Returns: object array of returned values from the listeners

eve.f⚓➭

* Returns function that will fire given event with optional arguments. Arguments that will be passed to the result function will be also concated to the list of final arguments.

 el.onclick = eve.f("click", 1, 2);
 eve.on("click", function (a, b, c) {
     console.log(a, b, c); // 1, 2, [event object]
 });

Arguments

event string event name
varargs … and any other arguments

Returns: function possible event handler function

eve.listeners⚓➭

Internal method which gives you array of all event handlers that will be triggered by the given name.

Arguments

name string name of the event, dot (.) or slash (/) separated

Returns: array array of event handlers

eve.nt⚓➭

* Could be used inside event handler to figure out actual name of the event. *

Arguments

subname optional string subname of the event

Returns: string name of the event, if subname is not specified

Returns: boolean true, if current event’s name contains subname

eve.nts⚓➭

* Could be used inside event handler to figure out actual name of the event. * *

Returns: array names of the event

eve.off⚓➭

* Removes given function from the list of event listeners assigned to given name. If no arguments specified all the events will be cleared. *

Arguments

name string name of the event, dot (.) or slash (/) separated, with optional wildcards
f function event handler function

eve.on⚓➭

* Binds given event handler with a given name. You can use wildcards “*” for the names:

 eve.on("*.under.*", f);
 eve("mouse.under.floor"); // triggers f

Use eve to trigger the listener. *

Arguments

name string name of the event, dot (.) or slash (/) separated, with optional wildcards
f function event handler function

Returns: function returned function accepts a single numeric parameter that represents z-index of the handler. It is an optional feature and only used when you need to ensure that some subset of handlers will be invoked in a given order, despite of the order of assignment.

Example:

 eve.on("mouse", eatIt)(2);
 eve.on("mouse", scream);
 eve.on("mouse", catchIt)(1);

This will ensure that catchIt() function will be called before eatIt().

If you want to put your handler before non-indexed handlers, specify a negative value. Note: I assume most of the time you don’t need to worry about z-index, but it’s nice to have this feature “just in case”.

eve.once⚓➭

* Binds given event handler with a given name to only run once then unbind itself.

 eve.once("login", f);
 eve("login"); // triggers f
 eve("login"); // no listeners

Use eve to trigger the listener. *

Arguments

name string name of the event, dot (.) or slash (/) separated, with optional wildcards
f function event handler function

Returns: function same return function as eve.on

eve.stop⚓➭

* Is used inside an event handler to stop the event, preventing any subsequent listeners from firing.

eve.unbind⚓➭

* See eve.off

eve.version⚓➭

string

* Current version of the library.