jQuery.event.move

Project

Github: github.com/stephband/jquery.event.move
Issues: github.com/stephband/jquery.event.move/issues

*UPDATE 2.0.0*: `move` events are now compatible with jQuery 3.x. In addition, the underlying implementation is rewritten using vanilla DOM (where before it was jQuery special events only) – jQuery is no longer a requirement.

Move events

movestart: Fired following touchmove or mousemove, when the touch (or mouse) crosses a threshold distance from the position of the mousedown or touchstart.
move: Fired on every animation frame where a touchmove or mousemove has changed position.
moveend: Fired following mouseup or touchend, after the last move event, and in the case of touch events when the finger that started the move has been lifted.

Move event objects are augmented with the properties:

e.pageX, e.pageY: Current page coordinates of pointer.
e.startX, e.startY: Page coordinates the pointer had at movestart.
e.distX, e.distY: Distance the pointer has moved since movestart.
e.deltaX, e.deltaY: Distance the pointer has moved since last move event.
e.velocityX, e.velocityY: Velocity in pixels/ms, averaged over the last few events.

How to use move events

Native DOM

var node = document.querySelector('.mydiv');

// A movestart event must be bound
// and explicitly enabled
node.addEventListener('movestart', function(e) {
  e.enableMove();
});

node.addEventListener('move', function(e) {
  // move .mydiv horizontally
  this.style.left = (e.startX + e.distX) + 'px';
})

node.addEventListener('moveend', function() {
  // move is complete!
});

.enableMove() is a necessary performance optimisation (that works around the DOM's lack of event inspection).

jQuery

jQuery('.mydiv')
.on('move', function(e) {
  // move .mydiv horizontally
  jQuery(this).css({ left: e.startX + e.distX });
})
.on('moveend', function() {
  // move is complete!
});

(jQuery's special event system does the work of enabling move events so there is no need to explicitly bind to movestart.)

Why not just use mouse or touch events?

Well, yes, you can. But move events abstract away the details that need attention when writing this kind of interaction model with mouse and touch events:

Supports mouse and touch devices, exposing the same event API for both
Throttles moves to animation frames, preventing unneccesary calls
Ignores the right mouse button and clicks with modifier keys
Prevents text selection while moving
Handles multiple touches
Deals with bug (Chrome, possibly all Android) where changedTouches includes touches that have not changed
Handles browser differences where touches in iOS are live objects, where in Android they are static
Does not bork interaction with form inputs inside moveable nodes
Suppresses drag and drop events

Move events are intended as 'building blocks' for helping to build interactions. They track individual fingers or a single mouse, and expose properties on their event objects that are useful for detecting gestures.

What about drag events?

Move events are designed to compliment drag events, where the two have different meanings: drag events are for transferring data while move events are for making interactive interfaces. That said, movestart, move and moveend events deliberately echo dragstart, drag and dragend events, with one main difference: where the drag event fires continuously whether you have moved the pointer or not, the move event fires only after the pointer has been moved, and only on animation frames.

Where both a dragstart and any move event are bound to the same node, drag events are suppressed.