Line chart API reference

• Example
• Properties
• Methods
• Errorbars
• Combining the Line and Bar charts
• Alternative colors
• Accumulative filled Line charts
• Custom tickmarks
• The coordinates properties
• The coords2 array
• The __index2__ property on tooltips
• Note about the data_arr array
• Events
• Effects

Example

<script>
    data = [
        [8,7,6,4,9,5,6,7,9],
        [1,3,4,2,5,0,3,1,1]
    ];

    xaxisLabels = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep'];

    //
    // Configure and make the first draw of the Line chart
    //
    myLine = new RGraph.Line({
        id: 'cvs',
        data: data,
        options: {
            tooltips: '%{key}',
            tooltipsFormattedUnitsPost: '%',
            tooltipsFormattedKeyColors: ['red','blue','#0f0'],
            tooltipsFormattedKeyLabels: ['John','Richard','Luis'],
            tooltipsCss: {
                fontSize: '16pt',
                textAlign: 'left'
            },
            backgroundGridVlines: false,
            backgroundGridBorder: false,
            colors: ['red','blue','green'],
            linewidth: 2,
            spline: true,
            tickmarksStyle: 'dot',
            tickmarksSize: 6,
            xaxisLabels: xaxisLabels,
            xaxis: false,
            yaxis: false,
            marginLeft: 40,
            marginInner: 15,
            shadow: false,
            labelsAbove: true,
            labelsAboveSize: 10,
                labelsAboveUnitsPost: '%',
            labelsAboveOffsety: -5,
            textSize: 16
        }
    }).draw();




    //
    // This function switches the dataset. It uses the reverse:
    // option of the trace() and wave() effects to hide the
    // lines, switches the data and then animates the lines
    // back in
    //
    function change ()
    {
        var butChange = document.getElementById('changeData');
        
        // Because this is a composite animation - turn
        // off the labelsAbove option ourselves
        myLine.set('labelsAbove', false);

        // If the chart is currently animating - don't do
        // anything
        if (!myLine.animating) {
            
            myLine.animating       = true;
            butChange.disabled     = true;
            butChange.style.cursor = 'default';
            
            // Call the reverse wave() function
            myLine.trace({frames: 75, reverse: true})
                 .wave({frames: 90, reverse: true}, function ()
                 {

                     // Change the data
                     myLine.original_data =
                     [
                         RGraph.arrayRandom(9, 0, 10),
                         RGraph.arrayRandom(9, 0, 10)
                     ];
                    
                     // Show the new data by animating with the
                     // wave() effect
                     setTimeout(function ()
                     {
                        myLine.trace({frames: 90})
                         myLine.wave({frames: 150}, function ()
                         {
                             myLine.animating       = false;
                             butChange.disabled     = false;
                             butChange.style.cursor = 'pointer';
                            
                             // Re-enable labelsAbove
                             myLine.set('labelsAbove', true);
                            
                             RGraph.redraw();
                         });
                     }, 500);
                });
        }
    }
</script>

Properties

You can use these properties to control how the chart appears. You can set them by including them in the options section of the configuration as shown above.

• Background properties
• X-axis properties
• Y-axis properties
• Labels and text properties
• Margin properties
• Colors properties
• Shadow properties
• Interactive features properties
• Title properties
• Trendline properties
• Null value properties
• Key properties
• Miscellaneous properties

function myFormatter(opt)
{
    var num = Number(opt.number) * 5;

    return String(num)
}
obj.set('yaxisScaleFormatter', myFormatter);

labelsAboveFormatter: function (opt)
{
    var obj     = opt.object,
        value   = opt.value,
        index   = opt.index,
        dataset = opt.dataset;

    return value;
}

<div style="margin-left: 50px; display: inline-block">
    <canvas id="cvs" width="650" height="250"></canvas>
</div>

tooltipsFormattedKeyColorsCss : {
    border: "1px solid #ddd";
}

