Difference between revisions of "TeeChart for JavaScript and HTML5"

From Steema Software Reference Wiki
Jump to: navigation, search
 
(35 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Category:JS]]
 
[[Category:JS]]
 +
[[Image:html5.png|200px]]<br />
 +
=TeeChart for Javascript User Guide=
 +
'''Rev. 1.0, March 2012'''
 +
{{DISPLAYTITLE:<span style="position: absolute; clip: rect(1px 1px 1px 1px); clip: rect(1px, 1px, 1px, 1px);">{{FULLPAGENAME}}</span>}}
 +
__TOC__
 +
== Introduction ==
 +
This document explains in detail how to create charts and graphs using the TeeChart for Javascript library.
 +
Adding charts to your web pages or applications is fun and easy, see the one-minute [http://www.steema.com/files/public/teechart/html5/jscript/docs/TeeChart%20for%20Javascript%20Getting%20Started%20Guide.html Starting Guide], play with the [http://www.steema.com/files/public/teechart/html5/jscript/demos/ Online Demos] or discover the full [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/index.html TeeChart API Reference].
 +
Compared with other programming environments (Java, .NET, Delphi VCL / FireMonkey, etc), the TeeChart Javascript api implements an essential subset of features in order to minimize both the script size and coding complexity.
 +
Current script sizes are [http://www.steema.com/files/public/teechart/html5/jscript/src/teechart.js 64KB] (minified) and 13KB (gzipped)
  
<span class="c16">TeeChart</span><span class="c13">tm</span><span class="c16"> for Javascript</span>
+
== The Tee namespace ==
 +
Full code is wrapped around a single "[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.html Tee]" identifier (namespace) to avoid cluttering the browser Window global space.  Several "classes" in an object-oriented manner exist Inside the Tee namespace, being [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Chart.html Tee.Chart] the main class that defines a chart.
 +
== The Canvas ==
 +
Charts are displayed by default using [http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html HTML5 Canvas] elements. The main class "Tee.Chart" should be initialized passing the &lt;canvas&gt; element or its id as string:
 +
&lt;canvas id="canvas1" width="300" height="200"&gt;&lt;/canvas&gt;
 +
Using the canvas id:
 +
var Chart1=new Tee.Chart("canvas1");
 +
Or using the element:
 +
var Chart1=new Tee.Chart(document.getElementById("canvas1"));
 +
Hidden charts can be created without passing any canvas parameter:
 +
<br />var Chart1=new Tee.Chart();
 +
Drawing
 +
Charts are rendered to canvas when calling the draw method:
 +
Chart1.draw();
  
<span>User</span><span> Guide</span>
+
== Bounds and position ==
 +
The default xy position of charts inside canvas is 0,0  (left-top corner), and the default size is the same as the associated canvas.
 +
You can override them by changing the chart bounds property:
 +
Chart1.bounds.x=50; <br />Chart1.bounds.y=20;
 +
Chart1.bounds.width=200;
 +
Chart1.bounds.height=150;
 +
== Format ==
 +
Most objects (like Series, Annotations and chart sub-objects) include a "format" property to
 +
group all visual attributes in a common place.
 +
The [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Format.html Format] class provides the following properties:<br />
 +
'''fill'''<br />  A color in css string format, for example:  #123456,  rgb(255,0,0),   rgba(0,255,0,0.5),  "blue"
 +
Chart1.panel.format.fill = "blue";
 +
'''round'''<br />  Amount in pixels of roundness of rectangle corners (x: horizontal, y: vertical)
 +
Chart1.panel.format.round = { x:10, y:10 }
 +
Chart1.legend.format.round.y = 5;
 +
'''transparency'''<br />  Amount of semi-glass effect, from 0 to 1. (default is zero)
 +
Chart1.legend.format.transparency = 0.5;
 +
'''shadow'''<br /> Properties to control drop-shadow visibility behind filled shapes or stroked lines.<br />
 +
var s = Chart1.panel.format.shadow;
 +
s.visible = true;
 +
s.width = 4;        // can be negative for left-side shadow
 +
s.height = 4;     // can be negative for top-side shadow
 +
s.blur = 5;
 +
s.color = "silver";
 +
'''gradient'''<br /> 
 +
Attributes to fill shapes using a gradient of colors:
 +
var g = Chart1.panel.format.gradient;
 +
g.visible = true;
 +
g.colors = [ "red", "yellow", "green" ];  // array of colors
 +
g.stops = [ 0, 0.1, 1 ];   //  percentages from 0 to 1 for each color (default is null, automatic)
 +
// "bottomtop", "leftright", "rightleft", "radial", "diagonalup", "diagonaldown"
 +
g.direction = "topbottom";  
 +
'''stroke'''<br /> Attributes used to draw lines and outlines around filled shapes:
 +
 var s = Chart1.panel.format.stroke;
 +
s.fill = "black";
 +
s.size = 4;             // line thickness
 +
s.join = "round";    // segment joins ("round", "miter", "bevel" )
 +
s.cap = "square";   // ending line terminators ("square", "butt", "round" )
 +
s.dash = [ 5,10 ];   // dot-dash... array of pixels (default is null to draw solid lines)
 +
s.gradient.visible = true;   // gradient object with colors, direction, etc
 +
'''font'''<br />  Properties to display text:
 +
var f = Chart1.title.format.font;
 +
f.style = "22px Verdana";     // or: "bold italic 14px Tahoma", etc, etc
 +
f.fill = "blue";
 +
f.shadow.visible = true;    // text drop-shadow
 +
f.stroke.fill = "white";        // draws an outline around text
 +
f.gradient.visible = true;   // fills text with gradient instead of using font.fill
 +
f.textAlign = "center";    // horizontal alignment: "start", "end", "left", "center", "right"
 +
// vertical alignment: "top", "middle", "bottom", "alphabetic", "hanging", "ideographic"
 +
f.baseLine = "top";   
  
<span></span>
+
== Background ==
 +
The chart background appearance is controlled by the "panel" sub-object:
 +
Chart1.panel.transparent = false;
 +
The panel property includes a format subproperty to control background's appearance:
 +
Chart1.panel.format.gradient.visible = true;
 +
Chart1.panel.format.shadow.color="black";
 +
... etc
  
=== <span class="c10">Rev. 1.0, March 2012</span> ===
+
== Title and Footer ==
 +
These two chart properties are used to display text at chart top and bottom sides:
 +
Chart1.title.text = "Hello";
 +
Chart1.footer.text = "World";
 +
Multiple-line text is done by adding "\n" line-feed delimiters:
 +
Chart1.title.text = "Hello \n World";
 +
Title and Footer are Annotation-derived objects, and such they inherit the "format" sub-properties:
 +
Chart1.title.visible = true;
 +
Chart1.title.transparent = false;
 +
Chart1.title.format.gradient.visible = true;
 +
Chart1.title.format.round.x=20;
 +
== Adding data to series ==
 +
Data is added to a chart using "[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Series.html Series]" objects.
 +
Multiple series can exist in the same chart. Each series can be of a different type ([http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Line.html line], [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Area.html area], [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Bar.html bar], [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Pie.html pie], etc) so you can mix several styles altogether.
 +
Direct data:
 +
The simplest way to add data to a chart is by passing an array of values at chart construction time:
 +
var Chart1=new Tee.Chart("canvas1", [ 5,6,2,9,1] );
 +
This creates a new series object of type Tee.Bar by default, and assigns the array to series.data.values property.
 +
Multiple series are created when passing a multi-dimensional array:
 +
var Chart1=new Tee.Chart("canvas1", [ [ 5,6,2,9,1], [ 8,4,3,7,5] ] );
 +
The default series style Tee.Bar can be changed passing a type parameter:
 +
var Chart1=new Tee.Chart("canvas1", [ [ 5,6,2,9,1], [ 8,4,3,7,5] ] , Tee.Area);
 +
Creating series:
 +
Series are manually added into a chart using the addSeries method:
 +
var bar =Chart1.addSeries(new Tee.Bar());
 +
Series have a default "title" string property that is used at chart legend.
 +
When series are added to a chart, title is assigned to "Series" plus the series index in the [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Chart.html#series Chart1.series.items] array ("Series1", "Series2" and so on).
 +
You can override the default title:
 +
bar.title = "My Data";
 +
By default series are empty, they contain no data.
 +
For testing purposes its handy to add random values, for example:
 +
Chart1.addSeries(new Tee.Line()).addRandom(1000);  // Thousand random points
 +
Data can be specified inline when creating the series:
 +
Chart1.addSeries(new Tee.Pie( [ 10, 20, 30, 40 ] ));
 +
All data is stored under the series "data" property arrays.
 +
You can access and modify data directly:
 +
var a = new Tee.Area();
 +
Chart1.addSeries( a );
 +
a.data.values =  [ 10, 20, 30, 40 ];
 +
Each series point has an associated text label. By default, labels are empty. You can modify them using the data.labels property:
 +
a.data.labels =  [ "a", "b", "c", "d" ];
 +
Some series allow specifying point positions or other point parameters.
 +
For example, [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Line.html Line] and [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.PointXY.html PointXY] series can optionally display each line segment or point at a specific "X" axis coordinate:
 +
var p = new Tee.PointXY();
 +
p.data.values = [5, 7, 9];
 +
p.data.x = [0.23, 14, 16];
 +
Chart1.addSeries(p);
 +
Other series like [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Bubble.html Bubble] have a "data.radius" array, and [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Candle.html Candle] series have data.open, data.close, data.high and data.low arrays.
 +
Adding data from other sources
 +
Several helper functions are provided in a separate script (teechart-table.js) to import data from different sources (see the online demos for details), for example:
 +
From a textarea html element:
 +
Chart1.addSeries(new Tee.Bar(document.getElementById("data")) );
 +
&lt;textarea id="data" rows="20" cols="20" wrap="off"&gt;<br />  7,Apples<br />  4<br />  3,Oranges<br />  9<br />  1,Banana<br />  6,Kiwis<br />  2&lt;/textarea&gt;
 +
From a table html element:
 +
Chart1.fromTable('table1', Tee.Bar, true, 0,0);
 +
&lt;table id="table1"&gt;...&lt;/table&gt;<br />
 +
From a text file URL:
 +
// Warning: data file url should be at "same domain origin"
 +
Chart1.addSeries(new Tee.Bar("http://myweb.com/mydata.txt"));
 +
From another series in same or different chart:
 +
// Simply assign the "data" property from one series to another:
 +
Chart1.series.items[0].data = Chart2.series.items[3].data;
 +
From xml formatted text:
 +
  var b=Chart1.addSeries(new Tee.Bar());<br />  b.loadXML(document.getElementById("xml"));
 +
...<br />&lt;textarea id="xml" rows="10" cols="60" "wrap="off"&gt;<br />&lt;series name="Friends" color="Blue" metric="Quantity"&gt;<br />  &lt;point name="Facebook" value="123"/&gt;<br />  &lt;point name="Twitter" value="456"/&gt;<br />  &lt;point name="Google " value="789"/&gt;<br />&lt;/series&gt;<br />&lt;/textarea&gt;<br />
 +
From JSON formatted text:
 +
var b=Chart1.addSeries(new Tee.Bar());<br />b.loadJSON(document.getElementById("json"));
  
=== [[Image:image00.png]]<span class="c10"><br /></span><span class="c7 c10">[http://www.steema.com www.steema.com]</span> ===
+
== The Legend ==
 +
The indicator where series names and series points are displayed is called the [http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Chart.Legend.html legend.]
 +
Several properties can be used to customize the legend behaviour and appearance.
 +
Chart1.legend.visible = true;
 +
Chart1.legend.transparent = false;
 +
Chart1.legend.format.fill = "yellow";
 +
Legend position and orientation:
 +
Chart1.legend.position = "left";  // "top", "bottom", "right"
 +
Chart1.legend.inverted = false;    // draws items in normal order
 +
Select what to display at legend:
 +
Chart1.legend.legendStyle = "values";   // "auto", "series", "values"
 +
Chart1.legend.textStyle = "percentlabel";    // show point value as percent, and point text label
 +
Font and formatting:
 +
Chart1.legend.format.font.style = "20px Arial";
 +
Margins to chart top and chart axes:
 +
// distance from chart edge, percentage from 0 to 100 ( 0 means automatic )
 +
Chart1.legend.align = 0; 
 +
// distance from legend to axes
 +
Chart1.legend.padding = 5;   //  in pixels
 +
Title text on top of items:
 +
Chart1.legend.title.text = "My Legend";
 +
Chart1.legend.title.visible = true;
 +
Symbols next to legend items:
 +
Chart1.legend.symbol.visible = true;
 +
Chart1.legend.symbol.width = 20;
 +
Chart1.legend.symbol.format.shadow.width = 5;
 +
Other legend properties:
 +
Chart1.legend.fontColor = true;  // each item text is painted using its point or series color
 +
Chart1.dividing.fill = "blue";   // draws lines between legend items
 +
== Axes ==
 +
Most Series data are displayed using axes to convert from data values to canvas pixel coordinates.  Some series like Pie and Donut do not use axes.
 +
There exist four default axes inside a chart:  left, top, right and bottom.
 +
var a = Chart1.axes.left;
 +
Each series has two properties that control which horizontal and vertical axes are used.
 +
By default, the horizontal axis is "bottom", and the vertical axis is "left".
 +
Chart1.series.items[0].horizAxis = "top";
 +
Chart1.getSeries(1).vertAxis = "right";
 +
Series can also display using both axes:
 +
Chart1.series.items[2].horizAxis = "both";
 +
Axis visibility is controlled globally by the Chart1.axes.visible property, and individually using the axis visible:
 +
Chart1.axes.visible = true;
 +
Chart1.axes.bottom.visible = true;
 +
Scales are automatically controlled by default. Each axis calculates its minimum and maximum values based on its associated series values and visual properties.
 +
You can override axis automatic scales and set them manually:
 +
var a = Chart1.axes.left;
 +
a.automatic = false;
 +
a.minimum = 50;
 +
a.maximum = 200;
 +
The above code is equivalent to:
 +
Chart1.axes.left.setMinMax( 50, 200 );
 +
Logarithmic scales
 +
Axes scales are linear by default. The log property determines the axis to use natural logarithm scaling instead of linear:
 +
Chart1.axes.left.log = true;
 +
Axis Labelling
 +
Each axis automatically calculates the "best" distance from labels, using labels formatting properties like font.size.  Custom labels can be controlled changing the axis increment property:
 +
Chart1.axes.bottom.increment = 100;   // one label at each 100 values in axis scale.
 +
Increment is zero by default, meaning automatic calculation.
 +
Labels can display series values or series point labels. This is controlled with the labelStyle property:
 +
// options are:  "auto", "none", "value", "mark", "text", "x"
 +
Chart1.axes.left.labels.labelStyle = "text";
 +
When series contain date-time values, labels are formatted according to dateFormat property using [http://blog.stevenlevithan.com/archives/date-time-format Steven Levithan &lt;stevenlevithan.com&gt; date.format.js] library.
 +
Chart1.series.items[0].data.x = [ new Date() ];
 +
Chart1.axes.bottom.labels.dateFormat = "shortDate";
 +
Other properties that control labels:
 +
Chart1.axes.left.labels.alternate = true;  // double quantity of labels
 +
Chart1.axes.right.labels.visible = false;  // show or hide labels
 +
Chart1.axes.left.labels.decimals = 3;    // output numbers with up to 3 fixed decimals
 +
Chart1.axes.bottom.labels.rotation = 90;    // 90 degree rotation
 +
Axis Grids
 +
The axis grid property includes a format to draw grid lines that go across chart axes space.
 +
Chart1.axes.left.grid.visible = true;
 +
When grid fill color is not empty, grids are filled alternatively as "bands":
 +
Chart1.axes.left.grid.format.fill = "red";
 +
Grid lines format is controlled by stroke property:
 +
Chart1.axes.left.grid.format.stroke.size = 5;
 +
Default grid lines are solid lines. The lineDash property displays dash-dot grids:
 +
Chart1.axes.left.grid.lineDash = true;
 +
On browsers that natively support canvas dash strokes, the above code is equivalent to:
 +
Chart1.axes.left.grid.format.stroke.dash = [10,5];   // see "dash" stroke property
 +
Axis Ticks
 +
Axis include ticks an innerTicks properties of type "Ticks", that have a stroke property.
 +
Ticks are drawn from labels to axis. Inner ticks display from axis towards inside.
 +
Chart1.axes.bottom.innerTicks.visible = true;
 +
Chart1.axes.left.ticks.length = 9;
 +
Chart1.axes.top.ticks.stroke.fill = "blue";
 +
Minor Ticks
 +
From tick to tick, the minorTicks axis property can be used to display small sub-ticks:
 +
Chart1.axes.left.minorTicks.visible = true;
 +
Chart1.axes.left.minorTicks.length = 2;
 +
Chart1.axes.left.minorTicks.count = 5;
 +
Chart1.axes.left.minorTicks.stroke.fill = "green";
 +
Axis Title
 +
Close to an axis, the title property is used to display text that identifies the axis:
 +
Chart1.axes.bottom.title.text = "Quantity";
 +
Chart1.axes.bottom.title.text.format.font.fill = "red";
 +
Axis positioning
 +
Size and position of axes is automatic by default.
 +
The axis startPos and endPos properties control the pixel coordinate of axes.
 +
== Axes Wall ==
 +
The rectangular space where axes are painted is called "the back wall".
 +
Formatting is provided using the walls.back property:
 +
Chart1.walls.back.visible = true;
 +
Chart1.walls.back.transparent = false;
 +
Chart1.walls.back.format.gradient.visible = true;
 +
== Series ==
 +
Inheriting from a common Series class, several charting styles are provided, each as a different object class with its own properties and methods.
 +
# Line
 +
# Bar  / Horizontal Bar
 +
# Area / Horizontal Area
 +
# PointXY (scatter)
 +
# Pie
 +
# Donut
 +
# Bubble
 +
# Candle (financial OHLC)
 +
Series Marks
 +
The marks property displays text annotations near series points:
 +
var s = new Tee.Bar();
 +
s.marks.visible = true;
 +
s.marks.style = "percent";
 +
== Series and Colors ==
 +
Charts have a palette property (an array [ ] of colors in string format).
 +
This palette is used by series to paint its points, and by chart legend to display series items symbols.
 +
Chart1.palette = [ "red", "blue", "green", "yellow" ];
 +
Colors in the palette are reused in a circular way when more series or more points in a series exist than the size of the palette.
 +
Series also contain a palette of colors to override the chart palette. By default is a "null" empty array so they share the chart palette.
 +
== Zoom and Scroll ==
 +
Charts can be zoomed and scrolled by manual code or mouse / touch events.
 +
Default behaviour is to drag the right mouse button inside axes to scroll, and drag a rectangle using the left mouse button to zoom / unzoom (zoom dragging to bottom-right direction, and unzoom dragging to left-top direction).
 +
This can be overridden using the chart zoom and scroll properties:
 +
Chart1.zoom.enabled = true;
 +
Chart1.zoom.mouseButton = 0;   // 0=left button, 1=middle, 2=right button
 +
Chart1.zoom.stroke.fill = "yellow";
 +
Chart1.scroll.enabled = true;
 +
Chart1.scroll.mouseButton = 2;
 +
Chart1.scroll.direction = "horizontal";  // can be: "vertical" or "both"
 +
The chart onzoom event is triggered when the user releases the mouse button after the chart is zoomed.
 +
The chart onscroll event is triggered while the user is scrolling the chart by dragging it.
 +
== Exporting a Chart ==
 +
To obtain a PNG or JPEG image from a chart, you can use the canvas toDataURL method, or the included toImage function:
 +
Chart1.toImage( "img" );   // fills &lt;img id="img"&gt; element with chart as PNG image.
 +
Chart1.toImage( "img" , "jpg", 90 );   // fills image with a jpeg image with 90% compression
 +
== Charting Tools ==
 +
Some features are implemented as a "tool" objects.  These objects can be added to a chart tools array property to activate them.<br />
 +
'''Annotations'''<br />
 +
Custom text can be displayed at any chart position using annotation tools:
 +
Chart1.tools.add( new Tee.Annotation( Chart1, "Hello", 50, 50 ) );
 +
The annotation object has a format, text and position properties.
 +
Annotations can also act as buttons when using the onclick event:
 +
var  b1=new Tee.Annotation(Chart1, "button 1", 100, 100);
 +
b1.cursor="pointer";
 +
b1.onclick=function(button,x,y) { alert("Clicked button 1"); }
 +
Chart1.tools.add( b1 );
 +
'''Tooltips'''<br />
 +
This tool displays series data when moving the mouse over series data point.
 +
var  tip=new Tee.ToolTip(Chart1);
 +
tip.format.font.style="16px Tahoma";
 +
Chart1.tools.add(tip);
 +
The ToolTip tool provides onshow, onhide and ongettext events.<br />
 +
'''Cursors'''<br />
 +
Draggable cursor lines are implemented as a tool object:
 +
var t=new Tee.CursorTool(Chart1);
 +
t.format.stroke.size=2;
 +
t.format.stroke.fill="#BB0000";
 +
Chart1.tools.add(t);
 +
The cursor tool includes a direction property (to display cursor as an horizontal line, vertical or both) and an onchange event that is triggered when the cursor is dragged.<br />
 +
'''Dragging Points'''<br />
 +
The DragTool implements mouse / touch point dragging.
 +
Chart1.tools.add(new Tee.DragTool(Chart1));
 +
Includes onchanging and onchanged events.
 +
The target property determines which series and which series point index is being dragged.<br />
 +
'''Slider'''<br />
 +
A generic slider control that can be used inside a chart to change any value.
 +
var slider=new Tee.Slider(Chart1);
 +
slider.min=1;
 +
slider.max=100;
 +
slider.position=10;
 +
slider.thumbSize=12;
 +
slider.horizontal=true;
 +
slider.bounds.x=50;
 +
slider.bounds.y=10;
 +
slider.bounds.width=150;
 +
slider.bounds.height=20;
 +
slider.onChanging=function(slider,value) {
 +
    Chart1.title.format.font.style = value.toFixed(0) " Verdana";
 +
    return value;
 +
  }
 +
  Chart1.tools.add(slider);<br />
 +
'''Scroller'''<br />
 +
The scroller tool displays a simplified view of another chart and allows scrolling it.
 +
Please refer to [http://www.steema.com/files/public/teechart/html5/jscript/demos/extra/scroller.htm this demo] for a complete example.
  
<span></span>
+
== Series Animations ==
 
+
Simple animations performed by changing axis scales or rotating transformations:
<span></span>
+
  var a=new Tee.SeriesAnimation(Chart1);
 
+
  a.duration=500; // milliseconds
==  ==
+
  Chart1.tools.add(a);
 
+
The animate method to start the animation can be called for example from an html button:
# <span class="c7">[#h.5aasyc8efz27 Introduction]</span>
+
&lt;BUTTON type="button" onclick="Chart1.tools.items[0].animate();"&gt;Animate&lt;/BUTTON&gt;
# <span class="c7">[#h.uo65ckhz2255 The Tee namespace]</span>
+
== Acknowledgements ==
# <span class="c7">[#h.9kdvcpaijarh The Canvas]</span>
+
The following are libraries and code snippets that have been used to develop TeeChart for Javascript:
# <span class="c7">[#h.z8hzcw8aygpa Bounds and position]</span>
+
[http://blog.stevenlevithan.com/archives/date-time-format date.format.js] by Steven Levithan
# <span class="c7">[#h.ajm83yle9kyv Format]</span>
+
Used by chart axes to format date-time string labels from series data. (See axis dateFormat property).
# <span class="c7">[#h.wzimsamdqjvo Background]</span>
+
[http://scaledinnovation.com/analytics/splines/aboutSplines.html splines] Copyright 2010 by Robin W. Spencer
# <span class="c7">[#h.x6ai963c0auo Title and Footer]</span>
+
Custom modified code to draw smooth curves between series points (Line, Area, etc).
# <span class="c7">[#h.w0yogj4s6fau Adding data to series]</span>
+
[http://jquery.org/ JQuery.js], [http://www.json.org/ JSON] and [http://threejs.org/ Three.js] are technologies used in TeeChart online demos that are optional (not required by TeeChart).
# <span class="c7">[#h.dbxarmn89fbq The Legend]</span>
+
# <span class="c7">[#h.9dndi52jbc3h Axes]</span>
+
# <span class="c7">[#h.lcg67chm65vm Axes Wall]</span>
+
# <span class="c7">[#h.ohnbslgr4xs2 Series]</span>
+
# <span class="c7">[#h.bx72e5n6jt6y Series and Colors]</span>
+
# <span class="c7">[#h.5hwd8zlu10n6 Zoom and Scroll]</span>
+
# <span class="c7">[#h.fr09v96kok89 Exporting a Chart]</span>
+
# <span class="c7">[#h.lujew5980kvc Charting Tools]</span>
+
# <span class="c7">[#h.4lem8wtepfp1 Acknowledgements]</span>
+
 
+
<span></span>
+
 
+
<span></span>
+
 
+
==  ==
+
 
+
== <span>Introduction</span> ==
+
 
+
<span></span>
+
 
+
<span>This document explains in detail how to create charts and graphs using the TeeChart for Javascript library.</span>
+
 
+
<span></span>
+
 
+
<span>Adding charts to your web pages or applications is fun and easy, see the one-minute </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/TeeChart for Javascript Getting Started Guide.html Starting Guide]</span><span>, play with the </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/demos/ Online Demos]</span><span> or discover the full </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/index.html TeeChart API Reference]</span><span>.</span>
+
 
+
<span></span>
+
 
+
<span>Compared with other programming environments (Java, .NET, Delphi VCL / FireMonkey, etc), the TeeChart Javascript api implements an essential subset of features in order to minimize both the script size and coding complexity.</span>
+
 
+
<span></span>
+
 
+
<span>Current script sizes are </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/src/teechart.js 64KB]</span><span> (minified) and 13KB (gzipped)</span>
+
 
+
== <span>The Tee namespace</span> ==
+
 
+
<span></span>
+
 
+
<span>Full code is wrapped around a single €œ</span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.html Tee]</span><span>€ identifier (namespace) to avoid cluttering the browser Window global space.  Several €œclasses€ in an object-oriented manner exist Inside the Tee namespace, being </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Chart.html Tee.Chart]</span><span> the main class that defines a chart.</span>
+
 
+
<span></span>
+
 
+
== <span>The Canvas</span> ==
+
 
+
<span></span>
+
 
+
<span>Charts are displayed by default using </span><span class="c7">[http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html HTML5 Canvas]</span><span> elements. The main class €œTee.Chart€ should be initialized passing the &lt;canvas&gt; element or its id as string:</span>
+
 
+
<span></span>
+
 
+
<span class="c14">&lt;canvas id="canvas1" width="300" height="200"&gt;&lt;/canvas&gt;</span>
+
 
+
<span class="c14"></span>
+
 
+
<span class="c11">Using the canvas id:</span>
+
 
+
<span></span>
+
 
+
<span class="c3 c6">var Chart1=new Tee.Chart("canvas1");</span>
+
 
+
<span>€¦</span>
+
 
+
<span></span>
+
 
+
<span class="c11">Or using the element:</span>
+
 
+
<span class="c11"></span>
+
 
+
<span class="c3 c6">var Chart1=new Tee.Chart(document.getElementById("canvas1"));</span>
+
 
+
<span></span>
+
 
+
<span>Hidden charts can be created without passing any canvas parameter:</span>
+
 
+
<span><br /></span><span class="c3 c6">var Chart1=new Tee.Chart();</span>
+
 
+
<span class="c6"></span>
+
 
+
<span class="c6"></span>
+
 
+
<span class="c6">Drawing</span>
+
 
+
<span></span>
+
 
+
<span>Charts are rendered to canvas when calling the draw method:</span>
+
 
+
<span></span>
+
 
+
<span class="c3 c6">Chart1.draw();</span>
+
 
+
== <span>Bounds and position</span> ==
+
 
+
<span></span>
+
 
+
<span>The default xy position of charts inside canvas is 0,0  (left-top corner), and the default size is the same as the associated canvas.</span>
+
 
+
<span>You can override them by changing the chart bounds property:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.bounds.x=50; <br />Chart1.bounds.y=20; </span>
+
 
+
<span class="c3">Chart1.bounds.width=200; </span>
+
 
+
<span class="c3">Chart1.bounds.height=150;</span>
+
 
+
<span></span>
+
 
+
== <span>Format</span> ==
+
 
+
<span></span>
+
 
+
<span>Most objects (like Series, Annotations and chart sub-objects) include a €œformat€ property to </span>
+
 
+
<span>group all visual attributes in a common place.</span>
+
 
+
<span></span>
+
 
+
<span>The </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Format.html Format]</span><span> class provides the following properties:</span>
+
 
+
<span></span>
+
 
+
<span class="c6">fill</span><span><nowiki>:  A color in css string format, for example:  #123456,  rgb(255,0,0),   rgba(0,255,0,0.5),  €œblue€</nowiki></span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.panel.format.fill = €œblue€;</span>
+
 
+
<span></span>
+
 
+
<span class="c6">round</span><span><nowiki>:  Amount in pixels of roundness of rectangle corners (x: horizontal, y: vertical)</nowiki></span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.panel.format.round = { x:10, y:10 }</span>
+
 
+
<span class="c3">Chart1.legend.format.round.y = 5;</span>
+
 
+
<span></span>
+
 
+
<span class="c6">transparency</span><span><nowiki>:  Amount of semi-glass effect, from 0 to 1. (default is zero)</nowiki></span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.legend.format.transparency = 0.5;</span>
+
 
+
<span></span>
+
 
+
<span class="c6">shadow</span><span><nowiki>: Properties to control drop-shadow visibility behind filled shapes or stroked lines.</nowiki></span>
+
 
+
<span></span>
+
 
+
<span class="c3">   var s = Chart1.panel.format.shadow;</span>
+
 
+
<span class="c3">   s.visible = true;</span>
+
 
+
<span class="c3">   s.width = 4;        </span><span>// can be negative for left-side shadow</span>
+
 
+
<span class="c3">   s.height = 4;     </span><span>// can be negative for top-side shadow</span>
+
 
+
<span class="c3">   s.blur = 5;</span>
+
 
+
<span class="c3">   s.color = €œsilver€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c6">gradient:  </span><span>Attributes to fill shapes using a gradient of colors:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">  var g = Chart1.panel.format.gradient;</span>
+
 
+
<span class="c3">  g.visible = true;</span>
+
 
+
<span class="c3">  g.colors = [ €œred€, €œyellow€, €œgreen€ ];</span><span>  // array of colors </span>
+
 
+
<span>  </span><span class="c3">g.stops = [ 0, 0.1, 1 ]; </span><span>  //  percentages from 0 to 1 for each color (default is null, automatic)</span>
+
 
+
<span></span>
+
 
+
<span>  // €œbottomtop€, €œleftright€, €œrightleft€, €œradial€, €œdiagonalup€, €œdiagonaldown€</span>
+
 
+
<span>  </span><span class="c3">g.direction = €œtopbottom€; </span><span>  </span>
+
 
+
<span></span>
+
 
+
<span class="c6">stroke: </span><span>Attributes used to draw lines and outlines around filled shapes:</span>
+
 
+
<span></span>
+
 
+
<span>    </span><span class="c3">var s = Chart1.panel.format.stroke;</span>
+
 
+
<span class="c3">    s.fill = €œblack€;</span>
+
 
+
<span class="c3">    s.size = 4;</span><span>             // line thickness</span>
+
 
+
<span>    </span><span class="c3">s.join = €œround€;</span><span>    // segment joins (€œround€, €œmiter€, €œbevel€ )</span>
+
 
+
<span>    </span><span class="c3">s.cap = €œsquare€;</span><span>   // ending line terminators (€œsquare€, €œbutt€, €œround€ )</span>
+
 
+
<span>    </span><span class="c3">s.dash = [ 5,10 ];</span><span>   // dot-dash... array of pixels (default is null to draw solid lines)</span>
+
 
+
<span>    </span><span class="c3">s.gradient.visible = true;</span><span>   // gradient object with colors, direction, etc</span>
+
 
+
<span></span>
+
 
+
<span class="c6">font</span><span><nowiki>:  Properties to display text:</nowiki></span>
+
 
+
<span></span>
+
 
+
<span>   </span><span class="c3">var f = Chart1.title.format.font;</span>
+
 
+
<span class="c3">   f.style = €œ22px Verdana€; </span><span>    // or: €œbold italic 14px Tahoma€, etc, etc</span>
+
 
+
<span>  </span><span class="c3"> f.fill = €œblue€;</span>
+
 
+
<span class="c3">   f.shadow.visible = true;    </span><span>// text drop-shadow</span>
+
 
+
<span class="c3">   f.stroke.fill = €œwhite€;</span><span>        // draws an outline around text</span>
+
 
+
<span>  </span><span class="c3"> f.gradient.visible = true;</span><span>   // fills text with gradient instead of using font.fill</span>
+
 
+
<span>   </span><span class="c3">f.textAlign = €œcenter€;</span><span>    // horizontal alignment: €œstart€, €œend€, €œleft€, €œcenter€, €œright€</span>
+
 
+
<span></span>
+
 
+
<span>   // vertical alignment: €œtop€, €œmiddle€, €œbottom€, €œalphabetic€, €œhanging€, €œideographic€</span>
+
 
+
<span>   </span><span class="c3">f.baseLine = €œtop€;</span><span>    </span>
+
 
+
== <span>Background</span> ==
+
 
+
<span></span>
+
 
+
<span>The chart background appearance is controlled by the €œpanel€ sub-object:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.panel.transparent = false;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>The panel property includes a format subproperty to control background€™s appearance:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.panel.format.gradient.visible = true;</span>
+
 
+
<span class="c3">Chart1.panel.format.shadow.color=€black€;</span>
+
 
+
<span class="c3">€¦ etc</span>
+
 
+
== <span>Title and Footer</span> ==
+
 
+
<span></span>
+
 
+
<span>These two chart properties are used to display text at chart top and bottom sides:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.title.text = €œHello€;</span>
+
 
+
<span class="c3">Chart1.footer.text = €œWorld€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Multiple-line text is done by adding €œ\n€ line-feed delimiters:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.title.text = €œHello \n World€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Title and Footer are Annotation-derived objects, and such they inherit the €œformat€ sub-properties:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.title.visible = true;</span>
+
 
+
<span class="c3">Chart1.title.transparent = false;</span>
+
 
+
<span class="c3">Chart1.title.format.gradient.visible = true;</span>
+
 
+
<span class="c3">Chart1.title.format.round.x=20;</span>
+
 
+
== <span>Adding data to series</span> ==
+
 
+
<span></span>
+
 
+
<span>Data is added to a chart using €œ</span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Series.html Series]</span><span>€ objects.</span>
+
 
+
<span>Multiple series can exist in the same chart. Each series can be of a different type (</span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Line.html line]</span><span>, </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Area.html area]</span><span>, </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Bar.html bar]</span><span>, </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Pie.html pie]</span><span>, etc) so you can mix several styles altogether.</span>
+
 
