cajal

cajal is a javascript library to draw and animate shapes on the HTML5 canvas element

Installation

Download the source and include the cajal.js file in the head section of your html document:

<script type="text/javascript" src="cajal.js"></script>

Getting an instance of cajal

To create a instance of the cajal library call the cajal constructor and pass the id attribute or the DOM-object of your canvas element as an argument

<canvas id="mycanvas" width="800" height="600"></canvas>
<script type="text/javascript">
	//passing the element id attribute
	var c = new cajal('mycanvas');
	//in combination with jQuery
	var c2 = new cajal($('#mycanvas').get(0));
</script>

Global settings

There are a few options you can set globally for the cajal instance by passing a literal object as a second parameter to the cajal constructor.

<canvas id="mycanvas" width="800" height="600"></canvas>
<script type="text/javascript">
	var c = new cajal('mycanvas', {
		globalAlpha: 0.5,
		globalCompositeOperation: 'lighter',
	});
</script>

This literal object can have the following variables:

• autoClearCanvas: Boolean weather the canvas is cleared automatically each draw() call [default value true]
• globalAlpha: Double between 0 and 1 which defines the global alpha value applied to each item drawn
• globalCompositeOperation: Describes how the items are drawn to the canvas [default value source-over] (more information)
• loopFps: Frame rate for animations (frames/sec)

The shapes

Each shape is an object that is independet from the canvas it is later drawn on. So you can draw the same shape (e.g. a circle) on several canvas elements.

Circle

You can create a circle by calling the circle constructor cajal.Circle(xPos, yPos, radius). The arguments are the x and y position of the circle and the radius.

var circle = new cajal.Circle(50, 80, 30);

Item specific methods

• center(): The return value is a literal object with the x and the y coordinates of the circle's center. (For example: { x: 50, y: 80})

Rectangular

Create a rectangular using cajal.Rect(xPos, yPos, width, height, [radius]). The parameter radius is optional for creating a rectangular with rounded corners.

//normal rectangular
var rect = new cajal.Rect(50, 80, 100, 120);

//rounded corners
var roundedRect = new cajal.Rect(50, 80, 100, 120,30);

Item specific methods

• center(): The return value is a literal object with the x and the y coordinates of the rectangular's center. (For example: { x: 50, y: 80})
• width(): Returns the width of the rectangular
• height(): Returns the height of the rectangular

Path

Create a path object with cajal.Path(xPos, yPos). There are several methods you can call to add points, or bezier curves to this path.

var path = cajal.Path(20, 30).to(100, 30).to(100, 80).close();

Item specific methods

• line(xPos, yPos): Draw a line from the last point in path to the position (xPos, yPos)
• to(xPos, yPos): Synonym for line(xPos, yPos)
• quadraticCurve(xPos, yPos, cx, cy): Draw a quadratic bezier curve to (xPos, yPos) with the control point (cx, cy)
• bezierCurve(xPos, yPos, c1x, c1y, c2x, c2y): Draw a quadratic bezier curve to (xPos, yPos) with the control points (c1x, c1y) and (c2x, c2y)
• close(): Close the path (every path will be automatically closed before drawing it on the canvas)
• center(): The return value is a literal object with the approximate x and the y coordinates of the path's center. (For example: { x: 50, y: 80})

Text

Create a text object with cajal.Text(xPos, yPos, text).

var text = cajal.Text(20, 30, 'cajal - canvas javascript library');

Item specific methods

• append(text): Append text to the current text
• prepend(text): Prepend text to the current text
• text(text): Set new text
• center(): The return value is a literal object with the approximate x and the y coordinates of the center. (For example: { x: 50, y: 80})

Polygon

Create a symmetric polygon object with cajal.Polygon(xPos, yPos, edges, radius). Example: create a poygon with 5 edges and a radius of 30px

var poly = cajal.Polygon(20, 30, 5, 30);

Item specific methods

• setPoints(n, r): Set the number of edges and the radius to new values
• center(): The return value is a literal object with the x and the y coordinates of the center. (For example: { x: 50, y: 80})

Circle sector

