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