# 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 = 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.

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