+
<span></span>
+
 
+
<span class="c6">Direct data:</span>
+
 
+
<span></span>
+
 
+
<span>The simplest way to add data to a chart is by passing an array of values at chart construction time:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var Chart1=new Tee.Chart("canvas1", [ 5,6,2,9,1] );</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>This creates a new series object of type Tee.Bar by default, and assigns the array to series.data.values property.</span>
+
 
+
<span></span>
+
 
+
<span>Multiple series are created when passing a multi-dimensional array:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var Chart1=new Tee.Chart("canvas1", [ [ 5,6,2,9,1], [ 8,4,3,7,5] ] );</span>
+
 
+
<span></span>
+
 
+
<span>The default series style Tee.Bar can be changed passing a type parameter:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var Chart1=new Tee.Chart("canvas1", [ [ 5,6,2,9,1], [ 8,4,3,7,5] ] , Tee.Area);</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c6">Creating series:</span>
+
 
+
<span></span>
+
 
+
<span>Series are manually added into a chart using the addSeries method:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var bar =Chart1.addSeries(new Tee.Bar());</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Series have a default €œtitle€ string property that is used at chart legend.</span>
+
 
+
<span>When series are added to a chart, title is assigned to €œSeries€ plus the series index in the </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Chart.html#series Chart1.series.items]</span><span> array (€œSeries1€, €œSeries2€ and so on).</span>
+
 
