diff --git a/docs/reference.html b/docs/reference.html index ef3eec9..5b2b35c 100644 --- a/docs/reference.html +++ b/docs/reference.html @@ -1,7 +1,7 @@ -g.Raphaël Reference
  1. Element
  2. Element.blob()
  3. Element.darker()
  4. Element.drop()
  5. Element.flag()
  6. Element.label()
  7. Element.lighter()
  8. Element.popup()
  9. Element.resetBrightness()
  10. Element.tag()
  11. Paper
  12. Paper.blob()
  13. Paper.drop()
  14. Paper.flag()
  15. Paper.label()
  16. Paper.popup()
  17. Paper.tag()
  18. g
  19. g.colors
  20. g.shim
  21. g.txtattr

g.Raphaël Reference

 Element

-

 Element.blob(angle, x, y)

+g.Raphaël Reference
  1. Element
  2. Element.blob()
  3. Element.darker()
  4. Element.drop()
  5. Element.flag()
  6. Element.label()
  7. Element.lighter()
  8. Element.popup()
  9. Element.resetBrightness()
  10. Element.tag()
  11. Paper
  12. Paper.barchart()
  13. Paper.blob()
  14. Paper.dotchart()
  15. Paper.drop()
  16. Paper.flag()
  17. Paper.label()
  18. Paper.linechart()
  19. Paper.piechart()
  20. Paper.popup()
  21. Paper.tag()
  22. Paper.vbarchart()
  23. dotchart
  24. dotchart.axis
  25. dotchart.click()
  26. dotchart.covers
  27. dotchart.each()
  28. dotchart.hover()
  29. dotchart.href()
  30. dotchart.series
  31. g
  32. g.colors
  33. g.shim
  34. g.txtattr
  35. linechart
  36. linechart.axis
  37. linechart.click()
  38. linechart.clickColumn()
  39. linechart.each()
  40. linechart.eachColumn()
  41. linechart.hover()
  42. linechart.hoverColumn()
  43. linechart.hrefColumn()
  44. linechart.lines
  45. linechart.shades
  46. linechart.symbols

g.Raphaël Reference

 Element

+

 Element.blob(angle, x, y)

Puts the context Element in a 'blob' tooltip. Can also be used on sets.

Parameters @@ -24,7 +24,7 @@ fill: "0-#c9de96-#8ab66b:44-#398235" }).blob(60); -

 Element.darker(times)

+

 Element.darker(times)

Makes the context element darker by decreasing the brightness and increasing the saturation by a given factor. Can be called on Sets.

Parameters @@ -42,7 +42,7 @@ "stroke-width": 2 }).darker(6); -

 Element.drop(angle, x, y)

+

 Element.drop(angle, x, y)

Puts the context Element in a 'drop' tooltip. Can also be used on sets.

Parameters @@ -65,7 +65,7 @@ fill: "0-#c9de96-#8ab66b:44-#398235" }).drop(60); -

 Element.flag(angle, x, y)

+

 Element.flag(angle, x, y)

Puts the context Element in a 'flag' tooltip. Can also be used on sets.

Parameters @@ -88,7 +88,7 @@ fill: "0-#c9de96-#8ab66b:44-#398235" }).flag(60); -

 Element.label()

+

 Element.label()

Puts the context Element in a 'label' tooltip. Can also be used on sets.

Returns: object path element of the label.

@@ -99,7 +99,7 @@ fill: "0-#c9de96-#8ab66b:44-#398235" }).label(); -

 Element.lighter(times)

+

 Element.lighter(times)

Makes the context element lighter by increasing the brightness and reducing the saturation by a given factor. Can be called on Sets.

Parameters @@ -117,7 +117,7 @@ "stroke-width": 2 }).lighter(6); -

 Element.popup(dir, size, x, y)

+

 Element.popup(dir, size, x, y)

Puts the context Element in a 'popup' tooltip. Can also be used on sets.

Parameters @@ -143,7 +143,7 @@ fill: "0-#c9de96-#8ab66b:44-#398235" }).popup(); -

 Element.resetBrightness()

+

 Element.resetBrightness()

Resets brightness and saturation levels to their original values. See Element.lighter and Element.darker. Can be called on Sets.

Returns: object Element

@@ -155,7 +155,7 @@ "stroke-width": 2 }).lighter(6).resetBrightness(); -

 Element.tag(angle, r, x, y)

+

 Element.tag(angle, r, x, y)

Puts the context Element in a 'tag' tooltip. Can also be used on sets.

Parameters @@ -182,7 +182,43 @@ }).tag(60);

 Paper

-

 Paper.blob(x, y, text, angle)

+

 Paper.barchart(x, y, width, height, values, opts)

+

Creates a horizontal bar chart +

+

Parameters +

+
x
+
number
+
x coordinate of the chart
+
y
+
number
+
y coordinate of the chart
+
width
+
number
+
width of the chart (respected by all elements in the set)
+
height
+
number
+
height of the chart (respected by all elements in the set)
+
values
+
array
+
values
+
opts
+
object
+
options for the chart
+
+
  1. {
    1. typestringtype of endings of the bar. Default: 'square'. Other options are: 'round', 'sharp', 'soft'. +
    2. gutternumber(string) default '20%' (WHAT DOES IT DO?) +
    3. vgutternumber  +
    4. colorsarraycolors be used repeatedly to plot the bars. If multicolumn bar is used each sequence of bars with use a different color. +
    5. stackedbooleanwhether or not to tread values as in a stacked bar chart +
    6. to
    7. stretchboolean  +
  2. }
