Last updated January 2, 2012. Created by danielb on April 24, 2009.
Log in to edit this page.

This document provides a programmer's reference to the Drawing API.

Drawing Canvas

Canvas
Description: The top level drawing element, this will contain the other elements:

<?php
/*
* An example canvas function.
* You would execute this with drawing_get_canvas('example_canvas');
*/
function example_canvas() {
 
$canvas = array();
 
$canvas['#width'] = '640px';
 
$canvas['#height'] = '480px';
 
// canvas elements go here
 
$canvas['example_element'] = array(
   
'#type' => 'circle',
   
'#fill' => 'red',
   
'#cx' => 200,
   
'#cy' => 200,
   
'#r' => 20,
  );
  return
$canvas;
}
?>

Attributes: #method, #height, #width.
GD-only attributes: #format.

Shape Elements

Rectangle
Description: draw a rectangle. Main parameters are the coordinates of the top-left corner, height and width:
<?php
$canvas
['oblong'] = array(
 
'#type' => 'rectangle',
 
'#cx' => 5,
 
'#cy' => 5,
 
'#height' => 50,
 
'#width' => 20,
);
?>

Attributes: #cx, #cy, #height, #width, #weight, #stroke, #stroke-width, #fill, #opacity.
Ellipse
Description: draw a ellipse. Main parameters are the coordinates of the center and the radii in x and y direction.
Attributes: #cx, #cy, #rx, #ry, #weight, #stroke, #stroke-width, #fill, #opacity.
Circle
Description: draw a circle. Main parameters are the coordinates of the center and the radius.
Attributes: #cx, #cy, #r, #weight, #stroke, #stroke-width, #fill, #opacity.
Line
Description: draw a line. Main parameters are the coordinates of the ending points:

<?php
$canvas
['line_example'] = array(
 
'#type' => 'line',
 
'#stroke' => 'green',
 
'#cx1' => 5,
 
'#cy1' => 5,
 
'#cx2' => 75,
 
'#cy2' => 75,
);
?>

Attributes: #cx1, #cy1, #cx2, #cy2, #weight, #stroke, #stroke-width, #opacity.

Polyline (multipoints)
Description: draw a set of connected straight line segments. Main parameters are the points that make up the polyline. Syntax is forming an array:
<?php
$canvas
['polyline01'] = array(
 
'#type' => 'polyline',
 
'#stroke' => 'pink',
 
'#points' => array(
   
1 => array(
     
'#cx' => 5,
     
'#cy' => 5,
    ),
   
2 => array(
     
'#cx' => 75,
     
'#cy' => 75,
    ),
  ),
);
?>

Attributes: #points array of arrays (each with keys #cx, #cy), #weight, #stroke, #stroke-width, #fill, #opacity.

Polygon (multipoints)
Description: draw a set of connected straight line segments and close it. Main parameters are the points that make up the polygon. Syntax is the same as of the polyline.
Attributes: #points array of arrays (each with keys #cx, #cy), #weight, #stroke, #stroke-width, #fill, #opacity.
Path (multipoints)
Description: draw the outline of the shape point by point. You can use bezier, arc curves with this type.

Main parameters are the points that make up the shape. There are two syntaxes available for defining the shape: a machine friendly (implicit), and an inclusion friendly (explicit). Default is the implicit declaration, explicit has to be indicated by setting the #explicit to the explicit SVG path data string. Examples:

Explicit path:

<?php
$canvas
['path_explicit'] = array(
 
'#type' => 'path',
 
'#explicit' => 'M 100 100 L 300 100 L 200 300 z',
);
?>

Implicit path:

