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 { initPointer, track, Sprite } = kontra;

// this function must be called first before pointer
// functions will work
initPointer();

let sprite = 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
  }
});

track(sprite);
sprite.render();
import { initPointer, track, Sprite } from 'path/to/kontra.mjs';

// this function must be called first before pointer
// functions will work
initPointer();

let sprite = 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
  }
});

track(sprite);
sprite.render();
import { initPointer, track, Sprite } from 'kontra';

// this function must be called first before pointer
// functions will work
initPointer();

let sprite = 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
  }
});

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() function and it will be called instead. The function is passed the pointer object. Use this function to determine how the pointer circle should collide with the object.

let { Sprite } = kontra;

let sprite = 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;
  }
});
import { Sprite } from 'path/to/kontra.mjs';

let sprite = 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;
  }
});
import { Sprite } from 'kontra';

let sprite = 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

initPointer(​)

Initialize pointer event listeners. This function must be called before using other pointer functions.

onPointerDown(​callback)

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

let { initPointer, onPointerDown } = kontra;

initPointer();

onPointerDown(function(e, object) {
  // handle pointer down
})
import { initPointer, onPointerDown } from 'path/to/kontra.mjs';

initPointer();

onPointerDown(function(e, object) {
  // handle pointer down
})
import { initPointer, onPointerDown } from 'kontra';

initPointer();

onPointerDown(function(e, object) {
  // handle pointer down
})

onPointerDown Parameters

callback

Function. Function to call on pointer down.

onPointerUp(​callback)

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

let { initPointer, onPointerUp } = kontra;

initPointer();

onPointerUp(function(e, object) {
  // handle pointer up
})
import { initPointer, onPointerUp } from 'path/to/kontra.mjs';

initPointer();

onPointerUp(function(e, object) {
  // handle pointer up
})
import { initPointer, onPointerUp } from 'kontra';

initPointer();

onPointerUp(function(e, object) {
  // handle pointer up
})

onPointerUp Parameters

callback

Function. Function to call on pointer up.

pointer

Object containing the radius and current x and y position of the pointer relative to the top-left corner of the canvas.

let { initPointer, pointer } = kontra;

initPointer();

console.log(pointer);  //=> { x: 100, y: 200, radius: 5 };
import { initPointer, pointer } from 'path/to/kontra.mjs';

initPointer();

console.log(pointer);  //=> { x: 100, y: 200, radius: 5 };
import { initPointer, pointer } from 'kontra';

initPointer();

console.log(pointer);  //=> { x: 100, y: 200, radius: 5 };

pointerOver(​object)

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 { initPointer, track, pointer, pointerOver, Sprite } = kontra;

initPointer();

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

track([sprite1, sprite2]);

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

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

console.log(pointerOver(sprite1));  //=> false
console.log(pointerOver(sprite2));  //=> true
import { initPointer, track, pointer, pointerOver, Sprite } from 'path/to/kontra.mjs';

initPointer();

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

track([sprite1, sprite2]);

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

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

console.log(pointerOver(sprite1));  //=> false
console.log(pointerOver(sprite2));  //=> true
import { initPointer, track, pointer, pointerOver, Sprite } from 'kontra';

initPointer();

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

track([sprite1, sprite2]);

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

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

console.log(pointerOver(sprite1));  //=> false
console.log(pointerOver(sprite2));  //=> true

pointerOver Parameters

object

Object. The object to check if the pointer is over.

pointerOver Return value

true if the pointer is currently over the object, false otherwise.

pointerPressed(​button)

Check if a button is currently pressed. Use during an update() function to perform actions each frame.

let { initPointer, pointerPressed } = kontra;

initPointer();

Sprite({
  update: function() {
    if (pointerPressed('left')){
      // left mouse button pressed
    }
    else if (pointerPressed('right')) {
      // right mouse button pressed
    }
  }
});
import { initPointer, pointerPressed } from 'path/to/kontra.mjs';

initPointer();

Sprite({
  update: function() {
    if (pointerPressed('left')){
      // left mouse button pressed
    }
    else if (pointerPressed('right')) {
      // right mouse button pressed
    }
  }
});
import { initPointer, pointerPressed } from 'kontra';

initPointer();

Sprite({
  update: function() {
    if (pointerPressed('left')){
      // left mouse button pressed
    }
    else if (pointerPressed('right')) {
      // right mouse button pressed
    }
  }
});

pointerPressed Parameters

button

String. Button to check for pressed state.

pointerPressed Return value

true if the button is pressed, false otherwise.

track(​objects)

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

let { initPointer, track } = kontra;

initPointer();

track(obj);
track([obj1, obj2]);
import { initPointer, track } from 'path/to/kontra.mjs';

initPointer();

track(obj);
track([obj1, obj2]);
import { initPointer, track } from 'kontra';

initPointer();

track(obj);
track([obj1, obj2]);

track Parameters

objects

Object or an Array of Objects. Objects to track.

untrack(​objects)

Remove the callback function for a bound set of objects.

let { untrack } = kontra;

untrack(obj);
untrack([obj1, obj2]);
import { untrack } from 'path/to/kontra.mjs';

untrack(obj);
untrack([obj1, obj2]);
import { untrack } from 'kontra';

untrack(obj);
untrack([obj1, obj2]);

untrack Parameters

objects

Object or an Array of Objects. Object or objects to stop tracking.