Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

API: Events

rsandor edited this page · 14 revisions

How Events Work

Gury allows you to bind events to individual objects in a canvas. Gury provides a few common mouse events and will handle triggering automatically as a user moves around and clicks on the canvas. Let's get started with a quick example:

// Create a new Gury instance
$g().size(128, 128).background('black')

  // Place a circle in the middle of the scene
  .add('circle', new Circle(64, 64, 50, {color: 'red'}))

  // Add an enter listener to change the color when 
  // the user's cursor enters the circle:
  .mouseenter('circle', function(e) {
    this.color = 'white';
  })

  // And finally a listener to revert the color when
  // The user's cursor exits the circle
  .mouseleave('circle', function(e) {
    this.color = 'red';
  })

  // Place and draw the scene
  .place('#my_container').draw();

When the mouse moves over the canvas Gury automatically tracks its position and determines if it is over an object in the scene. When Gury detects that the cursor has entered the circle it triggers the mouseenter event on the circle and executes the handler that we defined above. Gury handles the mouseleave event in a similar fashion.

Gury uses native canvas rendering to determine if the mouse is over an object in the scene. This means that any object you can draw on a canvas is automatically supported by Gury with pixel-perfect accuracy for mouse events. And don't worry about speed if you have a lot of non-evented objects on the screen, Gury is smart and only checks for objects that have been bound to particular events as they are triggered.

For more examples of how to use Gury Events see demos/events.html and demos/multi-canvas.html in the repository.

Methods

Below are the various methods currently supported by Gury for working with events.

.bind(q, name, closure)

Binds an event listener to the given object. The q parameter can be an object or a tag, the name parameter is the name of the event to bind, and the closure parameter is a function that handles the event. Here is an example:

var box = new Box('red');
$g().add(box).bind(box, 'click', function(e) {
  alert('You clicked on the box! Mouse Position (' + e.canvasX + ', ' + e.canvasY + ')');
});

.unbind(q, name, closure)

Unbinds an event listener to the given object. The q parameter can be an object or tag, the name parameter is the name of the event to bind, and the optional closure parameter is function that was previously bound. If you do not provide a closure parameter then all handlers for the event with the given name will be removed. If you do not provide a name parameter then all listeners for all events will be removed from the object. Here's an example:

// Add a couple of colored boxes
var box = new Box('red'), box2 = new Box('green');
$g().add('box.red', box).add('box.green', box2)
  // Add a mousedown listener for all boxes
  .bind('box', 'mousedown', function(e) { alert('Mouse Down!'); })
  // Remove all listeners for red boxes
  .unbind('box.red');

.trigger(object, name, e)

Triggers an event for the given object for the event with the given name and the event object e. This method simply allows you to trigger events on objects in the Gury instance. For now it is a bit simplistic, but should be fleshed out soon.

.click(q, closure)

Helper function that allows you to define click listeners on objects. Here is an example:

// The .bind() example simplified
$g().add('box', new Box('red')).click('box', function(e) {
  alert('You clicked on the box! Mouse Position (' + e.canvasX + ', ' + e.canvasY + ')');
});

.mousedown(q, closure)

Allows you to define mouse down listeners for objects. Here's an example:

var circle = new Circle('blue');
$g().add(circle).mousedown(circle, function(e) { this.color = 'yellow'; });

.mouseup(q, closure)

Allows you to define mouse up listeners for objects. An example:

// Add the circle
var circle = new Circle('blue');
$g().add(circle)
  // Change the color to yellow on "mouse down"
  .mousedown(circle, function(e) { this.color = 'yellow'; });
  // Change back to blue on "mouse up"
  .mouseup(circle, function(e) { this.color = 'blue'; });

.mousemove(q, closure)

Allows you to define mouse move listeners for objects, example:

// Add a circle and a box
$g().add('shape', new Circle('red')).add('shape', new Box('green'))
  // Add a mouse move listener to change the colors on move
  .mousemove('shape', function(e) { this.color = "blue"; });

.mouseenter(q, closure)

Allows you to define mouse enter listeners for objects, example:

var box = new Box('green');
$g().add(box).mouseenter(box, function(e) { this.size += 20; });

.mouseleave(q, closure)

Allows you to define mouse leave listeners for objects, example:

// Add a box to the instance
var box = new Box('green');
$g().add(box)
  // Add a mouse enter to make the box bigger on hover
  .mouseenter(box, function(e) { this.size += 20; })
  // Add a mouse leave to make the box smaller when not hovering
  .mouseleave(box, function(e) { this.size -= 20; });
Something went wrong with that request. Please try again.