+

Returns: object path element of the popup

+

Usage +

+
r.barchart(0, 0, 620, 260, [76, 70, 67, 71, 69], {})
+
+

 Paper.blob(x, y, text, angle)

Puts the given text into a 'blob' tooltip. The text is given a default style according to g.txtattr. See Element.blob

Parameters @@ -205,7 +241,59 @@

paper.blob(50, 50, "$9.99", 60);
 
-

 Paper.drop(x, y, text, angle)

+

 Paper.dotchart(x, y, width, height, valuesx, valuesy, size, opts)

+

Plots a dot chart +

+

Parameters +

+
x
+
number
+
x coordinate of the chart
+
y
+
number
+
y coordinate of the chart
+
width
+
number
+
width of the chart (respected by all elements in the set)
+
height
+
number
+
height of the chart (respected by all elements in the set)
+
valuesx
+
array
+
values used to plot x asis
+
valuesy
+
array
+
values used to plot y asis
+
size
+
array
+
values used as data
+
opts
+
object
+
options for the chart
+
+

Possible options +

+
  1. {
    1. maxnumbermaximum diameter of a dot [default: 100] +
    2. symbolstringsymbol used for rendering on the chart. The only possible option is 'circle' [default] +
    3. gutternumberdistance between symbols on the chart [default: 10] +
    4. heatbooleanwhether or not to enable coloring higher value symbols with warmer hue [default: false] +
    5. opacitynumberopacity of the symbols [default: 1] +
    6. hrefarrayarray of URLs to set up click-throughs on the symbols +
    7. axisstringWhich axes should be renedered. String of four values evaluated in order 'top right bottom left' e.g. '0 0 1 1'. +
    8. axisxstepnumberthe number of steps to plot on the axis X +
    9. axisystepnumberthe number of steps to plot on the axis Y +
    10. axisxlabelsarraylabels to be rendered instead of numeric values on axis X +
    11. axisylabelsarraylabels to be rendered instead of numeric values on axis Y +
    12. axisxtypestringPossible values: 't' [default], '|', ' ', '-', '+' +
    13. axisytypestringPossible values: 't' [default], '|', ' ', '-', '+' +
  2. }
+

Returns: object dotchart object

+

Usage +

+
//life, expectancy, country and spending per capita (fictional data)
+r.dotchart(0, 0, 620, 260, [76, 70, 67, 71, 69], [0, 1, 2, 3, 4], [100, 120, 140, 160, 500], {max: 10, axisylabels: ['Mexico', 'Argentina', 'Cuba', 'Canada', 'United States of America'], heat: true, axis: '0 0 1 1'})
+
+

 Paper.drop(x, y, text, angle)

Puts the given text into a 'drop' tooltip. The text is given a default style according to g.txtattr. See Element.drop

Parameters @@ -228,7 +316,7 @@

paper.drop(50, 50, "$9.99", 60);
 
-

 Paper.flag(x, y, text, angle)

+

 Paper.flag(x, y, text, angle)

Puts the given text into a 'flag' tooltip. The text is given a default style according to g.txtattr. See Element.flag

Parameters @@ -251,7 +339,7 @@

paper.flag(50, 50, "$9.99", 60);
 
-

 Paper.label(x, y, text)

+

 Paper.label(x, y, text)

Puts the given text into a 'label' tooltip. The text is given a default style according to g.txtattr. See Element.label

Parameters @@ -271,7 +359,88 @@

paper.label(50, 50, "$9.99");
 
-

 Paper.popup(x, y, text, dir, size)

+

 Paper.linechart(x, y, width, height, valuesx, valuesy, opts)

+

Creates a line chart +

+

Parameters +

+
x
+
number
+
x coordinate of the chart
+
y
+
number
+
y coordinate of the chart
+
width
+
number
+
width of the chart (including the axis)
+
height
+
number
+
height of the chart (including the axis)
+
valuesx
+
array
+
values to plot on axis x
+
valuesy
+
array
+
values to plot on axis y
+
opts
+
object
+
options for the chart
+
+
  1. {
    1. gutternumberdistance between symbols on the chart +
    2. symbolstring(array) symbol to be plotted as nodes of the chart, if array are passed symbols are printed iteratively. Currently 'circle' and '' (no symbol) are the only supported options. +
    3. widthnumbercontrols the size of the plotted symbol. Also controls the thickness of the line using a formula stroke-width=width/2. This option is likely to change in the future versions of g.raphael. +
    4. colorsarraycolors to plot data series. Raphael default colors are used if not passed +
    5. shadebooleanwhether or not to plot a shade of the chart [default: false]. Currently only a shade between the line and x axis is supported. +
    6. nostrokebooleanwhether or not to plot lines [default: false]. Only practical when shade is enabled. +
    7. dashstringchanges display of the line from continues to dashed or dotted (Possible values are the same as stroke-dasharray attribute, see Element.attr). +
    8. smoothbooleanchanges display of the line from point-to-point straight lines to curves (type C, see Paper.path). +
    9. axisstringWhich axes should be renedered. String of four values evaluated in order 'top right bottom left' e.g. '0 0 1 1'. +
    10. axisxstepnumberdistance between values on axis X +
    11. axisystepnumberdistance between values on axis Y +
  2. }
