Internal API documentation

• Overview
• Canvas and context references
• Paths in the RGraph libraries
• Working with events
• Working with chart coordinates
• Working with chart data
• Updating your charts dynamically
• Setting properties
• References available on RGraph objects
• Scale information
• Adding text to your charts
• The on function for events
• RGraph functions
  • Type checking functions
  • GET functions
  • Clipping functions
  • Array functions
  • String functions
  • Number functions
  • Miscellaneous functions
  • Custom RGraph event-related functions
  • Trigonometry functions
  • Other functions
• The RGraph ObjectRegistry

Overview

Working with RGraph objects is purposefully easy, to make them straightforward 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 Google Sheets functionality resides in RGraph.common.sheets.js, so if you don't need this facility, 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 examples that are included in the download archive.

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>
    // 1/2 First draw the chart
    bar = new RGraph.Bar({
        id: 'cvs',
        data: [1,5,8,4,6,3,1,5,7,8,4,6],
        options: {
            xaxisLabels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
        }
    }).draw()

    // 2/2 Now get hold of the references
    context = bar.context; // Get hold of a reference to the context
    canvas  = bar.canvas;  // Get hold of a reference to the canvas

</script>

Paths in the RGraph libraries

For speed and convenience - RGraph uses a custom path function to facilitate path drawing.

If you look through the RGraph source code you might see the RGraph.path function in use or calls to this.path . This function makes the canvas path syntax, which is quite verbose, much less so. As an example:

RGraph.path({
    object: this,
    path:   'b r % % % % s % f %',
    args:   [5, 5, 100, 100, 'black', 'red']
});

this.path(
    'b r % % % % s % f %',
    5,5,100,100,
    'black','red'
);

This is a shorter and clearer way of doing a beginPath, rect (at x=5,y=5, 100 wide and 100 high) stroking it in black and finally filling it in red.

For comparison here is the equivalent code that doesn't use the path function:

this.context.beginPath();
this.context.rect(5, 5,100,100);
this.context.strokeStyle = 'black';
this.context.fillStyle = 'red';
this.context.stroke();
this.context.fill();

If you're interested in an RGraph.path function that works with any canvas (ie your own) then take a look at the SVG-like path function. This is a function that is added to the 2D context (when you include the code in your page) and makes creating and using canvas paths far nicer. It looks like this:

context.path('b r 0 0 100 100 f red');

That represents the following code:

context.fillStyle = 'red'
context.beginPath();
context.rect(0,0,100,100);
context.fill();

The RGraph.path function is part of the RGraph.common.core.js file and inside the RGraph classes it can be referenced like this:

RGraph.path({
    object: this,
    path:   'b r % % % % f %',
    args:   [x, y, width, height, 'red']
});

this.path(
    'b r % % % % f %',
    x, y, width, height,
    'red'
);

Update (version 5.2)
The syntax for calling this function was extended so that you can call it from either inside or outside of your chart object in these ways:

// The RGraph.path() function is added as a member function to each chart object
bar.path({
    path: 'b r % % % % f red',
    args: [x, y, width, height]
});

// A less verbose way of calling the function - similar to the sprintf function
bar.path('b r % % % % f red', x, y, width, height);

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 RGraph chart object adds a reference to itself to the canvas and you can access it like this:

<script>
    document.getElementById("myCanvas").onclick = function (e)
    {
        var canvas = e.target;
    
        // The RGraph object constructors add __object__ to the canvas.
        var bar = canvas.__object__;
    }
</script>

If you have multiple objects on your canvas (eg a combined Line chart and Bar chart) the __object__ reference will be a reference to the last object that you added to the canvas. So in order to get other objects, you'll need to use the ObjectRegistry.

Working with chart coordinates

For many chart types, the coordinates of elements (eg bars, lines etc) are to be found in the variable obj.coords. This is usually a multi-dimensional array consisting of the coordinates of those shapes or 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 coordinates array is usually flat, even when you have multiple sets of data. The obj.coords2 array is similar but indexed slightly differently. Eg In a grouped Bar chart the obj.coords2[0] array contains all of the coordinates from the first group of bars - ie for a group of three bars it will contain:

• obj.coords2[0][0]
• obj.coords2[0][1]
• obj.coords2[0][2]

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 coords = obj.coords;

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 variable obj.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 associated data variables are listed below¹.

