Horizontal Bar chart API reference

• Example
• Properties
• Methods
• The obj.data_arr array
• The coordinates properties
• Events
• Effects

Example

<script>
    labels = ['Richard','Gulliver','John'];
    data   = [280,45,133];
    
    // To show a stacked or grouped chart each element of the data array should
    // be an array containing the data to be shown.
    // data = [[120,80,60],[30,12,13],[50,50,33]]

    new RGraph.HBar({
        id: 'cvs',
        data: data,
        options: {
            marginInner: 15,
            backgroundBarsColor1: 'white',
            backgroundBarsColor2: 'white',
            backgroundGrid: true,
            backgroundGridHlines: false,
            backgroundGridBorder: false,
            colors: ['red','green','blue'],
            xaxis: false,
            yaxisLabels: labels,
            yaxisLabelsSize: 26,
            yaxisTickmarksCount: 0,
            yaxisLinewidth: 3,
            tooltips: '<b>Results:</b><br />%{key}',
            tooltipsFormattedKeyLabels: ['Sales','Sales','Sales'],
            tooltipsCss: {
                fontSize: '16pt',
                textAlign: 'left'
            },
            corners: 'round',
            cornersRoundRadius: 50
        }
    }).draw();
</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
• Margin properties
• Color properties
• Labels and text properties
• Title properties
• Shadow properties
• Key properties
• Line properties
• Interactive features properties
• Miscellaneous properties

function myFormatter(opt)
{
    var obj = opt.object,
        num = opt.number;

    return num + 'F'; // An example of formatting
}

<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'
}

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

Methods

obj.set(name, value)
An accessor that you can use to set the values of properties.

obj.getShape(event)
This method makes it easy to get hold of which bar or segment has been clicked on or hovered over. It returns an object which has the following indexes available:

<script>
    obj.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,
                width  = shape.width,
                height = shape.height;
            
            obj.path(
                'b r % % % % s black f red',
                x, y, width, height
            );
        }
    }
</script>

This method is similar to the getShape method described above but when comparing the mouse position to the bar coordinates this method only takes into account the mouse y position. This method is used when the Horizontal Bar chart is made to be adjustable.

The second argument is optional and allows you to specify the (RGraph) object to be used in the checks.

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 necessarily in an event listener). It returns null if the mouse or coordinates are in the margin areas. An example:

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

This method can be used to get an appropriate x coordinate for a value when you're doing custom drawing on the chart. It returns null if the value is out of range.

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 listener function. For example:

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

The function is useful if you use method chaining when creating your charts:

obj = new RGraph.HBar({
    id: 'cvs',
    data: [5,8,6,4,3,5],
    options: {
        marginLeft: 55,
        marginInner: 5,
        yaxisLabels: ['Hoolio','Jill','Pete','Kevin','Lucy','John']
    }
}).on('mousemove', function (e, shape)
{
    // Put your mousemove event code here

}).on('click', function (e, shape)
{
    // Put your click event code here
})
.draw()

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 obj.data_arr array

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 Horizontal Bar 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 bars that are drawn on the chart.
  
  
• obj.coords2 A multi-dimensional array that's used for when you're showing a grouped or stacked chart. Indexed first by the group and then by the bar/segment in that group. So on a grouped chart which has two groups with 3 bars in each group you would get the following entries in the obj.coords2 array:
  • obj.coords2[0][0]
  • obj.coords2[0][1]
  • obj.coords2[0][2]
  • obj.coords2[1][0]
  • obj.coords2[1][1]
  • obj.coords2[1][2]
  
  
• obj.coordsLines A multi-dimensional array of the coordinates that make up the vertical line if it's shown on the chart. Even though there's only one line supported by the Horizontal Bar chart this is still a multi-dimensional array. So for a line that has three points you would see in the obj.coordsLines variable:
  • obj.coordsLines[0] (all of the coordinates of the line)
  • obj.coordsLines[0][0] (the x and y coordinates of the first point on the line)
  • obj.coordsLines[0][0][0] (the x coordinate of the first point on the line)
  • obj.coordsLines[0][0][1] (the y coordinate of the first point on the line)
  • obj.coordsLines[0][1][0] (the x coordinate of the second point on the line)
  • obj.coordsLines[0][1][1] (the y coordinate of the second point on the line)
  • obj.coordsLines[0][2][0] (the x coordinate of the third point on the line)
  • obj.coordsLines[0][2][1] (the y coordinate of the third point on the line)
  
  
• obj.coordsSpline If you've configured your line to be a spline then this holds all of the coordinates that make it up. Even though there's only one line permitted per object, this is still a multi-dimensional array. So, 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 line)
  • obj.coordsSpline[0][0] (the x and y coordinates of the first point on the spline)
  • obj.coordsSpline[0][0][0] (the x coordinate of the first point on the spline)
  • obj.coordsSpline[0][0][1] (the y coordinate of the first point on the spline)
  • obj.coordsSpline[0][1][0] (the x coordinate of the second point on the spline)
  • obj.coordsSpline[0][1][1] (the y coordinate of the second point on the spline)
  • obj.coordsSpline[0][2][0] (the x coordinate of the third point on the spline)
  • obj.coordsSpline[0][2][1] (the y coordinate of the third point on the spline)
  Important: The 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.

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.
• 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.HBar({
    id: 'cvs',
    data: [4,8,6,3,5,8,9],
    options: {
    }
}).on('draw', function (obj)
{
    console.log('The draw event has fired');
    
}).draw();

Effects

There's a stopAnimation() function that you can use to stop an animation immediately if you need to. There's a line chart demo called demos/line-effects-stop-animation.html in the download archive that demonstrates the use of this function.

• The wave effect (effects-hbar-wave.html in the download archive
• The grow effect (effects-hbar-grow.html in the download archive

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

    obj = new RGraph.HBar({
        id: 'cvs',
        data: [4,8,6,3,5,2,4],
        options: {
            marginLeft: 35,
            marginInner: 5
        }
    }).grow({frames: 60}, myCallback)
</script>