<?php
$canvas
['path_implicit'] = array(
  array(
   
'#type' => 'path',
   
// "M <x>,<y> "
   
array(
     
'#command' => 'moveto',
     
'#points' => array(
        array(<
x>, <y>),
      ),
    ),
   
// "z "
   
array(
     
'#command' => 'closepath',
    ),
   
// "c <x1>,<y1> <x2>,<y2> <x>,<y> "
   
array(
     
'#command' => 'curveto',
     
'#relative' => TRUE,
     
'#points' => array(
        array(<
x1>, <y1>, <x2>, <y2>, <x>, <y>),
      ),
    ),
   
// "A <rx>,<ry>, <x-axis-rotation>, <large-arc-flag>,<sweep-flag>, <x>,<y> "
   
array(
     
'#command' => 'elliptical_arc',
     
'#points' => array(
        array(<
rx>, <ry>, <x-axis-rotation>, <large-arc-flag>, <sweep-flag>, <x>, <y>),
      ),
    ),
  ),
);
?>

The example above does not have real values, which are all numbers, but uses <placeholders> indicating the variable name. The variable names can be used as keys for the variables values if supplying them out of order (not yet). For an explanation of what these variable names mean see: http://www.w3.org/TR/SVG/paths.html

Attributes: #weight, #stroke, #stroke-width, #fill, #opacity, #explicit.
Sub-elements: Each child element is an associative array with keys:
'#command' - Contains the name of a command, or it's alias.
'#points' - (if applicable) An array of points, each point is an array containing one set of the variables required by the command.
'#relative' - (optional) Boolean TRUE indicating that the supplied points are relative to the previous point. Defaults to FALSE unless the #command used is the 'relative alias' then it is forced to TRUE.

Here is a table that gives a quick overview of the commands available.

Command Alias Relative alias Point

moveto

Start a new path from (x,y).

M m x y

closepath

Draw a straight line back to the start of the shape.

Z z

lineto

Draw a straight line to (x,y).

L l x y

horizontal_lineto

Draw a horizontal line to this x ordinate.

H h x

vertical_lineto

Draw a horizontal line to this y ordinate.

V v y

curveto

Draw a cubic bezier to (x,y) using control points (x1,y1) and (x2,y2).

C c x1 y1 x2 y2 x y

smooth_curveto

Draw a cubic bezier to (x,y) using an interpolated control point and control point (x2,y2).

S s x2 y2 x y

bezier_curveto

Draw a quadratic bezier to (x,y) using control point (x1,y1).

Q q x1 y1 x y

smooth_bezier_curveto

Draw a quadratic bezier to (x,y) using an interpolated control point.

T t x y

elliptical_arc

Draw an elliptical curve to (x,y) with radii rx and ry and a rotation angle of x-axis-rotation. Set large-arc-flag to 0 for small arc, 1 for large arc. Set sweep-flag to 0 for negative angle, 1 for positive angle.

A a rx ry x-axis-rotation large-arc-flag sweep-flag x y
Text
Description: print text.
Attributes: #cx, #cy, #rotate, #value, #weight, #font, #font-size, #bold, #italic, #align, #width, #stroke, #stroke-width, #fill, #opacity.

Special Elements

Group
Description: group one or more objects.
Attributes: #transform, #height, #width, #weight.

Transformations

Only the group element is capable of declaring transformations for them. #transform is an array containing the names of the valid transformations, and their arguments in array format.
Example:

<?php
$canvas
['plot'] = array(
   
'#type' => 'group',
   
'#stroke' => 'black',
   
'#stroke-width' => 2,
   
'#transform' => array(
     
'translate' => array('50', -50),
     
'scale' => array(1,-1),
    ),
  );
?>

Transformation syntax

  • 'matrix' => array(a, b, c, d, e, f),
  • 'translate' => array(x, y),
  • 'scale' => array(x, y),
  • 'rotate' => array(a),
  • 'skewX' => array(a),
  • 'skewY => array(a),

These transformations are based on The SVG transform attribute.

File
Description: embedded png/jpg/gif file (can be image output of php file)
Attributes: #height, #width, #location, #weight.

Example:

<?php
$canvas
['sparkline'] = array(
 
'#type' => 'file',
 
'#location' => drupal_get_path('module', 'sparkline') . '/sparkline.php',
 
'#height' => '200px',
 
'#width' => '200px',
);
?>

Attributes

Here is a complete list of attributes for reference, of course some only apply to certain drawing elements.