1. In the table, obj refers to your chart object.
2. 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.
3. For the Scatter chart, each data point is an array of X/Y coordinates, the color and the tooltip for that point.

Updating your charts dynamically

<script>
    num = Number('23');
    num = parseInt('43');
    dec = parseFloat('43.5');
</script>

• RGraph.AJAX.getNumber(url, callback)
• RGraph.AJAX.getString(url, callback)
• RGraph.AJAX.getCSV(url, callback[, separator])
• RGraph.AJAX.getJSON(url, callback)
• RGraph.AJAX.post(url, data, callback)

You can see fuller definitions for these functions in the API documention below.

Note: You could also use jquery for ajax queries:

<script>
    $.get('/getData.html', function (data)
    {
        // Use the console.log() function to show the returned data
        console.log(data);
    });
</script>
        

A common request is to be able to update charts dynamically. This is quite straight-forward and consists of three steps:

1. Get your new data from the server (with an ajax request for example).
2. Set the data on your chart object. See the above table for the appropriate property to use.
3. Call the draw method again (you might need to use the RGraph.redraw function to fully redraw the canvas if you have multiple charts)

If you don't need to get data from your server (ie it's all client-side) then you can skip the first step. Also, it may be sufficient to simply recreate the entire object from scratch. This means that you won't have to update any RGraph internal properties - just recreate the chart object and configuration. Note though that if you update the chart frequently (ie multiple times per second) then performance may be slightly degraded.

Setting properties

