git.roojs.org Git - raphael/blob - README.markdown

   1 # Raphaël
   2
   3 Cross-browser vector graphics the easy way.
   4
   5 ## What is it?
   6
   7 Raphaël is a small JavaScript library that should simplify your work with vector graphics on the web. If you want to create your own specific chart or image crop and rotate widget, for example, you can achieve it simply and easily with this library.
   8
   9 Raphaël uses the SVG W3C Recommendation and VML (mostly equivalent Internet Explorer implementation) as a base for creating graphics. This means every graphical object you create is also a DOM object, so you can attach JavaScript event handlers or modify them later. Raphaël’s goal is to provide an adapter that will make drawing vector art (similar to Flash) compatible cross-browser and easy.
  10
  11 Raphaël currently supports Firefox 3.0+, Safari 3.0+, Opera 9.5+ and Internet Explorer 6.0+.
  12
  13 ## How to use it?
  14
  15 Download and include ‘raphael.js’ (or, ‘raphael-packed.js’ for a minimized version) into your HTML page. When it’s loaded, use it as simply as:
  16
  17     // Creates canvas 320 × 200 at 10, 50
  18     var paper = Raphael(10, 50, 320, 200);
  19     // Creates circle at x = 50, y = 40, with radius 10
  20     var circle = paper.circle(50, 40, 10);
  21     // Sets the fill attribute of the circle to red (#f00)
  22     circle.attr("fill", "#f00");
  23     // Sets the stroke attribute of the circle to white (#fff)
  24     circle.attr("stroke", "#fff");
  25
  26 ## Reference
  27
  28 This section provides a function reference for the Raphaël JavaScript library.
  29
  30 ### Main Function
  31
  32 #### Raphael
  33
  34 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.
  35
  36 ##### Parameters
  37
  38 1. container HTMLElement or string
  39 2. width number
  40 3. height number
  41
  42 or
  43
  44 1. x number
  45 2. y number
  46 3. width number
  47 4. height number
  48
  49 ##### Usage
  50
  51     // Each of the following examples create a canvas that is 320px wide by 200px high
  52     // Canvas is created at the viewport’s 10,50 coordinate
  53     var paper = Raphael(10, 50, 320, 200);
  54     // Canvas is created at the top left corner of the #notepad element (or its top right corner in dir="rtl" elements)
  55     var paper = Raphael(document.getElementById("notepad"), 320, 200);
  56     // Same as above
  57     var paper = Raphael("notepad", 320, 200);
  58
  59 ### Element’s generic methods
  60
  61 Each object created on the canvas shares these same generic methods:
  62
  63 #### node
  64
  65 Gives you a reference to the DOM object, so you can assign event handlers or just mess around.
  66
  67 ##### Usage
  68
  69     var c = paper.circle(10, 10, 10); // draw a circle at coordinate 0,0 with radius 10
  70     c.node.onclick = function () { c.attr("fill", "red"); };
  71
  72 #### rotate
  73
  74 Rotates the element by the given degree from either its 0,0 corner or its centre point.
  75
  76 ##### Parameters
  77
  78 1. degree number Degree of rotation (0 – 360°)
  79 2. isAbsolute boolean \[optional\] Specifies the rotation point. Use ‘true’ to rotate the element around its centre point. The default, ‘false’, rotates the element from its 0,0 coordinate.
  80
  81 ##### Usage
  82
  83     var c = paper.circle(10, 10, 10);
  84     c.rotate(45);        // rotation is relative
  85     c.rotate(45, true);  // rotation is absolute
  86
  87 #### translate
  88
  89 Moves the element around the canvas by the given distances.
  90
  91 ##### Parameters
  92
  93 1. dx number Pixels of translation by X axis
  94 2. dy number Pixels of translation by Y axis
  95
  96 ##### Usage
  97
  98     var c = paper.circle(10, 10, 10);
  99     c.translate(10, 10); // moves the circle down the canvas, in a diagonal line
 100
 101 #### scale
 102
 103 Resizes the element by the given multiplier.
 104
 105 ##### Parameters
 106
 107 1. Xtimes number Amount to scale horizontally
 108 2. Ytimes number Amount to scale vertically
 109
 110 ##### Usage
 111
 112     var c = paper.circle(10, 10, 10);
 113     c.scale(1.5, 1.5); // makes the circle 1.5 times larger
 114     c.scale(.5, .75);  // makes the circle half as wide, and 75% as high
 115
 116 #### attr
 117
 118 Sets the attributes of elements directly.
 119
 120 ##### Parameters
 121
 122 1. attributeName string
 123 2. value string
 124
 125 or
 126
 127 1. params object
 128
 129 ###### Possible parameters
 130
 131 Please refer to the [SVG specification](http://www.w3.org/TR/SVG/) for an explanation of these parameters.
 132
 133 * cx number
 134 * cy number
 135 * fill colour
 136 * fill-opacity number
 137 * font string
 138 * font-family string
 139 * font-size number
 140 * font-weight string
 141 * gradient object
 142 * height number
 143 * opacity number
 144 * path pathString
 145 * r number
 146 * rotation number
 147 * rx number
 148 * ry number
 149 * scale CSV
 150 * stroke colour
 151 * stroke-dasharray string [“-”, “.”, “-.”, “-..”, “. ”, “- ”, “--”, “- .”, “--.”, “--..”]
 152 * stroke-linecap string [“butt”, “square”, “round”, “miter”]
 153 * stroke-linejoin string [“butt”, “square”, “round”, “miter”]
 154 * stroke-miterlimit number
 155 * stroke-opacity number
 156 * stroke-width number
 157 * translation CSV
 158 * width number
 159 * x number
 160 * y number
 161
 162 ##### Usage
 163
 164     var c = paper.circle(10, 10, 10);
 165     c.attr("fill", "black");                              // using strings
 166     c.attr({fill: "#000", stroke: "#f00", opacity: 0.5}); // using params object
 167
 168 #### animate
 169
 170 Linearly changes an attribute from its current value to its specified value in the given amount of milliseconds.
 171
 172 ##### Parameters
 173
 174 1. newAttrs object A parameters object of the animation results.
 175 2. ms number The duration of the animation, given in milliseconds.
 176 3. callback function \[optional\]
 177
 178 ##### Usage
 179
 180     var c = paper.circle(10, 10, 10);
 181     c.animate({cx: 20, r: 20}, 2000);
 182
 183 #### getBBox
 184
 185 Returns the dimensions of an element.
 186
 187 ##### Usage
 188
 189     var c = paper.circle(10, 10, 10);
 190     var width = c.getBBox().width;
 191
 192 #### toFront
 193
 194 Moves the element so it is the closest to the viewer’s eyes, on top of other elements.
 195
 196 ##### Usage
 197
 198     var c = paper.circle(10, 10, 10);
 199     c.toFront();
 200
 201 #### toBack
 202
 203 Moves the element so it is the furthest from the viewer’s eyes, behind other elements.
 204
 205 ##### Usage
 206
 207     var c = paper.circle(10, 10, 10);
 208     c.toBack();
 209
 210 #### insertBefore
 211
 212 Inserts current object before the given one
 213
 214 ##### Usage
 215
 216     var r = paper.rect(10, 10, 10, 10);
 217     var c = paper.circle(10, 10, 10);
 218     c.insertBefore(r);
 219
 220 #### insertAfter
 221
 222 Inserts current object after the given one
 223
 224 ##### Usage
 225
 226     var c = paper.circle(10, 10, 10);
 227     var r = paper.rect(10, 10, 10, 10);
 228     c.insertAfter(r);
 229
 230 ### Graphic Primitives
 231
 232 #### circle
 233
 234 Draws a circle.
 235
 236 ##### Parameters
 237
 238 1. x number X coordinate of the centre
 239 2. y number Y coordinate of the centre
 240 3. r number radius
 241
 242 ##### Usage
 243
 244     var c = paper.circle(10, 10, 10);
 245
 246 #### rect
 247
 248 Draws a rectangle.
 249
 250 ##### Parameters
 251
 252 1. x number X coordinate of top left corner
 253 2. y number Y coordinate of top left corner
 254 3. width number
 255 4. height number
 256 5. r number \[optional\] radius for rounded corners, default is 0
 257
 258 ##### Usage
 259
 260     // regular rectangle
 261     var c = paper.rect(10, 10, 10, 10);
 262     // rectangle with rounded corners
 263     var c = paper.rect(10, 10, 100, 50, 10);
 264
 265 #### ellipse
 266
 267 Draws an ellipse.
 268
 269 ##### Parameters
 270
 271 1. x number X coordinate of the centre
 272 2. y number X coordinate of the centre
 273 3. rx number Horisontal radius
 274 4. ry number Vertical radius
 275
 276 ##### Usage
 277
 278     var c = paper.ellipse(100, 100, 30, 40);
 279
 280 #### image
 281
 282 Embeds an image into the SVG/VML canvas.
 283
 284 ##### Parameters
 285
 286 1. src string URI of the source image
 287 2. x number X coordinate position
 288 3. y number Y coordinate position
 289 4. width number Width of the image
 290 5. height number Height of the image
 291
 292 ##### Usage
 293
 294     var c = paper.image("apple.png", 10, 10, 100, 100);
 295
 296 #### path
 297
 298 Initialises path drawing. Typically, this function returns an empty ‘path’ object and to draw paths you use its built-in methods like ‘lineTo’ and ‘curveTo’. However, you can also specify a path literally by supplying the path data as a second argument.
 299
 300 ##### Parameters
 301
 302 1. params object Attributes for the resulting path as described in the ‘attr’ reference.
 303 2. pathString string \[optional\] Path data in [SVG path string format](http://www.w3.org/TR/SVG/paths.html#PathData).
 304
 305 ##### Usage
 306
 307     var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50); // draw a diagonal line
 308     var c = paper.path({stroke: "#036"}, "M 10 10 L 50 50");            // same
 309
 310 ### Path Methods
 311
 312 #### absolutely
 313
 314 Sets a trigger to count all following units as absolute ones, unless said otherwise. (This is on by default.)
 315
 316 ##### Usage
 317
 318     var c = paper.path({stroke: "#036"}).absolutely()
 319         .moveTo(10, 10).lineTo(50, 50);
 320
 321 #### relatively
 322
 323 Sets a trigger to count all following units as relative ones, unless said otherwise.
 324
 325 ##### Usage
 326
 327     var c = paper.path({stroke: "#036"}).relatively()
 328         .moveTo(10, 10).lineTo(50, 50);
 329
 330 #### moveTo
 331
 332 Moves the drawing point to the given coordinates.
 333
 334 ##### Parameters
 335
 336 1. x number X coordinate
 337 2. y number Y coordinate
 338
 339 ##### Usage
 340
 341     // Begins drawing the path at coordinate 10,10
 342     var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);
 343
 344 #### lineTo
 345
 346 Draws a straight line to the given coordinates.
 347
 348 ##### Parameters
 349
 350 1. x number X coordinate
 351 2. y number Y coordinate
 352
 353 ##### Usage
 354
 355     // Draws a line starting from 10,10 to 50,50
 356     var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);
 357
 358 #### cplineTo
 359
 360 Draws a curved line to the given coordinates. The line will have horizontal anchors on start and on finish.
 361
 362 ##### Parameters
 363
 364 1. x number
 365 2. y number
 366 3. width number
 367
 368 ##### Usage
 369
 370     var c = paper.path({stroke: "#036"}).moveTo(10, 10).cplineTo(50, 50);
 371
 372 #### curveTo
 373
 374 Draws a bicubic curve to the given coordinates.
 375
 376 ##### Parameters
 377
 378 1. x1 number
 379 2. y1 number
 380 3. x2 number
 381 4. y2 number
 382 5. x3 number
 383 6. y3 number
 384
 385 ##### Usage
 386
 387   var c = paper.path({stroke: "#036"}).moveTo(10, 10).curveTo(10, 15, 45, 45, 50, 50);
 388
 389 #### qcurveTo
 390
 391 Draws a quadratic curve to the given coordinates.
 392
 393 ##### Parameters
 394
 395 1. x1 number
 396 2. y1 number
 397 3. x2 number
 398 4. y2 number
 399
 400 ##### Usage
 401
 402     var c = paper.path({stroke: "#036"}).moveTo(10, 10).curveTo(10, 15, 45, 45, 50, 50);
 403
 404 #### addRoundedCorner
 405
 406 Draws a quarter of a circle from the current drawing point.
 407
 408 ##### Parameters
 409
 410 1. r number
 411 2. dir string two letters direction
 412
 413 Possible dir values
 414
 415 * dl: down left
 416 * dr: down right
 417 * ld: left down
 418 * lu: left up
 419 * rd: right down
 420 * ru: right up
 421 * ul: up left
 422 * ur: up right
 423
 424 ##### Usage
 425
 426     var c = paper.path({stroke: "#036"}).moveTo(10, 10).addRoundedCorner(10, "rd");
 427
 428 #### andClose
 429
 430 Closes the path being drawn.
 431
 432 ##### Usage
 433
 434     var c = paper.path({stroke: "#036"}).moveTo(10, 10).andClose();
 435
 436 ## License
 437
 438 [http://www.opensource.org/licenses/mit-license.php](http://www.opensource.org/licenses/mit-license.php)
 439
 440 Copyright (c) 2008 Dmitry Baranovskiy (http://raphaeljs.com)