mmouse v3.1.1

MMouse - Moving mouse

Track mouse movements in JavaScript. Mmouse is fully decoupled from the DOM - you must provide the glue between browser events and mmouse, and it will keep track of movement state within an element.

Example

var tracker = mmouse.trackMovement({
  onMove: function (e) {
    moveMyThingTo(e.offsetX, e.offsetY);
  }
});

el.addEventListener('mousedown', tracker.start);
el.addEventListener('mouseup', tracker.stop);
el.addEventListener('mouseout', tracker.stop);
el.addEventListener('mousemove', function (e) {
  e.preventDefault(); // Prevents marking text while dragging
  tracker.track(e);
});

API

var tracker = mmouse.trackMovement(options)

Creates a new tracker. The options allow for refinements to how mmouse calculates movements inside an element.

options.enabled

Control the initial state of the tracker. Default is true.

options.onMove

A function to call when the tracker is moving. Will be passed a movement object (see below).

options.onStart

A function to call when the tracker initiates movement. Will be passed a movement object. If this function returns boolean false, the move being initiated is aborted.

options.onStop

A function to call when the tracker terminates movement. Will be passed a movement object.

options.getMinY

A function that takes no arguments, and returns the minimum allowable value for y. This value will be requested and used to calculate the movement object's posY property. It is also used by the tracker to readjust for further movement.

options.getMinX

A function that takes no arguments, and returns the minimum allowable value for x. This value will be requested and used to calculate the movement object's posX property. It is also used by the tracker to readjust for further movement.

options.getMaxY

A function that takes no arguments, and returns the maximum allowable value for x. This value will be requested and used to calculate the movement object's posX property. It is also used by the tracker to readjust for further movement.

options.getMaxX

A function that takes no arguments, and returns the maximum allowable value for x. This value will be requested and used to calculate the movement object's posX property. It is also used by the tracker to readjust for further movement.

options.getWidth

A function that takes no arguments, and returns the width of the element being tracked. If you are dragging a smaller element across a bigger element, you want to have this function representing the sliding element width such that the correct max x position can be calculated.

options.getHeight

A function that takes no arguments, and returns the height of the element being tracked. If you are dragging a smaller element across a bigger element, you want to have this function representing the sliding element height such that the correct max y position can be calculated.

var tracker = mmouse.trackMovementIn(el, options)

Creates a tracker that scopes movement inside a particular DOM element. This tracker provides getMinX, getMaxX, getMinY, and getMaxY functions to keep movement contained in the element. They cannot be overridden - use trackMovement(options) if you need custom min/max coordinates.

Tracker API

tracker.enable()

Enable tracking

tracker.disable()

Disable tracking

tracker.start(e)

Start tracking. Typically bound to mousedown. Expects an event object with pageX and pageX properties (a regular DOM event is fine).

tracker.stop(e)

Stop tracking. Typically bound to mouseup and possibly mouseout. Expects an event object with pageX and pageX properties (a regular DOM event is fine).

tracker.track(e)

Track movement. Only tracks if start has been called, and stop has not been called since. Typically bound to mousemove. Expects an event object with pageX and pageX properties (a regular DOM event is fine).

tracker.move({x, y})

Move the tracker x pixels horixontally and y pixels vertically.

tracker.moveTo({x, y})

Move the tracker to position x/y.

The movement object

startX

The x position the movement started from.

startY

The y position the movement started from.

endX

The x position the movement ended in.

endY

The y position the movement ended in.

dx

The horizontal difference of a movement. Relative to the previous move event. Dragging the mouse to the left three pixels will issue three events with a dx of -1. To get the elapsed difference, calculate endX - startX.

dy

The vertical difference of a movement. Relative to the previous move event. Dragging the mouse downwards three pixels will issue three events with a dy of 1. To get the elapsed difference, calculate endY - startY.

posX

The new horizontal position after the movement. This value is ensured to be within the min and max x/y if functions to calculate those are available. For instance, if the mouse drags out of an element, you may want to stop whatever element is being dragged at the far edge of the element (and not allow it to escape its container).

posY

The new, clamped, vertical position after the movement (see above).