To set RGraph properties you can use the json style configuration (which is the default now) or you can use each objects setter directly (there's also a corresponding getter).

obj.set({
    marginLeft:   35,
    marginRight:  35,
    marginTop:    35,
    marginBottom: 35
});

obj.get('marginLeft');
obj.get('marginRight');
obj.get('marginTop');
obj.get('marginBottom');

References that are 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 and settings are stored. Typically the objects are named with the format __xxx__ or with an obvious prefix (such as the word rgraph), and you can inspect the objects by using a console (eg the inspector that's part of Google Chrome - press CTRL+SHIFT+J when viewing the webpage). Some examples are:

• __object__ on the canvas - a reference to the chart object
• RGraph.Registry.get('tooltip') - a reference to the currently visible tooltip (if any). This in turn has the following available:
  • __text__ - Since setting innerHTML can cause changes in HTML, this is the original tooltip text.
  • __index__ - This is the numerical index corresponding to the tooltips array that you set.
  • __dataset__ - Used in some charts and corresponding to the dataset.
  • __canvas__ - A reference to the original canvas that triggered the tooltip.
• RGraph.Registry.get('mousedown') - Used in annotating, and stipulates whether the mouse button is currently pressed.
• RGraph.Registry.get('contextmenu') - The currently shown context menu, if any. This in turn has the following properties:
  • __canvas__ - The original canvas object.

Scale information

For the Bar chart, Bipolar chart, Horizontal Bar chart, Line chart, Scatter chart and Waterfall chart the scale that is used is stored in the scale2 class variable. Eg:

<script>
    bar = new RGraph.Bar({
        id: 'cvs',
        data: [56,43,52,54,51,38,46,42,52],
        options: {
        }
    }).draw();
    
    scale = bar.scale2;
</script>

Adding text to your charts

If you want to add arbitrary text to your chart(s) you can either use the RGraph.Drawing.Text drawing API object or use the RGraph text function directly. The drawing api object has advantages in that it supports adding tooltips and/or click/mousemove events to the text and is automatically redrawn for you. So if you do use tooltips or other interactive features then you don't have to worry about using the draw event.

The on() function for events

The on function can be used to set events (both custom and the click/mousemove events) on your canvas without breaking method chaining. For example:

bar = new RGraph.Bar({
    id: 'cvs',
    data: [4,8,6,4,3,5,4],
    options: {
        marginLeft: 35,
        marginBottom: 35,
        xaxisLabels: ['Mon','Tue','Wed','Thu','Fri','Sat','Sun']
    }
}).on('draw', function  (obj)
{
    alert('Chart has been drawn!');
}).draw()

RGraph functions

• Type checking functions
• GET functions
• Clipping function
• Array functions
• String functions
• Number functions
• Miscellaneous functions
• Custom RGraph event-related functions
• Trigonometry functions
• Other functions

This is a list of some of the functions available to you in the RGraph common libraries. Arguments in square brackets are optional.

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

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

Clipping functions

// Sometimes this may be necessary to reset the antialiasing fix that RGraph applies to the canvas
obj.canvas.__rgraph_aa_translated__ = false;

var original_array = [4,6,8,['blah',44,7,null],3,2,5];

var myCopy1 = RGraph.arrayClone(original_array, true);

<script>
    var myArray = [
        [546,'Richard',12],
        [351,'John',56],
        [846,'Lucy',43],
        [777,'Barbara',12]
    ];
    
    var newArray = RGraph.arrayColumn(myArray, 1);
    
   // Returns:
   // ['Richard','John','Lucy','Barbara']

var data = [
    [4,8,5,6,2],
    [4,4,1,2,3],
    [9,8,6,5,3]
];

seq = RGraph.groupedIndexToSequential(data,2,2);
// seq is now 12

<script>
    myArray = [1, 1, null, {a: 1, b:null}];

    arr = RGraph.arrayRemoveNull(myArray, {objects: true,value: 'XXX'});
    console.log(arr); // Result: [1, 1, 'XXX', {a: 1, b:'XXX'}]

    arr2 = RGraph.arrayRemoveNull(myArray);
    console.log(arr2); // Result: [1, 1, {a: 1, b: null}]
</script>

var myArray = [8,4,6,5,3,5,1];
var last_element = RGraph.arrayLast(myArray); // 1

var myArray = [8,4,6,5,3,5,1];
var last_element = myArray.at(-1); // 1

RGraph.numberFormat({
       object: obj,
       number: number,
     unitspre: '$',
    unitspost: 'c',
        point: '.',
     thousand: ','
});

RGraph.addCss("div#myGrid table.rgraph-datagrid thead tr th {box-sizing: border-box;}");

RGraph.fade('#myElement', 1, 30);

name=value,name2=value2,name3="A quoted value with spaces"

{
    name: value,
    name2: value2
    name3: A quoted value with spaces
}

function clearAndRedraw (obj)
{
    RGraph.clearAnnotations(obj.canvas);
    RGraph.clear(obj.canvas);
    obj.draw();
}

RGraph.setShadow({
    object: obj,
    prefix: 'shadow'
});

context.beginPath();
context.strokeStyle = 'black';
context.fillStyle = 'red';
RGraph.roundedRect({
    context: context,
          x: 5,
          y: 5,
      width: 100,
     height: 100,
     radius: 25,
    roundbl: false,
    roundbr: false
});
context.stroke();
context.fill();

myGradient = RGraph.linearGradient({
    object: obj,
        x1: 0,
        y1: 0,
        x2: 0,
        y2: 250,
    colors: ['red', 'black']
});

myGradient = RGraph.radialGradient({
    object: obj,
        x1: 250,
        y1: 250,
        r1: 0,
        x2: 250,
        y2: 250,
        r2: 250,
    colors: ['red', 'black']
});

RGraph.text({
    object:         obj,
    font:           'Arial',
    size:           10,
    bold:           false,
    italic:         false,
    color:         'black',
    text:           'Some text',
    x:              100,
    y:              100,
    valign:         'bottom', // bottom/center/top
    halign:         'left',   // left/center/right
    bounding:       false,
    boundingFill:   'red',
    boundingStroke: 'black',
    marker:         false,
    accessible:     false,
    tag:            'myTag'
});

// Using a string of text as the tag
var nodes = RGraph.text.find({
    id: 'cvs',
   tag: 'labels'
});

// Using a regex as the tag
var nodes = RGraph.text.find({
    object: myBar,
   tag: /^lab/
});

// Using a string as the text option
var nodes = RGraph.text.find({
    id: 'cvs',
  text: '10km'
});

// Using a regex as the text option
var nodes = RGraph.text.find({
    id: 'cvs',
  text: /^10/
});

// Using the callback option
var nodes = RGraph.text.find({
        id: 'cvs',
      text: /^10/
  callback: function (args)
  {
      var obj   = args.object,
          nodes = args.nodes;
    
    // Do something here
  }
});

bar.set({
    contextmenu: [
        ['Get PNG', RGraph.showPNG],
        null,
        ['Cancel', function () {}]
    ]
});

<script>
    RGraph.AJAX('/getdata.html', function (str)
    {
        // Handle the response and create the chart
    });
</script>

<script>
    RGraph.AJAX.getString('/getdata.html', function (str)
    {
        // Handle the response and create the chart
    });
</script>

<script>
    RGraph.AJAX.getNumber('/getdata.html', function (number)
    {
        // Handle the response and create the chart
    });
</script>

<script>
    RGraph.AJAX.getJSON('/getdata.html?json', function (json)
    {
        // Handle the response and create the chart
    });
</script>

<script>
    RGraph.AJAX.getCSV('/getdata.html', function (csv)
    {
        // Handle the response and create the chart
    }, ',');
</script>

RGraph.PHP.time();
RGraph.PHP.time('now + 1 year');    // OR now + 1y
RGraph.PHP.time('now + 2 weeks');   // OR now + 2w
RGraph.PHP.time('now + 14 days');   // OR now + 14d
RGraph.PHP.time('now - 24 hours');  // OR now - 24h
RGraph.PHP.time('now - 60 minutes');// OR now - 60m
RGraph.PHP.time('now - 10 seconds');// OR now - 10s

// 12:02 17th January 2025
RGraph.PHP.date('H:i jS F Y');

// 2025-05-17 12:02:03
RGraph.PHP.date('Y-m-d H:i:s');

// 2016-10-31 20:02:03
RGraph.PHP.date('Y-m-d H:i:s', 1477944123);

// 2026-05-19 12:08:05 (See the RGraph.PHP.time() function
//                      above for the possibilities that you
//                      have to modify the timestamp.)
RGraph.PHP.date('Y-m-d H:i:s', 'now + 1y + 2d');

The RGraph ObjectRegistry

The RGraph ObjectRegistry allows you to have multiple charts on a single canvas - both having dynamic features. You can combine any of the chart types in RGraph, such as Meter charts, Gauge charts, Progress bars etc. Because it's a common combination, there's a special class for the combined Bar chart and Line chart which you use like this:

<script>
    bar = new RGraph.Bar({
        id: 'cvs',
        data: [4,8,5,7,8,9],
        options: {
            xaxisLabels: ['Alex','Doug','Charles','Nick','Michelle','Ali'],
            colors: ['red'],
            tooltips: ['Alex','Doug','Charles','Nick','Michelle','Ali'],
            textSize: 14,
            marginInner: 20,
            combinedEffect: 'wave',
            yaxis: false,
            backgroundGridVlines: false,
            backgroundGridBorder: false
        }
    });


    line = new RGraph.Line({
        id: 'cvs',
        data: [3,9,4,9,6,5],
        options: {
            textSize: 14,
            colors: ['black'],
            linewidth: 2,
            tooltips: ['1984','1985','1986','1987','1988','1989'],
            shadow: false,
            spline: true,
            combinedEffect: 'trace'
            combinedEffectOptions: '{frames: 60}'
        }
    });
    
    // Create the combination object - this draws the chart
    combo = new RGraph.CombinedChart(bar, line).draw();
</script>

You can have as many chart types as you want with the CombinedChart class, but the Bar chart should be the first one that you add to it. Because it's a common combination, the CombinedChart class changes the Line chart margins to match the Bar charts.

When you create an object it's added to the ObjectRegistry automatically so that it can be redrawn as needed. objects are indexed by canvas id and also by uid. This means that you can quickly get hold of all of the pertinent objects for a given canvas, or one particular object if you need it. The following methods are available:

Note: You can also use these aliases:

// Iterate through all of the objects in the ObjectRegistry
RGraph.ObjectRegistry.iterate(function (obj)
{
    alert('The objects UID is: ' + obj.uid);
});

// Iterate through all of the bar chart objects in the ObjectRegistry
RGraph.ObjectRegistry.iterate(function (obj)
{
    alert('The objects UID is: ' + obj.uid);
}, 'bar');

// Iterate through all of the bar,line and pie chart objects in the ObjectRegistry
RGraph.ObjectRegistry.iterate(function (obj)
{
    alert('The objects UID is: ' + obj.uid);
}, 'bar,line,pie');

Note:

Since the ObjectRegistry was introduced objects have to be registered regardless of whether they use dynamic features or not. As a result of this, you may be experiencing objects being redrawn when you don't want them to be. To solve this you need to remove them from the ObjectRegistry. How to remove an object from the ObjectRegistry is documented here.