The SVG text function
- The options to the function
- A full source code example
- Using carriage returns in your text
- Disabling events for the text
- The RGraph.SVG.text.find() function
- The defaults object
The RGraph.SVG.text
function is a function that can be used to
add text to an svg
tag - in RGraphs case this will be a chart.
It has several features that make common tasks (eg font selection, size,
font-weight and alignment) significantly easier than creating the text
tags
yourself and adding them to the svg
tag.
It's used by all of the charts libraries and there's no reason that you shouldn't use the function too if you need to add extra text to your chart.
It looks like this (assume that you have a chart object
called obj
):
RGraph.SVG.text({ object: obj, parent: obj.svg.all, tag: 'Some text', text: 'A nice red\r\nBar chart!', x: 50, y: 260, halign: 'left', valign: 'bottom', font: 'Verdana', size: 18, bold: true, italic: true, color: 'blue', background: 'rgba(232,232,232,0.75)', padding: 5, link: 'http://www.google.com', linkTarget: '_blank' });
The options to the function
Here's a breakdown of the options that are available to you:
The chart object. This is required.
Default:
parent
RGraph
svg
charts have all of the elements inside one group - a g
tag - which has the class attribute set to all-elements
.So you can add your elements to that if you want, but you don't have to if you don't want to. This property is optional.
Default: none (optional)
tag
The tag element enables you to find specific
text
tags at a later point using the RGraph.SVG.text.find
function.Default: none
text
The text that you want to display.
Default: none
x
The X coordinate.
Default: none
y
The Y coordinate.
Default: none
halign
The horizontal alignment, This can be
left
, center
or right
.Default: left
valign
The vertical alignment, This can be
top
, center
or bottom
.Default: bottom
font
The font face to be used.
Default: sans-serif
size
The size of the text (measured in points).
Default: 12
bold
Whether the text is bold or not.
Default: false
italic
Whether the text is italic or not.
Default: false
color
The color of the text.
Default: black
background
The background color (if any).
Default: [no color)
padding
The padding that's used on the text.
Default: 0
events
Whether or not the text should receive mouse events (eg
mouseover
and click
).Default: true
link
If specified this is the
href
of where to link to.Default: [an empty string]
linkTarget
The target for the link (this is just like the target for regular
html
links).Default: _blank
A full source code example
Here's an example of a full chart. Notice that, unlike
the canvas
libraries, even though we're drawing on the chart and have dynamic
features enabled (ie tooltips) the extra text that is being added doesn't need
to be added in the draw
event. This is because with svg
the scene is not
repeatedly being redrawn like a canvas
chart is.
<script> obj = new RGraph.SVG.Bar({ id: 'cc', data: [7,6,5,2,3,5,8], options: { colors: ['gradient(red:#faa)'], xaxisLabels: ['Mon','Tue','Wed','Thu','Fri','Sat','Sun'], tooltips: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday xaxis: false, yaxis: false, shadow: true, backgroundGridVlines: false, backgroundGridBorder: false } }).draw(); RGraph.SVG.text({ object: obj, parent: obj.svg.all, tag: 'Some text', text: 'A nice red\r\nBar chart!', x: 50, y: 260, halign: 'left', valign: 'bottom', font: 'Verdana', size: 18, bold: true, italic: true, color: 'blue', background: 'rgba(232,232,232,0.75)', padding: 5, link: 'http://www.google.com', linkTarget: '_blank' }); </script>
Using carriage returns in your text
Carriage returns are catered for as of version 4.65 - all you need to do is
use
\r\n
in your text - as you might expect. The example above uses a
carriage return so that the text spans two lines.
Disabling events for the text
If you don't want the text to accept mouse events (such as click
and
mouseover
) then you can disable them by using the events
property. By
default this is true - so the text will be liable for the click
and mouseover
events.
But if you set this property to false then any events will be ignored and the
text will be transparent to the mouse - allowing you to click elements behind
the text as if the text wasn't there.
The RGraph.SVG.text.find() function
Like the canvas
libraries there's an api
function that can help you get
hold of the text nodes that RGraph adds to your charts: the
RGraph.SVG.text.find
function.
This function is very similar to the canvas
version in its operation - here's
an example.
<script>
obj = new RGraph.SVG.Bar({
id: 'cc',
data: [4,8,6,3,5,8,4],
options: {
xaxisLabels: ['Mon','Tue','Wed','Thu','Fri','Sat','Sun'],
labelsAbove: true,
labelsAboveUnitsPost: '%',
marginInner: 20,
textSize: 20,
textBold: true
}
}).draw();
RGraph.SVG.text.find({
object: obj, // Give the object to get the relevant SVG tag
// svg: obj.svg, // Or give the actual SVG tag itself (you could also use document.getElementById()
here)
tag: 'labels.above', // Exact match tag to find (eg labels.above
// tag: /^labels/ // A regex that matches the text nodes that we want
// text: 'Thu' // Exact match text to find (eg Mon)
// text: /^t/i // A regex that matches the text nodes that we want
callback: function (opt)
{
alert(opt.nodes); // This is the nodes that were found
alert(opt.nodes.length + ' node(s) found')
}
});
</script>
The options that you can give this function are:
-
id
- Theid
of the chart. If you prefer you can give theobject
argument instead. -
object
- This can be given instead of theid
option and is used to get thesvg
tag. -
tag
- This can be a string or a regular expression that is matched against the tag attribute (that RGraph adds to text nodes) of the text. -
text
- This can be a string or a regular expression that is matched against the text (that you see) itself. -
callback
- The optionalcallback
can be a function that is called when the search has found any matching text nodes. If no nodes are found then the function is still called but with an empty array.
There's an example of using this function in
the RGraph.SVG.text.find
howto
document.
The defaults object
As with the canvas
RGraph.text
function, if you have a lot of text to
add to your canvas
then you may want to use the defaults
object. As it sounds, this object allows you to set the default values that are used for the
text function so you can set the values once instead of on every call to the function.
For example:
obj = new RGraph.SVG.Bar({ id: 'cc', data: [4,8,6,4,5,3,5], options: { } }).draw(); RGraph.SVG.text.defaults = { font: 'Comic sans MS', size: 20, bold: true, color: 'blue' }; RGraph.SVG.text({ object: obj, x: 50, y: 50, text: 'Some example text!' }); RGraph.SVG.text({ object: obj, x: 50, y: 100, italic: true, bold: false, text: 'Some more example text but in italic instead of bold!' });