Kontra​.pointer

A simple pointer API. You can use it move the main sprite or respond to a pointer event. Works with both mouse and touch events.

Pointer events can be added on a global level or on individual sprites or objects. Before an object can receive pointer events, you must tell the pointer which objects to track and the object must haven been rendered to the canvas using object.render().

After an object is tracked and rendered, you can assign it an onDown, onUp, or onOver functions which will be called whenever a pointer down, up, or over event happens on the object.

let sprite = kontra.sprite({
  onDown: function() {
    // handle on down events on the sprite
  },
  onUp: function() {
    // handle on up events on the sprite
  },
  onOver: function() {
    // handle on over events on the sprite
  }
});
kontra.pointer.track(sprite);
sprite.render();

By default, the pointer is treated as a circle and will check for collisions against objects assuming they are rectangular (have a width and height property).

If you need to perform a different type of collision detection, assign the object a collidesWithPointer(pointer) function and it will be called instead, passing the current pointer object. Use this function to determine how the pointer circle should collide with the object.

let sprite = kontra.sprite({
  x: 10,
  y: 10,
  radius: 10
  collidesWithPointer: function(pointer) {
    // perform a circle v circle collision test
    let dx = pointer.x - this.x;
    let dy = pointer.y - this.y;
    return Math.sqrt(dx * dx + dy * dy) < this.radius;
  });

Table of Contents

Available buttons

Below is a list of buttons that you can use.

  • left, middle, right

kontra.pointer​.onDown(callback)

callback {function}
Function to call on pointer down.

Register a function to be called on all pointer down events. Will be passed the original Event and the target object (if there is one).

kontra.pointer.onDown(function(event, object) {
  // do something on pointer down
});

kontra.pointer​.onUp(callback)

callback {function}
Function to call on pointer up.

Register a function to be called on all pointer up events. Will be passed the original Event and the target object (if there is one).

kontra.pointer.onDown(function(event, object) {
  // do something on pointer up
});

kontra.pointer​.over(object)

object {object}
The object to check if the pointer is over.

Check to see if the pointer is currently over the object. Since multiple objects may be rendered on top of one another, only the top most object under the pointer will return true.

let sprite1 = kontra.sprite({
  x: 10,
  y: 10,
  width: 10,
  height: 10
});
let sprite2 = kontra.sprite({
  x: 15,
  y: 10,
  width: 10,
  height: 10
});

kontra.pointer.track([sprite1, sprite2]);

sprite1.render();
sprite2.render();

kontra.pointer.x = 14;
kontra.pointer.y = 15;

console.log(kontra.pointer.over(sprite1));  //=> false
console.log(kontra.pointer.over(sprite2));  //=> true

kontra.pointer​.pressed(button)

button {string}
button name.

Returns true if the button is pressed. Use during an update() function to perform actions each frame.

kontra.sprite({
  update: function() {
    if (kontra.pointer.pressed('left')){
      // left mouse button pressed
    }
    else if (kontra.keys.pressed('right')) {
      // right mouse button pressed
    }
  }
});

kontra.pointer​.radius

{number}

The radius of the virtual pointer. Defaults to 5.

kontra.pointer​.track(object)

object {object | object[]}
Objects to track.

Begin tracking pointer events for a set of objects. Takes a single object or an array of objects.

kontra.pointer​.untrack(object)

object {object | object[]}
Objects to untrack.

Stop tracking pointer events for a set of objects. Takes a single object or an array of objects.

kontra.pointer​.x

{number}

The current x position of the pointer relative to the top-left corner of the canvas.

kontra.pointer​.y

{number}

The current y position of the pointer relative to the top-left corner of the canvas.