Fuel gauge
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
Chart configuration properties
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'] |
The color of the Fuel Gauge. Note that despite there being only one color, this is still an array.
Default: ['red']
Margin properties
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
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: 45
Labels and text properties
Property | Description | Default |
---|---|---|
labelsEmpty | The text that's used as the empty label. | 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 text used as the full label. | 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> | false |
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 |
text | This allows you to add custom text to your chart if you want to. There's a dedicated page that describes this option here. | null |
The text that's used as the empty label.
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 text used as the full label.
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: false
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
text
This allows you to add custom text to your chart if you want to. There's a dedicated page that describes this option here.
Default: null
Scale properties
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 that's used as the decimal separator.
Default: .
scaleThousand
The character that's used as the thousand separator.
Default: ,
Interactive features properties
Property | Description | Default |
---|---|---|
contextmenu | The context menu. For more details see the contextmenu documentation page. | 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 |
The context menu. For more details see the contextmenu documentation page.
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 |
responsive | This option is new to the July 2023 release (v6.13) and allows you to inline the responsive configuration instead of appending it on to the end of the object it as a function. The documentation and demo pages have been updated to use this new option. You can read more about the responsive feature by reading the responsive configuration page. | null |
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
responsive
This option is new to the July 2023 release (v6.13) and allows you to inline the responsive configuration instead of appending it on to the end of the object it as a function. The documentation and demo pages have been updated to use this new option. You can read more about the responsive feature by reading the responsive configuration page.
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 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
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.
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.
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 standardmousedown
event.adjust
This event fires (repeatedly) during adjusting - like the standardmousemove
event.adjustend
This event fires at the end of adjusting - like the standardmouseup
event.annotatebegin
This event fires at the start of annotating - like the standardmousedown
event.annotate
This event fires (repeatedly) during annotating - like the standardmousemove
event.annotateend
This event fires at the end of annotating - like the standardmouseup
event.annotateclear
This event fires at the end of theRGraph.clearAnnotations
function.beforeclear
This event fires at the start of theRGraph.clear
function.clear
This event fires at the end of theRGraph.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 thedraw
method before anything has been done.firstdraw
This event fires at the end of thedraw
function - but only the first time that thedraw
function is called.draw
This event fires at the end of thedraw
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
These effects are available and can be used instead of thedraw
function. There are also generic effects available which
you can see here:
Generic effects and transitions
- 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>