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 #### getBBox
 173
 174 Returns dimensions of given element.
 175
 176 ##### Usage
 177
 178     var c = paper.circle(10, 10, 10);
 179     var width = c.getBBox().width;
 180
 181 #### toFront
 182
 183 Moves element to front in hierarchy.
 184
 185 ##### Usage
 186
 187     var c = paper.circle(10, 10, 10);
 188     c.toFront();
 189
 190 #### toBack
 191
 192 Moves element to back in hierarchy.
 193
 194 ##### Usage
 195
 196     var c = paper.circle(10, 10, 10);
 197     c.toBack();
 198
 199 ### Graphic Primitives
 200
 201 #### circle
 202
 203 Creates circle.
 204
 205 ##### Parameters
 206
 207    1. x number X coordinate of the centre
 208    2. y number Y coordinate of the centre
 209    3. r number radius
 210
 211 ##### Usage
 212
 213     var c = paper.circle(10, 10, 10);
 214
 215 #### rect
 216
 217 Creates rectangle.
 218
 219 ##### Parameters
 220
 221    1. x number X coordinate of top left corner
 222    2. y number Y coordinate of top left corner
 223    3. width number
 224    4. height number
 225    5. r number [optional] radius for rounded corners, default is 0
 226
 227 ##### Usage
 228
 229     // regular rectangle
 230     var c = paper.rect(10, 10, 10, 10);
 231     // rounded rectangle
 232     var c = paper.rect(10, 10, 100, 50, 10);
 233
 234 #### ellipse
 235
 236 Creates an ellipse.
 237
 238 ##### Parameters
 239
 240    1. x number X coordinate of the centre
 241    2. y number X coordinate of the centre
 242    3. rx number Horisontal radius
 243    4. ry number Vertical radius
 244
 245 ##### Usage
 246
 247     var c = paper.ellipse(100, 100, 30, 40);
 248
 249 #### image
 250
 251 Embeds an image in SVG/VML area.
 252
 253 ##### Parameters
 254
 255    1. src string
 256    2. x number
 257    3. y number
 258    4. width number
 259    5. height number
 260
 261 ##### Usage
 262
 263     var c = paper.image("apple.png", 10, 10, 100, 100);
 264
 265 #### path
 266
 267 Initialise path drawing. In general case this function returns empty path object. To draw path use built in methods like lineTo and curveTo.
 268
 269 ##### Parameters
 270
 271    1. params object Similar to object for attr method
 272    2. pathString string [optional] path in SVG path string format. See SVG documentation.
 273
 274 ##### Usage
 275
 276     var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);
 277
 278 ### Path Methods
 279
 280 #### absolutely
 281
 282 Sets trigger to count all following units as absolute ones, unless said otherwise. [on by default]
 283
 284 Usage
 285
 286     var c = paper.path({stroke: "#036"}).absolutely()
 287         .moveTo(10, 10).lineTo(50, 50);
 288
 289 #### relatively
 290
 291 Sets trigger to count all following units as relative ones, unless said otherwise.
 292
 293 ##### Usage
 294
 295     var c = paper.path({stroke: "#036"}).relatively()
 296         .moveTo(10, 10).lineTo(50, 50);
 297
 298 #### moveTo
 299
 300 Moves drawing point to given coordinates.
 301
 302 ##### Parameters
 303
 304    1. x number
 305    2. y number
 306
 307 ##### Usage
 308
 309     var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);
 310
 311 #### lineTo
 312
 313 Draws straight line to given coordinates.
 314
 315 ##### Parameters
 316
 317    1. x number
 318    2. y number
 319
 320 ##### Usage
 321
 322     var c = paper.path({stroke: "#036"}).moveTo(10, 10).lineTo(50, 50);
 323
 324 #### cplineTo
 325
 326 Draws curved line to given coordinates. Line will have horizontal anchors on start and on finish.
 327
 328 ##### Parameters
 329
 330    1. x number
 331    2. y number
 332    3. width number
 333
 334 ##### Usage
 335
 336     var c = paper.path({stroke: "#036"}).moveTo(10, 10).cplineTo(50, 50);
 337
 338 #### curveTo
 339
 340 Draws bicubic curve to given coordinates.
 341
 342 ##### Parameters
 343
 344    1. x1 number
 345    2. y1 number
 346    3. x2 number
 347    4. y2 number
 348    5. x3 number
 349    6. y3 number
 350
 351 ##### Usage
 352
 353   var c = paper.path({stroke: "#036"}).moveTo(10, 10).curveTo(10, 15, 45, 45, 50, 50);
 354
 355 #### qcurveTo
 356
 357 Draws quadratic curve to given coordinates.
 358
 359 ##### Parameters
 360
 361    1. x1 number
 362    2. y1 number
 363    3. x2 number
 364    4. y2 number
 365
 366 ##### Usage
 367
 368     var c = paper.path({stroke: "#036"}).moveTo(10, 10).curveTo(10, 15, 45, 45, 50, 50);
 369
 370 #### addRoundedCorner
 371
 372 Draws quarter of circle form current point.
 373
 374 ##### Parameters
 375
 376    1. r number
 377    2. dir string two letters direction
 378
 379 Possible dir values
 380
 381 * lu: left up
 382 * ld: left down
 383 * ru: right up
 384 * rd: right down
 385 * ur: up right
 386 * ul: up left
 387 * dr: down right
 388 * dl: down left
 389
 390 ##### Usage
 391
 392     var c = paper.path({stroke: "#036"}).moveTo(10, 10).addRoundedCorner(10, "rd");
 393
 394 #### andClose
 395
 396 Closes the path.
 397
 398 ##### Usage
 399
 400 var c = paper.path({stroke: "#036"}).moveTo(10, 10).andClose();
 401
 402 # License
 403
 404 http://www.opensource.org/licenses/mit-license.php
 405
 406 Copyright (c) 2008 Dmitry Baranovskiy (http://raphaeljs.com)