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(), onOver(), or onOut() functions which will be called whenever a pointer down, up, over, or out 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
  },
  onOut: function() {
    // handle on out 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
  },
  onOut: function() {
    // handle on out 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
  },
  onOut: function() {
    // handle on out 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 = Srite({
  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 = Srite({
  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 = Srite({
  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;
  }
});

Available Buttons

Below is a list of buttons that you can use. If you need to extend or modify this list, you can use the pointerMap property.

left, middle, right

getPointer([canvas])

Get the pointer object which contains the radius, current x and y position of the pointer relative to the top-left corner of the canvas, and which canvas the pointer applies to.

let { initPointer, getPointer } = kontra;

initPointer();

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

import { initPointer, getPointer } from 'path/to/kontra.mjs';

initPointer();

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

import { initPointer, getPointer } from 'kontra';

initPointer();

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

getPointer Parameters

canvas Optional: HTMLCanvasElement. The canvas which maintains the pointer. Defaults to core.getCanvas().

getPointer Return value

Object. pointer with properties x, y, and radius. If using touch events, also has a touches object with keys of the touch identifier and the x/y position of the touch as the value.

initPointer([options])

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

If you need to use multiple canvas, you'll have to initialize the pointer for each one individually as each canvas maintains its own pointer object.

initPointer Parameters

options Optional: Object. Pointer options.
options.radius Optional: Number. Radius of the pointer. Defaults to 5.
options.canvas Optional: HTMLCanvasElement. The canvas that event listeners will be attached to. Defaults to core.getCanvas().

initPointer Return value

Object. The pointer object for the canvas.

offPointer(direction)

Unregister the callback for a pointer event.

let { initPointer, offPointer } = kontra;

initPointer();

offPointer('down');

import { initPointer, offPointer } from 'path/to/kontra.mjs';

initPointer();

offPointer('down');

import { initPointer, offPointer } from 'kontra';

initPointer();

offPointer('down');

offPointer Parameters

direction: 'down' or 'up'. Direction of the pointer event.

onPointer(direction, callback)

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

let { initPointer, onPointer } = kontra;

initPointer();

onPointer('down', function(e, object) {
  // handle pointer down
});

import { initPointer, onPointer } from 'path/to/kontra.mjs';

initPointer();

onPointer('down', function(e, object) {
  // handle pointer down
});

import { initPointer, onPointer } from 'kontra';

initPointer();

onPointer('down', function(e, object) {
  // handle pointer down
});

onPointer Parameters

direction: 'down' or 'up'. Direction of the pointer event.
callback: Function. Function to call on pointer event.

pointerMap

Object. A map of pointer button indices to button names. Modify this object to expand the list of available buttons.

let { pointerMap, pointerPressed } = kontra;

pointerMap[2] = 'buttonWest';

if (pointerPressed('buttonWest')) {
  // handle west face button
}

import { pointerMap, pointerPressed } from 'path/to/kontra.mjs';

pointerMap[2] = 'buttonWest';

if (pointerPressed('buttonWest')) {
  // handle west face button
}

import { pointerMap, pointerPressed } from 'kontra';

pointerMap[2] = 'buttonWest';

if (pointerPressed('buttonWest')) {
  // handle west face button
}

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

Boolean. 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

Boolean. true if the button is pressed, false otherwise.

track(...objects)

Begin tracking pointer events for an object.

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: A list of (Object or Array of Objects). Object to track. Can be a single object, an array of objects, or a comma-separated list of objects.

untrack(...objects)

Stop tracking pointer events for an object.

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: A list of (Object or Array of Objects). Object to untrack. Can be a single object, an array of objects, or a comma-separated list of objects.