Fuel gauge API reference

Summary: Documentation about the Fuel Gauge including information about all of the options that are available to you. The Fuel Gauge is a simple meter that can be used to show the magnitude of a value.

The available configuration options for the Fuel Gauge are shown here.

Example
Properties
Methods
Animation effects

Example

<script>
    // Create the Fuel chart. The arguments are: the minimum value, the maximum value, and the actual value.
    fuel = 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

Chart configuration properties

Property	Description	Default
centerx	If required, you can position the Fuel Gauge using this instead of the margins.	null
centery	If required, you can position the Fuel Gauge using this instead of the margins.	null
radius	If required, you can size the Fuel Gauge using this instead of the margins.	null

centerx
If required, you can position the Fuel Gauge using this instead of the margins.
Default: null

centery
If required, you can position the Fuel Gauge using this instead of the margins.
Default: null

radius
If required, you can size the Fuel Gauge using this instead of the margins.
Default: null

Color properties

Property	Description	Default
colors	The color of the Fuel Gauge. Note that despite there being only one color, this is still an array.	['red']

colors
The color of the Fuel Gauge. Note that despite there being only one color, this is still an array.
Default: ['red']

Margin properties

Property	Description	Default
marginLeft	The left margin of the chart, (the margin is where the labels and title are)).	5
marginRight	The right margin of the chart, (the margin is where the labels and title are).	5
marginTop	The top margin of the chart, (the margin is where the labels and title are).	5
marginBottom	The bottom margin of the chart, (the margin is where the labels and title are).	5

marginLeft
The left margin of the chart, (the margin is where the labels and title are)).
Default: 5

marginRight
The right margin of the chart, (the margin is where the labels and title are).
Default: 5

marginTop
The top margin of the chart, (the margin is where the labels and title are).
Default: 5

marginBottom
The bottom margin of the chart, (the margin is where the labels and title are).
Default: 5

Needle properties

Property	Description	Default
needleColor	The color of the needle (not including the bulb at the bottom). Note that this is not an array - it's just a string.	red
needleRadiusOffset	By increasing this you can shorten the needle and by decreasing it you can lengthen the needle.	r45

needleColor
The color of the needle (not including the bulb at the bottom). Note that this is not an array - it's just a string.
Default: red

needleRadiusOffset
By increasing this you can shorten the needle and by decreasing it you can lengthen the needle.
Default: r45

Labels and text properties

Property	Description	Default
labelsEmpty	The label used as the empty text.	E
labelsEmptyOffsetx	This allows you finer grained control in the horizontal direction over the text positioning if you need it.	0
labelsEmptyOffsety	This allows you finer grained control in the vertical direction over the text positioning if you need it.	0
labelsFull	The label used as the full text.	F
labelsFullOffsetx	This allows you finer grained control in the horizontal direction over the text positioning if you need it.	0
labelsFullOffsety	This allows you finer grained control in the vertical direction over the text positioning if you need it.	0
labelsColor	The color used for the text on the chart.	null
labelsFont	The font used for the text.	null
labelsSize	The size of the text.	null
labelsBold	Whether the labels are bold or not.	null
labelsItalic	Whether the labels are italic or not.	null
textColor	The color used for the text on the chart.	black
textFont	The font used for the text.	Arial
textSize	The size of the text.	12
textBold	Whether the labels are bold or not.	false
textItalic	Whether the labels are italic or not.	false
textAccessible	A new feature in 2016 that allows you to use DOM text in place of canvas text. It makes for much higher quality text that you can also select if desired (for copy/paste operations). It won't fit all situations and you can read more about the DOM text feature here. A good way to control borders/margins/padding etc is not to set them on the canvas but to wrap the canvas in a div and set them on that like this: <div style="margin-left: 50px; display: inline-block"> <canvas id="cvs" width="650" height="250"></canvas> </div>	true
textAccessibleOverflow	This can be `visible` or `hidden` and it controls whether the text is clipped to the edges of the canvas. It defaults to be visible and means you can set small margins if you wish.	visible
textAccessiblePointerevents	This controls whether the DOM text responds to mouse based events or not (it sets the `pointer-events` CSS property to `none`).	true

labelsEmpty
The label used as the empty text.
Default: E

labelsEmptyOffsetx
This allows you finer grained control in the horizontal direction over the text positioning if you need it.
Default: 0

labelsEmptyOffsety
This allows you finer grained control in the vertical direction over the text positioning if you need it.
Default: 0

labelsFull
The label used as the full text.
Default: F

labelsFullOffsetx
This allows you finer grained control in the horizontal direction over the text positioning if you need it.
Default: 0

