1. Animation
  2. Animation.delay()
  3. Animation.repeat()
  4. Element
  5. Element.animate()
  6. Element.animateWith()
  7. Element.attr()
  8. Element.click()
  9. Element.clone()
  10. Element.data()
  11. Element.dblclick()
  12. Element.drag()
  13. Element.getBBox()
  14. Element.getPointAtLength()
  15. Element.getSubpath()
  16. Element.getTotalLength()
  17. Element.glow()
  18. Element.hide()
  19. Element.hover()
  20. Element.id
  21. Element.insertAfter()
  22. Element.insertBefore()
  23. Element.mousedown()
  24. Element.mousemove()
  25. Element.mouseout()
  26. Element.mouseover()
  27. Element.mouseup()
  28. Element.next
  29. Element.node
  30. Element.onDragOver()
  31. Element.paper
  32. Element.pause()
  33. Element.prev
  34. Element.raphael
  35. Element.remove()
  36. Element.removeData()
  37. Element.resume()
  38. Element.rotate()
  39. Element.scale()
  40. Element.setTime()
  41. Element.show()
  42. Element.status()
  43. Element.stop()
  44. Element.toBack()
  45. Element.toFront()
  46. Element.touchcancel()
  47. Element.touchend()
  48. Element.touchmove()
  49. Element.touchstart()
  50. Element.transform()
  51. Element.translate()
  52. Element.unclick()
  53. Element.undblclick()
  54. Element.undrag()
  55. Element.unhover()
  56. Element.unmousedown()
  57. Element.unmousemove()
  58. Element.unmouseout()
  59. Element.unmouseover()
  60. Element.unmouseup()
  61. Element.untouchcancel()
  62. Element.untouchend()
  63. Element.untouchmove()
  64. Element.untouchstart()
  65. Matrix
  66. Matrix.add()
  67. Matrix.clone()
  68. Matrix.invert()
  69. Matrix.rotate()
  70. Matrix.scale()
  71. Matrix.split()
  72. Matrix.toTransformString()
  73. Matrix.translate()
  74. Matrix.x()
  75. Matrix.y()
  76. Paper
  77. Paper.bottom
  78. Paper.circle()
  79. Paper.clear()
  80. Paper.customAttributes
  81. Paper.ellipse()
  82. Paper.forEach()
  83. Paper.getById()
  84. Paper.getElementByPoint()
  85. Paper.getFont()
  86. Paper.image()
  87. Paper.path()
  88. Paper.print()
  89. Paper.raphael
  90. Paper.rect()
  91. Paper.remove()
  92. Paper.renderfix()
  93. Paper.safari()
  94. Paper.set()
  95. Paper.setFinish()
  96. Paper.setSize()
  97. Paper.setStart()
  98. Paper.setViewBox()
  99. Paper.text()
  100. Paper.top
  101. Raphael()
  102. Raphael.angle()
  103. Raphael.animation()
  104. Raphael.color()
  105. Raphael.deg()
  106. Raphael.easing_formulas
  107. Raphael.el
  108. Raphael.findDotsAtSegment()
  109. Raphael.fn
  110. Raphael.format()
  111. Raphael.fullfill()
  112. Raphael.getColor()
  113. Raphael.getColor.reset()
  114. Raphael.getPointAtLength()
  115. Raphael.getRGB()
  116. Raphael.getSubpath()
  117. Raphael.getTotalLength()
  118. Raphael.hsb()
  119. Raphael.hsb2rgb()
  120. Raphael.hsl()
  121. Raphael.hsl2rgb()
  122. Raphael.is()
  123. Raphael.matrix()
  124. Raphael.ninja()
  125. Raphael.parsePathString()
  126. Raphael.parseTransformString()
  127. Raphael.path2curve()
  128. Raphael.pathToRelative()
  129. Raphael.rad()
  130. Raphael.registerFont()
  131. Raphael.rgb()
  132. Raphael.rgb2hsb()
  133. Raphael.rgb2hsl()
  134. Raphael.setWindow()
  135. Raphael.snapTo()
  136. Raphael.st
  137. Raphael.svg
  138. Raphael.type
  139. Raphael.vml
  140. Set
  141. Set.clear()
  142. Set.exclude()
  143. Set.forEach()
  144. Set.pop()
  145. Set.push()
  146. Set.splice()
  147. eve()
  148. eve.listeners()
  149. eve.nt()
  150. eve.on()
  151. eve.stop()
  152. eve.unbind()
  153. eve.version

Raphaël Reference

 Animation

 Animation.delay(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

 Animation.repeat(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.

or

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

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

or

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.attr(…)

Sets the attributes of the element.

Parameters

attrName
string
attribute’s name
value
string
value

or

params
object
object of name/value pairs

or

attrName
string
attribute’s name

or

attrNames
array
in this case method returns array of current values for given attribute names

Returns: object Element if attrsName & value or params are passed in.

Returns: ... value of the attribute if only attrsName is passed in.

Returns: array array of values of the attribute if attrsNames is passed in.

Returns: object object of attributes if nothing is passed in.

Possible parameters

Please refer to the SVG specification for an explanation of these parameters.

  1. arrow-endstringarrowhead on the end of the path. The format for string is <type>[-<width>[-<length>]]. Possible types: classic, block, open, oval, diamond, none, width: wide, narrow, midium, length: long, short, midium.
  2. clip-rectstringcomma or space separated values: x, y, width and height
  3. cursorstringCSS type of the cursor
  4. cxnumber 
  5. cynumber 
  6. fillstringcolour, gradient or image
  7. fill-opacitynumber 
  8. fontstring 
  9. font-familystring 
  10. font-sizenumberfont size in pixels
  11. font-weightstring 
  12. heightnumber 
  13. hrefstringURL, if specified element behaves as hyperlink
  14. opacitynumber 
  15. pathstringSVG path string format
  16. rnumber 
  17. rxnumber 
  18. rynumber 
  19. srcstringimage URL, only works for Element.image element
  20. strokestringstroke colour
  21. stroke-dasharraystring[“”, “-”, “.”, “-.”, “-..”, “. ”, “- ”, “--”, “- .”, “--.”, “--..”]
  22. stroke-linecapstring[“butt”, “square”, “round”]
  23. stroke-linejoinstring[“bevel”, “round”, “miter”]
  24. stroke-miterlimitnumber 
  25. stroke-opacitynumber 
  26. stroke-widthnumberstroke width in pixels, default is '1'
  27. targetstringused with href
  28. textstringcontents of the text element. Use \n for multiline text
  29. text-anchorstring[“start”, “middle”, “end”], default is “middle
  30. titlestringwill create tooltip with a given text
  31. transformstringsee Element.transform
  32. widthnumber 
  33. xnumber 
  34. ynumber 

Gradients

Linear gradient format: “‹angle›-‹colour›[-‹colour›[:‹offset›]]*-‹colour›”, example: “90-#fff-#000” – 90° gradient from white to black or “0-#fff-#f00:20-#000” – 0° gradient from white via red (at 20%) to black.

radial gradient: “r[(‹fx›, ‹fy›)]‹colour›[-‹colour›[:‹offset›]]*-‹colour›”, example: “r#fff-#000” – gradient from white to black or “r(0.25, 0.75)#fff-#000” – gradient from white to black with focus point at 0.25, 0.75. Focus point coordinates are in 0..1 range. Radial gradients can only be applied to circles and ellipses.

Path String

Please refer to SVG documentation regarding path string. Raphaël fully supports it.

Colour Parsing

  • 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%)”)
  • rgba(•••, •••, •••, •••) — red, green and blue channels’ values: (“rgba(200, 100, 0, .5)”)
  • rgba(•••%, •••%, •••%, •••%) — same as above, but in %: (“rgba(100%, 175%, 0%, 50%)”)
  • hsb(•••, •••, •••) — hue, saturation and brightness values: (“hsb(0.5, 0.25, 1)”)
  • hsb(•••%, •••%, •••%) — same as above, but in %
  • hsba(•••, •••, •••, •••) — same as above, but with opacity
  • hsl(•••, •••, •••) — almost the same as hsb, see Wikipedia page
  • hsl(•••%, •••%, •••%) — same as above, but in %
  • hsla(•••, •••, •••, •••) — same as above, but with opacity
  • Optionally for hsb and hsl you could specify hue as a degree: “hsl(240deg, 1, .5)” or, if you want to go fancy, “hsl(240°, 1, .5)

 Element.click(handler)

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(key, [value])

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(handler)

