Miscellaneous information

• Upper and lower limits for horizontal bars
• Setting the canvas width and height
• The canvas coordinate system
• Debugging tips
• Inspecting an RGraph chart
• Double click context menus
• Adding your own event handlers
• Carriage returns and newlines in labels
• Character set issues
• How to identify an RGraph object
• Static Y-axis
• Ingraph labels
• Shorthand for ingraph labels
• Data types
• Adding text to your charts
• Crosshairs
• Crosshairs and the Scatter chart
• Logarithmic scale
• Clearing/Resetting the canvas
• CSV data
• How to convert degrees to radians
• Internet Explorer pseudo-constants
• RGraph pseudo-constants

As of April 2016, there's also a textAccessible option that makes the text on the chart real text that can be read by screen readers. It also appears at a better quality than native canvas text. From version 6.08 this option is no longer enabled by default.

Upper and lower limits for horizontal bars

If you don't wish to specify an upper or lower limit for horizontal bars, and you just want them to extend to the upper or lower limits of the chart, whatever they may be, you can specify null for the value determining how far they extend. For cases where the x-axis is in the middle and you're specifying a negative start value, or you want the bar to extend all the way to the bottom, you can simply specify an arbitrary length (eg -999999). Eg:

bar.set({
    backgroundHbars: [[0, null, 'green'], [0,-999999,'red']]
});

Setting the canvas width and height

To set the canvas width and height you must use the html width/height attributes and NOT css. If you do use css, the canvas will be scaled, and not enlarged, to fit the new width/height. Eg:

<canvas id="cvs" width="200" height="100">[No canvas support]<canvas>

Note: When you resize the canvas using css, not only will it be scaled (not enlarged), but it will also NOT be cleared.

The canvas coordinate system

The canvas coordinate system starts in the top left of the canvas (at [0,0] - the X value increasing as you go right and the Y value as you go down), much like the css coordinates for the entire page. The margins go around the canvas (ie top/bottom/left/right - where the labels and titles are placed), and the actual chart sits in the middle.

Debugging tips

If you're having a hard time debugging your chart, try these:

• Ensure you have only one chart on the page
• Make sure you have disabled your web browsers cache (the Firefox Web Developer toolbar can do this for Firefox)
• Try using Firebug for Firefox or the Webkit developer tools for Google Chrome (CTRL_SHIFT+J) and Safari (CTRL+ALT+C). There's a video about using the Chrome developer tools here. These are very useful tools that make development much easier.
• Reduce the page to the bare minimum.
• Start with a very basic chart and build it up slowly.

There is a howto for debugging with Chrome here. It also links to a video about the Chrome dev tools from Google I/O 2010.

Inspecting an RGraph chart

To help when debugging your RGraph charts and canvas elements, you can use your browser's built-in debugging tools. An example is the WebKit developer tools that are available in Google Chrome and Apple Safari. There is a screenshot of these tools (in docked mode) here. To view these tools in Google Chrome press CTRL+SHIFT+J. Inspect the canvas, and then the last object that you created can be found via the __object__ property.

Double click context menus

Windows Opera, Windows Safari, Mac Safari and Mac Firefox all attach the context menu to the double click event (left mouse button), not the right, to make it more reliable.

Adding your own event handlers

Because each RGraph object exposes the canvas element (the same as what you get from document.getElementById), you can use normal procedures to add your own event handlers. Eg If you wanted to add your own click listener you could do this:

<script>
    bar = new RGraph.Bar({
        id: 'cvs',
        data: [7,4,2,6,3,4,8],
        options: {
        }
    }).draw();

    bar.canvas.onclick = function ()
    {
    }
</script>

Carriage returns and newlines in labels

You can put carriage returns in your labels by using the string \r\n. This means your labels will span multiple lines. Like so:

bar.set({
    xaxisLabels: 'John\r\n(Winner!)', ...
});

Character set issues

If you're seeing strange, unrecognised characters in your text labels or titles, you may need to specify the correct character set that the browser should use. In php you can do this with the header function (which, as the name suggests, sends an HTTP header):

