RGraph: API documentation

• Overview
• Canvas and context references
• Working with events
• Working with graph data
• RGraph functions
  • Arrays
  • Strings
  • Miscellaneous
  • Other

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 graph type there are only two files required - the common library and the graph specific library. Eg:

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

RGraph.common.js is a function library that contains a large set of functions that support the graph classes. Each of the graph libraries (RGraph.*.js) contains that particular graphs class. If you'd like to see a "bare bones" implementation, you can look at the basic example.

Canvas and context references

Each graph 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 graph object. For this reason the constructor of each object adds a reference to the object to the canvas and you can access them like this:

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

Working with graph data

Another variable you may need is the data variable. This is where the data for the graph is stored. It is usually untouched, so it is as you supplied to the graph objects constructor. An 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.

RGraph functions

This is a list of some of the functions available to you in RGraph.common.js. 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.js"></script>

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

Arrays

• (number) RGraph.array_max(array)
  Returns the maximum value in the array.

• (number) RGraph.array_sum(array)
  Returns the sum of all values in the array. You can also pass a single integer, in which case it is simply returned as-is.

• (array) RGraph.array_clone(array)
  Creates a copy/clone of the given array. Only numerically indexed arrays are supported.

• (array) RGraph.array_reverse(array)
  Returns a reversal of the given array.

Strings

• (string) RGraph.rtrim(string)
  Strips the right hand white space from the string that you pass it.

• (string) RGraph.number_format(number[, prepend[, append]])
  This formats the given number (which can be either an integer or a float. The prepend and append variables are strings which are added to the string (eg 5%).

Miscellaneous

• (object) RGraph.FixEventObject(event)
  Pass this function an event object and it will attempt to "fill in" the missing properties (depending on the browser). It tries to add:
  
  
  • pageX (MSIE)
  • pageY (MSIE)
  • target (MSIE)
  • offsetX (FF)
  • offsetY (FF)

• (number) RGraph.GetDays(date)
  This returns the number of days in the given month. The argument should be a Date object.

• (null) RGraph.pr(mixed)
  Emulates the PHP function print_r() by recursively printing the structure of whatever you pass to it. It handles numbers, strings, arrays, booleans, functions and objects.

• (null) pd(mixed)
  An alias of the above albeit far shorter to type.

• (null) RGraph.Clear(canvas[, color])
  Clears the canvas by drawing a white (or the optional color you give) rectangle over it.

• (array) RGraph.getMouseXY(event)
  When passed your event object, it returns the X and Y coordinates (in relation to the canvas) of the mouse pointer.

• (number) RGraph.degrees2Radians(number)
  Converts and returns the given number of degrees to radians. 1 radian = 57.3 degrees.

• (array) RGraph.getScale(max)
  Given the maximum value this will return an appropriate scale.

• (mixed) RGraph.Registry.Get(name)
  In conjunction with the next function, this is an implementation of the Registry pattern which can be used for storing settings.
  
  
• (mixed) RGraph.Registry.Set(name, value)
  In conjunction with the previous function, this is an implementation of the Registry pattern which can be used for storing settings.
  
  
• (null) RGraph.Register(object)
  This function is used in conjunction with the next to register a canvas for redrawing. Canvases are redrawn (for example) when tooltips or crosshairs are being used.
  
  
• (null) RGraph.Redraw()
  This function is used in conjunction with the previous to redraw a canvas. Canvases are redrawn (for example) when tooltips or crosshairs are being used.
  
  

Other

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

• (null) RGraph.lineByAngle(context, x, y, angle, length)
  This function draws a line from the given X and Y coordinates at the specified angle.
  
  
• (null) RGraph.Text(context, font, size, x, y, text[[[[[[, valign], halign], border], angle], background], bold])
  This function acts as a wrapper around the canvas text functionality.
  
  
• (null) RGraph.DrawTitle(canvas, text, gutter[, centerx[, size]])
  This function draws the title. The centerx argument is the center point to use. If not given the center of the canvas is used.
  
  
• (null) RGraph.Tooltip(canvas, text, x, y)
  This function shows a tooltip.
  
  
• (null) RGraph.DrawKey(object, key, colors)
  This function draws the key. The first argument is the graph object, the second is an array of key information and the last is an array of the colors to use.
  
  
• (null) RGraph.DrawBars(object)
  This draws the horizontal background bars. The argument is the graph object.
  
  
• (null) RGraph.DrawInGraphLabels(object)
  This draws the in-graph labels. The argument is the graph object.
  
  
• (null) RGraph.DrawCrosshairs(object)
  This function draws the crosshairs. The argument is the graph object.
  
  

Questions

If you have a question regarding the API, please ask on the mailing list