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](http://www.w3.org/TR/SVG/) and [VML](http://msdn.microsoft.com/en-us/library/bb264280.aspx) (a mostly equivalent implementation for Internet Explorer) as a base for drawing 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 cross-browser compatible and easy to do.
  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 10,10 with radius of 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 center 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. (Not all attributes can be animated.)
 175 2. ms number The duration of the animation, given in milliseconds.
 176 3. callback function \[optional\]
 177
 178 ##### Attributes that can be animated
 179
 180 The `newAttrs` parameter accepts an object whose properties are the attributes to animate. However, not all attributes listed in the `attr` method reference can be animated. The following is a list of those properties that can be animated:
 181
 182 * cx number
 183 * cy number
 184 * fill colour
 185 * fill-opacity number
 186 * font-size number
 187 * height number
 188 * opacity number
 189 * path pathString
 190 * r number
 191 * rotation number
 192 * rx number
 193 * ry number
 194 * scale CSV
 195 * stroke colour
 196 * stroke-opacity number
 197 * stroke-width number
 198 * translation CSV
 199 * width number
 200 * x number
 201 * y number
 202
 203 ##### Usage
 204
 205     var c = paper.circle(10, 10, 10);
 206     c.animate({cx: 20, r: 20}, 2000);
 207
 208 #### getBBox
 209
 210 Returns the dimensions of an element.
 211
 212 ##### Usage
 213
 214     var c = paper.circle(10, 10, 10);
 215     var width = c.getBBox().width;
 216
 217 #### toFront
 218
 219 Moves the element so it is the closest to the viewer’s eyes, on top of other elements.
 220
 221 ##### Usage
 222
 223     var c = paper.circle(10, 10, 10);
 224     c.toFront();
 225
 226 #### toBack
 227
 228 Moves the element so it is the furthest from the viewer’s eyes, behind other elements.
 229
 230 ##### Usage
 231
 232     var c = paper.circle(10, 10, 10);
 233     c.toBack();
 234
 235 #### insertBefore
 236
 237 Inserts current object before the given one
 238
 239 ##### Usage
 240
 241     var r = paper.rect(10, 10, 10, 10);
 242     var c = paper.circle(10, 10, 10);
 243     c.insertBefore(r);
 244
 245 #### insertAfter
 246
 247 Inserts current object after the given one
 248
 249 ##### Usage
 250
 251     var c = paper.circle(10, 10, 10);
 252     var r = paper.rect(10, 10, 10, 10);
 253     c.insertAfter(r);
 254
 255 ### Graphic Primitives
 256
 257 #### circle
 258
 259 Draws a circle.
 260
 261 ##### Parameters
 262
 263 1. x number X coordinate of the centre
 264 2. y number Y coordinate of the centre
 265 3. r number radius
 266
 267 ##### Usage
 268
 269     var c = paper.circle(10, 10, 10);
 270
 271 #### rect
 272
 273 Draws a rectangle.
 274
 275 ##### Parameters
 276
 277 1. x number X coordinate of top left corner
 278 2. y number Y coordinate of top left corner
 279 3. width number
 280 4. height number
 281 5. r number \[optional\] radius for rounded corners, default is 0
 282
 283 ##### Usage
 284
 285     // regular rectangle
 286     var c = paper.rect(10, 10, 10, 10);
 287     // rectangle with rounded corners
 288     var c = paper.rect(10, 10, 100, 50, 10);
 289
 290 #### ellipse
 291
 292 Draws an ellipse.
 293
 294 ##### Parameters
 295
 296 1. x number X coordinate of the centre
 297 2. y number X coordinate of the centre
 298 3. rx number Horisontal radius
 299 4. ry number Vertical radius
 300
 301 ##### Usage
 302
 303     var c = paper.ellipse(100, 100, 30, 40);
 304
 305 #### image
 306
 307 Embeds an image into the SVG/VML canvas.
 308
 309 ##### Parameters
 310
 311 1. src string URI of the source image
 312 2. x number X coordinate position
 313 3. y number Y coordinate position
 314 4. width number Width of the image
 315 5. height number Height of the image
 316
 317 ##### Usage
 318
 319     var c = paper.image("apple.png", 10, 10, 100, 100);
 320
 321 #### text
 322
 323 Draws a text string.
 324
 325 ##### Parameters
 326
 327 1. x number X coordinate position
 328 2. y number Y coordinate position
 329 3. text string The text string to draw.
 330
 331 ##### Usage
 332
 333     var t = paper.text(10, 10, "Look mom, I'm scalable!");
 334
 335 #### path
 336
 337 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.
 338
 339 ##### Parameters
 340
 341 1. params object Attributes for the resulting path as described in the `attr` reference.
 342 2. pathString string \[optional\] Path data in [SVG path string format](http://www.w3.org/TR/SVG/paths.html#PathData).
 343
 344 ##### Usage
 345
 346     var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50); // draw a diagonal line
 347     var c = paper.path({stroke: "#036"}, "M 10 10 L 50 50");            // same
 348
 349 ### Path Methods
 350
 351 #### absolutely
 352
 353 Sets a trigger to count all following units as absolute ones, unless said otherwise. (This is on by default.)
 354
 355 ##### Usage
 356
 357     var c = paper.path({stroke: "#036"}).absolutely()
 358         .moveTo(10, 10).lineTo(50, 50);
 359
 360 #### relatively
 361
 362 Sets a trigger to count all following units as relative ones, unless said otherwise.
 363
 364 ##### Usage
 365
 366     var c = paper.path({stroke: "#036"}).relatively()
 367         .moveTo(10, 10).lineTo(50, 50);
 368
 369 #### moveTo
 370
 371 Moves the drawing point to the given coordinates.
 372
 373 ##### Parameters
 374
 375 1. x number X coordinate
 376 2. y number Y coordinate
 377
 378 ##### Usage
 379
 380     // Begins drawing the path at coordinate 10,10
 381     var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);
 382
 383 #### lineTo
 384
 385 Draws a straight line to the given coordinates.
 386
 387 ##### Parameters
 388
 389 1. x number X coordinate
 390 2. y number Y coordinate
 391
 392 ##### Usage
 393
 394     // Draws a line starting from 10,10 to 50,50
 395     var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);
 396
 397 #### cplineTo
 398
 399 Draws a curved line to the given coordinates. The line will have horizontal anchors on start and on finish.
 400
 401 ##### Parameters
 402
 403 1. x number
 404 2. y number
 405 3. width number
 406
 407 ##### Usage
 408
 409     var c = paper.path({stroke: "#036"}).moveTo(10, 10).cplineTo(50, 50);
 410
 411 #### curveTo
 412
 413 Draws a bicubic curve to the given coordinates.
 414
 415 ##### Parameters
 416
 417 1. x1 number
 418 2. y1 number
 419 3. x2 number
 420 4. y2 number
 421 5. x3 number
 422 6. y3 number
 423
 424 ##### Usage
 425
 426     var c = paper.path({stroke: "#036"}).moveTo(10, 10).curveTo(10, 15, 45, 45, 50, 50);
 427
 428 #### qcurveTo
 429
 430 Draws a quadratic curve to the given coordinates.
 431
 432 ##### Parameters
 433
 434 1. x1 number
 435 2. y1 number
 436 3. x2 number
 437 4. y2 number
 438
 439 ##### Usage
 440
 441     var c = paper.path({stroke: "#036"}).moveTo(10, 10).curveTo(10, 15, 45, 45, 50, 50);
 442
 443 #### addRoundedCorner
 444
 445 Draws a quarter of a circle from the current drawing point.
 446
 447 ##### Parameters
 448
 449 1. r number
 450 2. dir string Two-letter directional instruction, as described below.
 451
 452 Possible dir values
 453
 454 * dl: down left
 455 * dr: down right
 456 * ld: left down
 457 * lu: left up
 458 * rd: right down
 459 * ru: right up
 460 * ul: up left
 461 * ur: up right
 462
 463 ##### Usage
 464
 465     var c = paper.path({stroke: "#036"}).moveTo(10, 10).addRoundedCorner(10, "rd");
 466
 467 #### andClose
 468
 469 Closes the path being drawn.
 470
 471 ##### Usage
 472
 473     var c = paper.path({stroke: "#036"}).moveTo(10, 10).andClose();
 474
 475 ## License
 476
 477 [http://www.opensource.org/licenses/mit-license.php](http://www.opensource.org/licenses/mit-license.php)
 478
 479 Copyright (c) 2008 Dmitry Baranovskiy ([http://raphaeljs.com](http://raphaeljs.com/))