<?php
    header("Content-Type: text/html; charset=ISO-8859-1");
?>

If you use Apache, you could use the header directive, though this may be overridden by other directives, eg AddDefaultCharset.

How to identify an RGraph object

Because identity can sometimes be a tricky affair, there are a few RGraph properties that you can use to check whether an object is an RGraph object:

• obj.isrgraph - This is a boolean that you can use to identify an RGraph object.
• obj.type - This identifies the type of an RGraph object. It is a string that contains a one-word description of the object's type, eg bar/line/pie.

Static Y-axis

The example of a static Y-axis has been updated and you can now find it here.

Ingraph labels

As well as an array of strings, like this:

obj.set({
    labelsIngraph: ['First label','Second label']
});

The string can also be an array, consisting of color and placement information, like this:

obj.set({
    labelsIngraph: ['First label',['Second label', 'red', 'yellow', -1, 50] ]
});

You can read more information about this here.

Shorthand for ingraph labels

Instead of providing a full array of null elements for ingraph labels that may get a little unwieldy, you can instead specify an integer that specifies how many elements to skip. Like this:

line.set({
    labelsIngraph: [6, 'July', 3, 'November']
});

Data types

If your data values aren't the correct type - ie numbers - it can cause problems. Pay particular attention to this when you're getting your data from data sources that may be classed as strings, such as json or ajax requests.

Adding text to your charts

You can add arbitrary text to your charts by using the RGraph drawing API text object. Another way is to use the draw custom event and the RGraph.text api function, but the drawing object is by far the easiest and it requires the least time and coding. It also allows you to add tooltips and click/mousemove events to the text.

Crosshairs

Some chart types can use crosshairs. The supported charts are:

• Bar charts
• Line charts
• Scatter charts
• Waterfall charts

There are various options that control the crosshairs, though because some apply to the readout, they are only applicable to the Scatter chart. The crosshairs can be customised by stipulating the linewidth, the color and whether only the horizontal, vertical or both lines are shown.

There are two example pages - one Line and one Scatter - that show the snap option (that restricts the crosshairs to data points) and how you can then get the dataset/point out of the chart:

• Line chart (line-crosshairs-snap.html in the download archive)
• Scatter chart (scatter-crosshairs-snap.html in the download archive)

Crosshairs and the Scatter chart

Because the x-axis is scaled, the Scatter chart has the extra ability to have a readout for the coordinates when the crosshairs are in use. This is shown in the example above. The appropriate properties are:

• obj.canvas.__crosshairs_x__
• obj.canvas.__crosshairs_y__
• obj.canvas.__crosshairs_labels__ (this is the coordinates readout)

In the above example the coordinates are put in the text input by using the custom event crosshairs. This is as follows:

function myFunc (obj)
{
    var x = obj.canvas.__crosshairs_x__;
    var y = obj.canvas.__crosshairs_y__;

    document.getElementById("crosshairs.out").value = x + ',' + y;
}
RGraph.addCustomEventListener(scatter, 'crosshairs', myFunc);

Logarithmic scale

It's possible to get a logarithmic scale in RGraph by using the yaxisScaleSpecific property. The actual scale that is used when drawing the chart is 0 to 1, and the scale that is displayed is 10, 100, 1000, 10,000, 100,000 (for example). Here's a sample chart:

<script>
    data = [10,10,100,100,1000,1000,10000,10000,100000,100000,1000000,1000000];
    
    // Put the data into log(100000) format
    // The RGraph.log() function is part of the common library
    for (var i=0; i<data.length; ++i) {
        data[i] = RGraph.log(data[i], 10);
    }
    
    line = new RGraph.Line({
        id: 'cvs',
        data: data,
        options: {
            marginLeft: 60,
            yaxisScaleMax: 6,
            yaxisLabelsSpecific: ['1,000,000', '100,000','10,000','1000','100','10'],
            yaxisTickmarksCount: 10,
            xaxisTickmarksCount: 11,
            backgroundGridHlinesCount: 6,
            backgroundGridVlinesCount: 12
        }
    })
