From 770ba5201f5c60b2bb36602ff9d359f641e33125 Mon Sep 17 00:00:00 2001 From: Yves Fischer Date: Sun, 23 Oct 2011 21:14:40 +0200 Subject: Charting with flask, rgraph and custom "timeseries database" --- schall/static/RGraph/docs/api.html | 817 +++++++++++++++++++++++++++++++++++++ 1 file changed, 817 insertions(+) create mode 100644 schall/static/RGraph/docs/api.html (limited to 'schall/static/RGraph/docs/api.html') diff --git a/schall/static/RGraph/docs/api.html b/schall/static/RGraph/docs/api.html new file mode 100644 index 0000000..b7010fd --- /dev/null +++ b/schall/static/RGraph/docs/api.html @@ -0,0 +1,817 @@ + + + + + + RGraph: HTML5 Javascript charts library - API documentation + + + + + + + + + + + + + + + + + + + + + +
+ + Mention RGraph on Twitter + +
+ + + +
+ + +
+ + + + +

RGraph: HTML5 Javascript charts library - API documentation

+ + + +
+ + + + +

Overview

+ +

+ Working with RGraph objects is purposefully easy, to make them straight forward to integrate into your own scripts if you want to. For any + particular chart type there are a few files required - the common libraries and the chart specific library. Eg: +

+ + 
+<script src="RGraph.common.core.js"></script>
+<script src="RGraph.bar.js"></script>
+
+ +

+ RGraph.common.core.js is a function library that contains a large set of functions that support the chart classes. + Some functions, and sets of functions, have their own files. For example, the zoom functions reside in RGraph.common.zoom.js, + so if you don't need zoom, you don't need this file. + Each of the chart libraries (RGraph.*.js) contains that particular charts class. If you'd like to see a "bare bones" + implementation, you can look at the basic example. There's also a + skeleton example to make it easier to create new chart types. +

+ + +

Canvas and context references

+ +

+ Each chart object maintains references to the context and canvas as properties. So to get hold of them all you + need to do is this: +

+ + 
+<script>
+    window.onload = function ()
+    {
+        // 1/2 First draw the chart
+        var myBar = new RGraph.Bar('myCanvas', [1,5,8,4,6,3,1,5,7,8,4,6]);
+        myBar.Set('chart.labels', ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']);
+        myBar.Draw();
+    
+        // 2/2 Now get hold of the references
+        var context = myBar.context; // Get hold of a reference to the context
+        var canvas  = myBar.canvas;  // Get hold of a reference to the canvas
+    }
+</script>
+
+ + +

Working with events

+ +

+ When working with events, you may come across the situation where you have a reference to the canvas, but + also need to access the chart object. For this reason the constructor of each object adds a reference to the object to the + canvas and you can access it like this: +

+ + 
+<script>
+    document.getElementById("myCanvas").onclick = function (e)
+    {
+        var src = (RGraph.isIE8() ? event.srcElement) : e.target;
+    
+        // The RGraph object constructors add __object__ to the canvas.
+        var myBar = src.__object__;
+    }
+</script>
+
+ + +

Working with chart coordinates

+ +

+ For most chart types, the coordinates of elements (eg bars, lines etc) are to be found in the class variable obj.coords. + This is usually a multi-dimensional array consisting of the coordinates of those shapes, or of points. As an example the bar + chart maintains the X, Y, width and height of each bar (or sections of bars in a stacked bar chart). The coords array is + usually a flat array, even when you have multiple sets of data. +

+ +

+ By using the RGraph.getMouseXY() function and this array you can determine if a bar was clicked on, or if the mouse is near a + line point etc. +

+ + 
+var myCoords = myBar.coords;
+
+ +

+ Note: Previously the coords array values sometimes included the margin values, and sometimes didn't. As of 17th + April 2010 the values have all been unified to not include the margin values, so the values are as reported. +

+ +

+ Note: + The Line chart also has an object variable myObj.coords2, where the coordinates are indexed differently - + by line index. +

+ + +

Working with chart data

+ +

+ Another variable you may need is the data variable. For most chart types, this is where the data is stored. It is usually + untouched, so it is as you supplied to the chart objects constructor. A notable exception to this is filled line charts. + Here the original data is stored in the class variable original_data. The data supplied is modified to produce the stacking + effect. If you need to modify a filled line charts data you will need to change this variable instead. +

+ +

+ Not all chart types use the data variable. For some the name is different so that it makes a little more sense. The + chart types and their associate data variables are listed below1. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Chart typeData variable(s)
Barobj.data
Bi-polarobj.left, obj.right
DonutThis is now a variant of the Pie chart
Fuelobj.min, obj.max, obj.value
Funnelobj.data
GanttSee the docs
Gaugeobj.min, obj.max, obj.value
Horizontal Barobj.data
Horizontal Progress barobj.max, obj.value
LEDobj.text
Lineobj.original_data3
Meterobj.min, obj.max, obj.value
Odometerobj.start, obj.end, obj.value
Pieobj.angles, obj.data
Radial Scatter chartobj.data
Roseobj.max, obj.data
Scatterobj.max, obj.data2
Thermometerobj.min, obj.max, obj.value
Traditional Radarobj.data, obj.max
Vertical Progress barobj.max, obj.value
Waterfall chartobj.max, obj.data
+ +
    +
  1. In the table, obj refers to your chart object.
    2. +
  2. For the Scatter chart, each data point is an array of X/Y coordinates, the color and the tooltip for that point.
    3. +
  3. + The Line chart obj.original_data is an aggregation of all the datasets given to the Line chart, so the first + dataset is held in obj.original_data[0], the second in obj.original_data[1] etc. +
    4. +
+ + +

Updating your charts dynamically

+ +

+ Note: + It is important that you're careful with types when making AJAX requests. Since the response is initially a string, + and your AJAX function/library may not do conversions for you, you may need to convert these strings to numbers. To + do this you can use the Number() or parseInt() functions. For example: +

+ + 
+<script>
+    num = Number('23');
+    num = parseInt('43');
+</script>
+
+ +

+ A common request is to be able to update charts dynamically. This is quite simple and consists of three steps: +

+ +
    +
  1. Get the new data from the server (with an AJAX request for example).
    2. +
  2. Set the data in your chart object. See the above table for the appropriate property to use.
    3. +
  3. Call the .Draw() method again.
    4. +
+ +

+ If you don't need to get data from your server (ie it's all client-side) then you can omit the first step. Also, it may be + sufficient to simply recreate the entire object from scratch. This means that you won't have to alter and + RGraph internal properties - just recreate the chart object and configuration. There's a simple function + you can use for AJAX purposes here. +

