EVT/on()

This function binds an event/gesture handler to an element. This works like EventTarget.addEventListener() but adds support for user gestures and custom event implementation.

Import

import on from '@web-native-js/play-ui/src/evt/on.js';

Syntax

on(el, eventName, handler[, params = {}]);

Parameters

  • el - HTMLElement: The source DOM element.

  • eventName - String: The event name.

  • handler - Function: The handler function. This recieves:

    • event - an event object

  • params - Object: Additional parameters.

Return A Listener instance.

Usage

on(document.body, 'doubletap', event => {
console.log('You doubletapped me!', event.details);
});

Use the trigger() method to fire the event.

// Trigger
trigger(document.body, 'doubletap');
// And we can add details
trigger(document.body, 'doubletap'), {time:0});

Tagging a Listener

The params.tags parameter can be used to tag a listener. Tags are an array of values (strings, numbers, objects, etc) that can be used to identify the listener for later use.

on(el, eventName, handler, {tags:['#tag']});

The Returned Listener Instance

The on() function returns a Listener instance that gives us per-instance control.

// Obtain the Listener instance
let instance = on(el, eventName, handler);
// Synthetically trigger the listener
instance.fire({
type: 'doubletap',
});
// Disconnect the listener
instance.disconnect();

Gestures

PlayUI uses the Hammer.js gesture library to support the following gestures out of the box. For details of these gestures, see the Hammer.js documentation.

  • press: press, pressup

  • rotate: rotate, rotatestart, rotatemove, rotateend, rotatecancel

  • pinch: pinch, pinchstart, pinchmove, pinchend, pinchcancel, pinchin, pinchout

  • pan: pan, panstart, panmove, panend, pancancel, panleft, panright, panup, pandown

  • swipe: swipe, swipeleft, swiperight, swipeup, swipedown

  • tap: tap, (by custom extension: tripletap, doubletap, singletap)

Ensure to include Hammer in your page.

<script src="//unpkg.com/@web-native-js/cui/ext/hammer.min.js"></script>