Respond to Touch and Desktop events using the same handlers, including tap (click), long-press, drag, long-press-drag, pinch/mouse zoom. Used in commercial SPAs and featured in the best-selling book Single Page Web Applications - JavaScript end-to-end.
npm install jquery.event.ueThe plugin recognizes mouse, keyboard, and touch motions that have
the same intent and publishes unified events for them. For example,
a long-press intent is expressed with a mouse by pressing-and-holding
on the left mouse button for over half a second without substantially moving
the mouse. The same intent on a touch device is expressed by placing a
finger on the screen for over half a second without substantially moving the
finger. This pugin recognizes both motions as having the same intent
and publishes a single uheld event for either.
Here are the full list of intents supported by this unified event
plugin:
- utap - Mouse-click (mouse) / Finger tap (touch)
- uheld - Long-mouse-press / Finger-press-and-hold
- udrag - Mouse-click-and-drag / Finger Swipe
- uhelddrag - Long-mouse-press-and-drag / Finger-press-and-hold-and-drag
- zoom - Mouse-click-and-drag-Y + shift / Finger-pinch
This plugin is used in multiple commercial SPAs and is featured in the
best-selling book [Single Page Web Applications - JavaScript end-to-end][1],
also [available on Amazon][2].
Please see the ue-test.html file for a demonstration of the different intents.
Expected behavior is expressed in the BR corner of the tiles. If you see any
unexpected behavior while testing motions on your device please file a bug report
so we can fix it!
``html`
....
js
// bind to a mouse click or tap event
$( '#utap' ) .on( 'utap', onTap ); // bind to a long-press event
$( '#uheld' ).on( 'uheld', onHeld );
// bind to zoom events
$( '#uzoom' )
.bind( 'uzoomstart', onZoomstart )
.bind( 'uzoommove', onZoommove )
.bind( 'uzoomend', onZoomend )
;
// bind to drag events
$( '#udrag' )
.bind( 'udragstart', onDragstart )
.bind( 'udragmove', onDragmove )
.bind( 'udragend', onDragend )
;
// bind to hold-drag events
$('#uhelddrag')
.bind('uheldstart', onDragstart )
.bind('uheldmove', onDragmove )
.bind('uheldend', onDragend )
;
`Intents
See the file for example use of the
event object.$3
A click intent results in a utap event.
- The Desktop motion is Left Mouse Button [LMB] down-up
where the mouse-down time is less than the tap tolerance and
the location movement is less than the drag tolerance.
- The Touch motion is touchstart-move-end where
the touch time is less than the tap tolerance and the location
movement is less than the drag tolerance.You may tweak the tap, drag, and long-press tolerances
in the
defaultOptMap at the top of the lib. The API will have
a method to change these values in the future.$3
A long-press intent results in a uheld event.
- The Desktop motion is Left Mouse Button [LMB] down-up
where the mouse-down time exceeds the long-press tolerance and
the location movement is less than the drag tolerance.
- The Touch motion is touchstart-move-end where
the touch time exceeds the long-press tolerance and
the location movement is less than the drag tolerance.$3
A drag intent results in a single udragstart event, one or more
udragmove events, and a final udragend event.
- The Desktop motion is LMB down - mouse-move - LMB up
where the mouse-down time exceeds the tap tolerance and
the location movement is greater than the drag tolerance.
- The Touch is touchstart-move-end, where
the touch time exceeds drag tolerance,The event order is as follows:
-
udragstart - fires at the start of a drag
- udragmove - fires each time the pointer moves
- udragend - fires at the end of a drag $3
The held-drag intent results in a single uheldstart event, one or more
uheldmove events, and a final uheldend event.
- The Desktop motion is LMB down+hold - mouse-move - LMB up
where the mouse-down time exceeds the held tolerance and the
mouse has stayed within the drag tolerance, after which
the location movement is greater than the drag tolerance.
- The Touch is touchstart+hold-move-end, where
the touch time exceeds the held tolerance and the touch as
stayed within the drag tolerance, after which the touch
location is greater than the the drag tolerance.The event order is as follows:
-
uheldstart - fires at the start of a held-drag
- uheldmove - fires each time the pointer moves
- uheldend - fires at the end of a held-drag$3
A zoom intent results in a single uzoomstart event, one or more
uzoommove events, and a final uzoomend event.- The Desktop motion is shift+LMB down - move-mouse - LMB up where
the mouse-down time exceeds the tap tolerance and
the location movement is greater than the drag tolerance.
- The Touch motion is two-point-touch - pinch - two-point-release.
The event order is as follows:
-
uzoomstart - fires at the start of zoom
- uzoommove - fires as zoom amount changes
- uzoomend - fires at end of zoom motionEvent Attributes
The event object for all ue events include these attributes in addition
to those already provided by jQuery:`js
var attr_list = [
event.px_start_x, // X-position at start of motion
event.px_start_y, // Y-ibid
event.px_current_x, // X-position, current
event.px_current_y, // Y-ibid
event.px_end_x, // X-position for x at end of motion
event.px_end_y, // Y-ibid
event.px_delta_zoom, // Zoom delta since last motion event
event.px_delta_x, // X-ibid
event.px_delta_y, // Y-ibid
event.px_tdelta_x, // X-delta since beginning of motion
event.px_tdelta_y, // Y-ibid
event.orig_target, // Element under cursor at start of motion
event.elem_bound, // Element on which event was bound
event.elem_target, // Element under the cursor for this event
event.timeStamp, // Timestamp of this event
event.ms_elapsed, // Elapsed time since start of motion
event.ms_timestart, // Start time of motion
event.ms_timestop, // top time of motion
];
`Error handling
This code ignores bad input, and does not throw exceptions. As JS implementations are (finally) seeing improved exception handling, expect this to change in 2.x.Namespacing
jQuery event namespacing is fully supported, as shown in this example:js
$( '#msg' )
.on( 'utap.mytap', onTapMsg )
.on( 'uheld.mytap', onHeldMsg );$( '#msg' ).unbind( '.mytap' );
`
Use libraries, not frameworks
This is a library that strives to be best-in-class.
If you are considering using an SPA framework, please read [Do you
really want an SPA framework?][0] first.Release Notes
$3
Michael S. Mikowski (mike[dot]mikowski[at]gmail[dotcom])$3
Dual licensed under the MIT or GPL Version 2
http://jquery.org/license$3
Updated to ignore most input elements (input, textarea, select) by default.
See the setting.$3
- Removed all references to console object
- Changed deprecated bind and unbind to on and off$3
- Changed default option key to ignore_select
- The value is now "" instead of ":input"
- Updated README and published to npm (1.2.5)$3
Updated to handle zooming correctly.$3
Stopped preventDefault() from firing on events not controlled by the plugin.$3
No code changes. Updated npm keywords. Fixed typos.
Bumped version number to represent maturity and stability.
Redirected library discussion to blog post.$3
The default px_radius parameter was doubled from 5px to 10px. This made utap
and events work much better on smaller screens. Confirmed compatible with
with jQuery 2.1.4, thus 1.7.0 - 2.1.4 appear safe.$3
No code changes. Updated npm keywords. Fixed typos.
Bumped version number to represent maturity and stability.
Redirected library discussion to blog post.$3
Fixed held logic, added px_tdelta_x and px_tdelta_y` to attributes.