Attributes marked 'SVG only' and 'GD only' obviously lack support from all toolkits and shouldn't be relied upon unless forcing the #method on the canvas which is usually best to avoid. Attributes marked 'advanced use only' are usually for internal purposes but can be manipulated by explicitly setting them, though also not recommended. The behavior of these attributes is not completely documented.

  • #a: (SVG only) Anchor, link to other pages, documents. Just like <a> in HTML.
  • #align: Text alignment, can be: 'left', 'center', or 'right'.
  • #bold: Boolean indicating if text is bold or not.
  • #class: (SVG only) A custom class used for targetting SVG elements for CSS/JS.
  • #cx: Anchor point of element, measured in pixels from the left of the canvas to the left edge of the shape for rectangles, center for circles/ellipses.
  • #cy: Anchor point of element, measured in pixels from the top of the canvas to the top edge of the shape for rectangles, center for circles/ellipses.
  • #cx1, #cy1: In some cases the same as #cx and #cy, and in others the same as #cxN and #cyN.
  • #cxN, #cyN: The Nth (x,y) coordinate of a vertex/corner/point in a list of coordinates.
  • #directory: (GD only) The directory path where to save the GD image. Default is file_directory_path() .'/drawing_gd' (advanced use only).
  • #explicit: A string of 'SVG path data' used in the path shape element as an alternative to supplying child elements to specify the segments of the shape.
  • #file: (GD only) Full path and filename where to save the GD image. Default is #directory/#filename (advanced use only).
  • #filename (GD only) The filename where to save the GD image. Default is #gd_id.#format (advanced use only).
  • #fill: Color of fill in the shape, can be given as 'blue', '#0000ff', or 'rgb(0,0,255)'.
  • #fill_args: (GD only) Array of args to append to the param array passed to #fill_func (advanced use only).
  • #fill_func: (GD only) String name of function to use to draw fill (advanced use only).
  • #fill-opacity: (GD only) 1 is opaque, 0 is transparent. Default is value of #opacity.
  • #format: (GD only) Force a file format (gif/png/jpg) when using the GD Drawing toolkit, defaults to 'png'.
  • #font: Can be 'serif', 'sans-serif', or 'monospace'.
  • #font-size: The font size of the text.
  • #gd_id: (GD only) A custom ID used for identifying GD images (advanced use only).
  • #height: Height of the shape.
  • #id: (SVG only) A custom unique ID used for identifying SVG elements for CSS/JS.
  • #italic: Boolean indicating whether text is italic.
  • #location: Full path and filename of an existing input file (can be a php script).
  • #method: The Drawing toolkit to use, e.g. 'gd' or 'svg'. If not set, will use the site default (recommended if possible).
  • #opacity: Decimal range from 0 to 1. 1 is opaque, 0 is transparent. Default is 1.
  • #points: Multipoint declaration, syntax is specific to the #command used..
  • #r: Radius of the circle.
  • #rx: Radius in the x direction (one half width of the circle/ellipse).
  • #ry: Radius in the y direction (one half height of the circle/ellipse).
  • #rotate: Rotation of the object around 0,0. Units in degrees.
  • #stroke: Color of stroke around the shape, can be given as 'blue', '#0000ff', or 'rgb(0,0,255)'.
  • #stroke_args: (GD only) Array of args to append to the param array passed to #stroke_func (advanced use only).
  • #stroke_func: (GD only) String name of function to use to draw stroke (advanced use only).
  • #stroke-opacity: (GD only) 1 is opaque, 0 is transparent. Default is value of #opacity.
  • #stroke-width: Thickness of lines. Default is 1.
  • #transform: Apply transformations, see Transformations section below.
  • #value: For text this is the string of text to use.
  • #weight: Use for ordering elements against each other.
  • #width: Width of the shape.

Tips

  • The order of array elements is significant. However, Drupal's rendering system can throw it off. If that affects you and you aren't using #weight properties to fix it, you can also set #sorted = TRUE on the array and Drupal will keep the order as-is.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.