dojox.gfx 0.9 documentation

Underlying concepts

dojox.gfx is a cross-platform declarative interactive graphics package. It follows SVG loosely as the underlying model. At present time SVG and VML back-ends are implemented.
On conceptual level dojox.gfx has a simple declarative model:
In order to draw a picture a programmer constructs a pseudo-DOM from a surface object, shapes, and groups, sets appropriate attributes, and picture is drawn automatically by a browser. Modifications of shapes change picture automatically. It is possible to attach event handlers to shapes using dojox.connect().
Following conventions are used:

Common shape methods

All shape objects support following methods:

Visual properties

Color

Anywhere color is accepted following objects can be used to define it:

Stroke property

A stroke property is an object that defines how to draw an outline of a shape. It is not supported by an image and a group shapes. Following properties are recognized:
By default all shapes are created with "null" stroke meaning "no stroke is performed".
If a string was specified as a stroke property, it is interpreted as a color, the rest is taken from defaults.

Fill property

A fill property is an object that defines how to fill a shape. It is not supported by an image and a group shapes. Four types of fills can be used:
By default all shapes are created with "null" fill meaning "no fill is performed".
Important implementation details for VML renderer:

Geometric properties

Coordinates and transformations

Linear transformations are a very important part of any graphics library. We deal with 2D graphics, and we operate with 3 by 3 matrices:

xx xy dx
yx yy dy
 0  0  1

Because the third row is always constant we use an abbreviated way to write it: {xx: 1, xy: 0, yx: 0, yy: 1, dx: 0, dy: 0} - this is an identity matrix. The same simplification goes for coordinates:

x
y
1

Because the third element is always 1 we "add" it virtually: {x: 12, y: 33}. The result of application of a matrix to a vector is predictable:

xx * x + xy * y + dx
yx * x + yy * y + dy

(I skipped the dummy third "coordinate").

In order to understand transformations you need to be familiar with fundamentals of matrices (matrix multiplication, multiplication of a vector by a matrix, order of multiplications). dojox.gfx uses a mnemonic way to describe a matrix: xx scales an X component of a coordinate, yy scales a Y component, xy, and yx affect both components, dx moves an X component, and dy moves a Y component.
Simple examples:
More complex examples:
Don't worry, in most cases you don't need to calculate all members of a transformation matrix directly. As you can see not all members of matrix should be specified - all skipped members going to be copied from the identity matrix. There is a shortcut for scaling - if a number N is used instead of a matrix, it is assumed that it represents a uniform scaling matrix {xx: N, yy: N}.
The way to apply a matrix to a coordinate:
The way to combine transformations together:
Effectively all transformations are always applied from right to left sequentially, and they can be combined producing a matrix, which defines a complex transformation. dojox.gfx.matrix defines Matrix2D class, as well as numerous helpers (Matrix2D is propagated to dojox.gfx namespace for convenience). Most important of them (all in dojox.gfx.matrix namespace) are listed below. In all signatures a, b, c, and e are numbers (coordinate components or scaling factors), p is a 2D coordinate, r is an angle in radians, d is an angle in degrees (positive value of an angle is CW), m is a matrix.
Constants:
Matrix creators:
Useful operations:
The last function is extremely useful and there is a shortcut for it: anywhere a matrix is expected, an array of matrices can be specified as well. Examples:
More complex example: imagine you have a surface 500 by 500 pixels, and you want everything in it to be magnified around its center by 2, and rotated (around the center as well) by 30 degrees CW. It is easy: [translate(250, 250), rotateg(-30), scale(2), translate(-250, -250)]. Explanations:
  1. All scaling, rotating, and skewing operations work around (0, 0) point. Let's move the center of our picture to (0, 0): translate(-250, -250).
  2. Now we can scale it: scale(2).
  3. Now we can rotate it: rotateg(-30).
  4. Now let's move our center back: translate(250, 250).
