<li>pathString <em>string</em> [optional] Path data in <ahref="http://www.w3.org/TR/SVG/paths.html#PathData"title="Details of a path's data attribute's format are described in the SVG specification.">SVG path string format</a>.</li>

</ol>

<h4>Usage</h4>

<preclass="javascript code"><code>var c = paper.path("M10 10L90 90");

// draw a diagonal line:

// move to 10,10, line to 90,90</code></pre>

<h3id="clear">

clear

</h3>

<p>

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

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>var c = paper.path("M10 10L90 90");

paper.clear();</code></pre>

<h2id="Element">

Element’s generic methods

</h2>

<p>

Each object created on the canvas shares these same generic methods:

</p>

<h3id="node">

node

</h3>

<p>

Gives you a reference to the DOM object, so you can assign event handlers or just mess around.

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>// 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");

};</code></pre>

<h3id="paper">

paper

</h3>

<p>

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

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>Raphael.el.cross = function () {

this.attr({fill: "red"});

this.paper.path("M10,10L50,50M50,10L10,50")

.attr({stroke: "red"});

}</code></pre>

<h3id="remove">

remove

</h3>

<p>

Removes element from the DOM. You can’t use it after this method call.

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>var c = paper.circle(10, 10, 10);

c.remove();</code></pre>

<h3id="hide">

hide

</h3>

<p>

Makes element invisible.

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>var c = paper.circle(10, 10, 10);

c.hide();</code></pre>

<h3id="show">

show

</h3>

<p>

Makes element visible.

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>var c = paper.circle(10, 10, 10);

c.show();</code></pre>

<h3id="rotate">

rotate

</h3>

<p>

Rotates the element by the given degree from its center point.

</p>

<h4>Parameters</h4>

<ol>

<li>degree <em>number</em> Degree of rotation (0 – 360°)</li>

<li>isAbsolute <em>boolean</em> [optional] Specifies is degree is relative to previous position (<code>false</code>) or is it absolute angle (<code>true</code>)</li>

</ol>

<p>or</p>

<ol>

<li>degree <em>number</em> Degree of rotation (0 – 360°)</li>

<li>cx <em>number</em> [optional] X coordinate of the origin of rotation</li>

<li>cY <em>number</em> [optional] Y coordinate of the origin of rotation</li>

</ol>

<h4>Usage</h4>

<preclass="javascript code"><code>var c = paper.circle(10, 10, 10);

c.rotate(45); // rotation is relative

c.rotate(45, true); // rotation is absolute</code></pre>

<h3id="translate">

translate

</h3>

<p>

Moves the element around the canvas by the given distances.

</p>

<h4>Parameters</h4>

<ol>

<li>dx <em>number</em> Pixels of translation by X axis</li>

<li>dy <em>number</em> Pixels of translation by Y axis</li>

</ol>

<h4>Usage</h4>

<preclass="javascript code"><code>var c = paper.circle(10, 10, 10);

// moves the circle 10&nbsp;px to the right and down

c.translate(10, 10);</code></pre>

<h3id="scale">

scale

</h3>

<p>

Resizes the element by the given multiplier.

</p>

<h4>Parameters</h4>

<ol>

<li>Xtimes <em>number</em> Amount to scale horizontally</li>

<li>Ytimes <em>number</em> Amount to scale vertically</li>

<li>centerX <em>number</em> [optional] X of the center of scaling, default is the center of the element</li>

<li>centerY <em>number</em> [optional] Y of the center of scaling, default is the center of the element</li>

</ol>

<h4>Usage</h4>

<preclass="javascript code"><code>var c = paper.circle(10, 10, 10);

// makes the circle 1.5 times larger

c.scale(1.5, 1.5);

// makes the circle half as wide, and 75% as high

c.scale(.5, .75);</code></pre>

<h3id="attr">

attr

</h3>

<p>

Sets the attributes of elements directly.

</p>

<h4>Parameters</h4>

<ol>

<li>attributeName <em>string</em></li>

<li>value <em>string</em></li>

</ol>

<p>or</p>

<ol>

<li>params <em>object</em></li>

</ol>

<p>or</p>

<ol>

<li>attributeName <em>string</em> in this case method returns current value for given attribute name</li>

</ol>

<p>or</p>

<ol>

<li>attributeNames <em>array</em> in this case method returns array of current values for given attribute names</li>

</ol>

<p>or</p>

<p>no parameters, in this case object containing all attributes will be returned</p>

<h4>Possible parameters</h4>

<p>Please refer to the <ahref="http://www.w3.org/TR/SVG/"title="The W3C Recommendation for the SVG language describes these properties in detail.">SVG specification</a> for an explanation of these parameters.</p>

<liid="attr-path">path <em>pathString</em> <ahref="http://www.w3.org/TR/SVG/paths.html#PathData"title="Details of a path’s data attribute’s format are described in the SVG specification.">SVG path string format</a></li>

<li>keyFrames <em>object</em> Key-value map, where key represents keyframe timing: [“from”, “20%”, “to”, “35%”, etc] and value is the same as <code>newAttrs</code> from above, except it could also have <samp>easing</samp> and <samp>callback</samp> properties</li>

<li>ms <em>number</em> The duration of the animation, given in milliseconds.</li>

</ol>

<p>Look at the <ahref="bounce.html">example of keyframes usage</a></p>

<h4>Attributes that can be animated</h4>

<p>The <code>newAttrs</code> parameter accepts an object whose properties are the attributes to animate. However, not all attributes listed in the <code>attr</code> method reference can be animated. The following is a list of those properties that can be animated:</p>

<ul>

<li>clip-rect <em>string</em></li>