A circle sector (circular sector) is the part of a circle defined by a radius and an angle, that you can find in a pie chart for example. You can create that circle sector with the method cajal.CircleSector(x, y, r, angle) Example: create a circle sector with an angle of 120 Degrees and a radius of 50

var csec = cajal.CircleSector(20, 30, 50, 120);

Circle segment

A circle segment (circular segment) is a part of a circle defined by a radius and an angle. Compared with the circle sector, a segment does not contain the inner part of a circle. It is cut off by a line from the start and end point of the circular arc. You can create that circle segment with the method cajal.CircleSegment(x, y, r, angle) Example: create a circle segment with an angle of 120 Degrees and a radius of 50

var cseg = cajal.CircleSsegment(20, 30, 50, 120);

Item specific methods

• close(): Connect the end and start point of the circular arc with a line.

Methods for every item

There are a bunch of methods that you can call on each item object to modify it.

• clone(): Returns a clone of the item
• hide(): Hide the item (will not be drawn on the canvas)
• show(): Show the item if it was hidden
• changeMatrix(m11, m12, m21, m22, dy, dx): Change the matrix of the canvas element only for this item. The current matrix will be multiplied with your matrix (scaling, rotation and moving can be done in one step if you know the basics of matrix stuff)
• setMatrix(m11, m12, m21, m22, dy, dx): Set the matrix of the canvas element only for this item. The current matrix will be overwritten with your matrix (scaling, rotation and moving can be done in one step if you know the basics of matrix stuff)
• rotate(angle, [point]): Rotate the item to the given angle (in degrees). If you want the item not to rotate around its center but around a specific point, can pass a literal object with x and y as the points parameter. ({x:23, y: 56} will rotate around the point (23|65) )
• rotateBy(angle, [point]): Rotate the item by a given angle (in degrees). If you want the item not to rotate around its center but around a specific point, can pass a literal object with x and y as the points parameter. ({x:23, y: 56} will rotate around the point (23|65) )
• move(x, y): Move the item to the given position
• moveBy(dx, dy): Move the item by the given offset
• scale(dx, dy): Scale the item to a given size item.scale(1.2, 1.2) will scale your item to 120% of its initial size
• scaleBy(dx, dy): Scale the item by a given size item.scaleBy(1.5, 1.5) will scale your item to 150% of its current size
• options(options): Set draw options for this item as described in the chapter below

Draw options

The draw options must be a literal object with the following optional variables. Other variables will be ignored by the script and can be used as a data storage for item relevant information

• stroke: Color to stroke, or null for no stroke. Accepted values are hexadecimal color codes (e.g. #175175), strings (e.g. red or blue), rgb(a) values (e.g. rgba(120,200,85,0.7) or rgb(120,200,85)) [default value: null]
• fill: Color to fill, or null for no filling. Accepted values are hexadecimal color codes (e.g. #175175), strings (e.g. red or blue), rgb(a) values (e.g. rgba(120,200,85,0.7) or rgb(120,200,85)) [default value: null]
• width: Width of the stroke line [default value: 1]
• font: Font size and family for text renderings [default value: '13px sans-serif']
• lineCap: Accepted values: butt, square and round [default value: butt] (more information)
• lineJoin: Accepted values: miter, bevel and round [default value: miter] (more information)
• miterLimit: [default value: 10] (more information)
• shadowX: Shadow x offset
• shadowX: Shadow y offset
• shadowBlur: Shadow blur value
• shadow: Shadow color or null for no shadow. Accepted values are hexadecimal color codes (e.g. #175175), strings (e.g. red or blue), rgb(a) values (e.g. rgba(120,200,85,0.7) or rgb(120,200,85)) [default value: null]

How to add, remove and draw items to the canvas

First of all you need an instance of cajal for the canvas element that you want to draw on.

Add items

Then you can add items with the method add(). There are two ways to use this method. You can either pass the item as one argument, or you pass an itemId and the item as two arguments. If you want to change the item you need to specify a name (itemId) for it, so that you can access the item with the get-Method afterwards. In the case of a more simple usage, you can pass only the item object, but you will not be able to change this item afterwards. If you add an item with an itemId that already exists, it will be overwritten.

Example: drawing a circle

// get the cajal instance
var c = cajal('mycanvas');