--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/cm/media/js/lib/yui/yui_3.10.3/docs/event/touch.html Tue Jul 16 14:29:46 2013 +0200
@@ -0,0 +1,411 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <title>Touch Events and Abstractions</title>
+ <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic">
+ <link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css">
+ <link rel="stylesheet" href="../assets/css/main.css">
+ <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
+ <link rel="shortcut icon" type="image/png" href="../assets/favicon.png">
+ <script src="../../build/yui/yui-min.js"></script>
+
+</head>
+<body>
+<!--
+<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
+-->
+<div id="doc">
+ <div id="hd">
+ <h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1>
+ </div>
+
+ <a href="#toc" class="jump">Jump to Table of Contents</a>
+
+
+ <h1>Touch Events and Abstractions</h1>
+ <div class="yui3-g">
+ <div class="yui3-u-3-4">
+ <div id="main">
+ <div class="content"><div class="intro">
+ <p>The <code>event-touch</code> module extends the <a
+ href="index.html#event-whitelist">whitelist of DOM events</a> to include the
+ native touch and gesture events and adds relevant information to event
+ facades.</p>
+
+ <p>The <code>event-move</code> module adds a set of abstract events that adapt to
+ the client environment to handle either touch or mouse input.</p>
+
+ <p>The <code>event-flick</code> module adds a "flick" event on top of the gesture
+ abstraction layer to capture a user flicking an element with mouse or
+ finger.</p>
+
+ <p>The <code>event-gestures</code> module is a rollup of these three, but will
+ potentially roll in more gesture based events in the future.</p>
+</div>
+
+<h2 id="using-touch-events">Using Touch Events</h2>
+
+<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>
+
+<p>The set of common low-level touch events, which exist on most touch-enabled OSes are supported:</p>
+
+<ul>
+ <li><code>touchstart</code></li>
+ <li><code>touchmove</code></li>
+ <li><code>touchend</code></li>
+ <li><code>touchcancel</code></li>
+</ul>
+
+<p>Additionally, the iOS specific touch events, <code>gesturestart</code>,
+<code>gesturechange</code> and <code>gestureend</code>, are also supported.
+YUI doesn't replicate support for these events on other touch OSes currently,
+due to their lack of DOM level multi-touch support. At the point at which they
+do expose multi-touch information in the lower level touch events, we can build
+in cross-platform support for multi-touch gestures.</p>
+
+<pre class="code prettyprint">node.on("touchstart", function () {
+ this.addClass("detached");
+});</pre>
+
+
+<h4 id="the-touch-event-facade">The Touch Event Facade</h4>
+
+<p>The event facade passed to touch events has the common set of touch specific
+array properties available:</p>
+
+<ul>
+ <li><code>touches</code></li>
+ <li><code>changedTouches</code></li>
+ <li><code>touchTargets</code></li>
+</ul>
+
+<p>These event objects in these arrays are also normalized, just the same as
+the event object pass to any other DOM listener.</p>
+
+<p>The event object for the iOS gesture events have <code>scale</code> and
+<code>rotation</code> properties, the same as the native event object.</p>
+
+<h2 id="move">Cross-Device Gesture Support</h2>
+
+<p>The <code>event-move</code> module provides the following events that
+<em>roughly</em> relate to the associated touch or mouse event, depending on the client
+device:</p>
+
+<table>
+<thead>
+ <tr>
+ <th>Abstract event</th>
+ <th>Mouse event</th>
+ <th>Touch event</th>
+ </th>
+</thead>
+<tbody>
+ <tr>
+ <td><strong><code>gesturemovestart</code></strong></td>
+ <td><code>mousedown</code></td>
+ <td><code>touchstart</code></td>
+ </tr>
+ <tr>
+ <td><strong><code>gesturemove</code></strong></td>
+ <td><code>mousemove</code></td>
+ <td><code>touchmove</code></td>
+ </tr>
+ <tr>
+ <td><strong><code>gesturemoveend</code></strong></td>
+ <td><code>mouseup</code></td>
+ <td><code>touchend</code></td>
+ </tr>
+</tbody>
+</table>
+
+<p>I say "roughly" because the gesture events aim to encapsulate common
+interactions rather than just serving as a relay to other events. Where this
+comes out is in the additional configuration that can be included in the
+subscription as a third argument.</p>
+
+<pre class="code prettyprint">// Notify me when the user puts a finger down, or mouses down on
+// the car node
+car.on("gesturemovestart", alignForMove, {
+
+ // fire the event only after 300ms of continuous contact...
+ minTime: 300,
+
+ // ...or if the finger/mouse moves more than 3px
+ minDistance: 3
+});
+
+// Move the car node when the user moves the finger or mouse.
+// Note the `this` override parameter is shifted to account for
+// the configuration param
+car.on("gesturemove", car.move, null, car);
+
+
+// Notify me when the user lifts their finger, or lets go of
+// the mouse button (only if a gesturemovestart was received
+// on the node).
+car.on("gesturemoveend", screechingHalt);</pre>
+
+
+<p>The complete set of configuration parameters for the gesture events is <a href="http://yuilibrary.com/yui/docs/api/module_event-move.html#event_gesturemove">in the API docs</a>.</p>
+
+<h4 id="related-events">Related Events</h4>
+
+<p>The three gesture events are related to each other. They are notifications
+for the start, progress, and end of the same gesture. <code>gesturemove</code> and
+<code>gesturemoveend</code> subscriptions won't execute unless a <code>gesturemovestart</code>
+happens.</p>
+
+<p>If you need them to fire separately, such as when attaching and detaching
+subscribers dynamically, the <code>gesturemove</code> and <code>gesturemoveend</code> events can be
+subscribed to individually by configuring <code>standAlone: true</code></p>
+
+<pre class="code prettyprint">// Doesn't require an associated `gesturemovestart` subscription
+Y.one("doc").on("gesturemove", function(e) {...}, {
+ standAlone:true
+});</pre>
+
+
+<p>Under the hood, the DOM listeners which monitor mousemove/touchmove and
+mouseup/touchend are bound to the <code>document</code> by default. The node only provides
+the shared context to relate the three events.</p>
+
+
+<h2 id="flick">Flick Gesture Event</h2>
+
+<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>
+
+<pre class="code prettyprint">myNode.on("flick", function(e) {
+
+ // Some of the flick specific data on the event facade
+
+ var flick = e.flick,
+ velocity = flick.velocity,
+ distance = flick.distance,
+ axis = flick.axis,
+ startX = flick.start.pageX,
+ startY = flick.start.pageY,
+
+ // The event object itself is the event object for
+ // the event which concludes the flick (the mouseup or touchend)
+
+ endX = e.pageX,
+ endY = e.pageY,
+ endTarget = e.target;
+
+});</pre>
+
+
+<p>Like with the supporting gesture events, when subscribing to
+<code>flick</code>, you can also pass additional configuration to control
+when and how the flick subscriber is notified.</p>
+
+<pre class="code prettyprint">// Custom config, with no context or extra args
+myNode.on("flick", flickHandler, {
+
+ // only notify me if the flick covered
+ // more than 20px and was faster than 0.8 px/ms
+ minDistance: 20,
+ minVelocity: 0.8,
+
+ // prevent the default behavior for the
+ // underlying mouse/touch events
+ preventDefault: true
+});
+
+// Another option to avoid confusion when specifying the `this`
+// override or bound arguments for events with custom signatures
+// is to use Y.bind
+myNode.on("flick", Y.bind(o.flickHandler, o, arg1), {
+ minDistance: 20,
+ minVelocity: 0.8,
+ preventDefault: true
+});
+
+// Alternately, make sure to account for the additional subscription
+// parameter by passing null if there is no configuration.
+myNode.on("flick", o.flickHandler, null, o, arg1);</pre>
+
+
+<p>The complete set of configuration parameters for the <code>flick</code> event is <a href="http://yuilibrary.com/yui/docs/api/module_event-flick.html#event_flick">in the API docs</a>.</p>
+
+<h2 id="caveats">Caveats</h2>
+
+<ol>
+ <li>The <code>flick</code> event doesn't (yet) support delegation.</li>
+ <li>
+ The <code>delegate()</code> signature for the gesture events is
+ <code>node.delegate('gesturemove', callback, <em>filter</em>,
+ <em>gestureConfig</em>)</code>, reversing the order of the delegation
+ filter and extra params from the <a href="hover.html"><code>hover</code></a> and
+ <a href="key.html"><code>key</code></a> events. This may be changed in a future
+ release.
+ </li>
+</ol>
+
+</div>
+ </div>
+ </div>
+
+ <div class="yui3-u-1-4">
+ <div class="sidebar">
+
+ <div id="toc" class="sidebox">
+ <div class="hd">
+ <h2 class="no-toc">Table of Contents</h2>
+ </div>
+
+ <div class="bd">
+ <ul class="toc">
+<li>
+<a href="#using-touch-events">Using Touch Events</a>
+<ul class="toc">
+<li>
+<a href="#the-touch-event-facade">The Touch Event Facade</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#move">Cross-Device Gesture Support</a>
+<ul class="toc">
+<li>
+<a href="#related-events">Related Events</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#flick">Flick Gesture Event</a>
+</li>
+<li>
+<a href="#caveats">Caveats</a>
+</li>
+</ul>
+ </div>
+ </div>
+
+
+
+ <div class="sidebox">
+ <div class="hd">
+ <h2 class="no-toc">Examples</h2>
+ </div>
+
+ <div class="bd">
+ <ul class="examples">
+
+
+ <li data-description="Use the Event Utility to attach simple DOM event handlers.">
+ <a href="basic-example.html">Simple DOM Events</a>
+ </li>
+
+
+
+ <li data-description="Using the synthetic event API to create a DOM event that fires in response to arrow keys being pressed.">
+ <a href="synth-example.html">Creating an Arrow Event for DOM Subscription</a>
+ </li>
+
+
+
+ <li data-description="Supporting cross-device swipe gestures, using the event-move gesture events">
+ <a href="swipe-example.html">Supporting A Swipe Left Gesture</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+ </ul>
+ </div>
+ </div>
+
+
+
+ <div class="sidebox">
+ <div class="hd">
+ <h2 class="no-toc">Examples That Use This Component</h2>
+ </div>
+
+ <div class="bd">
+ <ul class="examples">
+
+
+
+
+
+
+
+
+ <li data-description="Creating an accessible menu button using the Focus Manager Node Plugin, Event's delegation support and mouseenter event, along with the Overlay widget and Node's support for the WAI-ARIA Roles and States.">
+ <a href="../node-focusmanager/node-focusmanager-button.html">Accessible Menu Button</a>
+ </li>
+
+
+
+ <li data-description="Shows how to extend the base widget class, to create your own Widgets.">
+ <a href="../widget/widget-extend.html">Extending the Base Widget Class</a>
+ </li>
+
+
+
+ <li data-description="Example Photo Browser application.">
+ <a href="../dd/photo-browser.html">Photo Browser</a>
+ </li>
+
+
+
+ <li data-description="Portal style example using Drag & Drop Event Bubbling and Animation.">
+ <a href="../dd/portal-drag.html">Portal Style Example</a>
+ </li>
+
+
+
+ <li data-description="Use IO to request data over HTTP.">
+ <a href="../io/get.html">HTTP GET to request data</a>
+ </li>
+
+
+ </ul>
+ </div>
+ </div>
+
+ </div>
+ </div>
+ </div>
+</div>
+
+<script src="../assets/vendor/prettify/prettify-min.js"></script>
+<script>prettyPrint();</script>
+
+<script>
+YUI.Env.Tests = {
+ examples: [],
+ project: '../assets',
+ assets: '../assets/event',
+ name: 'event',
+ title: 'Touch Events and Abstractions',
+ newWindow: '',
+ auto: false
+};
+YUI.Env.Tests.examples.push('basic-example');
+YUI.Env.Tests.examples.push('synth-example');
+YUI.Env.Tests.examples.push('swipe-example');
+YUI.Env.Tests.examples.push('node-focusmanager-button');
+YUI.Env.Tests.examples.push('widget-extend');
+YUI.Env.Tests.examples.push('photo-browser');
+YUI.Env.Tests.examples.push('portal-drag');
+YUI.Env.Tests.examples.push('get');
+
+</script>
+<script src="../assets/yui/test-runner.js"></script>
+
+
+
+</body>
+</html>