<li>cx <em>number</em></li>

<li>cy <em>number</em></li>

<li>fill <em>colour</em></li>

<li>fill-opacity <em>number</em></li>

<li>font-size <em>number</em></li>

<li>height <em>number</em></li>

<li>opacity <em>number</em></li>

<li>path <em>pathString</em></li>

<li>r <em>number</em></li>

<li>rotation <em>string</em></li>

<li>rx <em>number</em></li>

<li>ry <em>number</em></li>

<li>scale <em>string</em></li>

<li>stroke <em>colour</em></li>

<li>stroke-opacity <em>number</em></li>

<li>stroke-width <em>number</em></li>

<li>translation <em>string</em></li>

<li>width <em>number</em></li>

<li>x <em>number</em></li>

<li>y <em>number</em></li>

</ul>

<h4>Easing</h4>

<p>

For easing use built in functions or add your own by adding new functions to <code>Raphael.easing_formulas</code> object. Look at the <ahref="easing.html">example of easing usage</a>.

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>var c = paper.circle(10, 10, 10);

c.animate({cx: 20, r: 20}, 2000);

c.animate({cx: 20, r: 20}, 2000, "bounce");

c.animate({

"20%": {cx: 20, r: 20, easing: ">"},

"50%": {cx: 70, r: 120, callback: function () {…}},

"100%": {cx: 10, r: 10}

}, 2000);</code></pre>

<h3id="animateWith">

animateWith

</h3>

<p>

The same as <ahref="#animate"><code>animate</code></a> method, but synchronise animation with another element.

</p>

<h4>Parameters</h4>

<p>The same as for <ahref="#animate"><code>animate</code></a> method, but first argument is an element.</p>

<h4>Usage</h4>

<preclass="javascript code"><code>var c = paper.circle(10, 10, 10),

r = paper.rect(10, 10, 10, 10);

c.animate({cx: 20, r: 20}, 2000);

r.animateWith(c, {x: 20}, 2000);</code></pre>

<h3id="animateAlong">

animateAlong

</h3>

<divclass="sample"id="along-sample"></div>

<p>

Animates element along the given path. As an option it could rotate element along the path.

</p>

<h4>Parameters</h4>

<ol>

<li>path <em>object</em> or <em>string</em> path element or path string along which the element will be animated</li>

<li>ms <em>number</em> The duration of the animation, given in milliseconds.</li>

<li>rotate <em>boolean</em> [optional] if true, element will be rotated along the path</li>

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. <ahref="http://wiki.github.com/sorccu/cufon/about">More about Cufón and how to convert your font form TTF, OTF, etc to JavaScript file</a>. Returns original parameter, so it could be used with chaining.

You can add your own method to the canvas. For example if you want to draw 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 Raphael.fn object. Please note that you can create your own namespaces inside fn object. Methods will be run in context of canvas anyway. You should alter fn object before Raphaël instance was created, otherwise it will take no effect.

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 mathods, you can redefine element method at any time.

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>Raphael.el.red = function () {

this.attr({fill: "#f00"});

};

// then use it

paper.circle(100, 100, 20).red();

</code></pre>

<h3id="custom-attributes">

Custom Attributes

</h3>

<p>

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:

<li>hsl(•••, •••, •••) — almost the same as hsb, see <ahref="http://en.wikipedia.org/wiki/HSL_and_HSV"title="HSL and HSV - Wikipedia, the free encyclopedia">Wikipedia page</a></li>

<li>hsl(•••%, •••%, •••%) — same as above, but in %</li>

<li>hsla(•••, •••, •••) — same as above, but with opacity</li>

<li>Optionally for hsb and hsl you could specify hue as a degree: “<samp>hsl(240deg,&nbsp;1,&nbsp;.5)</samp>” or, if you want to go fancy, “<samp>hsl(240°,&nbsp;1,&nbsp;.5)</samp>”</li>

</ul>

<h4>Usage</h4>

<preclass="javascript code"><code>paper.circle(100, 100, 20).attr({

fill: "hsb(0.6, 1, 0.75)",

stroke: "red"

});</code></pre>

<h3id="safari">

safari

</h3>

<p>

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

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>paper.safari();</code></pre>

<h3id="ninja-mode">

“Ninja Mode”

</h3>

<p>

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

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>(function (local_raphael) {

var paper = local_raphael(10, 10, 320, 200);

…

})(Raphael.ninja());

</code></pre>

<h3id="events">

Events

</h3>

<p>

You can attach events to elements by using element.node and your favourite library (<samp>$(circle.node).click(…)</samp>) or you can use built-in methods:

</p>

<h4>Usage</h4>

<preclass="javascript code"><code>element.click(function (event) {

this.attr({fill: "red"});

});

element.dblclick(function (event) {

this.attr({fill: "red"});

});

element.mousedown(function (event) {

this.attr({fill: "red"});

});

element.mousemove(function (event) {

this.attr({fill: "red"});

});

element.mouseout(function (event) {

this.attr({fill: "red"});

});

element.mouseover(function (event) {

this.attr({fill: "red"});

});

element.mouseup(function (event) {

this.attr({fill: "red"});

});

element.hover(function (event) {

this.attr({fill: "red"});

}, function (event) {

this.attr({fill: "black"});

}, overScope, outScope);</code></pre>

<p>

Second parameter is optional scope. By default handlers are run in the scope of the element. To unbind events use the same method names with “un” prefix, i.e. <samp>element.unclick(f);</samp>

</p>

<h3id="drag-n-drop">

Drag ’n’ Drop

</h3>

<p>

To make element “draggable” you need to call method <code>drag</code> on element.