Using keys or legends
- Introduction
- Key configuration properties
- Active key elements
- Using interactive keys on your charts
- HTML Keys
Introduction
Using a key on your chart allows you to provide information about what the datasets that are displayed on the chart represent.
Keys can be used in two different modes - a horizontal one designed to sit in the margins of the chart, and a vertical one that is designed to sit over the chart.
Key configuration properties
The available key properties and their defaults are listed below (some chart types have slightly different defaults to suit):
An array of key elements (this is the text that is displayed in the key.
Default: [] (An empty array)
keyHalign
The horizontal alignment of the key
Default: right
keyPosition
This determines the positioning/layout of the key. Possible values are graph and margin.
Default: graph
keyPositionMarginBoxed
When the key is in margin mode this determines if it sits in a box.
Default: false
keyPositionMarginHSpace
When the key is in margin mode this adds horizontal space to the key items (ie they're more spaced out).
Default:
keyPositionGraphBoxed
When the key is in graph mode this determines if it sits in a box.
Default: true
keyPositionX
This allows you to specify an X coordinate for the key.
Default: null
keyPositionY
This allows you to specify a Y coordinate for the key.
Default: null
keyPositionOffsetx
This allows you to offset the X coordinate for the key by a given amount.
Default: null
keyPositionOffsety
This allows you to offset the Y coordinate for the key by a given amount.
Default: null
keyShadow
This controls whether the key has a shadow or not.
Default: false
keyShadowOffsetx
This controls the X offset for the shadow.
Default: 2
keyShadowOffsety
This controls the Y offset for the shadow.
Default: 2
keyShadowColor
This controls the color of the shadow.
Default: #666
keyShadowBlur
This controls the blur that's applied to the shadow.
Default: 3
keyColors
If the calculated colors are not what you want to see - this allows you to specify your own colors.
Default: null
keyColorShape
This is the shape that the color blob takes on.
Default: square (can be an array of shapes)
keyBackground
The background of the key.
Default: white
keyRounded
Whether the corners of the key are square or rounded.
Default: true
keyLinewidth
The
linewidth used for the key.Default: 1
keyLabelsFont
The font used for the key text.
Default: [same as the textFont setting]
keyLabelsSize
The size of the text in the key.
Default: [same as the textSize setting]
keyLabelsColor
The color of the text in the key.
Default: black
keyLabelsBold
Whether the text in the key is bold or not.
Default: false
keyLabelsItalic
Whether the text in the key is italic or not.
Default: false
keyLabelsOffsetx
The offset that gets applied to the X coordinate to the key text.
Default:
keyLabelsOffsety
The offset that gets applied to the Y coordinate to the key text.
Default:
keyTextAccessible
By default the key text IS NOT accessible but by using this setting you can override this.
Default: null
keyInteractive
Whether the key is interactive or not. Not all chart types support this.
Default: false
keyInteractiveHighlightChartFill
The highlight fill color that's used to highlight the chart by the interactive key.
Default: rgba(255,255,255,0.7)
keyInteractiveHighlightChartStroke
The highlight stroke color that's used to highlight the chart by the interactive key.
Default: black
Active key elements
When you hover over or click on a key element/entry then the RGraph registry will hold details of the relevant key entry. So in your event listener, you will be able to determine the key entry like this:
key = RGraph.Registry.get('key-element');
And you could use it like this:
// Assume that the line variable is your line chart object
line.canvas.onmousemove = function (e)
{
var key = RGraph.Registry.get('key-element');
if (key) {
// Log the details of the object to the console
console.log(key);
}
};
Using interactive keys on your charts
canvas text for the key
- not DOM text. You can enable textAccessible if you want but
the interactive key will ignore it.
Formerly the interactive key was only implemented for the Line and Pie charts. As of mid-2013, however, it was rewritten and is now available with a lot more chart types. The demo pages for the interactive key are available in the download archive.
Having been rewritten
the interactive key now uses the drawing API
Rect object and the dynamic library:
<script src="RGraph.common.core.js"></script>
<script src="RGraph.common.dynamic.js"></script>
<script src="RGraph.common.key.js"></script>
<script src="RGraph.drawing.rect.js"></script>
<script>
line = new RGraph.Line({
id: 'cvs',
data: [
[458,435,466,148,396,485,456],
[153,245,256,33,216,248,344],
[55,56,43,374,76,78,85]
],
options: {
textSize: 12,
marginTop: 45,
marginLeft: 35,
marginRight: 35,
marginBottom: 35,
marginInner: 15,
xaxisLabels: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'],
tickmarksStyle: 'endcircle',
linewidth: 3,
xaxisTickmarksStyle: 12,
spline: true,
key: ['Rob','Julie','Jack'],
keyPosition: 'margin',
keyInteractive: true,
title: 'A Line chart with interactive key',
titleSize: 16
}
}).draw();
</script>
HTML keys
In December 2013 a function was added to RGraph that allows you to use anHTML key next to your chart. This key is made up
of div and span tags so you may find it easier to interact with.
You can read more about HTML keys on this page.