</script>

Clearing/Resetting the canvas

With the addition of the ObjectRegistry, objects are always registered in their constructors, regardless of whether they use dynamic features or not, to allow them to be redrawn when necessary. This means that if you use one canvas to draw multiple charts on then you may get previous charts appearing if you use features such as tooltips that redraw the canvas.

To get around this you not only need to clear the canvas (with RGraph.clear) but you will also need to remove previous objects from the ObjectRegistry. You can do this in a few ways:

1. RGraph.ObjectRegistry.clear This clears the entire ObjectRegistry allowing you to "start from scratch" again with a clean slate.
2. RGraph.ObjectRegistry.clear(canvas) A slight variation on the above, this is the same method but with a canvas object (the same as what you get from document.getElementById ) passed as the first argument. Only objects that are registered to use this canvas will be cleared.
3. RGraph.ObjectRegistry.clear(id) The same as the above but instead of passing it the canvas object you can pass it the ID (a string) of the canvas.
4. RGraph.ObjectRegistry.remove(obj) This method removes a single object from the ObjectRegistry.
5. RGraph.reset(canvas) This method clears the ObjectRegistry of objects applicable to the canvas, clears the anti-aliasing translate fix and clears the canvas.

   Note: If you use the same canvas for multiple charts you will need to use this function instead of the RGraph.clear function.

CSV data

If your data is initially in csv form a simple way to pass it to RGraph is to print it as part of the page in a hidden div tag. You can then use the standard document.getElementById to retrieve it and the split function to convert it to an array. Keep in mind that if you do this you will end up with an array of strings - so you will need to loop through the array converting the strings to numbers.

There's also a CSV reader that's a part of RGraph. You can read more by following the link.

How to convert degrees to radians

To convert degrees, which everyone knows and understands, to radians - which is what angles are measured in when working with canvas you can use this formula:

radians = (Pi / 180) * degrees

Which would translate to this javascript code:

<script>
    degrees = 78;
    radians = (Math.PI / 180) * degrees;
<script>

There are also some shortcut functions that are available to make things easier:

<script>
    // Convert degrees to radians
    radians = RGraph.toRadians(degrees);
    
    // Convert radians to degrees
    degrees = RGraph.toDegrees(radians);
</script>

Internet Explorer pseudo-constants

For conditionally enabling or disabling features in Internet Explorer there are constants available for you to use: RGraph.ISIE, RGraph.ISIE6, RGraph.ISIE8, RGraph.ISIE9, RGraph.ISIE9UP, RGraph.ISIE10, RGraph.ISIE10UP You can use them like this:

<script>
    if (RGraph.ISIE9UP) {
        // ...
    }
</script>

RGraph pseudo-constants

For a few common arrays RGraph provides some pseudo-constants that you can make use of (they're actually just normal variables that use upper-case for their names). The variables that are available are:

RGraph.MONTHS_SHORT = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug',  'Sep', 'Oct', 'Nov', 'Dec'];
RGraph.MONTHS_LONG  = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
RGraph.DAYS_SHORT   = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
RGraph.DAYS_LONG    = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
RGraph.HOURS24      = ['00:00', '01:00', '02:00', '03:00', '04:00', '05:00', '06:00', '07:00', '08:00', '09:00', '10:00', '11:00', '12:00', '13:00', '14:00', '15:00', '16:00', '17:00', '18:00', '19:00', '20:00', '21:00', '22:00', '23:00'];
RGraph.HOURS12      = ['00:00', '01:00', '02:00', '03:00', '04:00', '05:00', '06:00', '07:00', '08:00', '09:00', '10:00', '11:00'];

To make use of them you can do this:

<script>
    new RGraph.Bar({
        id:'cvs',
        data: [4,8,6,3,5,4,8],
        options: {
            colors:['red'],
            xaxisLabels: RGraph.DAYS_SHORT,
            yaxis: false,
            backgroundGridVlines: false,
            backgroundGridBorder: false
        }
    }).draw();
</script>