git.roojs.org Git - raphael/blob - reference.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2    "http://www.w3.org/TR/html4/strict.dtd">
   3 <html lang="en">
   4     <head>
   5         <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6         <title>Raphaël Reference</title>
   7         <meta name="author" content="Dmitry Baranovskiy">
   8         <meta name="description" content="Vector Graphics JavaScript™ Library">
   9         <link rel="stylesheet" href="raphael.css" type="text/css" charset="utf-8" media="screen,projection">
  10         <link rel="stylesheet" type="text/css" media="print" href="/dmitry-print.css">
  11         <link rel="shortcut icon" href="/favicon16.png" type="image/x-icon">
  12         <link rel="apple-touch-icon" href="/favicon.png">
  13         <script src="../jquery.js" type="text/javascript" charset="utf-8"></script>
  14         <script src="../dmitry.js" type="text/javascript" charset="utf-8"></script>
  15     </head>
  16     <body class="raphael" id="raphael.dmitry.baranovskiy.com">
  17         <div id="header">
  18             <a href="http://twitter.com/statuses/user_timeline/17180567.atom" id="rss" name="rss">rss</a>
  19             <h1>
  20                 Raphaël—JavaScript Library
  21             </h1>
  22         </div>
  23         <div id="content">
  24             <div>
  25                 <div>
  26                     <div id="column-1">
  27                         <h2>Main Function</h2>
  28                         <h3 id="Raphael">
  29                             Raphael
  30                         </h3>
  31                         <p>
  32                             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.
  33                         </p>
  34                         <h4>Parameters</h4>
  35                         <ol>
  36                             <li>container <em>HTMLElement</em> or <em>string</em></li>
  37                             <li>width <em>number</em></li>
  38                             <li>height <em>number</em></li>
  39                         </ol>
  40                         <p>or</p>
  41                         <ol>
  42                             <li>x <em>number</em></li>
  43                             <li>y <em>number</em></li>
  44                             <li>width <em>number</em></li>
  45                             <li>height <em>number</em></li>
  46                         </ol>
  47                         <h4>Usage</h4>
  48                         <pre class="javascript code"><code>// Each of the following examples create a canvas that is 320px wide by 200px high
  49 // Canvas is created at the viewport's 10,50 coordinate
  50 var paper = Raphael(10, 50, 320, 200);
  51 // Canvas is created at the top left corner of the #notepad element (or its top right corner in dir="rtl" elements)
  52 var paper = Raphael(document.getElementById("notepad"), 320, 200);
  53 // Same as above
  54 var paper = Raphael("notepad", 320, 200);</code></pre>
  55                         <h2 id="Element">
  56                             Element’s generic methods
  57                         </h2>
  58                         <p>
  59                             Each object created on the canvas shares these same generic methods:
  60                         </p>
  61                         <h3 id="node">
  62                             node
  63                         </h3>
  64                         <p>
  65                             Gives you a reference to the DOM object, so you can assign event handlers or just mess around.
  66                         </p>
  67                         <h4>Usage</h4>
  68                         <pre class="javascript code"><code>var c = paper.circle(10, 10, 10); // draw a circle at coordinate 10,10 with radius of 10
  69 c.node.onclick = function () { c.attr("fill", "red"); };</code></pre>
  70                         <h3 id="rotate">
  71                             rotate
  72                         </h3>
  73                         <p>
  74                             Rotates the element by the given degree from either its 0,0 corner or its center point.
  75                         </p>
  76                         <h4>Parameters</h4>
  77                         <ol>
  78                             <li>degree <em>number</em> Degree of rotation (0 – 360°)</li>
  79                             <li>isAbsolute <em>boolean</em> [optional] Specifies the rotation point. Use <code>true</code> to rotate the element around its center point. The default, <code>false</code>, rotates the element from its 0,0 coordinate.</li>
  80                         </ol>
  81                         <h4>Usage</h4>
  82                         <pre class="javascript code"><code>var c = paper.circle(10, 10, 10);
  83 c.rotate(45);        // rotation is relative
  84 c.rotate(45, true);  // rotation is absolute</code></pre>
  85                         <h3 id="translate">
  86                             translate
  87                         </h3>
  88                         <p>
  89                             Moves the element around the canvas by the given distances.
  90                         </p>
  91                         <h4>Parameters</h4>
  92                         <ol>
  93                             <li>dx <em>number</em> Pixels of translation by X axis</li>
  94                             <li>dy <em>number</em> Pixels of translation by Y axis</li>
  95                         </ol>
  96                         <h4>Usage</h4>
  97                         <pre class="javascript code"><code>var c = paper.circle(10, 10, 10);
  98 c.translate(10, 10); // moves the circle down the canvas, in a diagonal line</code></pre>
  99                         <h3 id="scale">
 100                             scale
 101                         </h3>
 102                         <p>
 103                             Resizes the element by the given multiplier.
 104                         </p>
 105                         <h4>Parameters</h4>
 106                         <ol>
 107                             <li>Xtimes <em>number</em> Amount to scale horizontally</li>
 108                             <li>Ytimes <em>number</em> Amount to scale vertically</li>
 109                         </ol>
 110                         <h4>Usage</h4>
 111                         <pre class="javascript code"><code>var c = paper.circle(10, 10, 10);
 112 c.scale(1.5, 1.5); // makes the circle 1.5 times larger
 113 c.scale(.5, .75);  // makes the circle half as wide, and 75% as high</code></pre>
 114                         <h3 id="attr">
 115                             attr
 116                         </h3>
 117                         <p>
 118                             Sets the attributes of elements directly.
 119                         </p>
 120                         <h4>Parameters</h4>
 121                         <ol>
 122                             <li>attributeName <em>string</em></li>
 123                             <li>value <em>string</em></li>
 124                         </ol>
 125                         <p>or</p>
 126                         <ol>
 127                             <li>params <em>object</em></li>
 128                         </ol>
 129                         <h4>Possible parameters</h4>
 130                         <p>Please refer to the <a href="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>
 131                         <ul>
 132                             <li>cx <em>number</em></li>
 133                             <li>cy <em>number</em></li>
 134                             <li>fill <em>colour</em></li>
 135                             <li>fill-opacity <em>number</em></li>
 136                             <li>font <em>string</em></li>
 137                             <li>font-family <em>string</em></li>
 138                             <li>font-size <em>number</em></li>
 139                             <li>font-weight <em>string</em></li>
 140                             <li>gradient <em>object</em></li>
 141                             <li>height <em>number</em></li>
 142                             <li>opacity <em>number</em></li>
 143                             <li>path <em>pathString</em></li>
 144                             <li>r <em>number</em></li>
 145                             <li>rotation <em>number</em></li>
 146                             <li>rx <em>number</em></li>
 147                             <li>ry <em>number</em></li>
 148                             <li>scale <em>CSV</em></li>
 149                             <li>stroke <em>colour</em></li>
 150                             <li>stroke-dasharray <em>string</em> [“-”, “.”, “-.”, “-..”, “. ”, “- ”, “--”, “- .”, “--.”, “--..”]</li>
 151                             <li>stroke-linecap <em>string</em> [“butt”, “square”, “round”, “miter”]</li>
 152                             <li>stroke-linejoin <em>string</em> [“butt”, “square”, “round”, “miter”]</li>
 153                             <li>stroke-miterlimit <em>number</em></li>
 154                             <li>stroke-opacity <em>number</em></li>
 155                             <li>stroke-width <em>number</em></li>
 156                             <li>translation <em>CSV</em></li>
 157                             <li>width <em>number</em></li>
 158                             <li>x <em>number</em></li>
 159                             <li>y <em>number</em></li>
 160                         </ul>
 161                         <h4>Usage</h4>
 162                         <pre class="javascript code"><code>var c = paper.circle(10, 10, 10);
 163 c.attr("fill", "black");                              // using strings
 164 c.attr({fill: "#000", stroke: "#f00", opacity: 0.5}); // using params object</code></pre>
 165                         <h3 id="animate">
 166                             animate
 167                         </h3>
 168                         <p>
 169                             Linearly changes an attribute from its current value to its specified value in the given amount of milliseconds.
 170                         </p>
 171                         <h4>Parameters</h4>
 172                         <ol>
 173                             <li>newAttrs <em>object</em> A parameters object of the animation results.</li>
 174                             <li>ms <em>number</em> The duration of the animation, given in milliseconds.</li>
 175                             <li>callback <em>function</em> [optional]</li>
 176                         </ol>
 177                         <h4>Usage</h4>
 178                         <pre class="javascript code"><code>var c = paper.circle(10, 10, 10);</code>
 179 <code>c.animate({cx: 20, r: 20}, 2000);</code></pre>
 180                         <h3 id="getBBox">
 181                             getBBox
 182                         </h3>
 183                         <p>
 184                             Returns the dimensions of an element.
 185                         </p>
 186                         <h4>Usage</h4>
 187                         <pre class="javascript code"><code>var c = paper.circle(10, 10, 10);</code>
 188 <code>var width = c.getBBox().width;</code></pre>
 189                         <h3 id="toFront">
 190                             toFront
 191                         </h3>
 192                         <p>
 193                             Moves the element so it is the closest to the viewer’s eyes, on top of other elements.
 194                         </p>
 195                         <h4>Usage</h4>
 196                         <pre class="javascript code"><code>var c = paper.circle(10, 10, 10);</code>
 197 <code>c.toFront();</code></pre>
 198                         <h3 id="toBack">
 199                             toBack
 200                         </h3>
 201                         <p>
 202                             Moves the element so it is the furthest from the viewer’s eyes, behind other elements.
 203                         </p>
 204                         <h4>Usage</h4>
 205                         <pre class="javascript code"><code>var c = paper.circle(10, 10, 10);</code>
 206 <code>c.toBack();</code></pre>
 207                         <h3 id="insertBefore">
 208                             insertBefore
 209                         </h3>
 210                         <p>
 211                             Inserts current object before the given one.
 212                         </p>
 213                         <h4>Usage</h4>
 214                         <pre class="javascript code"><code>var r = paper.rect(10, 10, 10, 10);</code>
 215 <code>var c = paper.circle(10, 10, 10);</code>
 216 <code>c.insertBefore(r);</code></pre>
 217                         <h3 id="insertAfter">
 218                             insertAfter
 219                         </h3>
 220                         <p>
 221                             Inserts current object after the given one
 222                         </p>
 223                         <h4>Usage</h4>
 224                         <pre class="javascript code"><code>var r = paper.rect(10, 10, 10, 10);</code>
 225 <code>var c = paper.circle(10, 10, 10);</code>
 226 <code>r.insertAfter(c);</code></pre>
 227                         <h2>Graphic Primitives</h2>
 228                         <h3 id="circle">
 229                             circle
 230                         </h3>
 231                         <p>
 232                             Draws a circle.
 233                         </p>
 234                         <h4>Parameters</h4>
 235                         <ol>
 236                             <li>x <em>number</em> X coordinate of the centre</li>
 237                             <li>y <em>number</em> Y coordinate of the centre</li>
 238                             <li>r <em>number</em> radius</li>
 239                         </ol>
 240                         <h4>Usage</h4>
 241                         <pre class="javascript code"><code>var c = paper.circle(10, 10, 10);</code></pre>
 242                         <h3 id="rect">
 243                             rect
 244                         </h3>
 245                         <p>
 246                             Draws a rectangle.
 247                         </p>
 248                         <h4>Parameters</h4>
 249                         <ol>
 250                             <li>x <em>number</em> X coordinate of top left corner</li>
 251                             <li>y <em>number</em> Y coordinate of top left corner</li>
 252                             <li>width <em>number</em></li>
 253                             <li>height <em>number</em></li>
 254                             <li>r <em>number</em> [optional] radius for rounded corners, default is 0</li>
 255                         </ol>
 256                         <h4>Usage</h4>
 257                         <pre class="javascript code"><code>// regular rectangle</code>
 258 <code>var c = paper.rect(10, 10, 10, 10);</code>
 259 <code>// rectangle with rounded corners</code>
 260 <code>var c = paper.rect(10, 10, 100, 50, 10);</code></pre>
 261                         <h3 id="ellipse">
 262                             ellipse
 263                         </h3>
 264                         <p>
 265                             Draws an ellipse.
 266                         </p>
 267                         <h4>Parameters</h4>
 268                         <ol>
 269                             <li>x <em>number</em> X coordinate of the centre</li>
 270                             <li>y <em>number</em> X coordinate of the centre</li>
 271                             <li>rx <em>number</em> Horisontal radius</li>
 272                             <li>ry <em>number</em> Vertical radius</li>
 273                         </ol>
 274                         <h4>Usage</h4>
 275                         <pre class="javascript code"><code>var c = paper.ellipse(100, 100, 30, 40);</code></pre>
 276                         <h3 id="image">
 277                             image
 278                         </h3>
 279                         <p>
 280                             Embeds an image into the SVG/VML canvas.
 281                         </p>
 282                         <h4>Parameters</h4>
 283                         <ol>
 284                             <li>src <em>string</em> URI of the source image</li>
 285                             <li>x <em>number</em> X coordinate position</li>
 286                             <li>y <em>number</em> Y coordinate position</li>
 287                             <li>width <em>number</em> Width of the image</li>
 288                             <li>height <em>number</em> Height of the image</li>
 289                         </ol>
 290                         <h4>Usage</h4>
 291                         <pre class="javascript code"><code>var c = paper.image("apple.png", 10, 10, 100, 100);</code></pre>
 292                         <h3 id="path">
 293                             path
 294                         </h3>
 295                         <p>
 296                             Initialises path drawing. Typically, this function returns an empty <code>path</code> object and to draw paths you use its built-in methods like <code>lineTo</code> and <code>curveTo</code>. However, you can also specify a path literally by supplying the path data as a second argument.
 297                         </p>
 298                         <h4>Parameters</h4>
 299                         <ol>
 300                             <li>params <em>object</em> Attributes for the resulting path as described in the <code><a href="#attr">attr</a></code> reference.</li>
 301                             <li>pathString <em>string</em> [optional] Path data in <a href="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>
 302                         </ol>
 303                         <h4>Usage</h4>
 304                         <pre class="javascript code"><code>var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50); // draw a diagonal line
 305 var c = paper.path({stroke: "#036"}, "M 10 10 L 50 50");            // same</code></pre>
 306                         <h2>Path Methods</h2>
 307                         <h3 id="absolutely">
 308                             absolutely
 309                         </h3>
 310                         <p>
 311                             Sets a trigger to count all following units as absolute ones, unless said otherwise. (This is on by default.)
 312                         </p>
 313                         <h4>Usage</h4>
 314                         <pre class="javascript code"><code>var c = paper.path({stroke: "#036"}).absolutely()
 315     .moveTo(10, 10).lineTo(50, 50);</code></pre>
 316                         <h3 id="relatively">
 317                             relatively
 318                         </h3>
 319                         <p>
 320                             Sets a trigger to count all following units as relative ones, unless said otherwise.
 321                         </p>
 322                         <h4>Usage</h4>
 323                         <pre class="javascript code"><code>var c = paper.path({stroke: "#036"}).relatively()
 324     .moveTo(10, 10).lineTo(50, 50);</code></pre>
 325                         <h3 id="moveTo">
 326                             moveTo
 327                         </h3>
 328                         <p>
 329                             Moves the drawing point to the given coordinates.
 330                         </p>
 331                         <h4>Parameters</h4>
 332                         <ol>
 333                             <li>x <em>number</em> X coordinate</li>
 334                             <li>y <em>number</em> Y coordinate</li>
 335                         </ol>
 336                         <h4>Usage</h4>
 337                         <pre class="javascript code"><code>// Begins drawing the path at coordinate 10,10
 338 var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);</code></pre>
 339                         <h3 id="lineTo">
 340                             lineTo
 341                         </h3>
 342                         <p>
 343                             Draws a straight line to the given coordinates.
 344                         </p>
 345                         <h4>Parameters</h4>
 346                         <ol>
 347                             <li>x <em>number</em> X coordinate</li>
 348                             <li>y <em>number</em> Y coordinate</li>
 349                         </ol>
 350                         <h4>Usage</h4>
 351                         <pre class="javascript code"><code>// Draws a line starting from 10,10 to 50,50
 352 var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);</code></pre>
 353                         <h3 id="cplineTo">
 354                             cplineTo
 355                         </h3>
 356                         <p>
 357                             Draws a curved line to the given coordinates. The line will have horizontal anchors on start and on finish.
 358                         </p>
 359                         <h4>Parameters</h4>
 360                         <ol>
 361                             <li>x <em>number</em></li>
 362                             <li>y <em>number</em></li>
 363                             <li>width <em>number</em></li>
 364                         </ol>
 365                         <h4>Usage</h4>
 366                         <pre class="javascript code"><code>var c = paper.path({stroke: "#036"}).moveTo(10, 10).cplineTo(50, 50);</code></pre>
 367                         <h3 id="curveTo">
 368                             curveTo
 369                         </h3>
 370                         <p>
 371                             Draws a bicubic curve to the given coordinates.
 372                         </p>
 373                         <h4>Parameters</h4>
 374                         <ol>
 375                             <li>x1 <em>number</em></li>
 376                             <li>y1 <em>number</em></li>
 377                             <li>x2 <em>number</em></li>
 378                             <li>y2 <em>number</em></li>
 379                             <li>x3 <em>number</em></li>
 380                             <li>y3 <em>number</em></li>
 381                         </ol>
 382                         <h4>Usage</h4>
 383                         <pre class="javascript code"><code>var c = paper.path({stroke: "#036"}).moveTo(10, 10).curveTo(10, 15, 45, 45, 50, 50);</code></pre>
 384                         <h3 id="qcurveTo">
 385                             qcurveTo
 386                         </h3>
 387                         <p>
 388                             Draws a quadratic curve to the given coordinates.
 389                         </p>
 390                         <h4>Parameters</h4>
 391                         <ol>
 392                             <li>x1 <em>number</em></li>
 393                             <li>y1 <em>number</em></li>
 394                             <li>x2 <em>number</em></li>
 395                             <li>y2 <em>number</em></li>
 396                         </ol>
 397                         <h4>Usage</h4>
 398                         <pre class="javascript code"><code>var c = paper.path({stroke: "#036"}).moveTo(10, 10).curveTo(10, 15, 45, 45, 50, 50);</code></pre>
 399                         <h3 id="addRoundedCorner">
 400                             addRoundedCorner
 401                         </h3>
 402                         <p>
 403                             Draws a quarter of a circle from the current drawing point.
 404                         </p>
 405                         <h4>Parameters</h4>
 406                         <ol>
 407                             <li>r <em>number</em></li>
 408                             <li>dir <em>string</em> Two-letter directional instruction, as described below.</li>
 409                         </ol>
 410                         <h4>Possible <code>dir</code> values</h4>
 411                         <dl>
 412                             <dt>lu</dt>
 413                             <dd>left up</dd>
 414                             <dt>ld</dt>
 415                             <dd>left down</dd>
 416                             <dt>ru</dt>
 417                             <dd>right up</dd>
 418                             <dt>rd</dt>
 419                             <dd>right down</dd>
 420                             <dt>ur</dt>
 421                             <dd>up right</dd>
 422                             <dt>ul</dt>
 423                             <dd>up left</dd>
 424                             <dt>dr</dt>
 425                             <dd>down right</dd>
 426                             <dt>dl</dt>
 427                             <dd>down left</dd>
 428                         </dl>
 429                         <h4>Usage</h4>
 430                         <pre class="javascript code"><code>var c = paper.path({stroke: "#036"}).moveTo(10, 10).addRoundedCorner(10, "rd");</code></pre>
 431                         <h3 id="andClose">
 432                             andClose
 433                         </h3>
 434                         <p>
 435                             Closes the path being drawn.
 436                         </p>
 437                         <h4>Usage</h4>
 438                         <pre class="javascript code"><code>var c = paper.path({stroke: "#036"}).moveTo(10, 10).andClose();</code></pre>
 439                     </div>
 440                     <div id="column-2">
 441                         <h2>
 442                             <a href="index.html">Home</a>
 443                         </h2>
 444                         <h2>
 445                             Contents
 446                         </h2>
 447                         <ul id="contents">
 448                             <li>
 449                                 <a href="reference.html#Raphael"><code>Raphael</code></a>
 450                             </li>
 451                             <li>
 452                                 <a href="reference.html#node"><code>node</code></a>
 453                             </li>
 454                             <li>
 455                                 <a href="reference.html#rotate"><code>rotate</code></a>
 456                             </li>
 457                             <li>
 458                                 <a href="reference.html#translate"><code>translate</code></a>
 459                             </li>
 460                             <li>
 461                                 <a href="reference.html#scale"><code>scale</code></a>
 462                             </li>
 463                             <li>
 464                                 <a href="reference.html#attr"><code>attr</code></a>
 465                             </li>
 466                             <li>
 467                                 <a href="reference.html#attr"><code>animate</code></a>
 468                             </li>
 469                             <li>
 470                                 <a href="reference.html#getBBox"><code>getBBox</code></a>
 471                             </li>
 472                             <li>
 473                                 <a href="reference.html#toFront"><code>toFront</code></a>
 474                             </li>
 475                             <li>
 476                                 <a href="reference.html#toBack"><code>toBack</code></a>
 477                             </li>
 478                             <li>
 479                                 <a href="reference.html#circle"><code>circle</code></a>
 480                             </li>
 481                             <li>
 482                                 <a href="reference.html#rect"><code>rect</code></a>
 483                             </li>
 484                             <li>
 485                                 <a href="reference.html#ellipse"><code>ellipse</code></a>
 486                             </li>
 487                             <li>
 488                                 <a href="reference.html#image"><code>image</code></a>
 489                             </li>
 490                             <li>
 491                                 <a href="reference.html#path"><code>path</code></a>
 492                                 <ul>
 493                                     <li>
 494                                         <a href="reference.html#absolutely"><code>absolutely</code></a>
 495                                     </li>
 496                                     <li>
 497                                         <a href="reference.html#relatively"><code>relatively</code></a>
 498                                     </li>
 499                                     <li>
 500                                         <a href="reference.html#moveTo"><code>moveTo</code></a>
 501                                     </li>
 502                                     <li>
 503                                         <a href="reference.html#lineTo"><code>lineTo</code></a>
 504                                     </li>
 505                                     <li>
 506                                         <a href="reference.html#cplineTo"><code>cplineTo</code></a>
 507                                     </li>
 508                                     <li>
 509                                         <a href="reference.html#curveTo"><code>curveTo</code></a>
 510                                     </li>
 511                                     <li>
 512                                         <a href="reference.html#qcurveTo"><code>qcurveTo</code></a>
 513                                     </li>
 514                                     <li>
 515                                         <a href="reference.html#addRoundedCorner"><code>addRoundedCorner</code></a>
 516                                     </li>
 517                                     <li>
 518                                         <a href="reference.html#andClose"><code>andClose</code></a>
 519                                     </li>
 520                                 </ul>
 521                             </li>
 522                         </ul>
 523                     </div>
 524                     <div  id="footer">
 525                         <h3 id="copyright">
 526                             <a href="http://creativecommons.org/licenses/by-sa/3.0/" title="Creative Commons Attribution-ShareAlike 3.0 Unported" rel="license">Some Rights Reserved</a> by <a href="http://dmitry.baranovskiy.com/">Dmitry Baranovskiy</a>
 527                         </h3>
 528                         <h3 id="font">
 529                             A font by <a href="http://www.exljbris.nl">Jos Buivenga</a> | Logo by <a href="http://wasabicube.com/">Wasabicube</a>
 530                         </h3>
 531                     </div>
 532                 </div>
 533             </div>
 534         </div>
 535         <script type="text/javascript">
 536         var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
 537         document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
 538         </script>
 539         <script type="text/javascript">
 540         var pageTracker = _gat._getTracker("UA-616618-3");
 541         pageTracker._trackPageview();
 542         </script>
 543     </body>
 544 </html>