1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
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