This "around the point" operations are so important that there are several helpers for common transformations:
There is one more useful function: normalize(m), which returns a matrix in its canonical representation:
The same effect can be achieved with creating a matrix directly: new dojox.gfx.Matrix2D(m).

Font property

Text shapes (Text and TextPath) require a font in order to be rendered. A font description follows familiar CSS conventions. Following properties of font are recognized:
There is a useful shortcut: you can specify a font using a string similar to the CSS font property.
Implementation notes:

Individual graphics objects

This is a list of all important graphics objects and geometric shapes.

Surface

A surface is the main object, which represents a collection of shapes. No shapes can be drawn or created without a surface.
Following functions can be used to create a surface object:
Surface supports following methods:

Group

A group is a pseudo-shape, which represents a collection of shapes. Transformations applied to a group applied to all shapes of that group. It is used to aggregate shapes constructing a more complex shape, or to manage sub-pictures. The other way to use a group is to aggregate an event processing. It is planned to implement setting a (default) visual parameters to group's children including fill, stroke, and font properties.
A group combines features of a shape and a surface. It shares following methods with a shape:
It shares following methods with a surface:

Rectangle

A rectangle is a basic rectangular shape with optionally rounded corners. It can be created by the createRect() method of a surface or a group. The default shape description for rectangle is defined as the dojox.gfx.defaultRect object. Here is a list of all properties and their defaults:

Circle

A circle is a basic shape. It can be created by the createCircle() method of a surface or a group. The default shape description for circle is defined as the dojox.gfx.defaultCircle object. Here is a list of all properties and their defaults:

Ellipse

An ellipse is a basic shape. It can be created by the createEllipse() method of a surface or a group. The default shape description for ellipse is defined as the dojox.gfx.defaultEllipse object. Here is a list of all properties and their defaults:
An ellipse can be used to emulate a circle.

Line

A line is a basic shape that connects two points. It can be created by the createLine() method of a surface or a group. The default shape description for line is defined as the dojox.gfx.defaultLine object. Here is a list of all properties and their defaults:

Polyline

A polyline is a basic shape, which can be used to represent polylines and polygons. It can be created by the createPolyline() method of a surface or a group. The default shape description for polyline is defined as the dojox.gfx.defaultPolyline object. Here is a list of all properties and their defaults:
Typically a polyline is an unfilled polygon. A polyline can be "open" and "closed". The latter means that the first and the last points are the same. When filling open polylines, an edge connecting the first and the last points is assumed.
A polyline can be used to emulate a line.

Path

A path is the most versatile geometric shape, which can emulate all other geometric shapes. It can be created by the createPath() method of a surface or a group. The default shape description for path is defined as the dojox.gfx.defaultPath object. Here is a list of all properties and their defaults:
A path can be open or closed. The latter means that the first and the last points are the same. When filling open paths, a straight line connecting the first and the last points is assumed.
Path supports following methods for building path segments programmatically:
Implementation notes:

Image

An image is a shape that represents a resolution-independent color bitmap data. It can be created by the createImage() method of a surface or a group. The default shape description for image is defined as the dojox.gfx.defaultImage object. Here is a list of all properties and their defaults:
Changing width and height parameters you can stretch/shrink an image anisotropically.

Text

A text is a shape that anchors a text string to a point. It can be created by the createText() method of a surface or a group. It implements an additional text-specific method:
The default shape description for text shape is defined as the dojox.gfx.defaultText object. Here is a list of all properties and their defaults:
Implementation notes:

TextPath

A text path is a shape that flows text along an arbitrary path. Text path properties are based on the text shape properties.
It can be created by the createTextPath() method of a surface or a group. The TextPath shape object implements all methods of a Path shape object, and two additional methods:
The default shape description for text path shape is defined as the dojox.gfx.defaultTextPath object. It resembles a lot a text description object. Here is a list of all properties and their defaults:
Implementation notes: