~smagoun/whoopsie/whoopsie-lp1017637

<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>

100

<td><code>mousedown</code></td>

101

<td><code>touchstart</code></td>

102

</tr>

103

<tr>

104

<td><strong><code>gesturemove</code></strong></td>

105

<td><code>mousemove</code></td>

106

<td><code>touchmove</code></td>

107

</tr>

108

<tr>

109

<td><strong><code>gesturemoveend</code></strong></td>

110

<td><code>mouseup</code></td>

111

<td><code>touchend</code></td>

112

</tr>

113

</tbody>

114

</table>

115

116

<p>I say "roughly" because the gesture events aim to encapsulate common

117

interactions rather than just serving as a relay to other events. Where this

118

comes out is in the additional configuration that can be included in the

119

subscription as a third argument.</p>

120

121

<pre class="code prettyprint">// Notify me when the user puts a finger down, or mouses down on

122

// the car node

123

car.on("gesturemovestart", alignForMove, {

124

125

// fire the event only after 300ms of continuous contact...

126

minTime: 300,

127

128

// ...or if the finger/mouse moves more than 3px

129

minDistance: 3

130

});

131

132

// Move the car node when the user moves the finger or mouse.

133

// Note the `this` override parameter is shifted to account for

134

// the configuration param

135

car.on("gesturemove", car.move, null, car);

136

137

138

// Notify me when the user lifts their finger, or lets go of

139

// the mouse button (only if a gesturemovestart was received

140

// on the node).

141

car.on("gesturemoveend", screechingHalt);</pre>

142

143

144

<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>

145

146

<h4 id="related-events">Related Events</h4>

147

148

<p>The three gesture events are related to each other. They are notifications

149

for the start, progress, and end of the same gesture. <code>gesturemove</code> and

150

<code>gesturemoveend</code> subscriptions won't execute unless a <code>gesturemovestart</code>

151

happens.</p>

152

153

<p>If you need them to fire separately, such as when attaching and detaching

154

subscribers dynamically, the <code>gesturemove</code> and <code>gesturemoveend</code> events can be

155

subscribed to individually by configuring <code>standAlone: true</code></p>

156

157

<pre class="code prettyprint">// Doesn't require an associated `gesturemovestart` subscription

158

Y.one("doc").on("gesturemove", function(e) {...}, {

159

standAlone:true

160

});</pre>

161

162

163

<p>Under the hood, the DOM listeners which monitor mousemove/touchmove and

164

mouseup/touchend are bound to the <code>document</code> by default. The node only provides

165

the shared context to relate the three events.</p>

166

167

168

<h2 id="flick">Flick Gesture Event</h2>

169

170

<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>

171

172

<pre class="code prettyprint">myNode.on("flick", function(e) {

173

174

// Some of the flick specific data on the event facade

175

176

var flick = e.flick,

177

velocity = flick.velocity,

178

distance = flick.distance,

179

axis = flick.axis,

180

startX = flick.start.pageX,

181

startY = flick.start.pageY,

182

183

// The event object itself is the event object for

184

// the event which concludes the flick (the mouseup or touchend)

185

186

endX = e.pageX,

187

endY = e.pageY,

188

endTarget = e.target;

189

190

});</pre>

191

192

193

<p>Like with the supporting gesture events, when subscribing to

194

<code>flick</code>, you can also pass additional configuration to control

195

when and how the flick subscriber is notified.</p>

196

197

<pre class="code prettyprint">// Custom config, with no context or extra args

198

myNode.on("flick", flickHandler, {

199

200

// only notify me if the flick covered

201

// more than 20px and was faster than 0.8 px/ms

202

minDistance: 20,

203

minVelocity: 0.8,

204

205

// prevent the default behavior for the

206

// underlying mouse/touch events

207

preventDefault: true

208

});

209

210

// Another option to avoid confusion when specifying the `this`

211

// override or bound arguments for events with custom signatures

212

// is to use Y.bind

213

myNode.on("flick", Y.bind(o.flickHandler, o, arg1), {

214

minDistance: 20,

215

minVelocity: 0.8,

216

preventDefault: true

217

});

218

219

// Alternately, make sure to account for the additional subscription

220

// parameter by passing null if there is no configuration.

221

myNode.on("flick", o.flickHandler, null, o, arg1);</pre>

222

223

224

<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>

225

226

<h2 id="caveats">Caveats</h2>

227

228

<ol>

229

<li>The <code>flick</code> event doesn't (yet) support delegation.</li>

230

<li>

231

The <code>delegate()</code> signature for the gesture events is

232

<code>node.delegate('gesturemove', callback, <em>filter</em>,

233

<em>gestureConfig</em>)</code>, reversing the order of the delegation

234

filter and extra params from the <a href="hover.html"><code>hover</code></a> and

235

<a href="key.html"><code>key</code></a> events. This may be changed in a future

236

release.

237

</li>

238

</ol>

239

240

</div>

241

</div>

242

</div>

243

244

245

246

247

248

249

<h2 class="no-toc">Table of Contents</h2>

250

</div>

251

252

253

254

<li>

255

<a href="#using-touch-events">Using Touch Events</a>

256

257

<li>

258

<a href="#the-touch-event-facade">The Touch Event Facade</a>

259

</li>

260

</ul>

261

</li>

262

<li>

263

<a href="#move">Cross-Device Gesture Support</a>

264

265

<li>

266

<a href="#related-events">Related Events</a>

267

</li>

268

</ul>

269

</li>

270

<li>

271

<a href="#flick">Flick Gesture Event</a>

272

</li>

273

<li>

274

<a href="#caveats">Caveats</a>

275

</li>

276

</ul>

277

</div>

278

</div>

279

280

281

282

283

284

<h2 class="no-toc">Examples</h2>

285

</div>

286

287

288

289

290

291

292

<a href="basic-example.html">Simple DOM Events</a>

293

</li>

294

295

296

297

298

<a href="synth-example.html">Creating an Arrow Event for DOM Subscription</a>

299

</li>

300

301

302

303

304

<a href="swipe-example.html">Supporting A Swipe Left Gesture</a>

305

</li>

306

307

308

309

310

311

312

313

314

315

316

317

318

</ul>

319

</div>

320

</div>

321

322

323

324

325

326

<h2 class="no-toc">Examples That Use This Component</h2>

327

</div>

328

329

330

331

332

333

334

335

336

337

338

339

340

<a href="../widget/widget-extend.html">Extending the Base Widget Class</a>

341

</li>

342

343

344

345

346

<a href="../node-focusmanager/node-focusmanager-3.html">Accessible Menu Button</a>

347

</li>

348

349

350

351

352

<a href="../io/get.html">HTTP GET to request data</a>

353

</li>

354

355

356

357

358

<a href="../dd/photo-browser.html">Photo Browser</a>

359

</li>

360

361

362

363

364

<a href="../dd/portal-drag.html">Portal Style Example</a>

365

</li>

366

367

368

</ul>

369

</div>

370

</div>

371

372

</div>

373

</div>

374

</div>

375

</div>

376

377

378

379

380

</body>

381

</html>

Older »