+
<span></span>
+
 
+
<span>You can override the default title:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">bar.title = €œMy Data€;</span>
+
 
+
<span></span>
+
 
+
<span>By default series are empty, they contain no data.</span>
+
 
+
<span>For testing purposes its handy to add random values, for example:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.addSeries(new Tee.Line()).addRandom(1000);</span><span>  // Thousand random points</span>
+
 
+
<span></span>
+
 
+
<span>Data can be specified inline when creating the series:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.addSeries(new Tee.Pie( [ 10, 20, 30, 40 ] ));</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>All data is stored under the series €œdata€ property arrays.</span>
+
 
+
<span>You can access and modify data directly:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var a = new Tee.Area();</span>
+
 
+
<span class="c3">Chart1.addSeries( a );</span>
+
 
+
<span class="c3">a.data.values =  [ 10, 20, 30, 40 ];</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Each series point has an associated text label. By default labels are empty, you can modify them using the data.labels property:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">a.data.labels =  [ €œa€, €œb€, €œc€, €œd€ ];</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Some series allow specifying point positions or other point parameters.</span>
+
 
+
<span>For example, </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Line.html Line]</span><span> and </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.PointXY.html PointXY]</span><span> series can optionally display each line segment or point at a specific €œX€ axis coordinate:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var p = new Tee.PointXY();</span>
+
 
