9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<div class="intro">
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <p>The `event-touch` module extends the <a
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith href="index.html#appendixA">whitelist of DOM events</a> to include the
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith native touch and gesture events and adds relevant information to event
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith facades.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <p>The `event-move` module adds a set of abstract events that adapt to
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith the client environment to handle either touch or mouse input.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <p>The `event-flick` module adds a "flick" event on top of the gesture
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith abstraction layer to capture a user flicking an element with mouse or
2e7441169df0fcc324f2d44947beba7d237f5a37Luke Smith <p>The `event-gestures` module is a rollup of these three, but will
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith potentially roll in more gesture based events in the future.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<h2>Using Touch Events</h2>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>YUI DOM event support also extends to touch events. To use touch events in your application, you will need to include the <code>event-touch</code> module in your use statement.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>The set of common low-level touch events, which exist on most touch-enabled OSes are supported:</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li><code>touchstart</code></li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li><code>touchmove</code></li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li><code>touchend</code></li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li><code>touchcancel</code></li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>Additionally, the iOS specific touch events, <code>gesturestart</code>,
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<code>gesturechange</code> and <code>gestureend</code>, are also supported.
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke SmithYUI doesn't replicate support for these events on other touch OSes currently,
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithdue to their lack of DOM level multi-touch support. At the point at which they
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithdo expose multi-touch information in the lower level touch events, we can build
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithin cross-platform support for multi-touch gestures.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithnode.on('touchstart`, function () {
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<h4>The Touch Event Facade</h4>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>The event facade passed to touch events has the common set of touch specific
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smitharray properties available:</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li><code>touches</code></li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li><code>changedTouches</code></li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li><code>touchTargets</code></li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>These event objects in these arrays are also normalized, just the same as
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smiththe event object pass to any other DOM listener.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>The event object for the iOS gesture events have <code>scale</code> and
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<code>rotation</code> properties, the same as the native event object.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<h2 id="move">Cross-Device Gesture Support</h2>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>The <code>event-move</code> module provides the following events that
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<em>roughly</em> relate to the associated touch or mouse event, depending on the client
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <th>Abstract event</th>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <th>Mouse event</th>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <th>Touch event</th>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <td><strong>`gesturemovestart`</strong></td>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <td>`mousedown`</td>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <td>`touchstart`</td>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <td><strong>`gesturemove`</strong></td>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <td>`mousemove`</td>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <td>`touchmove`</td>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <td><strong>`gesturemoveend`</strong></td>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <td>`mouseup`</td>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <td>`touchend`</td>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>I say "roughly" because the gesture events aim to encapsulate common
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithinteractions rather than just serving as a relay to other events. Where this
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithcomes out is in the additional configuration that can be included in the
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithsubscription as a third argument.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// Notify me when the user puts a finger down, or mouses down on
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// the car node
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithcar.on("gesturemovestart", alignForMove, {
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith // fire the event only after 300ms of continuous contact...
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith minTime: 300,
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith minDistance: 3
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// Move the car node when the user moves the finger or mouse.
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// Note the `this` override parameter is shifted to account for
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// the configuration param
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// Notify me when the user lifts their finger, or lets go of
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// the mouse button (only if a gesturemovestart was received
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// on the node).
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithcar.on("gesturemoveend", screechingHalt);
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>The complete set of configuration parameters for the gesture events is <a href="{{apiDocs}}/module_event-move.html#event_gesturemove">in the API docs</a>.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<h4>Related Events</h4>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>The three gesture events are related to each other. They are notifications
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithfor the start, progress, and end of the same gesture. `gesturemove` and
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith`gesturemoveend` subscriptions won't execute unless a `gesturemovestart`
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>If you need them to fire separately, such as when attaching and detaching
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithsubscribers dynamically, the `gesturemove` and `gesturemoveend` events can be
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithsubscribed to individually by configuring `standAlone: true`</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// Doesn't require an associated `gesturemovestart` subscription
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke SmithY.one("doc").on("gesturemove", function(e) {...}, {
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith standAlone:true
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>Under the hood, the DOM listeners which monitor mousemove/touchmove and
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithmouseup/touchend are bound to the `document` by default. The node only provides
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smiththe shared context to relate the three events.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<h2 id="flick">Flick Gesture Event</h2>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>The flick gesture event is fired whenever the user initiates a flick gesture (with a finger or the mouse) on the node where the listener is attached.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke SmithmyNode.on("flick", function(e) {
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith // Some of the flick specific data on the event facade
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith // The event object itself is the event object for
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith // the event which concludes the flick (the mouseup or touchend)
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>Like with the supporting gesture events, when subscribing to
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<code>flick</code>, you can also pass additional configuration to control
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smithwhen and how the flick subscriber is notified.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// Custom config, with no context or extra args
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke SmithmyNode.on("flick", flickHandler, {
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith // only notify me if the flick covered
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith // more than 20px and was faster than 0.8 px/ms
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith minDistance: 20,
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith minVelocity: 0.8,
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith // prevent the default behavior for the
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith // underlying mouse/touch events
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith preventDefault: true
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// Another option to avoid confusion when specifying the `this`
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// override or bound arguments for events with custom signatures
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke SmithmyNode.on("flick", Y.bind(o.flickHandler, o, arg1), {
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith minDistance: 20,
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith minVelocity: 0.8,
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith preventDefault: true
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// Alternately, make sure to account for the additional subscription
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith// parameter by passing null if there is no configuration.
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke SmithmyNode.on("flick", o.flickHandler, null, o, arg1);
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<p>The complete set of configuration parameters for the `flick` event is <a href="{{apiDocs}}/module_event-flick.html#event_flick">in the API docs</a>.</p>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith<h2>Caveats</h2>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <li>The `flick` event doesn't (yet) support delegation.</li>
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith The `delegate()` signature for the gesture events is
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <code>node.delegate('gesturemove', callback, <em>filter</em>,
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <em>gestureConfig</em>)</code>, reversing the order of the delegation
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith filter and extra params from the <a href="hover.html">`hover`</a> and
9370dc2ba1162713a06e28b83c777f329d4b7eeeLuke Smith <a href="key.html">`key`</a> events. This may be changed in a future