+ + + +

Setting properties

+ +

+ To set RGraph properties, ideally you should use each objects setter (there's also a corresponding getter). These functions + accomodate some backwards compatibility changes, so by not using them you run the risk of your charts not working entirely as + expected. +

+ + 
+myObj.Set('chart.gutter.left', 25);
+myObj.Get('chart.gutter.left');
+
+ + +

 

+

References available on RGraph objects

+

+ RGraph stores various references to objects on the canvas (typically) to make getting hold of them easier. There's also a + Registry object in + which references are stored. Typically the objects are named with the format __xxx__, and you can inspect the + objects by using a console(eg the inspector that's part of Google Chrome - CTRL+SHIFT+J). Some examples are: +

+ + + + These are just a sample of what's available, to find more you should use an introspection tool or look at the source. + + + + +

Scale information

+

+ For the Bar, Bipolar, HBar, Line and Scatter charts the scale that is used is stored in the scale class variable. Eg: +

+ + 
+<script>
+    var myBar = new RGraph.Bar('cvs', [56,43,52,54,51,38,46,42,52]);
+    myBar.Draw();
+    
+    var myScale = myBar.scale
+</script>
+
+ + +

Adding text to your charts

+

+ If you want to add arbitrary text to your chart(s) you can use the API function RGraph.Text(). +

+ + 
+<script>
+    // Draw a basic chart
+    var myObj = new RGraph.Bar('myCanvas', [4,5,5,8,7,6,4,8,5,9]);
+    myObj.Draw();
+    
+    // Draw some text
+    myObj.context.beginPath();
+        size = 12;
+        font = 'Verdana';
+        text = 'Some text!;
+        x    = 10;
+        y    = 10;
+
+        RGraph.Text(myObj.context, font, size, x, y, text);
+    myObj.context.fill();
+</script>
+
+ + +

RGraph functions

+ +

+ This is a list of some of the functions available to you in the RGraph common libraries. + It's not every single one that's available, but is a list of the common ones that you're likely to want to use. Arguments + in square brackets are optional. +

+ + 
+<script src="RGraph.common.core.js"></script>
+
+<script>
+    // Returns 9
+    myArray = [3,2,5,4,9,7,8];
+    max = RGraph.array_max(myArray);
+</script>
+
+ + +

Arrays

+ + + + +

Strings

+ + + + +

Numbers

+ + + + +

Miscellaneous

+ + + + +

Custom RGraph event related functions

+ + + + +

Other

+ +

+ These are functions which are less generic, and used to build the charts. You may still wish to use them however. +

+ + + + + +

The skeleton file

+

+ The skeleton object + (RGraph.skeleton.js) gives you a base for creating new chart types that + match the RGraph object system (eg getters, setters, RGraph names etc). Example usage of the skeleton object would be: +

+ + 
+<script>
+    var myObj = new RGraph.Skeleton('cvs', [3,3,4,5,3,8,3,2,1,9]);
+    myObj.Set('chart.colors', ['red']);
+    myObj.Draw();
+
+    var colors = myObj.Get('chart.colors');
+</script>
+
+ + + \ No newline at end of file -- cgit v1.2.1