+
<span class="c3">p.data.values = [5, 7, 9];</span>
+
 
+
<span class="c3">p.data.x = [0.23, 14, 16];</span>
+
 
+
<span class="c3">Chart1.addSeries(p);</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Other series like</span><span class="c3"> </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Bubble.html Bubble]</span><span> have a €œdata.radius€ array, and </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Candle.html Candle]</span><span> series have data.open, data.close, data.high and data.low arrays.</span>
+
 
+
<span></span>
+
 
+
<span class="c6">Adding data from other sources</span>
+
 
+
<span class="c6 c15"></span>
+
 
+
<span>Several helper functions are provided in a separate script (teechart-table.js) to import data from different sources (see the online demos for details), for example:</span>
+
 
+
<span></span>
+
 
+
<span class="c11">From a textarea html element:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.addSeries(new Tee.Bar(document.getElementById("data")) );</span>
+
 
+
<span class="c3">&lt;textarea id="data" rows="20" cols="20" wrap="off"&gt;<br />  7,Apples<br />  4<br />  3,Oranges<br />  9<br />  1,Banana<br />  6,Kiwis<br />  2&lt;/textarea&gt;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c11">From a table html element:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.fromTable('table1', Tee.Bar, true, 0,0);</span>
+
 
+
<span class="c3">&lt;table id=€table1€&gt;...&lt;/table&gt;</span><span><br /></span>
+
 
