X-Git-Url: http://git.roojs.org/?p=raphael;a=blobdiff_plain;f=reference.html;h=cb0d1295fe9e38f4a8bd406199efeb1e5a97a10b;hp=49e9b6dd2514f1b3c27dc8de654a4e93ad8bfcda;hb=a8d0f3fa261b5dbd47dd6cc6c3391d5d90e5068f;hpb=65792bb06561d6ccf45a7e99712de8889958e848 diff --git a/reference.html b/reference.html index 49e9b6d..cb0d129 100644 --- a/reference.html +++ b/reference.html @@ -56,14 +56,139 @@

Usage

// Each of the following examples create a canvas that is 320px wide by 200px high
-// Canvas is created at the viewport's 10,50 coordinate
+// Canvas is created at the viewport’s 10,50 coordinate
 var paper = Raphael(10, 50, 320, 200);
-// Canvas is created at the top left corner of the #notepad element (or its top right corner in dir="rtl" elements)
+// Canvas is created at the top left corner of the #notepad element
+// (or its top right corner in dir="rtl" elements)
 var paper = Raphael(document.getElementById("notepad"), 320, 200);
 // Same as above
 var paper = Raphael("notepad", 320, 200);
 // Image dump
-var set = Raphael(["notepad", 320, 200, {type: "rect", x: 10, y: 10, width: 25, height: 25, stroke: "#f00"}, {type: "text", x: 30, y: 40, text: "Dump"}]);
+var set = Raphael(["notepad", 320, 200, { + type: "rect", + x: 10, + y: 10, + width: 25, + height: 25, + stroke: "#f00" +}, { + type: "text", + x: 30, + y: 40, + text: "Dump" +}]); +

+ circle +

+
+

+ Draws a circle. +

+

Parameters

+
    +
  1. x number X coordinate of the centre
    2. +
  2. y number Y coordinate of the centre
    3. +
  3. r number radius
    4. +
+

Usage

+ 
var c = paper.circle(50, 50, 40);
+

+ rect +

+
+

+ Draws a rectangle. +

+

Parameters

+
    +
  1. x number X coordinate of top left corner
    2. +
  2. y number Y coordinate of top left corner
    3. +
  3. width number
    4. +
  4. height number
    5. +
  5. r number [optional] radius for rounded corners, default is 0
    6. +
+

Usage

+ 
// regular rectangle
+var c = paper.rect(10, 10, 50, 50);
+// rectangle with rounded corners
+var c = paper.rect(40, 40, 50, 50, 10);
+

+ ellipse +

+
+

+ Draws an ellipse. +

+

Parameters

+
    +
  1. x number X coordinate of the centre
    2. +
  2. y number X coordinate of the centre
    3. +
  3. rx number Horisontal radius
    4. +
  4. ry number Vertical radius
    5. +
+

Usage

+ 
var c = paper.ellipse(50, 50, 40, 20);
+

+ image +

+
+

+ Embeds an image into the SVG/VML canvas. +

+

Parameters

+
    +
  1. src string URI of the source image
    2. +
  2. x number X coordinate position
    3. +
  3. y number Y coordinate position
    4. +
  4. width number Width of the image
    5. +
  5. height number Height of the image
    6. +
+

Usage

+ 
var c = paper.image("apple.png", 10, 10, 80, 80);
+

+ set +

+
+

+ Creates array-like object to keep and operate couple of elements at once. Warning: it doesn’t create any elements for itself in the page. +

+

Usage

+ 
var st = paper.set();
+st.push(
+    paper.circle(10, 10, 5),
+    paper.circle(30, 10, 5)
+);
+st.attr({fill: "red"});
+

+ text +

+
+

+ Draws a text string. If you need line breaks, put “\n” in the string. +

+

Parameters

+
    +
  1. x number X coordinate position.
    2. +
  2. y number Y coordinate position.
    3. +
  3. text string The text string to draw.
    4. +
+

Usage

+ 
var t = paper.text(50, 50, "Raphaël\nkicks\nbutt!");
+

+ path +

+
+

+ Creates a path element by given path data string. +

+

Parameters

+
    +
  1. pathString string [optional] Path data in SVG path string format.
    2. +
+

Usage

+ 
var c = paper.path("M10 10L90 90");
+// draw a diagonal line:
+// move to 10,10, line to 90,90

Element’s generic methods