+

Returns: object path element of the popup

+

Usage +

+
r.linechart(0, 0, 99, 99, [1,2,3,4,5], [[1,2,3,4,5], [1,3,9,16,25], [100,50,25,12,6]], {smooth: true, colors: ['#F00', '#0F0', '#FF0'], symbol: 'circle'});
+
+

 Paper.piechart(cx, cy, r, values, opts)

+

Creates a pie chart +

+

Parameters +

+
cx
+
number
+
x coordinate of the chart
+
cy
+
number
+
y coordinate of the chart
+
r
+
integer
+
radius of the chart
+
values
+
array
+
values used to plot
+
opts
+
object
+
options for the chart
+
+
  1. {
    1. strokestringcolor of the circle stroke in HTML color format [default "#FFF"] +
    2. strokewidthintegerwidth of the chart stroke [default 1] +
    3. initbooleanwhether or not to show animation when the chart is ready [default false] +
    4. colorsarraycolors be used to plot the chart +
    5. hrefarrayurls to to set up clicks on chart slices +
    6. legendarrayarray containing strings that will be used in a legend. Other label options work if legend is defined. +
    7. legendcolorstringcolor of text in legend [default "#000"] +
    8. legendothersstringtext that will be used in legend to describe options that are collapsed into 1 slice, because they are too small to render [default "Others"] +
    9. legendmarkstringsymbol used as a bullet point in legend that has the same colour as the chart slice [default "circle"] +
    10. legendposstringposition of the legend on the chart [default "east"]. Other options are "north", "south", "west" +
  2. }
+

Returns: object path element of the popup

+

Usage +

+
r.piechart(cx, cy, r, values, opts)
+
+

 Paper.popup(x, y, text, dir, size)

Puts the given text into a 'popup' tooltip. The text is given a default style according to g.txtattr. See Element.popup

Note: The dir parameter has changed from g.Raphael 0.4.1 to 0.5. The options 0, 1, 2, and 3 has been changed to 'down', 'left', 'up', and 'right' respectively. @@ -299,7 +468,7 @@

paper.popup(50, 50, "$9.99", 'down');
 
-

 Paper.tag(x, y, text, angle, r)

+

 Paper.tag(x, y, text, angle, r)

Puts the given text into a 'tag' tooltip. The text is given a default style according to g.txtattr. See Element.tag

Parameters @@ -325,26 +494,244 @@

paper.tag(50, 50, "$9.99", 60);
 
+

 Paper.vbarchart(x, y, width, height, values, opts)

+

Creates a vertical bar chart +

+

Parameters +

+
x
+
number
+
x coordinate of the chart
+
y
+
number
+
y coordinate of the chart
+
width
+
number
+
width of the chart (respected by all elements in the set)
+
height
+
number
+
height of the chart (respected by all elements in the set)
+
values
+
array
+
values
+
opts
+
object
+
options for the chart
+
+
  1. {
    1. typestringtype of endings of the bar. Default: 'square'. Other options are: 'round', 'sharp', 'soft'. +
    2. gutternumber(string) default '20%' (WHAT DOES IT DO?) +
    3. vgutternumber  +
    4. colorsarraycolors be used repeatedly to plot the bars. If multicolumn bar is used each sequence of bars with use a different color. +
    5. stackedbooleanwhether or not to tread values as in a stacked bar chart +
    6. to
    7. stretchboolean  +
  2. }
+

Returns: object path element of the popup

+

Usage +

+
r.vbarchart(0, 0, 620, 260, [76, 70, 67, 71, 69], {})
+
+

 dotchart

+

 dotchart.axis

+

Set containing Elements of the chart axis. Only exists if 'axis' definition string was passed to Paper.dotchart +

+

 dotchart.click(click handler)

+

Parameters +

+
click handler
+
function
+
handler for the event
+
+

Conveniece method to set up click event handler +

+

Returns: object dotchart object

+

 dotchart.covers

+

Set of Elements positioned above the symbols and mirroring them in size and shape. Covers are used as a surface for events capturing. Each cover has a property 'dot' being a reference to the actual data-representing symbol. +

+

 dotchart.each(callback, this)

+

Parameters +

+
callback
+
function
+
called for every item in dotchart.covers.
+
this
+
object
+
callback is executed in a context of a cover element object
+
+

Conveniece method iterating on every symbol in the chart +

+

Returns: object dotchart object

+

 dotchart.hover(mouseover handler, mouseout handler)

+

Parameters +

+
mouseover handler
+
function
+
handler for the event
+
mouseout handler
+
function
+
handler for the event
+
+

Conveniece method to set up hover-in and hover-out event handlers +

+

Returns: object dotchart object

+

 dotchart.href(map)

+

Parameters +

+
map
+
array
+
Array of objects {x: 1, y: 20, value: 15, href: "http://www.raphaeljs.com"}
+
+

Iterates on all dotchart.covers elements. If x, y and value on the object are the same as on the cover it sets up a link on a symbol using the passef href. +

+

Returns: object dotchart object

