Fuel gauge API reference

• Example
• Properties
• Methods
• The coordinates properties
• Events
• Effects

Example

<script>
    // Create the Fuel chart. The arguments are: the minimum value, the maximum value, and the actual value.
    new RGraph.Fuel({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 67,
        options: {
            needleColor: 'blue',
            colors: ['#ddf'],
            labelsEmpty: 'Empty!',
            labelsFull: 'Full',
            icon: '/images/water.jpg'
        }
    }).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.

• Chart configuration properties
• Color properties
• Margin properties
• Needle properties
• Labels and text properties
• Scale properties
• Interactive features properties
• Miscellaneous properties

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

Methods

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

obj.getAngle(value)

This method can be used to get an appropriate angle 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 handler function. For example:

.on('draw', function (obj)
{
    // Put 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 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. In the case of the Fuel chart the coordinates of text are recorded as usual in the obj.coordsText variable and the start angle, the end angle and the radius are recorded in the obj.angles property.

• obj.angles This is an object the holds the following properties:
  • start The start angle (measured in radians) of the scale.
  • end The end angle (measured in radians) of the scale.
  • needle The angle (measured in radians) that the needle is positioned at.
• 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.
• 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.

new RGraph.Fuel({
    id: 'cvs',
    min: 0,
    max: 50,
    value: 34,
    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 grow effect (effects-fuel-grow.html in the download archive

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

    new RGraph.Fuel({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 56,
        options: {
        }
    }).grow({frames: 60}, myCallback);
</script>