tooltipsFormattedListItems: [
    ['Bill','Jerry','Berty'], // First tooltip
    ['Gill','Carrie','Lucy'], // Second tooltip
    ['Pob','Nobby','Hilda']   // Third tooltip
]

.RGraph_tooltip ul#rgraph_formatted_tooltips_list li {
    text-align: left;
    color: yellow;
}

tooltipsPointerCss: {
    borderLeft: 'gray 2px solid',
    borderBottom: 'gray 2px solid'
}

tooltipsCss: {
    fontFamily: 'Verdana',
    fontSize: '20pt'
}

// Add a custom tickmark - just a regular circle
// but only drawn on every second point
tickmarksStyle: function (obj, dataset, value, index, x, y, color, prevX, prevY)
{
    if (index % 2 === 0) {
        obj.path(
            "b a % % % % % false f red",
            x, y, 7, 0, 6.29
        );
    }
}

combinedchartEffectOptions: '{frames: 300}'

obj.set('horizontalLines', [
    {
        value: 'average',
        dashed: true,
        labelPosition:'left bottom'
    },
    {
        value: 10.48,
        label:'Value (%{value})',
        labelValueDecimals: 2,
        labelValueThousand: ',',
        labelValuePoint:'.',
        labelValueUnitsPre:'',
        labelValueUnitsPost:''
        //labelValueFormatter: function (opt)
        //{
        //    return opt.number;
        //}
    }
]);

Methods

<script>
    line.canvas.onclick = function (e)
    {
        RGraph.redraw();
    
        var canvas  = e.target,
            obj     = canvas.__object__,
            shape   = obj.getShape(e);

        if (shape) {
            
            var x = shape.x,
                y = shape.y;
            
            obj.path(
                'b a % % 5 0 6.28 false s black f red',
                x, y
            );
        }
    }
</script>

