Colours, gradients and patterns
This page describes how to override the default colour list with your own selection of colours, gradients and pattern fills. The same colour formats are used for specifying how to fill the background areas of legends, tooltips, the grid area and the whole graph background area.
From version 3.4 SVGGraph also supports the use of gradients and patterns for stroking lines.
The colour list
In earlier versions of SVGGraph the default colours used for bars, pie slices and markers were picked at random from the list of named colours that SVG supports. In version 2.10, a new default colour scheme was added to make graphs more usable without having to choose your own.
The colours used may be overridden from the default set by passing an array
of SVGGraph colour types to the
$colours = array( 'red', 'green', '#00ffff', 'rgb(100,200,100)', array('red','green'), array('blue', 'pattern' => 'spot'), ); $graph->colours($colours);
The colours are assigned to each bar, pie slice or data set (for graphs that show multiple sets of data) in order from the array, repeating when the number of items to show is greater than the number of entries in the array.
Colour set and range functions
colours function specifies a single list of colours,
patterns and gradients to be used for the graph. The new colour functions added
in version 2.17 allow for specifying different colour arrays or ranges of
colours for each dataset on a multi-dataset graph.
This example shows a stacked bar graph with five datasets. The first four datasets each have their colours specified using one of the colour functions, as shown in the code fragment below:
$colours = array( 'red', '#0f0', array('red', 'blue'), array('green', 'white', 'h'), array('blue', 'white:0.1', 'blue'), array('red', 'pattern' => 'polkadot'), array('green', 'pattern' => 'line', 'angle' => 45), 'blue' ); $graph->colourSet(0, $colours); $graph->colourRangeHexRGB(1, '#f00', '#00f'); $graph->colourRangeHexHSL(2, '#f00', '#00f'); $graph->colourRangeHexHSL(3, '#f00', '#00f', true);
The first dataset in the example (dataset 0, the one at the bottom) uses the
colourSet function to set a list of colours. There are solid colours,
gradients and patterns included in the set. Because there are more bars on the
graph than entries in the list, the colours start to repeat. The different types
of colour entry are described in the sections after this.
Dataset 1 uses the
colourRangeHexRGB function to specify
an RGB colour range. The start and end colours are set to
#00f, and the colours in between are chosen as though there were a
straight line drawn between the two ends of the range in the RGB colour cube.
The number of colours in the range is dependent on the number of entries in the
Dataset 2 uses
colourRangeHexHSL to specify an HSL colour range.
The RGB values of each end of the range are converted to hue, saturation and
lightness values, and then these are interpolated to find the colours in between.
The difference between two hues on the colour wheel is an angle - by default,
the HSL colour range functions will use the smallest angle between the two ends
of the range (≤180°). For dataset 3, the optional
colourRangeHexHSL is set to
makes it choose the greater angle between the two hues (≥180°).
Finally, dataset 4 at the top of the graph does not have any colours set, so the first colour set is repeated.
For this example I've only used the
colourRangeHexRGB functions with their simple RGB hex code syntax.
Here is how the other functions could be used to create the same ranges:
$graph->colourRangeRGB(1, 255, 0, 0, 0, 0, 255); // #f00 -> #00f $graph->colourRangeRGBtoHSL(2, 255, 0, 0, 0, 0, 255); $graph->colourRangeHSL(3, 0, 1, 0.5, 240, 1, 0.5, true);
All of these colour functions (and some others) are listed on the function reference page.
To specify a single solid colour you may use any of the standard named colours, or hex notation, or RGB notation:
$red = 'red'; // named colour $red = '#ff0000'; // 6-digit hex notation $red = '#f00'; // 3-digit hex notation $red = 'rgb(255,0,0)'; // RGB notation
SVGGraph supports appending an opacity value to the colour using a colon as separator:
$red = 'red:0.25'; // 25% opacity $red = '#f00:0.5'; // 50% opacity
Not all areas of the graph support the opacity value - it will be ignored in these places.
SVGGraph supports specifying vertical or horizontal linear gradients as an array of colours, with the colours assigned from top to bottom or left to right.
At least two colours must be used in gradients. The first and last colours will be at the edges of the filled area, with any other colours evenly spaced across the gradient. A final 'h' or 'v' in the array of colours specifies whether the gradient should be vertical (the default) or horizontal.
The colours can be in any of the formats listed in the colours section above, including use of the opacity value, and with an optional gradient stop percentage at the start:
The stop value must be in the range 0-100. The opacity value must be in the range 0.0-1.0.
If a gradient stop value is not provided, the stops are evenly distributed. Multiple stops may have the same value to cause an instant change of colour or opacity.
Here are some examples:
// a horizontal gradient, red at both // sides and white in the centre array('red', 'white', 'red', 'h'); // a vertical gradient, red at the top, // white in the centre, blue at the bottom array('red', 'white', 'blue'); // a horizontal rainbow gradient array('red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet', 'h'); // a horizontal gradient, 10% opaque in the centre array('red','red:0.1','red','h'), // a vertical gradient, 33% blue, then // from 50% opaque red to 100% opaque red array('blue', '33:blue', '33:red:0.5', 'red'),
Gradients are supported by the bar graphs and for the filled area under line graphs, as well as the legend, tooltip, label, grid and graph backgrounds. Where gradients are not supported, the first colour in the array will be used to fill the area instead. The colour gradients defined in the example code above are shown in the bar graph below.
SVGGraph supports a number of simple predefined patterns, or you can define your own patterns using SVG code. The format of a pattern is an array beginning with a colour, a field called “pattern” which determines the pattern to use and some optional fields to fine-tune the appearance of the pattern:
$pattern = array( 'red', // foreground colour of pattern 'pattern' => 'cross', // predefined pattern to use 'back_colour' => '#ff0:0.3', // background colour 'size' => 20, // size of pattern 'angle' => 45 // rotation angle );
The only required fields are the initial colour and “pattern”. As with the gradients, the initial colour field is used as a fallback wherever patterns are not supported. The other fields all have default values, and are explained here:
- The background colour for the pattern, default white. Use
NULLfor a completely clear background.
- The size of the repeating pattern square. The default size is 10 pixels.
- The rotation angle of the pattern, in degrees. Default is no rotation.
- The width of the repeating pattern box. The default is the value of
- The height of the repeating pattern box. The default is the value of
Each of the predefined pattern types is shown below (all using the default background colour, size and rotation). The name of each pattern has been used to label the bar containing the pattern.
I've used contrasting colours on these examples to make it easier to see the edges - looking at it for too long could give you a headache though. The example below demonstrates a more muted palette and use of the size and angle options.
If the predefined patterns don't give you the effect that you want, you can define your own pattern as a block of SVG code. You must provide the SVG markup as the “pattern” along with separate “width” and “height” fields.
This example shows how to use a tiled rectangular image pattern:
$pattern = array( 'red', 'pattern' => '<image xlink:href="images/patt.png" width="20" height="15"/>', 'width' => 20, 'height' => 15, );
The initial colour field is still required as a fallback for places where patterns are not supported, though it does not have to appear in your pattern. The SVG markup you supply is not validated except to check that it contains “<” and “>”.
The “angle” and “back_colour” fields are supported for use with user-defined patterns, but the “size” option is replaced by the “width” and “height” options.
The example above uses the RSS feed icon rotated 45° on a pink background with decreasing opacity to draw the orange shapes. The blue and red patterns are created using figures, described in the next section.
From version 3.1 figures can also be used as patterns, with the name of the figure to use replacing the main colour in the array:
$pattern = array( 'round', // name of the figure to use 'pattern' => 'figure', 'size' => 12, // 12 pixel box );
The colours used in figures are set in the
figure option, so the foreground
colour is not needed in the pattern details.
The “size”, “width” and “height” pattern options should be used to set the size of the repeating box containing the figure.
Figure patterns are drawn from
with anything outside this box truncated. This is different to how figures are
used in markers, where the
(0,0) point is the centre of the marker.
The figure used for the red and blue pattern above is shown here:
$settings = array( 'figure' => array( array( 'round', array( 'circle', 'cx' => 4, 'cy' => 4, 'r' => 3, 'stroke' => 'blue' ), array( 'circle', 'cx' => 6, 'cy' => 6, 'r' => 3, 'stroke' => 'blue' ), array( 'circle', 'cx' => 5, 'cy' => 5, 'r' => 5, 'stroke' => 'red' ), ), ), );