Adds event handler for double click for the element.

Parameters

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

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:

  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(isWithoutTransform)

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. {
    1. x:numbertop left corner x
    2. y:numbertop left corner y
    3. width:numberwidth
    4. height:numberheight
  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

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

from
number
position of the start of the segment
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.glow([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. {
    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
  2. }

Returns: object Paper.set of elements that represents glow

 Element.hide()

Makes element invisible. See Element.show.

Returns: object Element

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

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

number

Unique id of the element. Especially usesful when you want to listen to events of the element, because all events are fired in format <module>.<action>.<id>. Also useful for Paper.getById method.

 Element.insertAfter()

Inserts current object after the given one.

Returns: object Element

 Element.insertBefore()

Inserts current object before the given one.

Returns: object Element

 Element.mousedown(handler)

Adds event handler for mousedown for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.mousemove(handler)

Adds event handler for mousemove for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.mouseout(handler)

Adds event handler for mouseout for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.mouseover(handler)

Adds event handler for mouseover for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.mouseup(handler)

Adds event handler for mouseup for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.next

object

Reference to the next element in the hierarchy.

 Element.node

object

Gives you a reference to the DOM object, so you can assign event handlers or just mess around. Note: Don’t mess with it.

Usage

// draw a circle at coordinate 10,10 with radius of 10
var c = paper.circle(10, 10, 10);
c.node.onclick = function () {
    c.attr("fill", "red");
};

 Element.onDragOver(f)

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

object

Internal reference to “paper” where object drawn. Mainly for use in plugins and element extensions.

Usage

Raphael.el.cross = function () {
    this.attr({fill: "red"});
    this.paper.path("M10,10L50,50M50,10L10,50")
        .attr({stroke: "red"});
}

 Element.pause([anim])

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

Parameters

anim
optional
object
animation object

Returns: object original element

 Element.prev

object

Reference to the previous element in the hierarchy.

 Element.raphael

object

Internal reference to Raphael object. In case it is not available.

Usage

Raphael.el.red = function () {
    var hsb = this.paper.raphael.rgb2hsb(this.attr("fill"));
    hsb.h = 1;
    this.attr({fill: this.paper.raphael.hsb2rgb(hsb).hex});
}

 Element.remove()

Removes element from the paper.

 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

key
optional
string
key

Returns: object Element

 Element.resume([anim])

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

Parameters

anim
optional
object
animation object

Returns: object original element

 Element.rotate(deg, [cx], [cy])

Adds rotation by given angle around given point to the list of transformations of the element.

Parameters

deg
number
angle in degrees
cx
optional
number
x coordinate of the centre of rotation
cy
optional
number
y coordinate of the centre of rotation

If cx & cy aren’t specified centre of the shape is used as a point of rotation.

Returns: object Element

 Element.scale(sx, sy, [cx], [cy])

Adds scale by given amount relative to given point to the list of transformations of the element.

Parameters

sx
number
horisontal scale amount
sy
number
vertical scale amount
cx
optional
number
x coordinate of the centre of scale
cy
optional
number
y coordinate of the centre of scale

If cx & cy aren’t specified centre of the shape is used instead.

Returns: object Element

 Element.setTime(anim, value)

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

Makes element visible. See Element.hide.

Returns: object Element

 Element.status([anim], [value])

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

or

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

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

or

Returns: object original element if value is specified

 Element.stop([anim])

Stops animation of the element.

Parameters

anim
optional
object
animation object

Returns: object original element

 Element.toBack()

Moves the element so it is the furthest from the viewer’s eyes, behind other elements.

Returns: object Element

 Element.toFront()

Moves the element so it is the closest to the viewer’s eyes, on top of other elements.

Returns: object Element

 Element.touchcancel(handler)

Adds event handler for touchcancel for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.touchend(handler)

Adds event handler for touchend for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.touchmove(handler)

Adds event handler for touchmove for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.touchstart(handler)

Adds event handler for touchstart for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.transform([tstr])

Adds transformation to the element which is separate to other attributes, i.e. translation doesn’t change x or y of the rectange. The format of transformation string is similar to the path string syntax:

"t100,100r30,100,100s2,2,100,100r45s1.5"

Each letter is a command. There are four commands: t is for translate, r is for rotate, s is for scale and m is for matrix.

So, the example line above could be read like “translate by 100, 100; rotate 30° around 100, 100; scale twice around 100, 100; rotate 45° around centre; scale 1.5 times relative to centre”. As you can see rotate and scale commands have origin coordinates as optional parameters, the default is the centre point of the element. Matrix accepts six parameters.

Usage

var el = paper.rect(10, 20, 300, 200);
// translate 100, 100, rotate 45°, translate -100, 0
el.transform("t100,100r45t-100,0");
// if you want you can append or prepend transformations
el.transform("...t50,50");
el.transform("s2...");
// or even wrap
el.transform("t50,50...t-50-50");
// to reset transformation call method with empty string
el.transform("");
// to get current value call it without parameters
console.log(el.transform());

Parameters

tstr
optional
string
transformation string

If tstr isn’t specified

Returns: string current transformation string

else

Returns: object Element

 Element.translate(dx, dy)

Adds translation by given amount to the list of transformations of the element.

Parameters

dx
number
horisontal shift
dy
number
vertical shift

Returns: object Element

 Element.unclick(handler)

Removes event handler for click for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.undblclick(handler)

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(f_in, f_out)

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(handler)

Removes event handler for mousedown for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.unmousemove(handler)

Removes event handler for mousemove for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.unmouseout(handler)

Removes event handler for mouseout for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.unmouseover(handler)

Removes event handler for mouseover for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.unmouseup(handler)

Removes event handler for mouseup for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.untouchcancel(handler)

Removes event handler for touchcancel for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.untouchend(handler)

Removes event handler for touchend for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.untouchmove(handler)

Removes event handler for touchmove for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Element.untouchstart(handler)

Removes event handler for touchstart for the element.

Parameters

handler
function
handler for the event

Returns: object Element

 Matrix

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

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(a, x, y)

Rotates the matrix

Parameters

a
number
 
x
number
 
y
number
 

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

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:

  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

x
number
 
y
number
 

 Matrix.x(x, y)

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(x, 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.bottom

Points to the bottom element on the paper

 Paper.circle(x, y, r)

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

Clears the paper, i.e. removes all the elements.

 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 + ", .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: ".5 .8 1"});
c.animate({hsb: "1 0 .5"}, 1e3);

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

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(callback, thisArg)

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

 Paper.getById(id)

Returns you element by its internal ID.

Parameters

id
number
id

Returns: object Raphaël element object

 Paper.getElementByPoint(x, y)

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.getFont(family, [weight], [style], [stretch])

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.image(src, x, y, width, height)

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([pathString])

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.

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 in 2.0 to make life easier.

Usage

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

 Paper.print(x, y, text, font, [size], [origin], [letter_spacing])

Creates set of shapes to represent given font at given position with given size. Result of the method is set object (see Paper.set) which contains each letter as separate path object.

Parameters

x
number
x position of the text
y
number
y position of the text
text
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 set of letters

Usage

var txt = r.print(10, 50, "print", r.getFont("Museo"), 30).attr({fill: "#fff"});
// following line will paint first letter in red
txt[0].attr({fill: "#f00"});

 Paper.raphael

Points to the Raphael object/function

 Paper.rect(x, y, width, height, [r])

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

Removes the paper from the DOM.

 Paper.renderfix()

Fixes the issue of Firefox and IE9 regarding subpixel rendering. If paper is dependant on other elements after reflow it could shift half pixel which cause for lines to lost their crispness. This method fixes the issue.

 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(width, height)

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

Usage

var st = paper.set();
st.push(
    paper.circle(10, 10, 5),
    paper.circle(30, 10, 5)
);
st.attr({fill: "red"});

 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(x, y, w, h, fit)

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.text(x, y, 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

or

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

or

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>})
callback
optional
function
callback function which is going to be executed in the context of newly created paper

or

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(x1, y1, x2, y2, [x3], [y3])

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(params, ms, [easing], [callback])

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.color(clr)

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

 Raphael.deg(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”

See also Easing demo.

 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(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

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

 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. Please note that you can create your own namespaces inside the fn object — methods will be run in the context of canvas anyway. You should alter the fn object before a Raphaël instance is created, otherwise it will take no effect.

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(token, …)

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{1},{2}h{3}v{4}h{5}z", x, y, width, height, -width));

 Raphael.fullfill(token, json)

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

 Raphael.getColor([value])

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(path, length)

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. {
    1. x:numberx coordinate
    2. y:numbery coordinate
    3. alpha:numberangle of derivative
  2. }

 Raphael.getRGB(colour)

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

 Raphael.getSubpath(path, from, to)

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(path)

Returns length of the given path in pixels.

Parameters

path
string
SVG path string.

Returns: number length.

 Raphael.hsb(h, s, b)

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(h, s, v)

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. {
    1. rnumberred,
    2. gnumbergreen,
    3. bnumberblue,
    4. hexstringcolor in HTML/CSS format: #••••••
  2. }

 Raphael.hsl(h, s, l)

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(h, s, l)

Converts HSL values to RGB object.

Parameters

h
number
hue
s
number
saturation
l
number
luminosity

Returns: object RGB object in format:

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

 Raphael.is(o, type)

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.matrix(a, b, c, d, e, f)

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(pathString)

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(TString)

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(pathString)

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.pathToRelative(pathString)

Utility method Converts path to relative form

Parameters

pathString
string array
path string or array of segments

Returns: array array of segments.

 Raphael.rad(deg)

Transform angle to radians

Parameters

deg
number
angle in degrees

Returns: number angle in radians.

 Raphael.registerFont(font)

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(r, g, b)

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(r, g, b)

Converts RGB values to HSB object.

Parameters

r
number
red
g
number
green
b
number
blue

Returns: object HSB object in format:

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

 Raphael.rgb2hsl(r, g, b)

Converts RGB values to HSL object.

Parameters

r
number
red
g
number
green
b
number
blue

Returns: object HSL object in format:

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

 Raphael.setWindow(newwin)

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

Parameters

newwin
window
new window object

 Raphael.snapTo(values, value, [tolerance])

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 () {
        this.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.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(element)

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(callback, thisArg)

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(index, count, [insertion…])

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(name, scope, varargs)

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.listeners(name)

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([subname])

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

or

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

 eve.on(name, f)

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 accept one number parameter that represents z-index of the handler. It is 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", eat)(2);
eve.on("mouse", scream);
eve.on("mouse", catch)(1);

This will ensure that catch function will be called before eat. If you want to put you hadler before not indexed handlers specify 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.stop()

Is used inside event handler to stop event

 eve.unbind(name, f)

Removes given function from the list of event listeners assigned to given name.

Arguments

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

 eve.version

string

Current version of the library.