@@ -77,8 +202,11 @@ var set = Raphael(["notepad", 320, 200, {type: "rect", x: 10, y: 10, width: 25, Gives you a reference to the DOM object, so you can assign event handlers or just mess around.

Usage

- 
var c = paper.circle(10, 10, 10); // draw a circle at coordinate 10,10 with radius of 10
-c.node.onclick = function () { c.attr("fill", "red"); };
+ 
// draw a circle at coordinate 10,10 with radius of 10
+var c = paper.circle(10, 10, 10);
+c.node.onclick = function () {
+    c.attr("fill", "red");
+};

paper

@@ -88,7 +216,8 @@ c.node.onclick = function () { c.attr("fill", "red"); };

Usage

Raphael.el.cross = function () {
     this.attr({fill: "red"});
-    this.paper.path("M10,10L50,50M50,10L10,50").attr({stroke: "red"});
+    this.paper.path("M10,10L50,50M50,10L10,50")
+        .attr({stroke: "red"});
 }

remove @@ -151,7 +280,8 @@ c.rotate(45, true); // rotation is absolute

Usage

var c = paper.circle(10, 10, 10);
-c.translate(10, 10); // moves the circle down the canvas, in a diagonal line
+// moves the circle 10 px to the right and down +c.translate(10, 10);

scale

@@ -167,8 +297,10 @@ c.translate(10, 10); // moves the circle down the canvas, in a diagonal line

Usage

var c = paper.circle(10, 10, 10);
-c.scale(1.5, 1.5); // makes the circle 1.5 times larger
-c.scale(.5, .75);  // makes the circle half as wide, and 75% as high
+// makes the circle 1.5 times larger +c.scale(1.5, 1.5); +// makes the circle half as wide, and 75% as high +c.scale(.5, .75);

attr

@@ -203,8 +335,8 @@ c.scale(.5, .75); // makes the circle half as wide, and 75% as high fill colour or gradient @@ -224,9 +356,9 @@ c.scale(.5, .75); // makes the circle half as wide, and 75% as highscale string comma or space separated values: xtimes, ytimes, cx, cy. See: scale
  • src string (URL)
  • stroke colour
    • -
  • stroke-dasharray string [“”, “-”, “.”, “-.”, “-..”, “. ”, “- ”, “--”, “- .”, “--.”, “--..”]
    • -
  • stroke-linecap string [“butt”, “square”, “round”]
    • -
  • stroke-linejoin string [“butt”, “square”, “round”, “miter”]
    • +
  • stroke-dasharray string [“”, “-”, “.”, “-.”, “-..”, “. ”, “- ”, “--”, “- .”, “--.”, “--..”]
    • +
  • stroke-linecap string [“butt”, “square”, “round”]
    • +
  • stroke-linejoin string [“bevel”, “round”, “miter”]
  • stroke-miterlimit number
  • stroke-opacity number
  • stroke-width number
    • @@ -237,9 +369,15 @@ c.scale(.5, .75); // makes the circle half as wide, and 75% as high

    Usage

    var c = paper.circle(10, 10, 10);
-c.attr("fill", "black");                              // using strings
-c.attr({fill: "#000", stroke: "#f00", opacity: 0.5}); // using params object
-c.attr({fill: "90-#fff-#000", "stroke-dasharray": "-..", "clip-rect": "10, 10, 100, 100"});
    +// using strings +c.attr("fill", "black"); +// using params object +c.attr({fill: "#000", stroke: "#f00", opacity: 0.5}); +c.attr({ + fill: "90-#fff-#000", + "stroke-dasharray": "-..", + "clip-rect": "10, 10, 100, 100" +});

    animate

    @@ -256,7 +394,7 @@ c.attr({fill: "90-#fff-#000", "stroke-dasharray": "-..", "clip-rect": "10, 10, 1
    1. newAttrs object A parameters object of the animation results. (Not all attributes can be animated.)
    2. ms number The duration of the animation, given in milliseconds.
      3. -
    3. easing string [“>”, “<”, “<>”, “backIn”, “backOut”, “bounce”, “elastic”] or function [optional]
      4. +
    4. easing string [“>”, “<”, “<>”, “backIn”, “backOut”, “bounce”, “elastic”] or function [optional]
    5. callback function [optional]

    Attributes that can be animated

    @@ -308,6 +446,7 @@ r.animateWith(c, {x: 20}, 2000);

    animateAlong

    +

    Animates element along the given path. As an option it could rotate element along the path.

    @@ -326,15 +465,34 @@ r.animateWith(c, {x: 20}, 2000); e.attr({rx: 4, ry: 4}); }); }); -

    - toFront +

    + animateAlongBack

    - Moves the element so it is the closest to the viewer’s eyes, on top of other elements. + Similar to animateAlong. Animates element along the given path, starting from the end of it. +

    +

    + onAnimation +

    +
    +

    + Sets or resets the function that will be called on each stage of the animation.

    +

    Parameters

    +
      +
    1. f function function that will be called on each stage of animation
      2. +

    Usage

    - 
    var c = paper.circle(10, 10, 10);
-c.toFront();
    + 
    var p = r.path("M10,50c0,50,80-50,80,0c0,50-80-50-80,0z"),
+    p2 = r.path(),
+    e = r.ellipse(10, 50, 4, 4).attr({stroke: "none", fill: "#f00"}).onAnimation(function () {
+        p2.attr({path: "M50,10L" + e.attr("cx") + "," + e.attr("cy")});
+    }),
+    b = r.rect(0, 0, 620, 400).attr({stroke: "none", fill: "#000", opacity: 0}).click(function () {
+        e.attr({rx: 5, ry: 3}).animateAlong(p, 4000, true, function () {
+            e.attr({rx: 4, ry: 4});
+        });
+    });

    getBBox

    @@ -419,6 +577,7 @@ var c = r.clone();

    getPointAtLength

    +

    Path specific method. Returns point description at given length.

    @@ -427,7 +586,7 @@ var c = r.clone();
  • length number length in pixels from the beginining of the path to the point

    • Usage

    - 
    var p = r.path("M100,100c0,50 100-50 100,0c0,50 -100-50 -100,0z");
+                        
    var p = r.path("M10,50c0,50,80-50,80,0c0,50-80-50-80,0z");
     var point = p.getPointAtLength(30);
     r.circle(point.x, point.y, 3);
    
                         
    Returned object format:
    
@@ -436,6 +595,22 @@ var c = r.clone();
  • y – y coordinate of the point
  • alpha – angle of the path at the point
    • +

    + getSubpath +

    +
    +

    + Path specific method. Returns the subpath string of a given path. +

    +

    Parameters

    +
      +
    1. from number length in pixels from the beginining of the path to the beginining of the subpath
      2. +
    2. to number length in pixels from the beginining of the path to the end of the subpath
      3. +
    +

    Usage

    + 
    var p = r.path("M10,50c0,50,80-50,80,0c0,50-80-50-80,0z");
+    var path = p.getSubpath(10, 60);
+    r.path(path).attr({stroke: "#f00"});

    setSize

    @@ -533,114 +708,6 @@ var c = r.clone(); 
    var txt = r.print(10, 50, "print", r.getFont("Museo"), 30).attr({fill: "#fff"});
 // following line will paint first letter in red
 txt[0].attr({fill: "#f00"});
    -

    - circle -

    -
    -

    - Draws a circle. -

    -

    Parameters

    -
      -
    1. x number X coordinate of the centre
      2. -
    2. y number Y coordinate of the centre
      3. -
    3. r number radius
      4. -
    -

    Usage

    - 
    var c = paper.circle(50, 50, 40);
    -

    - rect -

    -
    -

    - Draws a rectangle. -

    -

    Parameters

    -
      -
    1. x number X coordinate of top left corner
      2. -
    2. y number Y coordinate of top left corner
      3. -
    3. width number
      4. -
    4. height number
      5. -
    5. r number [optional] radius for rounded corners, default is 0
      6. -
    -

    Usage

    - 
    // regular rectangle
-var c = paper.rect(10, 10, 50, 50);
-// rectangle with rounded corners
-var c = paper.rect(40, 40, 50, 50, 10);
    -

    - ellipse -

    -
    -

    - Draws an ellipse. -

    -

    Parameters

    -
      -
    1. x number X coordinate of the centre
      2. -
    2. y number X coordinate of the centre
      3. -
    3. rx number Horisontal radius
      4. -
    4. ry number Vertical radius
      5. -
    -

    Usage

    - 
    var c = paper.ellipse(50, 50, 40, 20);
    -

    - image -

    -
    -

    - Embeds an image into the SVG/VML canvas. -

    -

    Parameters

    -
      -
    1. src string URI of the source image
      2. -
    2. x number X coordinate position
      3. -
    3. y number Y coordinate position
      4. -
    4. width number Width of the image
      5. -
    5. height number Height of the image
      6. -
    -

    Usage

    - 
    var c = paper.image("apple.png", 10, 10, 80, 80);
    -

    - set -

    -
    -

    - Creates array-like object to keep and operate couple of elements at once. Warning: it doesn’t create any elements for itself in the page. -

    -

    Usage

    - 
    var st = paper.set();
-st.push(paper.circle(10, 10, 5), paper.circle(30, 10, 5));
-st.attr({fill: "red"});
    -

    - text -

    -
    -

    - Draws a text string. If you need line breaks, put “\n” in the string. -

    -

    Parameters

    -
      -
    1. x number X coordinate position.
      2. -
    2. y number Y coordinate position.
      3. -
    3. text string The text string to draw.
      4. -
    -

    Usage

    - 
    var t = paper.text(50, 50, "Raphaël\nkicks\nbutt!");
    -

    - path -

    -
    -

    - Initialises path drawing. You can specify a path by supplying the path data as a second argument. -

    -

    Parameters

    -
      -
    1. pathString string [optional] Path data in SVG path string format.
      2. -
    -

    Usage

    - 
    var c = paper.path("M10 10L90 90");
-// draw a diagonal line: move to 10,10, line to 90,90

    Adding your own methods to canvas

    @@ -649,7 +716,7 @@ txt[0].attr({fill: "#f00"});

    Usage

    Raphael.fn.arrow = function (x1, y1, x2, y2, size) {
-    return this.path(// some code here);
+    return this.path( ... );
 };
 // or create namespace
 Raphael.fn.mystuff = {
@@ -683,18 +750,21 @@ paper.circle(100, 100, 20).red();
                             You could specify colour in this formats:
                         
    
                         
                         
    Usage
    
-                        
    paper.circle(100, 100, 20).attr({fill: "hsb(1, 255, 200)", stroke: "red"});
    
+                        
    paper.circle(100, 100, 20).attr({
+    fill: "hsb(1, 255, 200)",
+    stroke: "red"
+});
    
                         
    
                             safari
                         
    
@@ -715,6 +785,42 @@ paper.circle(100, 100, 20).red();
     …
 })(Raphael.ninja());
    +

    + Events +

    +

    + You can attach events to elements by using element.node and your favourite library ($(circle.node).click(…)) or you can use built-in methods: +

    +

    Usage

    + 
    element.click(function (event) {
+    this.attr({fill: "red"});
+});
+element.dblclick(function (event) {
+    this.attr({fill: "red"});
+});
+element.mousedown(function (event) {
+    this.attr({fill: "red"});
+});
+element.mousemove(function (event) {
+    this.attr({fill: "red"});
+});
+element.mouseout(function (event) {
+    this.attr({fill: "red"});
+});
+element.mouseover(function (event) {
+    this.attr({fill: "red"});
+});
+element.mouseup(function (event) {
+    this.attr({fill: "red"});
+});
+element.hover(function (event) {
+    this.attr({fill: "red"});
+}, function (event) {
+    this.attr({fill: "black"});
+});
    +

    + To unbind events use the same method names with “un” prefix, i.e. element.unclick(f); +

    @@ -727,6 +833,27 @@ paper.circle(100, 100, 20).red();
  • Raphael
    • +
  • + circle +
    • +
  • + rect +
    • +
  • + ellipse +
    • +
  • + image +
    • +
  • + set +
    • +
  • + text +
    • +
  • + path +
  • node
    • @@ -763,6 +890,9 @@ paper.circle(100, 100, 20).red();
  • animateAlong
    • +
  • + animateAlongBack +
  • getBBox
    • @@ -791,7 +921,7 @@ paper.circle(100, 100, 20).red(); getPointAtLength
  • - getSubpathsAtLength + getSubpath
  • setSize @@ -817,27 +947,6 @@ paper.circle(100, 100, 20).red();
  • print
    • -
  • - circle -
    • -
  • - rect -
    • -
  • - ellipse -
    • -
  • - image -
    • -
  • - set -
    • -
  • - text -
    • -
  • - path -
  • Adding your own methods to canvas
    • @@ -853,6 +962,9 @@ paper.circle(100, 100, 20).red();
  • “Ninja Mode”
    • +
  • + Events +