Skip to content
This repository

How Gury Works

Gury is a framework that makes it easier to perform common tasks with HTML5 Canvas tags in Canvas enabled browsers. It allows you to easily reference canvas tags in the DOM using JavaScript, create and place Canvas tags on the fly, and resize and style canvas tags. Let's get going with a quick example:

$g('my_canvas').size(200, 200).background("black");

The above example will search the DOM for a canvas tag with id="my_canvas" and create a new Gury instance that wraps that tag. Additionally it will resize the tag to 200px by 200px and set its background style to "black". But this is only the scratching the surface of what you can do with Gury, the next example shows a bit more:

$g("my_canvas").size(200, 200).background('black').add(function(ctx) {
  ctx.fillStyle = "red";
  ctx.fillRect(10, 10, 180, 180);
}).draw();

The above example starts out just like the first example, then it adds a custom rendering function that draws a red square in the middle of the canvas. Finally it calls the built-in Gury function .draw() to draw all of the added objects to the canvas. For more information on objects and drawing see API: Objects and API: Drawing and Animation respectively.

Methods

Below are the various methods and functions used to work with gury. Functions preceeded with a . should be called after you have obtained a Gury instance using the $g() or Gury() methods.

Gury(), $g()

Creates a new canvas node and returns the gury object representing that canvas.

Gury(id), $g(id)

Finds a canvas on the page with the given id and returns a gury object representing that canvas.

Gury.failWithException()

Returns true if Gury fails with an exception, and returns false if Gury actions fail silently. By default it will return true (which is recommended for development, but maybe not for production).

Gury.failWithException(b)

Allows you to set whether or not Gury will fail silently or with an exception. Just set the b parameter to false if you do not want to see failure exceptions and to true if you do.

.canvas

The canvas node represented by the gury object. Example:

$g().canvas.style.border = "5px solid red";

This will only return the first canvas registered to the Gury instance (see .register and .unregister below).

.ctx

The graphics context for the canvas represented by the gury object. Example:

$g().ctx.fillStyle = "#a0a";

This will only return the context of the first canvas registered to the Gury instance (see .register and .unregister below).

.place(node) / .place(selector)

This method is used to place canvas objects created using gury. If the node parameter is a DOM element then the canvas will be added as a child to that DOM element. If the node parameter is a string and jQuery is available the parameter is treated as a selector and the canvas is appended to the nodes returned by applying the jQuery selector.

This method will place each canvas bound to the Gury instance into the given node or selector. You can bind and remove additional canvases from the Gury instance by using the .register and .unregister methods detailed below.

Here's an example that places the canvas inside a node:

var container = document.getElementById('my_div');
$g().place(container);

And another that uses jQuery to place the canvas (given jQuery is loaded, of course):

$g().place('#my_div');

*** Important *** The second example requires that you have loaded jQuery before executing the script. If jQuery is not loaded then the method will throw an exception. For more information on jQuery see http://jquery.com

.size(width, height)

Changes the size of the canvas represented by the gury object. The parameters are expected to be in pixels. Example:

$g().size(200, 200);

which creates a new canvas and sizes it to 200px by 200px.

This method will affect the size of each canvas bound to the Gury instance (see .register and .unregister below).

.background(color)

Changes the background style of the canvas represented by the gury object. The color parameter is expected to be a string containing the CSS for the background of the canvas. Here's an example that set's an existing canvas' background to light gray:

$g('my_canvas').background('#aaa');

And another that resizes, sets the background, and finally places a canvas (this is a pretty common string of operation):

$g().size(400, 250).background('black').place('#my_div');

This method will affect the background style of each canvas bound to the Gury instance (see .register and .unregister below).

.register(canvas)

Registers a canvas with the Gury object. This allows you to have a single Gury object affecting multiple canvases on the same page. Here's an example

// First create a gury instance tied to a new canvas
var gury = $g();

// And then add an additional canvas
gury.register(document.createElement('canvas'));

.unregister(canvas)

Unregisters a canvas from the Gury object. Use this in conjunction with the .register(canvas) method detailed above:

// Create a new Gury instance with two canvases
var c2 = document.createElement('canvas');
var gury = $g().register(c2);

// Remove the second canvas from the instance
gury.unregister(c2);
Something went wrong with that request. Please try again.