This method can be used to get the value at a particular point or at the mouse coordinates based on the scale that is in use - not simply the coordinates of the mouse. The argument can either be an event object (for use in event listener functions) or a two-element array consisting of the X and Y coordinates (ie when you're not in an event listener). It returns null if the mouse or coordinates are in the margin areas. An example:

line.canvas.onclick = function (e)
{
    var obj   = e.target.__object__;
    var value = obj.getValue(e);
    
    // ...
}

This method can be used to get an appropriate Y coordinate for a value when you're doing custom drawing on the chart. It returns the coordinate for the maximum/minimum value if the given number is out of range.

This method returns an object containing the dataset and index of the first point that it comes across thats within the tolerance distance from the mouse click. You can pass it either the event object or a custom object containing the indexes: event (the event object), tolerance (the allowable distance from a point that you want to permit) and xonly which is whether you want to only consider the X coordinate when calculating the closest point (it defaults to false).

This method animates a single point to the given value. It doesn't take a dataset due to the nature of the how the function works - only the first dataset is accommodated. There's a demo of this function being used to implement a touch-device-friendly version of an adjustable line in the download archive called line-adjustable-onetouch.html.

This method can be used to set an event listener on an object. It operates similarly to the jquery on function. The first argument is the event that you wish to attach to and the second is the handler function. For example:

obj.on('draw', function (obj)
{
    // Put your event code here
});

The exec function is documented here.

The responsive function helps your charts respond to different browser window sizes and screen resolutions. For example, for smaller screens, you might want to have angled labels or show shorter versions of them completely.

Update: There is now the responsive configuration option available to you and this is now the preferred method of configuration.

The responsive function and configuration option are documented on their own page here.

The hide function hides a line by setting the color to rgba(0,0,0,0). Tooltips and other interactive features still work even though the line is not visible. You can give an integer (the index of the relevant line), an array of line indexes, or no argument at all in which case all of the lines on the chart are hidden

This function is the reverse of the above.

This function returns true or false as to whether the given line index is hidden or not.

This function returns whether the cursor is over one of the lines that is drawn on the chart. If there is a line being hovered over you'll get back an object containing the index of that line (the indexing begins at zero remember). There's also an easy way to add highlighting - the highlightDataset properties which are detailed above in the Miscellaneous section.

If you want to programmatically highlight one of your datasets then you can do so using this function. It takes an object of options as its only argument and that object can look like this:

line.highlightDataset({
    dataset: 1, // Required
    stroke: 'red',
    fill: '#fcc',
    linewidth: 4,
    linedash: [10,10]
});

The only required option to the function is the zero-indexed dataset: which naturally has to be given to highlight the correct dataset. Other options are optional.

Errorbars

Errorbars can allow you to show an upper and lower range for a particular point like the example page line-errorbars.html in the download archive shows. You can specify errorbars like this:

var line = new RGraph.Line({
    id: 'cvs',
    data: [12,18,10,8,5,4,3,2,14,5,6,9],
    options: {
        yaxisScaleMin: 5,
        errorbars: [1, [1,5],[5,1,'red',10],3,3,3,3,3,3,3,3,3,3],
        //errorbarsLinewidth: 10,
        //errorbarsColor: 'red',
        //errorbarsCapped: false,
        //errorbarsCappedWidth: 50,
        marginInner: 15,
        tickmarksStyle: 'circle',
        xaxis: false
    }
}).draw();

This would give you errorbars for each point and the elements of each errorbar array are (each one is optional - specify null if you want to give no value):

• The upper extent of the errorbar
• The lower extent of the errorbar
• The color of this errorbar
• The linewidth of this errorbar
• The (total) width of the cap at the end of this errorbar

Combining the Line and Bar charts

You can combine the Bar charts and Line charts. Find out more here. In the same vein, you can have Y axes on both the left and right sides.

Alternative colors

Instead of a string stipulating the color, each element of the colors array can be a two element array stipulating the up color, and the down color. To use alternating colors you must also stipulate the alternate property:

myLine.set('colors.alternate', true);
myLine.set('colors', ['red', ['blue', 'yellow'], 'green]);

Accumulative filled Line charts

The default behaviour of filled Line charts is to "stack" the lines on top of each other. This allows them all to be totally visible, no matter what (unless a line has a zero value of course). If this is not desired, then there is an option (filledAccumulative - true or false) to change this behaviour so that the lines are plotted "as-is". Keep in mind that if you set this option to false (ie the Lines are plotted as-is) it may be wiser to use semi-transparent colors or some parts of data sets (or even entire data sets) may be hidden by others. There's a comparison of the different modes here.

Custom tickmarks

If none of the available tickmark styles are suitable, you can instead specify a function object that draws the tickmark, enabling you to make the tickmark yourself. For example:

<script>
    line.set('tickmarksStyle', myTick);

    //
    // The function that is called once per tickmark, to draw it
    // 
    // @param object obj   The chart object
    // @param array  data  The entire line data
    // @param number value The individual point's value
    // @param number index The current index in the data array
    // @param number x     The X coordinate
    // @param number y     The Y coordinate
    // @param string color The color of the line
    // @param number prevX The previous X coordinate
    // @param number prevY The previous Y coordinate
    //
    function myTick (obj, data, value, index, x, y, color, prevX, prevY)
    {
        // Draw your custom tickmark here
    }
</script>

As of August 2014 you can also specify an image to use as a tickmark. Various styles of URL are supported:

obj.set({tickmarksStyle: 'image:foo.png'});     // Starts with image: prefix
obj.set({tickmarksStyle: '/images/foo.png'});   // Starts with a /
obj.set({tickmarksStyle: '../images/foo.png'}); // Starts with ../
obj.set({tickmarksStyle: 'data: ...'});         // Starts with data: (for inline images)
obj.set({tickmarksStyle: 'images/foo.png'});    // Starts with images/

The coordinates properties

As with the majority of the RGraph objects the coordinates of the various shapes are recorded and stored in various properties on the RGraph chart object. The Line chart is no different and has these properties available to you:

• obj.coords A straight-forward single dimension array of all of the coordinates of all of the points that are drawn on the chart.
  
  
• obj.coords2 A multi-dimensional array that indexes the coordinates slightly differently to the obj.coords array. With this array the coordinates are grouped by dataset. So the first three points of the Line would be stored as:
  • obj.coords2[0] // First datasets coordinates
  • obj.coords2[0][0]// First point on the first dataset
  • obj.coords2[0][0][0]// X coordinate of the first point on the first dataset
  • obj.coords2[0][0][1]// Y coordinate of the first point on the first dataset
  • obj.coords2[1] // Second datasets coordinates
  • obj.coords2[1][0]// First point on the second dataset
  • obj.coords2[1][0][0]// X coordinate of the first point on the second dataset
  • obj.coords2[1][0][1]// Y coordinate of the first point on the second dataset
  
  
• obj.coordsSpline If you've configured your line to be a spline then this holds all of the coordinates that make it up. This is a multi-dimensional array - one array for each line that's drawn on the chart. Similar to the above property, the coordinates for three points on a spline would look like this:
  • obj.coordsSpline[0] (all of the coordinates of the first spline)
  • obj.coordsSpline[0][0] (the x and y coordinates of the first point on the first spline)
  • obj.coordsSpline[0][0][0] (the x coordinate of the first point on the first spline)
  • obj.coordsSpline[0][0][1] (the y coordinate of the first point on the first spline)
  • obj.coordsSpline[0][1][0] (the x coordinate of the second point on the first spline)
  • obj.coordsSpline[0][1][1] (the y coordinate of the second point on the first spline)
  • obj.coordsSpline[0][2][0] (the x coordinate of the third point on the first spline)
  • obj.coordsSpline[0][2][1] (the y coordinate of the third point on the first spline)
  • obj.coordsSpline[1] (all of the coordinates of the second spline)
  • obj.coordsSpline[1][0] (the x and y coordinates of the first point on the second spline)
  • obj.coordsSpline[1][0][0] (the x coordinate of the first point on the second spline)
  • obj.coordsSpline[1][0][1] (the y coordinate of the first point on the second spline)
  • obj.coordsSpline[1][1][0] (the x coordinate of the second point on the second spline)
  • obj.coordsSpline[1][1][1] (the y coordinate of the second point on the second spline)
  • obj.coordsSpline[1][2][0] (the x coordinate of the third point on the second spline)
  • obj.coordsSpline[1][2][1] (the y coordinate of the third point on the second spline)
  Important: A spline is made up of many points in order to appear curved - so if you want just the coordinates of the points that represent the values you should use either the obj.coords or obj.coords2 variables instead.
  
  
• obj.coordsText This holds the coordinates of all of the text that has been added to the chart. Even if the text is blank (ie no text) then the coordinates will be added to this variable.

The __index2__ property on tooltips

When showing tooltips, one property of the tooltip is __index2__. This is the index that pertains to the individual dataset. In a function called from the tooltip event you can access it like this:

function myFunc (obj)
{
    var idx = RGraph.Registry.get('tooltip').__index2__;
}
RGraph.addCustomEventListener(obj, 'ontooltip', myFunc  );

Note about the data_arr array

Events

RGraph supports custom events that allow you to easily add interactivity to your charts if required. The following events are available:

• adjustbegin This event fires at the start of adjusting - like the standard mousedown event.
• adjust This event fires (repeatedly) during adjusting - like the standard mousemove event.
• adjustend This event fires at the end of adjusting - like the standard mouseup event.
• annotatebegin This event fires at the start of annotating - like the standard mousedown event.
• annotate This event fires (repeatedly) during annotating - like the standard mousemove event.
• annotateend This event fires at the end of annotating - like the standard mouseup event.
• annotateclear This event fires at the end of the RGraph.clearAnnotations function.
• beforeclear This event fires at the start of the RGraph.clear function.
• clear This event fires at the end of the RGraph.clear function.
• click This is similar to the standard canvas click event but this only fires when you click on a bar - not the whole canvas.
• crosshairs This event fires when you have the crosshairs feature enabled and you move the mouse.
• beforecontextmenu This event fires when you have the contextmenu enabled and it is about to appear.
• contextmenu This event fires when you have the contextmenu enabled and it has been displayed.
• beforedraw This event fires at the start of the draw method before anything has been done.
• firstdraw This event fires at the end of the draw function - but only the first time that the draw function is called.
• draw This event fires at the end of the draw function.
• beforeinteractivekey When you're using the interactive key this event fires just before the key and chart are highlighted.
• afterinteractivekey When you're using the interactive key this event fires just after the key and chart are highlighted.
• keyclick This event fires when you click on the key - you don't have to be using the interactive key, however.
• mousemove This event is similar to the standard mousemove event but only fires when you move the mouse over a bar on the chart.
• mouseover This event is similar to the standard mouseover event but only fires when you move the mouse over a bar on the chart.
• mouseout This event is similar to the standard mouseout event but only fires when you move the mouse away from a bar on the chart that you've previously hovered over.
• beforetooltip This event fires at the start of the tooltip showing process.
• tooltip This event fires after a tooltip has been shown.
• beforebackground This event fires before the background (grid, image, bars etc) has been drawn.
• background This event fires after the background (grid, image, bars etc) has been drawn.

new RGraph.Line({
    id: 'cvs',
    data: [4,8,6,3,5,8,9],
    options: {
    }
}).on('draw', function (obj)
{
    console.log('The draw event has fired');
    
}).draw();

Effects

• The unfold effect (effects-line-unfold.html in the download archive)
• The unfoldfromcenter effect (effects-line-unfoldfromcenter.html in the download archive)
• The Unfoldfromcentertrace effect (effects-line-unfoldfromcentertrace.html in the download archive)
• The foldtocenter effect (effects-line-foldtocenter.html in the download archive)
• The trace effect (effects-line-trace.html in the download archive)
• The wave effect (effects-line-wave.html in the download archive)

<script>
    //
    // Optional callback function that's called when the effect is complete
    //
    function myCallback (obj)
    {
        // ...
    }

    var obj = new RGraph.Line({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 56,
        options: {
            marginLeft: 35,
            marginInner: 5
        }
    // All of these arguments are optional
    }).trace({frames: 60, reverse: false}, myCallback)
    // .unfold({frames: 60}, myCallback)
    // .unfoldFromCenter({frames: 60}, myCallback)
    // .unfoldFromCenterTace({frames: 60}, myCallback)
    // .foldToCenter({frames: 60}, myCallback)
    // .trace({frames: 60}, myCallback) (shown in the example above)
    // .wave({frames: 60, reverse: false}, myCallback) (shown in the example above
</script>

The growPoint() function

If you want to use adjusting on a touch-based device (eg a tablet) then the default Line chart adjusting won't work because it really requires a mouse to function.

The obj.growPoint function can therefore be used to skirt this limitation and facilitate adjusting on these devices. There follows some sample code for an adjustable Line chart that uses this function instead of the built-in adjusting feature. You can also find a demo in the download archive that employs this function.

<script>
   line = new RGraph.Line({
        id: "cvs",
        data: [4,8,5,2,6,7,9,1,5,4,3,8],
        options: {
            xaxisLabels: ["Alf","Bob","Cal","Dug","Edd","Fay","Gof","Hal","Ind","Jay","Kev","Lou"],
            textSize: 14,
            spline: true,
            xaxis: false,
            yaxis: false,
            backgroundGridBorder: false,
            backgroundGridVlines: false,
            marginInner: 10,
            tickmarksStyle: "filledcircle",
            tickmarksSize: 3,
            shadow: false
        }
    }).draw();
    
    line.canvas.onclick = function (e)
    {
        var indexes = line.closest({
            event: e,
            tolerance: 25, // Optional - defaults to 25
            xonly: true    // Optional - defaults to false
        });

        if (!indexes) {
            return;
        }

        var value = line.getValue(e);

        line.growPoint({
            index:   indexes.index,
            value:   value,
            dataset: 0,  // Optional - defaults to 0
            frames:  15  // Optional - defaults to 15
        });
    }
</script>