+

 dotchart.series

+

Set of Elements containing the actual data-representing symbols. +

 g

-

 g.colors

+

 g.colors

An array of color values that charts will iterate through when drawing chart data values.

-

 g.shim

+

 g.shim

An attribute object that charts will set on all generated shims (shims being the invisible objects that mouse events are bound to)

Default value

{ stroke: 'none', fill: '#000', 'fill-opacity': 0 }
 
-

 g.txtattr

+

 g.txtattr

An attribute object that charts and tooltips will set on any generated text

Default value

{ font: '12px Arial, sans-serif', fill: '#fff' }
 
+

 linechart

+

 linechart.axis

+

Set containing Elements of the chart axis. The set is populated if 'axis' definition string was passed to Paper.linechart +

+

 linechart.click(click handler, this)

+

Parameters +

+
click handler
+
function
+
handler for the event
+
this
+
object
+
callback is executed in a context of a cover element
+
+

Conveniece method to set up click event handler on the lines of the chart +Use linechart.clickColumn to work with the entire chart area. +

+

Returns: object linechart object

+

 linechart.clickColumn(click handler, this)

+

Parameters +

+
click handler
+
function
+
handler for the event
+
this
+
object
+
callback is executed in a context of a cover element
+
+

Conveniece method to set up click event handler on the antire area of the chart. +The handler is passed a event object containing +

+
  1. {
    1. xnumberx coordinate on all lines in the chart +
    2. yarrayy coordinates of all lines corresponding to the x +
  2. }
+

Returns: object linechart object

+

 linechart.each(callback, this)

+

Parameters +

+
callback
+
function
+
function executed for every data point
+
this
+
object
+
context of the callback function.
+
+
  1. {
    1. xnumberx coordinate of the data point +
    2. ynumbery coordinate of the data point +
    3. valuenumbervalue represented by the data point +
  2. }
+

Iterates over each unique data point plotted on every line on the chart. +

+

Returns: object linechart object

+

 linechart.eachColumn(callback, this)

+

Parameters +

+
callback
+
function
+
function executed for every column
+
this
+
object
+
context of the callback function.
+
+
  1. {
    1. xnumberx coordinate of the data point +
    2. yarrayy coordinates of data points existing for the given x +
    3. valuesarrayvalues represented by the data points existing for the given x +
  2. }
+

Iterates over each column area (area plotted above the chart). +

+

Returns: object linechart object

+

 linechart.hover(mouseover handler, mouseout handler)

+

Parameters +

+
mouseover handler
+
function
+
handler for the event
+
mouseout handler
+
function
+
handler for the event
+
+

Conveniece method to set up hover-in and hover-out event handlers working on the lines of the chart. +Use linechart.hoverColumn to work with the entire chart area. +

+

Returns: object linechart object

+

 linechart.hoverColumn(mouseover handler, mouseout handler, this)

+

Parameters +

+
mouseover handler
+
function
+
handler for the event
+
mouseout handler
+
function
+
handler for the event
+
this
+
object
+
callback is executed in a context of a cover element
+
+

Conveniece method to set up hover-in and hover-out event handlers on the entire area of the chart. +The handlers are passed a event object containing +

+
  1. {
    1. xnumberx coordinate on all lines in the chart +
    2. yarrayy coordinates of all lines corresponding to the x +
  2. }
+

Returns: object linechart object

+

 linechart.hrefColumn(cols)

+

Parameters +

+
cols
+
object
+
object containing values as keys and URLs as values, e.g. {1: 'http://www.raphaeljs.com', 2: 'http://g.raphaeljs.com'}
+
+

Creates click-throughs on the whole area of the chart corresponding to x values +

+

Returns: object linechart object

+

 linechart.lines

+

Set containing Elements corresponding to lines plotted in the chart. +

+

 linechart.shades

+

Set containing Elements corresponding to shades plotted in the chart (if opts.shade was true). +

+

 linechart.symbols

+

Set containing Elements corresponding to symbols plotted in the chart. +