+
<span class="c11">From a text file URL:</span>
+
 
+
<span></span>
+
 
+
<span>// Warning: data file url should be at €œsame domain origin€ </span>
+
 
+
<span class="c3">Chart1.addSeries(new Tee.Bar(€œhttp://myweb.com/mydata.txt€));</span>
+
 
+
<span></span>
+
 
+
<span class="c11">From another series in same or different chart:</span>
+
 
+
<span></span>
+
 
+
<span>// Simply assign the €œdata€ property from one series to another:</span>
+
 
+
<span class="c3">Chart1.series.items[0].data = Chart2.series.items[3].data;</span>
+
 
+
<span></span>
+
 
+
<span class="c11">From xml formatted text:</span>
+
 
+
<span></span>
+
 
+
<span class="c3"> var b=Chart1.addSeries(new Tee.Bar());<br />  b.loadXML(document.getElementById("xml"));</span>
+
 
+
<span class="c3">...<br />&lt;textarea id="xml" rows="10" cols="60" "wrap="off"&gt;<br />&lt;series name="Friends" color="Blue" metric="Quantity"&gt;<br />  &lt;point name="Facebook" value="123"/&gt;<br />  &lt;point name="Twitter" value="456"/&gt;<br />  &lt;point name="Google " value="789"/&gt;<br />&lt;/series&gt;<br />&lt;/textarea&gt;<br /></span>
+
 
+
<span class="c11">From JSON formatted text:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var b=Chart1.addSeries(new Tee.Bar());<br />b.loadJSON(document.getElementById("json"));</span>
+
 
+
<span class="c3"></span>
+
 
+
<span></span>
+
 
+
== <span>The Legend</span> ==
+
 
+
<span></span>
+
 
+
<span>The indicator where series names and series points are displayed is called the </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/docs/tee/symbols/Tee.Chart.Legend.html legend.]</span>
+
 
+
<span>Several properties can be used to customize the legend behaviour and appearance.</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.legend.visible = true;</span>
+
 
+
<span class="c3">Chart1.legend.transparent = false;</span>
+
 
+
<span class="c3">Chart1.legend.format.fill = €œyellow€;</span>
+
 
+
<span></span>
+
 
+
<span>Legend position and orientation:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.legend.position = €œleft€;</span><span>  // €œtop€, €œbottom€, €œright€</span>
+
 
+
<span class="c3">Chart1.legend.inverted = false;</span><span>    // draws items in normal order</span>
+
 
+
<span></span>
+
 
+
<span>Select what to display at legend:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.legend.legendStyle = €œvalues€;</span><span>   // €œauto€, €œseries€, €œvalues€</span>
+
 
+
<span class="c3">Chart1.legend.textStyle = €œpercentlabel€;</span><span>    // show point value as percent, and point text label</span>
+
 
+
<span></span>
+
 
+
<span>Font and formatting:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.legend.format.font.style = €œ20px Arial€;</span>
+
 
+
<span></span>
+
 
+
<span>Margins to chart top and chart axes:</span>
+
 
+
<span></span>
+
 
+
<span>// distance from chart edge, percentage from 0 to 100 ( 0 means automatic )</span>
+
 
+
<span class="c3">Chart1.legend.align = 0;</span><span>  </span>
+
 
+
<span class="c3"></span>
+
 
+
<span>// distance from legend to axes</span>
+
 
+
<span class="c3">Chart1.legend.padding = 5;</span><span>   //  in pixels</span>
+
 
+
<span></span>
+
 
+
<span>Title text on top of items:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.legend.title.text = €œMy Legend€;</span>
+
 
+
<span class="c3">Chart1.legend.title.visible = true;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Symbols next to legend items:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.legend.symbol.visible = true;</span>
+
 
+
<span class="c3">Chart1.legend.symbol.width = 20;</span>
+
 
+
<span class="c3">Chart1.legend.symbol.format.shadow.width = 5;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Other legend properties:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.legend.fontColor = true;</span><span>  // each item text is painted using its point or series color</span>
+
 
+
<span class="c3">Chart1.dividing.fill = €œblue€;</span><span>   // draws lines between legend items</span>
+
 
+
<span></span>
+
 
+
== <span>Axes</span> ==
+
 
+
<span></span>
+
 
+
<span>Most Series data are displayed using axes to convert from data values to canvas pixel coordinates.  Some series like Pie and Donut do not use axes.</span>
+
 
+
<span></span>
+
 
+
<span>There exist four default axes inside a chart:  left, top, right and bottom.</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var a = Chart1.axes.left;</span>
+
 
+
<span></span>
+
 
+
<span>Each series has two properties that control which horizontal and vertical axes are used.</span>
+
 
+
<span>By default, the horizontal axis is €œbottom€, and the vertical axis is €œleft€.</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.series.items[0].horizAxis = €œtop€;</span>
+
 
+
<span class="c3">Chart1.getSeries(1).vertAxis = €œright€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Series can also display using both axes:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.series.items[2].horizAxis = €œboth€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Axis visibility is controlled globally by the Chart1.axes.visible property, and individually using the axis visible:</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c3">Chart1.axes.visible = true;</span>
+
 
+
<span class="c3">Chart1.axes.bottom.visible = true;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Scales are automatically controlled by default. Each axis calculates its minimum and maximum values based on its associated series values and visual properties.</span>
+
 
+
<span></span>
+
 
+
<span>You can override axis automatic scales and set them manually:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var a = Chart1.axes.left;</span>
+
 
+
<span class="c3">a.automatic = false;</span>
+
 
+
<span class="c3">a.minimum = 50;</span>
+
 
+
<span class="c3">a.maximum = 200;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>The above code is equivalent to:</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c3">Chart1.axes.left.setMinMax( 50, 200 );</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c6">Logarithmic scales</span>
+
 
+
<span></span>
+
 
+
<span>Axes scales are linear by default. The log property determines the axis to use natural logarithm scaling instead of linear:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.axes.left.log = true;</span>
+
 
+
<span></span>
+
 
+
<span class="c6">Axis Labelling</span>
+
 
+
<span></span>
+
 
+
<span>Each axis automatically calculates the €œbest€ distance from labels, using labels formatting properties like font.size.  Custom labels can be controlled changing the axis increment property:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.axes.bottom.increment = 100;</span><span>   // one label at each 100 values in axis scale.</span>
+
 
+
<span></span>
+
 
+
<span>Increment is zero by default, meaning automatic calculation.</span>
+
 
+
<span></span>
+
 
+
<span>Labels can display series values or series point labels. This is controlled with the labelStyle property:</span>
+
 
+
<span></span>
+
 
+
<span>// options are:  €œauto€, €œnone€, €œvalue€, €œmark€, €œtext€, €œx€</span>
+
 
+
<span class="c3">Chart1.axes.left.labels.labelStyle = €œtext€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>When series contain date-time values, labels are formatted according to dateFormat property using </span><span class="c7">[http://blog.stevenlevithan.com/archives/date-time-format Steven Levithan &lt;stevenlevithan.com&gt; date.format.js]</span><span> library.</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.series.items[0].data.x = [ new Date() ];</span>
+
 
+
<span class="c3">Chart1.axes.bottom.labels.dateFormat = €œshortDate€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Other properties that control labels:</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c3">Chart1.axes.left.labels.alternate = true;  // double quantity of labels</span>
+
 
+
<span class="c3">Chart1.axes.right.labels.visible = false;  // show or hide labels</span>
+
 
+
<span class="c3">Chart1.axes.left.labels.decimals = 3;    // output numbers with up to 3 fixed decimals</span>
+
 
+
<span class="c3">Chart1.axes.bottom.labels.rotation = 90;    // 90 degree rotation</span>
+
 
+
<span class="c15 c6"></span>
+
 
+
<span class="c6">Axis Grids</span>
+
 
+
<span></span>
+
 
+
<span>The axis grid property includes a format to draw grid lines that go across chart axes space.</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.axes.left.grid.visible = true;</span>
+
 
+
<span></span>
+
 
+
<span>When grid fill color is not empty, grids are filled alternatively as €œbands€:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.axes.left.grid.format.fill = €œred€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>Grid lines format is controlled by stroke property:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.axes.left.grid.format.stroke.size = 5;</span>
+
 
+
<span></span>
+
 
+
<span>Default grid lines are solid lines. The lineDash property displays dash-dot grids:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.axes.left.grid.lineDash = true;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>On browsers that natively support canvas dash strokes, the above code is equivalent to:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.axes.left.grid.format.stroke.dash = [10,5];  </span><span> // see €œdash€ stroke property</span>
+
 
+
<span></span>
+
 
+
<span class="c6">Axis Ticks</span>
+
 
+
<span></span>
+
 
+
<span>Axis include ticks an innerTicks properties of type €œTicks€, that have a stroke property.</span>
+
 
+
<span>Ticks are drawn from labels to axis. Inner ticks display from axis towards inside.</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.axes.bottom.innerTicks.visible = true;</span>
+
 
+
<span class="c3">Chart1.axes.left.ticks.length = 9;</span>
+
 
+
<span class="c3">Chart1.axes.top.ticks.stroke.fill = €œblue€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c6">Minor Ticks</span>
+
 
+
<span></span>
+
 
+
<span>From tick to tick, the minorTicks axis property can be used to display small sub-ticks:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.axes.left.minorTicks.visible = true;</span>
+
 
+
<span class="c3">Chart1.axes.left.minorTicks.length = 2;</span>
+
 
+
<span class="c3">Chart1.axes.left.minorTicks.count = 5;</span>
+
 
+
<span class="c3">Chart1.axes.left.minorTicks.stroke.fill = €œgreen€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c6">Axis Title</span>
+
 
+
<span></span>
+
 
+
<span>Close to an axis, the title property is used to display text that identifies the axis:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.axes.bottom.title.text = €œQuantity€;</span>
+
 
+
<span class="c3">Chart1.axes.bottom.title.text.format.font.fill = €œred€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c6">Axis positioning</span>
+
 
+
<span></span>
+
 
+
<span>Size and position of axes is automatic by default.</span>
+
 
+
<span>The axis startPos and endPos properties control the pixel coordinate of axes.</span>
+
 
+
<span></span>
+
 
+
== <span>Axes Wall</span> ==
+
 
+
<span></span>
+
 
+
<span>The rectangular space where axes are painted is called €œthe back wall€.</span>
+
 
+
<span>Formatting is provided using the walls.back property:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.walls.back.visible = true;</span>
+
 
+
<span class="c3">Chart1.walls.back.transparent = false;</span>
+
 
+
<span class="c3">Chart1.walls.back.format.gradient.visible = true;</span>
+
 
+
<span class="c3"></span>
+
 
+
== <span>Series</span> ==
+
 
+
<span></span>
+
 
+
<span>Inheriting from a common Series class, several charting styles are provided, each as a different object class with its own properties and methods.</span>
+
 
+
<span></span>
+
 
+
# <span>Line</span>
+
# <span>Bar  / Horizontal Bar </span>
+
# <span>Area / Horizontal Area</span>
+
# <span>PointXY (scatter)</span>
+
# <span>Pie</span>
+
# <span>Donut</span>
+
# <span>Bubble</span>
+
# <span>Candle (financial OHLC)</span>
+
 
+
<span></span>
+
 
+
<span class="c6">Series Marks</span>
+
 
+
<span class="c6"></span>
+
 
+
<span>The marks property displays text annotations near series points:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var s = new Tee.Bar();</span>
+
 
+
<span class="c3">s.marks.visible = true;</span>
+
 
+
<span class="c3">s.marks.style = €œpercent€;</span>
+
 
+
<span class="c3"></span>
+
 
+
== <span>Series and Colors</span> ==
+
 
+
<span></span>
+
 
+
<span>Charts have a palette property (an array [ ] of colors in string format).</span>
+
 
+
<span>This palette is used by series to paint its points, and by chart legend to display series items symbols.</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.palette = [ €œred€, €œblue€, €œgreen€, €œyellow€ ];</span>
+
 
+
<span></span>
+
 
+
<span>Colors in the palette are reused in a circular way when more series or more points in a series exist than the size of the palette.</span>
+
 
+
<span></span>
+
 
+
<span>Series also contain a palette of colors to override the chart palette. By default is a €œnull€ empty array so they share the chart palette.</span>
+
 
+
<span></span>
+
 
+
== <span>Zoom and Scroll</span> ==
+
 
+
<span></span>
+
 
+
<span>Charts can be zoomed and scrolled by manual code or mouse / touch events.</span>
+
 
+
<span>Default behaviour is to drag the right mouse button inside axes to scroll, and drag a rectangle using the left mouse button to zoom / unzoom (zoom dragging to bottom-right direction, and unzoom dragging to left-top direction).</span>
+
 
+
<span></span>
+
 
+
<span>This can be overridden using the chart zoom and scroll properties:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.zoom.enabled = true;</span>
+
 
+
<span class="c3">Chart1.zoom.mouseButton = 0;</span><span>   // 0=left button, 1=middle, 2=right button</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.zoom.stroke.fill = €œyellow€;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c3">Chart1.scroll.enabled = true;</span>
+
 
+
<span class="c3">Chart1.scroll.mouseButton = 2;</span>
+
 
+
<span class="c3">Chart1.scroll.direction = €œhorizontal€;</span><span>  // can be: €œvertical€ or €œboth€</span>
+
 
+
<span></span>
+
 
+
<span>The chart onzoom event is triggered when the user releases the mouse button after the chart is zoomed.</span>
+
 
+
<span></span>
+
 
+
<span>The chart onscroll event is triggered while the user is scrolling the chart by dragging it.</span>
+
 
+
<span></span>
+
 
+
== <span>Exporting a Chart</span> ==
+
 
+
<span></span>
+
 
+
<span>To obtain a PNG or JPEG image from a chart, you can use the canvas toDataURL method, or the included toImage function:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.toImage( €œimg€ );</span><span>   // fills &lt;img id=€img€&gt; element with chart as PNG image.</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.toImage( €œimg€ , €œjpg€, 90 );</span><span>   // fills image with a jpeg image with 90% compression</span>
+
 
+
<span></span>
+
 
+
== <span>Charting Tools</span> ==
+
 
+
<span></span>
+
 
+
<span>Some features are implemented as a €œtool€ objects.  These objects can be added to a chart tools array property to activate them.</span>
+
 
+
<span></span>
+
 
+
<span class="c6">Annotations</span>
+
 
+
<span></span>
+
 
+
<span>Custom text can be displayed at any chart position using annotation tools:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">Chart1.tools.add( new Tee.Annotation( Chart1, €œHello€, 50, 50 ) );</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>The annotation object has a format, text and position properties.</span>
+
 
+
<span>Annotations can also act as buttons when using the onclick event:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var  b1=new Tee.Annotation(Chart1, €œbutton 1€, 100, 100);</span>
+
 
+
<span class="c3">b1.cursor="pointer";</span>
+
 
+
<span class="c3">b1.onclick=function(button,x,y) { alert("Clicked button 1"); }</span>
+
 
+
<span class="c3">Chart1.tools.add( b1 );</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c6">Tooltips</span>
+
 
+
<span></span>
+
 
+
<span>This tool displays series data when moving the mouse over series data point.</span>
+
 
+
<span></span>
+
 
+
<span class="c3">var  tip=new Tee.ToolTip(Chart1);</span>
+
 
+
<span class="c3">tip.format.font.style="16px Tahoma";</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c3">Chart1.tools.add(tip);</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>The ToolTip tool provides onshow, onhide and ongettext events.</span>
+
 
+
<span></span>
+
 
+
<span class="c6">Cursors</span>
+
 
+
<span></span>
+
 
+
<span>Draggable cursor lines are implemented as a tool object:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">  var t=new Tee.CursorTool(Chart1);</span>
+
 
+
<span class="c3">  t.format.stroke.size=2;</span>
+
 
+
<span class="c3">  t.format.stroke.fill="#BB0000";</span>
+
 
+
<span class="c3">  Chart1.tools.add(t);</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>The cursor tool includes a direction property (to display cursor as an horizontal line, vertical or both) and an onchange event that is triggered when the cursor is dragged.</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c6">Dragging Points</span>
+
 
+
<span></span>
+
 
+
<span>The DragTool implements mouse / touch point dragging.</span>
+
 
+
<span></span>
+
 
+
<span class="c3">  Chart1.tools.add(new Tee.DragTool(Chart1));</span>
+
 
+
<span></span>
+
 
+
<span>Includes onchanging and onchanged events.</span>
+
 
+
<span>The target property determines which series and which series point index is being dragged.</span>
+
 
+
<span></span>
+
 
+
<span class="c6">Slider</span>
+
 
+
<span></span>
+
 
+
<span>A generic slider control that can be used inside a chart to change any value.</span>
+
 
+
<span></span>
+
 
+
<span class="c3"> var slider=new Tee.Slider(Chart1);</span>
+
 
+
<span class="c3">  slider.min=1;</span>
+
 
+
<span class="c3">  slider.max=100;</span>
+
 
+
<span class="c3">  slider.position=10;</span>
+
 
+
<span class="c3">  slider.thumbSize=12;</span>
+
 
+
<span class="c3">  slider.horizontal=true;</span>
+
 
+
<span class="c3">  slider.bounds.x=50;</span>
+
 
+
<span class="c3">  slider.bounds.y=10;</span>
+
 
+
<span class="c3">  slider.bounds.width=150;</span>
+
 
+
<span class="c3">  slider.bounds.height=20;</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c3">  slider.onChanging=function(slider,value) {</span>
+
 
+
<span class="c3">    Chart1.title.format.font.style = value.toFixed(0) €œ Verdana€;</span>
+
 
+
<span class="c3">    return value;</span>
+
 
+
<span class="c3">  }</span>
+
 
+
<span class="c3"></span>
+
 
+
<span class="c3">  Chart1.tools.add(slider);</span>
+
 
+
<span class="c3"></span>
+
 
+
<span></span>
+
 
+
<span></span>
+
 
+
<span class="c6">Scroller</span>
+
 
+
<span></span>
+
 
+
<span>The scroller tool displays a simplified view of another chart and allows scrolling it.</span>
+
 
+
<span>Please refer to </span><span class="c7">[http://www.steema.com/files/public/teechart/html5/jscript/demos/extra/scroller.htm this demo]</span><span> for a complete example.</span>
+
 
+
<span></span>
+
 
+
== <span>Series Animations</span> ==
+
 
+
<span></span>
+
 
+
<span>Simple animations performed by changing axis scales or rotating transformations:</span>
+
 
+
<span></span>
+
 
+
<span class="c3">  var a=new Tee.SeriesAnimation(Chart1);</span>
+
 
+
<span class="c3">  a.duration=500; // milliseconds</span>
+
 
+
<span class="c3">  Chart1.tools.add(a);</span>
+
 
+
<span class="c3"></span>
+
 
+
<span>The animate method to start the animation can be called for example from an html button:</span>
+
 
+
<span></span>
+
 
+
<span>&lt;BUTTON type="button" onclick="Chart1.tools.items[0].animate();"&gt;Animate&lt;/BUTTON&gt;</span>
+
 
+
==  ==
+
 
+
== <span>Acknowledgements</span> ==
+
 
+
<span></span>
+
 
+
<span></span>
+
 
+
<span>The following are libraries and code snippets that have been used to develop TeeChart for Javascript:</span>
+
 
+
<span></span>
+
 
+
<span></span>
+
 
+
<span class="c7">[http://blog.stevenlevithan.com/archives/date-time-format date.format.js]</span><span> by Steven Levithan</span>
+
 
+
<span>Used by chart axes to format date-time string labels from series data. (See axis dateFormat property).</span>
+
 
+
<span></span>
+
 
+
<span class="c7">[http://scaledinnovation.com/analytics/splines/aboutSplines.html splines]</span><span> Copyright 2010 by Robin W. Spencer</span>
+
 
+
<span>Custom modified code to draw smooth curves between series points (Line, Area, etc).</span>
+
 
+
<span></span>
+
 
+
<span class="c7">[http://jquery.org/ JQuery.js]</span><span>, </span><span class="c7">[http://www.json.org/ JSON]</span><span> and </span><span class="c7">[http://threejs.org/ Three.js]</span><span> are technologies used in TeeChart online demos that are optional (not required by TeeChart).</span>
+
 
+
<span></span>
+
 
+
<span></span>
+
 
+
<div>
+
 
+
<span></span>
+
 
+
</div>
+

Latest revision as of 14:19, 17 October 2014

Html5.png

TeeChart for Javascript User Guide

Rev. 1.0, March 2012

Introduction

This document explains in detail how to create charts and graphs using the TeeChart for Javascript library. Adding charts to your web pages or applications is fun and easy, see the one-minute Starting Guide, play with the Online Demos or discover the full TeeChart API Reference. Compared with other programming environments (Java, .NET, Delphi VCL / FireMonkey, etc), the TeeChart Javascript api implements an essential subset of features in order to minimize both the script size and coding complexity. Current script sizes are 64KB (minified) and 13KB (gzipped)

The Tee namespace

Full code is wrapped around a single "Tee" identifier (namespace) to avoid cluttering the browser Window global space.  Several "classes" in an object-oriented manner exist Inside the Tee namespace, being Tee.Chart the main class that defines a chart.

The Canvas

Charts are displayed by default using HTML5 Canvas elements. The main class "Tee.Chart" should be initialized passing the <canvas> element or its id as string:

<canvas id="canvas1" width="300" height="200"></canvas>

Using the canvas id:

var Chart1=new Tee.Chart("canvas1");

Or using the element:

var Chart1=new Tee.Chart(document.getElementById("canvas1"));

Hidden charts can be created without passing any canvas parameter:


var Chart1=new Tee.Chart();

Drawing Charts are rendered to canvas when calling the draw method:

Chart1.draw();

Bounds and position

The default xy position of charts inside canvas is 0,0  (left-top corner), and the default size is the same as the associated canvas. You can override them by changing the chart bounds property:

Chart1.bounds.x=50; 
Chart1.bounds.y=20; Chart1.bounds.width=200; Chart1.bounds.height=150;

Format

Most objects (like Series, Annotations and chart sub-objects) include a "format" property to group all visual attributes in a common place. The Format class provides the following properties:
fill
 A color in css string format, for example:  #123456,  rgb(255,0,0),   rgba(0,255,0,0.5),  "blue"

Chart1.panel.format.fill = "blue";

round
 Amount in pixels of roundness of rectangle corners (x: horizontal, y: vertical)

Chart1.panel.format.round = { x:10, y:10 }
Chart1.legend.format.round.y = 5;

transparency
 Amount of semi-glass effect, from 0 to 1. (default is zero)

Chart1.legend.format.transparency = 0.5;

shadow
Properties to control drop-shadow visibility behind filled shapes or stroked lines.

var s = Chart1.panel.format.shadow;
s.visible = true;
s.width = 4;        // can be negative for left-side shadow
s.height = 4;     // can be negative for top-side shadow
s.blur = 5;
s.color = "silver";

gradient
  Attributes to fill shapes using a gradient of colors:

var g = Chart1.panel.format.gradient;
g.visible = true;
g.colors = [ "red", "yellow", "green" ];  // array of colors 
g.stops = [ 0, 0.1, 1 ];   //  percentages from 0 to 1 for each color (default is null, automatic)
// "bottomtop", "leftright", "rightleft", "radial", "diagonalup", "diagonaldown"
g.direction = "topbottom";   

stroke
Attributes used to draw lines and outlines around filled shapes:  var s = Chart1.panel.format.stroke;

s.fill = "black";
s.size = 4;             // line thickness
s.join = "round";    // segment joins ("round", "miter", "bevel" )
s.cap = "square";   // ending line terminators ("square", "butt", "round" )
s.dash = [ 5,10 ];   // dot-dash... array of pixels (default is null to draw solid lines)
s.gradient.visible = true;   // gradient object with colors, direction, etc

font
 Properties to display text:

var f = Chart1.title.format.font;
f.style = "22px Verdana";     // or: "bold italic 14px Tahoma", etc, etc
f.fill = "blue";
f.shadow.visible = true;    // text drop-shadow
f.stroke.fill = "white";        // draws an outline around text
f.gradient.visible = true;   // fills text with gradient instead of using font.fill
f.textAlign = "center";    // horizontal alignment: "start", "end", "left", "center", "right"
// vertical alignment: "top", "middle", "bottom", "alphabetic", "hanging", "ideographic"
f.baseLine = "top";   

Background

The chart background appearance is controlled by the "panel" sub-object:

Chart1.panel.transparent = false;

The panel property includes a format subproperty to control background's appearance:

Chart1.panel.format.gradient.visible = true;
Chart1.panel.format.shadow.color="black";
... etc

Title and Footer

These two chart properties are used to display text at chart top and bottom sides:

Chart1.title.text = "Hello";
Chart1.footer.text = "World";

Multiple-line text is done by adding "\n" line-feed delimiters:

Chart1.title.text = "Hello \n World";

Title and Footer are Annotation-derived objects, and such they inherit the "format" sub-properties:

Chart1.title.visible = true;
Chart1.title.transparent = false;
Chart1.title.format.gradient.visible = true;
Chart1.title.format.round.x=20;

Adding data to series

Data is added to a chart using "Series" objects. Multiple series can exist in the same chart. Each series can be of a different type (line, area, bar, pie, etc) so you can mix several styles altogether. Direct data: The simplest way to add data to a chart is by passing an array of values at chart construction time:

var Chart1=new Tee.Chart("canvas1", [ 5,6,2,9,1] );

This creates a new series object of type Tee.Bar by default, and assigns the array to series.data.values property. Multiple series are created when passing a multi-dimensional array:

var Chart1=new Tee.Chart("canvas1", [ [ 5,6,2,9,1], [ 8,4,3,7,5] ] );

The default series style Tee.Bar can be changed passing a type parameter:

var Chart1=new Tee.Chart("canvas1", [ [ 5,6,2,9,1], [ 8,4,3,7,5] ] , Tee.Area);

Creating series: Series are manually added into a chart using the addSeries method:

var bar =Chart1.addSeries(new Tee.Bar());

Series have a default "title" string property that is used at chart legend. When series are added to a chart, title is assigned to "Series" plus the series index in the Chart1.series.items array ("Series1", "Series2" and so on). You can override the default title:

bar.title = "My Data";

By default series are empty, they contain no data. For testing purposes its handy to add random values, for example:

Chart1.addSeries(new Tee.Line()).addRandom(1000);  // Thousand random points

Data can be specified inline when creating the series:

Chart1.addSeries(new Tee.Pie( [ 10, 20, 30, 40 ] ));

All data is stored under the series "data" property arrays. You can access and modify data directly:

var a = new Tee.Area();
Chart1.addSeries( a );
a.data.values =  [ 10, 20, 30, 40 ];

Each series point has an associated text label. By default, labels are empty. You can modify them using the data.labels property:

a.data.labels =  [ "a", "b", "c", "d" ];

Some series allow specifying point positions or other point parameters. For example, Line and PointXY series can optionally display each line segment or point at a specific "X" axis coordinate:

var p = new Tee.PointXY();
p.data.values = [5, 7, 9];
p.data.x = [0.23, 14, 16];
Chart1.addSeries(p);

Other series like Bubble have a "data.radius" array, and Candle series have data.open, data.close, data.high and data.low arrays. Adding data from other sources Several helper functions are provided in a separate script (teechart-table.js) to import data from different sources (see the online demos for details), for example: From a textarea html element:

Chart1.addSeries(new Tee.Bar(document.getElementById("data")) );
<textarea id="data" rows="20" cols="20" wrap="off">
 7,Apples
 4
 3,Oranges
 9
 1,Banana
 6,Kiwis
 2</textarea>

From a table html element:

Chart1.fromTable('table1', Tee.Bar, true, 0,0);
<table id="table1">...</table>

From a text file URL:

// Warning: data file url should be at "same domain origin" 
Chart1.addSeries(new Tee.Bar("http://myweb.com/mydata.txt"));

From another series in same or different chart:

// Simply assign the "data" property from one series to another:
Chart1.series.items[0].data = Chart2.series.items[3].data;

From xml formatted text:   var b=Chart1.addSeries(new Tee.Bar());
 b.loadXML(document.getElementById("xml"));

...
<textarea id="xml" rows="10" cols="60" "wrap="off">
<series name="Friends" color="Blue" metric="Quantity">
 <point name="Facebook" value="123"/>
 <point name="Twitter" value="456"/>
 <point name="Google " value="789"/>
</series>
</textarea>

From JSON formatted text:

var b=Chart1.addSeries(new Tee.Bar());
b.loadJSON(document.getElementById("json"));

The Legend

The indicator where series names and series points are displayed is called the legend. Several properties can be used to customize the legend behaviour and appearance.

Chart1.legend.visible = true;
Chart1.legend.transparent = false;
Chart1.legend.format.fill = "yellow";

Legend position and orientation:

Chart1.legend.position = "left";  // "top", "bottom", "right"
Chart1.legend.inverted = false;    // draws items in normal order

Select what to display at legend:

Chart1.legend.legendStyle = "values";   // "auto", "series", "values"
Chart1.legend.textStyle = "percentlabel";    // show point value as percent, and point text label

Font and formatting:

Chart1.legend.format.font.style = "20px Arial";

Margins to chart top and chart axes:

// distance from chart edge, percentage from 0 to 100 ( 0 means automatic )
Chart1.legend.align = 0;  
// distance from legend to axes
Chart1.legend.padding = 5;   //  in pixels

Title text on top of items:

Chart1.legend.title.text = "My Legend";
Chart1.legend.title.visible = true;

Symbols next to legend items:

Chart1.legend.symbol.visible = true;
Chart1.legend.symbol.width = 20;
Chart1.legend.symbol.format.shadow.width = 5;

Other legend properties:

Chart1.legend.fontColor = true;  // each item text is painted using its point or series color
Chart1.dividing.fill = "blue";   // draws lines between legend items

Axes

Most Series data are displayed using axes to convert from data values to canvas pixel coordinates.  Some series like Pie and Donut do not use axes. There exist four default axes inside a chart:  left, top, right and bottom.

var a = Chart1.axes.left;

Each series has two properties that control which horizontal and vertical axes are used. By default, the horizontal axis is "bottom", and the vertical axis is "left".

Chart1.series.items[0].horizAxis = "top";
Chart1.getSeries(1).vertAxis = "right";

Series can also display using both axes:

Chart1.series.items[2].horizAxis = "both";

Axis visibility is controlled globally by the Chart1.axes.visible property, and individually using the axis visible:

Chart1.axes.visible = true;
Chart1.axes.bottom.visible = true;

Scales are automatically controlled by default. Each axis calculates its minimum and maximum values based on its associated series values and visual properties. You can override axis automatic scales and set them manually:

var a = Chart1.axes.left;
a.automatic = false;
a.minimum = 50;
a.maximum = 200;

The above code is equivalent to:

Chart1.axes.left.setMinMax( 50, 200 );

Logarithmic scales Axes scales are linear by default. The log property determines the axis to use natural logarithm scaling instead of linear:

Chart1.axes.left.log = true;

Axis Labelling Each axis automatically calculates the "best" distance from labels, using labels formatting properties like font.size.  Custom labels can be controlled changing the axis increment property:

Chart1.axes.bottom.increment = 100;   // one label at each 100 values in axis scale.

Increment is zero by default, meaning automatic calculation. Labels can display series values or series point labels. This is controlled with the labelStyle property:

// options are:  "auto", "none", "value", "mark", "text", "x"
Chart1.axes.left.labels.labelStyle = "text";

When series contain date-time values, labels are formatted according to dateFormat property using Steven Levithan <stevenlevithan.com> date.format.js library.

Chart1.series.items[0].data.x = [ new Date() ];
Chart1.axes.bottom.labels.dateFormat = "shortDate";

Other properties that control labels:

Chart1.axes.left.labels.alternate = true;  // double quantity of labels
Chart1.axes.right.labels.visible = false;  // show or hide labels
Chart1.axes.left.labels.decimals = 3;    // output numbers with up to 3 fixed decimals
Chart1.axes.bottom.labels.rotation = 90;    // 90 degree rotation

Axis Grids The axis grid property includes a format to draw grid lines that go across chart axes space.

Chart1.axes.left.grid.visible = true;

When grid fill color is not empty, grids are filled alternatively as "bands":

Chart1.axes.left.grid.format.fill = "red";

Grid lines format is controlled by stroke property:

Chart1.axes.left.grid.format.stroke.size = 5;

Default grid lines are solid lines. The lineDash property displays dash-dot grids:

Chart1.axes.left.grid.lineDash = true;

On browsers that natively support canvas dash strokes, the above code is equivalent to:

Chart1.axes.left.grid.format.stroke.dash = [10,5];   // see "dash" stroke property

Axis Ticks Axis include ticks an innerTicks properties of type "Ticks", that have a stroke property. Ticks are drawn from labels to axis. Inner ticks display from axis towards inside.

Chart1.axes.bottom.innerTicks.visible = true;
Chart1.axes.left.ticks.length = 9;
Chart1.axes.top.ticks.stroke.fill = "blue";

Minor Ticks From tick to tick, the minorTicks axis property can be used to display small sub-ticks:

Chart1.axes.left.minorTicks.visible = true;
Chart1.axes.left.minorTicks.length = 2;
Chart1.axes.left.minorTicks.count = 5;
Chart1.axes.left.minorTicks.stroke.fill = "green";

Axis Title Close to an axis, the title property is used to display text that identifies the axis:

Chart1.axes.bottom.title.text = "Quantity";
Chart1.axes.bottom.title.text.format.font.fill = "red";

Axis positioning Size and position of axes is automatic by default. The axis startPos and endPos properties control the pixel coordinate of axes.

Axes Wall

The rectangular space where axes are painted is called "the back wall". Formatting is provided using the walls.back property:

Chart1.walls.back.visible = true;
Chart1.walls.back.transparent = false;
Chart1.walls.back.format.gradient.visible = true;

Series

Inheriting from a common Series class, several charting styles are provided, each as a different object class with its own properties and methods.

  1. Line
  2. Bar  / Horizontal Bar
  3. Area / Horizontal Area
  4. PointXY (scatter)
  5. Pie
  6. Donut
  7. Bubble
  8. Candle (financial OHLC)

Series Marks The marks property displays text annotations near series points:

var s = new Tee.Bar();
s.marks.visible = true;
s.marks.style = "percent";

Series and Colors

Charts have a palette property (an array [ ] of colors in string format). This palette is used by series to paint its points, and by chart legend to display series items symbols.

Chart1.palette = [ "red", "blue", "green", "yellow" ];

Colors in the palette are reused in a circular way when more series or more points in a series exist than the size of the palette. Series also contain a palette of colors to override the chart palette. By default is a "null" empty array so they share the chart palette.

Zoom and Scroll

Charts can be zoomed and scrolled by manual code or mouse / touch events. Default behaviour is to drag the right mouse button inside axes to scroll, and drag a rectangle using the left mouse button to zoom / unzoom (zoom dragging to bottom-right direction, and unzoom dragging to left-top direction). This can be overridden using the chart zoom and scroll properties:

Chart1.zoom.enabled = true;
Chart1.zoom.mouseButton = 0;   // 0=left button, 1=middle, 2=right button
Chart1.zoom.stroke.fill = "yellow";
Chart1.scroll.enabled = true;
Chart1.scroll.mouseButton = 2;
Chart1.scroll.direction = "horizontal";  // can be: "vertical" or "both"

The chart onzoom event is triggered when the user releases the mouse button after the chart is zoomed. The chart onscroll event is triggered while the user is scrolling the chart by dragging it.

Exporting a Chart

To obtain a PNG or JPEG image from a chart, you can use the canvas toDataURL method, or the included toImage function:

Chart1.toImage( "img" );   // fills <img id="img"> element with chart as PNG image.
Chart1.toImage( "img" , "jpg", 90 );   // fills image with a jpeg image with 90% compression

Charting Tools

Some features are implemented as a "tool" objects.  These objects can be added to a chart tools array property to activate them.
Annotations
Custom text can be displayed at any chart position using annotation tools:

Chart1.tools.add( new Tee.Annotation( Chart1, "Hello", 50, 50 ) );

The annotation object has a format, text and position properties. Annotations can also act as buttons when using the onclick event:

var  b1=new Tee.Annotation(Chart1, "button 1", 100, 100);
b1.cursor="pointer";
b1.onclick=function(button,x,y) { alert("Clicked button 1"); }
Chart1.tools.add( b1 );

Tooltips
This tool displays series data when moving the mouse over series data point.

var  tip=new Tee.ToolTip(Chart1);
tip.format.font.style="16px Tahoma";
Chart1.tools.add(tip);

The ToolTip tool provides onshow, onhide and ongettext events.
Cursors
Draggable cursor lines are implemented as a tool object:

var t=new Tee.CursorTool(Chart1);
t.format.stroke.size=2;
t.format.stroke.fill="#BB0000";
Chart1.tools.add(t);

The cursor tool includes a direction property (to display cursor as an horizontal line, vertical or both) and an onchange event that is triggered when the cursor is dragged.
Dragging Points
The DragTool implements mouse / touch point dragging.

Chart1.tools.add(new Tee.DragTool(Chart1));

Includes onchanging and onchanged events. The target property determines which series and which series point index is being dragged.
Slider
A generic slider control that can be used inside a chart to change any value.

var slider=new Tee.Slider(Chart1);
slider.min=1;
slider.max=100;
slider.position=10;
slider.thumbSize=12;
slider.horizontal=true;
slider.bounds.x=50;
slider.bounds.y=10;
slider.bounds.width=150;
slider.bounds.height=20;
slider.onChanging=function(slider,value) {
   Chart1.title.format.font.style = value.toFixed(0) " Verdana";
   return value;
  }
  Chart1.tools.add(slider);

Scroller
The scroller tool displays a simplified view of another chart and allows scrolling it. Please refer to this demo for a complete example.

Series Animations

Simple animations performed by changing axis scales or rotating transformations:   var a=new Tee.SeriesAnimation(Chart1);   a.duration=500; // milliseconds   Chart1.tools.add(a); The animate method to start the animation can be called for example from an html button: <BUTTON type="button" onclick="Chart1.tools.items[0].animate();">Animate</BUTTON>

Acknowledgements

The following are libraries and code snippets that have been used to develop TeeChart for Javascript: date.format.js by Steven Levithan Used by chart axes to format date-time string labels from series data. (See axis dateFormat property). splines Copyright 2010 by Robin W. Spencer Custom modified code to draw smooth curves between series points (Line, Area, etc). JQuery.js, JSON and Three.js are technologies used in TeeChart online demos that are optional (not required by TeeChart).