labelsFullOffsety
This allows you finer grained control in the vertical direction over the text positioning if you need it.
Default: 0

labelsColor
The color used for the text on the chart.
Default: null

labelsFont
The font used for the text.
Default: null

labelsSize
The size of the text.
Default: null

labelsBold
Whether the labels are bold or not.
Default: null

labelsItalic
Whether the labels are italic or not.
Default: null

textColor
The color used for the text on the chart.
Default: black

textFont
The font used for the text.
Default: Arial

textSize
The size of the text.
Default: 12

textBold
Whether the labels are bold or not.
Default: false

textItalic
Whether the labels are italic or not.
Default: false

textAccessible
A new feature in 2016 that allows you to use DOM text in place of canvas text. It makes for much higher quality text that you can also select if desired (for copy/paste operations). It won't fit all situations and you can read more about the DOM text feature here. A good way to control borders/margins/padding etc is not to set them on the canvas but to wrap the canvas in a div and set them on that like this:

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

Default: true

textAccessibleOverflow
This can be visible or hidden and it controls whether the text is clipped to the edges of the canvas. It defaults to be visible and means you can set small margins if you wish.
Default: visible

textAccessiblePointerevents
This controls whether the DOM text responds to mouse based events or not (it sets the pointer-events CSS property to none).
Default: true

Scale properties

Property	Description	Default
scaleVisible	Instead of the Full/Empty labels you can set this to true to show a scale instead.	false
scaleLabelsCount	When you're showing a scale this controls how many labels are shown.	5
scaleDecimals	This determines how many decimal places are shown in the scale.	0
scaleUnitsPre	The units that the Y axis is measured in. This string is displayed before the actual number, allowing you to specify values such as "$50".	none
scaleUnitsPost	The units that the Y axis is measured in. This string is displayed after the actual number, allowing you to specify values such as "50ms".	none
scalePoint	The character used as the decimal separator.	.
scaleThousand	The character used as the thousand separator.	,

scaleVisible
Instead of the Full/Empty labels you can set this to true to show a scale instead.
Default: false

scaleLabelsCount
When you're showing a scale this controls how many labels are shown.
Default: 5

scaleDecimals
This determines how many decimal places are shown in the scale.
Default: 0

scaleUnitsPre
The units that the Y axis is measured in. This string is displayed before the actual number, allowing you to specify values such as "$50".
Default: none

scaleUnitsPost
The units that the Y axis is measured in. This string is displayed after the actual number, allowing you to specify values such as "50ms".
Default: none

scalePoint
The character used as the decimal separator.
Default: .

scaleThousand
The character used as the thousand separator.
Default: ,

Interactive features properties

Property	Description	Default
contextmenu	The context menu. For more details see here.	null
annotatable	Whether annotations are enabled for the chart (ie you can draw on the chart interactively.	false
annotatableColor	If you do not allow the use of the palette, then this will be the only color allowed for annotations.	black
annotatableLinewidth	This is the linewidth of the annotations.	1
adjustable	Whether the Fuel chart is adjustable or not.	false

contextmenu
The context menu. For more details see here.
Default: null

annotatable
Whether annotations are enabled for the chart (ie you can draw on the chart interactively.
Default: false

annotatableColor
If you do not allow the use of the palette, then this will be the only color allowed for annotations.
Default: black

annotatableLinewidth
This is the linewidth of the annotations.
Default: 1

adjustable
Whether the Fuel chart is adjustable or not.
Default: false

Miscellaneous properties

Property	Description	Default
icon	This should be a URL that represents the image to use as the icon on the chart. The default fuel icon is a data: URL, though you can specify any valid image URL.	[A data: URL of a fuel icon]
iconRedraw	If false then the chart is NOT redrawn when the image/icon loads. You may need to set this to false if you use the adjusting feature.	true
clearto	This is used in animations and effects as the default color to use when the canvas.	null

icon
This should be a URL that represents the image to use as the icon on the chart. The default fuel icon is a data: URL, though you can specify any valid image URL.
Default: [A data: URL of a fuel icon]

iconRedraw
If false then the chart is NOT redrawn when the image/icon loads. You may need to set this to false if you use the adjusting feature.
Default: true

clearto
This is used in animations and effects as the default color to use when the canvas.
Default: null

Methods

obj.get(name)
An accessor that you can use to retrieve the values of properties.

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.

obj.on(event, function)

This method can be used to set an event listener on an object. It operates in a similar way 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 option and method

The exec function is documented here.

obj.responsive(configuration)

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.

The responsive() function is documented on its own page here.

Animation effects

These effects are available and can be used instead of the draw() function. There are also generic effects available which you can see here: Generic effects and transitions

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)
    {
        // ...
    }

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