+ + + + \ No newline at end of file diff --git a/docs/reference.js b/docs/reference.js index 6280f4e..9585e01 100644 --- a/docs/reference.js +++ b/docs/reference.js @@ -29,7 +29,12 @@ Raphael(function () { prepare("Paper.label-extra").label(50, 50, "$9.99"); prepare("Paper.blob-extra").blob(50, 50, "Hello", 60); + prepare("Paper.dotchart-extra").dotchart(0, 0, 99, 99, [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], {max: 7, heat: true, gutter: 1, axisxstep: 4}); + prepare("Paper.linechart-extra").linechart(0, 0, 99, 99, [1,2,3,4,5], [[1,2,3,4,5], [1,3,9,16,25], [100,50,25,12,6]], {smooth: true, colors: ['#F00', '#0F0', '#FF0'], symbol: 'circle', width: 1}); + prepare("Element.lighter-extra").circle(50, 50, 20).attr(fill).lighter(6); prepare("Element.darker-extra").circle(50, 50, 20).attr(fill).darker(6); prepare("Element.resetBrightness-extra").circle(50, 50, 20).attr(fill).lighter(6).resetBrightness(); + + }); diff --git a/g.bar.js b/g.bar.js index b0834b7..9f72387 100644 --- a/g.bar.js +++ b/g.bar.js @@ -135,9 +135,35 @@ } } - /* - * Vertical Barchart - */ +/*\ + * Paper.vbarchart + [ method ] + ** + * Creates a vertical bar chart + ** + > Parameters + ** + - x (number) x coordinate of the chart + - y (number) y coordinate of the chart + - width (number) width of the chart (respected by all elements in the set) + - height (number) height of the chart (respected by all elements in the set) + - values (array) values + - opts (object) options for the chart + o { + o type (string) type of endings of the bar. Default: 'square'. Other options are: 'round', 'sharp', 'soft'. + o gutter (number)(string) default '20%' (WHAT DOES IT DO?) + o vgutter (number) + o colors (array) colors be used repeatedly to plot the bars. If multicolumn bar is used each sequence of bars with use a different color. + o stacked (boolean) whether or not to tread values as in a stacked bar chart + o to + o stretch (boolean) + o } + ** + = (object) path element of the popup + > Usage + | r.vbarchart(0, 0, 620, 260, [76, 70, 67, 71, 69], {}) + \*/ + function VBarchart(paper, x, y, width, height, values, opts) { opts = opts || {}; @@ -387,10 +413,45 @@ chart.covers = covers; return chart; }; - - /** - * Horizontal Barchart - */ + + //inheritance + var F = function() {}; + F.prototype = Raphael.g; + HBarchart.prototype = VBarchart.prototype = new F; //prototype reused by hbarchart + + Raphael.fn.barchart = function(x, y, width, height, values, opts) { + return new VBarchart(this, x, y, width, height, values, opts); + }; + +/*\ + * Paper.barchart + [ method ] + ** + * Creates a horizontal bar chart + ** + > Parameters + ** + - x (number) x coordinate of the chart + - y (number) y coordinate of the chart + - width (number) width of the chart (respected by all elements in the set) + - height (number) height of the chart (respected by all elements in the set) + - values (array) values + - opts (object) options for the chart + o { + o type (string) type of endings of the bar. Default: 'square'. Other options are: 'round', 'sharp', 'soft'. + o gutter (number)(string) default '20%' (WHAT DOES IT DO?) + o vgutter (number) + o colors (array) colors be used repeatedly to plot the bars. If multicolumn bar is used each sequence of bars with use a different color. + o stacked (boolean) whether or not to tread values as in a stacked bar chart + o to + o stretch (boolean) + o } + ** + = (object) path element of the popup + > Usage + | r.barchart(0, 0, 620, 260, [76, 70, 67, 71, 69], {}) + \*/ + function HBarchart(paper, x, y, width, height, values, opts) { opts = opts || {}; @@ -606,16 +667,8 @@ return chart; }; - //inheritance - var F = function() {}; - F.prototype = Raphael.g; - HBarchart.prototype = VBarchart.prototype = new F; - Raphael.fn.hbarchart = function(x, y, width, height, values, opts) { return new HBarchart(this, x, y, width, height, values, opts); }; - Raphael.fn.barchart = function(x, y, width, height, values, opts) { - return new VBarchart(this, x, y, width, height, values, opts); - }; })(); diff --git a/g.dot.js b/g.dot.js index 17f4c96..145343c 100644 --- a/g.dot.js +++ b/g.dot.js @@ -4,23 +4,25 @@ * Copyright (c) 2009 Dmitry Baranovskiy (http://g.raphaeljs.com) * Licensed under the MIT (http://www.opensource.org/licenses/mit-license.php) license. */ + (function () { var colorValue = function (value, total, s, b) { return 'hsb(' + [Math.min((1 - value / total) * .4, 1), s || .75, b || .75] + ')'; }; - + function Dotchart(paper, x, y, width, height, valuesx, valuesy, size, opts) { - var chartinst = this; - function drawAxis(ax) { +ax[0] && (ax[0] = chartinst.axis(x + gutter, y + gutter, width - 2 * gutter, minx, maxx, opts.axisxstep || Math.floor((width - 2 * gutter) / 20), 2, opts.axisxlabels || null, opts.axisxtype || "t", null, paper)); +ax[1] && (ax[1] = chartinst.axis(x + width - gutter, y + height - gutter, height - 2 * gutter, miny, maxy, opts.axisystep || Math.floor((height - 2 * gutter) / 20), 3, opts.axisylabels || null, opts.axisytype || "t", null, paper)); +ax[2] && (ax[2] = chartinst.axis(x + gutter, y + height - gutter + maxR, width - 2 * gutter, minx, maxx, opts.axisxstep || Math.floor((width - 2 * gutter) / 20), 0, opts.axisxlabels || null, opts.axisxtype || "t", null, paper)); +ax[3] && (ax[3] = chartinst.axis(x + gutter - maxR, y + height - gutter, height - 2 * gutter, miny, maxy, opts.axisystep || Math.floor((height - 2 * gutter) / 20), 1, opts.axisylabels || null, opts.axisytype || "t", null, paper)); } - + + //providing defaults + opts = opts || {}; + var chartinst = this; var xdim = chartinst.snapEnds(Math.min.apply(Math, valuesx), Math.max.apply(Math, valuesx), valuesx.length - 1), minx = xdim.from, maxx = xdim.to, @@ -43,6 +45,13 @@ gutter = Math.max.apply(Math, R.concat(gutter)); + /*\ + * dotchart.axis + [ object ] + ** + * Set containing Elements of the chart axis. Only exists if `'axis'` definition string was passed to @Paper.dotchart + ** + \*/ var axis = paper.set(), maxR = Math.max.apply(Math, R); @@ -104,20 +113,65 @@ covers[i].dot = series[i]; } + /*\ + * dotchart.covers + [ object ] + ** + * Set of Elements positioned above the symbols and mirroring them in size and shape. Covers are used as a surface for events capturing. Each cover has a property `'dot'` being a reference to the actual data-representing symbol. + ** + ** + \*/ res.covers = covers; + /*\ + * dotchart.series + [ object ] + ** + * Set of Elements containing the actual data-representing symbols. + ** + ** + \*/ res.series = series; res.push(series, axis, covers); + /*\ + * dotchart.hover + [ method ] + > Parameters + - mouseover handler (function) handler for the event + - mouseout handler (function) handler for the event + * Conveniece method to set up hover-in and hover-out event handlers + = (object) @dotchart object + ** + \*/ res.hover = function (fin, fout) { covers.mouseover(fin).mouseout(fout); return this; }; + /*\ + * dotchart.click + [ method ] + > Parameters + - click handler (function) handler for the event + * Conveniece method to set up click event handler + = (object) @dotchart object + ** + \*/ res.click = function (f) { covers.click(f); return this; }; + /*\ + * dotchart.each + [ method ] + > Parameters + - callback (function) called for every item in @dotchart.covers. + - this (object) callback is executed in a context of a cover element object + * Conveniece method iterating on every symbol in the chart + = (object) @dotchart object + ** + \*/ res.each = function (f) { if (!paper.raphael.is(f, "function")) { return this; @@ -130,6 +184,15 @@ return this; }; + /*\ + * dotchart.href + [ method ] + > Parameters + - map (array) Array of objects `{x: 1, y: 20, value: 15, href: "http://www.raphaeljs.com"}` + * Iterates on all @dotchart.covers elements. If x, y and value on the object are the same as on the cover it sets up a link on a symbol using the passef `href`. + = (object) @dotchart object + ** + \*/ res.href = function (map) { var cover; @@ -149,7 +212,46 @@ F.prototype = Raphael.g Dotchart.prototype = new F; - //public +/* + * dotchart method on paper + */ +/*\ + * Paper.dotchart + [ method ] + ** + * Plots a dot chart + ** + > Parameters + - x (number) x coordinate of the chart + - y (number) y coordinate of the chart + - width (number) width of the chart (respected by all elements in the set) + - height (number) height of the chart (respected by all elements in the set) + - valuesx (array) values used to plot x asis + - valuesy (array) values used to plot y asis + - size (array) values used as data + - opts (object) options for the chart + > Possible options + o { + o max (number) maximum diameter of a dot [default: 100] + o symbol (string) symbol used for rendering on the chart. The only possible option is `'circle'` [default] + o gutter (number) distance between symbols on the chart [default: 10] + o heat (boolean) whether or not to enable coloring higher value symbols with warmer hue [default: false] + o opacity (number) opacity of the symbols [default: 1] + o href (array) array of URLs to set up click-throughs on the symbols + o axis (string) Which axes should be renedered. String of four values evaluated in order `'top right bottom left'` e.g. `'0 0 1 1'`. + o axisxstep (number) the number of steps to plot on the axis X + o axisystep (number) the number of steps to plot on the axis Y + o axisxlabels (array) labels to be rendered instead of numeric values on axis X + o axisylabels (array) labels to be rendered instead of numeric values on axis Y + o axisxtype (string) Possible values: `'t'` [default], `'|'`, `' '`, `'-'`, `'+'` + o axisytype (string) Possible values: `'t'` [default], `'|'`, `' '`, `'-'`, `'+'` + o } + ** + = (object) @dotchart object + > Usage + | //life, expectancy, country and spending per capita (fictional data) + | r.dotchart(0, 0, 620, 260, [76, 70, 67, 71, 69], [0, 1, 2, 3, 4], [100, 120, 140, 160, 500], {max: 10, axisylabels: ['Mexico', 'Argentina', 'Cuba', 'Canada', 'United States of America'], heat: true, axis: '0 0 1 1'}) + \*/ Raphael.fn.dotchart = function(x, y, width, height, valuesx, valuesy, size, opts) { return new Dotchart(this, x, y, width, height, valuesx, valuesy, size, opts); } diff --git a/g.line.js b/g.line.js index 24fa8de..17df51d 100644 --- a/g.line.js +++ b/g.line.js @@ -4,6 +4,7 @@ * Copyright (c) 2009 Dmitry Baranovskiy (http://g.raphaeljs.com) * Licensed under the MIT (http://www.opensource.org/licenses/mit-license.php) license. */ + (function () { function shrink(values, dim) { @@ -78,6 +79,14 @@ len = Math.max(len, valuesy[i].length); } + /*\ + * linechart.shades + [ object ] + ** + * Set containing Elements corresponding to shades plotted in the chart (if `opts.shade` was `true`). + ** + ** + \*/ var shades = paper.set(); for (i = 0, ii = valuesy.length; i < ii; i++) { @@ -106,6 +115,14 @@ kx = (width - gutter * 2) / ((maxx - minx) || 1), ky = (height - gutter * 2) / ((maxy - miny) || 1); + /*\ + * linechart.axis + [ object ] + ** + * Set containing Elements of the chart axis. The set is populated if `'axis'` definition string was passed to @Paper.linechart + ** + ** + \*/ var axis = paper.set(); if (opts.axis) { @@ -116,7 +133,23 @@ +ax[3] && axis.push(chartinst.axis(x + gutter, y + height - gutter, height - 2 * gutter, miny, maxy, opts.axisystep || Math.floor((height - 2 * gutter) / 20), 1, paper)); } + /*\ + * linechart.lines + [ object ] + ** + * Set containing Elements corresponding to lines plotted in the chart. + ** + ** + \*/ var lines = paper.set(), + /*\ + * linechart.symbols + [ object ] + ** + * Set containing Elements corresponding to symbols plotted in the chart. + ** + ** + \*/ symbols = paper.set(), line; @@ -236,8 +269,7 @@ var X = x + gutter + ((valuesx[i] || valuesx[0])[j] - minx) * kx, nearX = x + gutter + ((valuesx[i] || valuesx[0])[j ? j - 1 : 1] - minx) * kx, Y = y + height - gutter - (valuesy[i][j] - miny) * ky; - - f ? (C = {}) : cvrs.push(C = paper.circle(X, Y, Math.abs(nearX - X) / 2).attr({ stroke: "none", fill: "#000", opacity: 0 })); + f ? (C = {}) : cvrs.push(C = paper.circle(X, Y, Math.abs(nearX - X) / 2).attr({ stroke: "#000", fill: "#000", opacity: 1 })); C.x = X; C.y = Y; C.value = valuesy[i][j]; @@ -259,18 +291,59 @@ chart.symbols = symbols; chart.axis = axis; + /*\ + * linechart.hoverColumn + [ method ] + > Parameters + - mouseover handler (function) handler for the event + - mouseout handler (function) handler for the event + - this (object) callback is executed in a context of a cover element + * Conveniece method to set up hover-in and hover-out event handlers on the entire area of the chart. + * The handlers are passed a event object containing + o { + o x (number) x coordinate on all lines in the chart + o y (array) y coordinates of all lines corresponding to the x + o } + = (object) @linechart object + ** + \*/ + chart.hoverColumn = function (fin, fout) { !columns && createColumns(); columns.mouseover(fin).mouseout(fout); return this; }; + /*\ + * linechart.clickColumn + [ method ] + > Parameters + - click handler (function) handler for the event + - this (object) callback is executed in a context of a cover element + * Conveniece method to set up click event handler on the antire area of the chart. + * The handler is passed a event object containing + o { + o x (number) x coordinate on all lines in the chart + o y (array) y coordinates of all lines corresponding to the x + o } + = (object) @linechart object + ** + \*/ chart.clickColumn = function (f) { !columns && createColumns(); columns.click(f); return this; }; + /*\ + * linechart.hrefColumn + [ method ] + > Parameters + - cols (object) object containing values as keys and URLs as values, e.g. {1: 'http://www.raphaeljs.com', 2: 'http://g.raphaeljs.com'} + * Creates click-throughs on the whole area of the chart corresponding to x values + = (object) @linechart object + ** + \*/ chart.hrefColumn = function (cols) { var hrefs = paper.raphael.is(arguments[0], "array") ? arguments[0] : arguments; @@ -291,23 +364,75 @@ return this; }; + /*\ + * linechart.hover + [ method ] + > Parameters + - mouseover handler (function) handler for the event + - mouseout handler (function) handler for the event + * Conveniece method to set up hover-in and hover-out event handlers working on the lines of the chart. + * Use @linechart.hoverColumn to work with the entire chart area. + = (object) @linechart object + ** + \*/ chart.hover = function (fin, fout) { !dots && createDots(); dots.mouseover(fin).mouseout(fout); return this; }; + /*\ + * linechart.click + [ method ] + > Parameters + - click handler (function) handler for the event + - this (object) callback is executed in a context of a cover element + * Conveniece method to set up click event handler on the lines of the chart + * Use @linechart.clickColumn to work with the entire chart area. + = (object) @linechart object + ** + \*/ chart.click = function (f) { !dots && createDots(); dots.click(f); return this; }; + /*\ + * linechart.each + [ method ] + > Parameters + - callback (function) function executed for every data point + - this (object) context of the callback function. + o { + o x (number) x coordinate of the data point + o y (number) y coordinate of the data point + o value (number) value represented by the data point + o } + * Iterates over each unique data point plotted on every line on the chart. + = (object) @linechart object + ** + \*/ chart.each = function (f) { createDots(f); return this; }; + /*\ + * linechart.eachColumn + [ method ] + > Parameters + - callback (function) function executed for every column + - this (object) context of the callback function. + o { + o x (number) x coordinate of the data point + o y (array) y coordinates of data points existing for the given x + o values (array) values represented by the data points existing for the given x + o } + * Iterates over each column area (area plotted above the chart). + = (object) @linechart object + ** + \*/ chart.eachColumn = function (f) { createColumns(f); return this; @@ -321,7 +446,42 @@ F.prototype = Raphael.g; Linechart.prototype = new F; - //public + /* + * linechart method on paper + */ +/*\ + * Paper.linechart + [ method ] + ** + * Creates a line chart + ** + > Parameters + ** + - x (number) x coordinate of the chart + - y (number) y coordinate of the chart + - width (number) width of the chart (including the axis) + - height (number) height of the chart (including the axis) + - valuesx (array) values to plot on axis x + - valuesy (array) values to plot on axis y + - opts (object) options for the chart + o { + o gutter (number) distance between symbols on the chart + o symbol (string) (array) symbol to be plotted as nodes of the chart, if array are passed symbols are printed iteratively. Currently `'circle'` and `''` (no symbol) are the only supported options. + o width (number) controls the size of the plotted symbol. Also controls the thickness of the line using a formula stroke-width=width/2. This option is likely to change in the future versions of g.raphael. + o colors (array) colors to plot data series. Raphael default colors are used if not passed + o shade (boolean) whether or not to plot a shade of the chart [default: false]. Currently only a shade between the line and x axis is supported. + o nostroke (boolean) whether or not to plot lines [default: false]. Only practical when shade is enabled. + o dash (string) changes display of the line from continues to dashed or dotted (Possible values are the same as stroke-dasharray attribute, see @Element.attr). + o smooth (boolean) changes display of the line from point-to-point straight lines to curves (type C, see @Paper.path). + o axis (string) Which axes should be renedered. String of four values evaluated in order `'top right bottom left'` e.g. `'0 0 1 1'`. + o axisxstep (number) distance between values on axis X + o axisystep (number) distance between values on axis Y + o } + ** + = (object) path element of the popup + > Usage + | r.linechart(0, 0, 99, 99, [1,2,3,4,5], [[1,2,3,4,5], [1,3,9,16,25], [100,50,25,12,6]], {smooth: true, colors: ['#F00', '#0F0', '#FF0'], symbol: 'circle'}); + \*/ Raphael.fn.linechart = function(x, y, width, height, valuesx, valuesy, opts) { return new Linechart(this, x, y, width, height, valuesx, valuesy, opts); } diff --git a/g.pie.js b/g.pie.js index 98d04cf..8d30675 100644 --- a/g.pie.js +++ b/g.pie.js @@ -3,7 +3,39 @@ * * Copyright (c) 2009 Dmitry Baranovskiy (http://g.raphaeljs.com) * Licensed under the MIT (http://www.opensource.org/licenses/mit-license.php) license. - */ + */ + + /*\ + * Paper.piechart + [ method ] + ** + * Creates a pie chart + ** + > Parameters + ** + - cx (number) x coordinate of the chart + - cy (number) y coordinate of the chart + - r (integer) radius of the chart + - values (array) values used to plot + - opts (object) options for the chart + o { + o stroke (string) color of the circle stroke in HTML color format [default `"#FFF"`] + o strokewidth (integer) width of the chart stroke [default `1`] + o init (boolean) whether or not to show animation when the chart is ready [default `false`] + o colors (array) colors be used to plot the chart + o href (array) urls to to set up clicks on chart slices + o legend (array) array containing strings that will be used in a legend. Other label options work if legend is defined. + o legendcolor (string) color of text in legend [default `"#000"`] + o legendothers (string) text that will be used in legend to describe options that are collapsed into 1 slice, because they are too small to render [default `"Others"`] + o legendmark (string) symbol used as a bullet point in legend that has the same colour as the chart slice [default `"circle"`] + o legendpos (string) position of the legend on the chart [default `"east"`]. Other options are `"north"`, `"south"`, `"west"` + o } + ** + = (object) path element of the popup + > Usage + | r.piechart(cx, cy, r, values, opts) + \*/ + (function () { function Piechart(paper, cx, cy, r, values, opts) { @@ -256,4 +288,4 @@ return new Piechart(this, cx, cy, r, values, opts); } -})(); +})(); \ No newline at end of file diff --git a/g.raphael.json b/g.raphael.json index d680b1f..486dc3d 100644 --- a/g.raphael.json +++ b/g.raphael.json @@ -1,9 +1,22 @@ { "title": "g.Raphaël", "output": "../g.raphael/docs/reference.html", - "scripts": ["../raphael-min.js", "../g.raphael.js", "reference.js"], + "scripts": ["../raphael-min.js", "../g.raphael.js", "../g.line.js", "../g.dot.js", "../g.bar.js", "../g.pie.js", "reference.js"], "files": [{ "url": "../g.raphael/g.raphael.js", "link": "https://github.com/DmitryBaranovskiy/g.raphael/blob/master/g.raphael.js" + },{ + "url": "../g.raphael/g.line.js", + "link": "https://github.com/DmitryBaranovskiy/g.raphael/blob/master/g.line.js" + },{ + "url": "../g.raphael/g.dot.js", + "link": "https://github.com/DmitryBaranovskiy/g.raphael/blob/master/g.dot.js" + },{ + "url": "../g.raphael/g.bar.js", + "link": "https://github.com/DmitryBaranovskiy/g.raphael/blob/master/g.bar.js" + }, + { + "url": "../g.raphael/g.pie.js", + "link": "https://github.com/DmitryBaranovskiy/g.raphael/blob/master/g.pie.js" }] }