EventHelper

Utility methods for dealing with Events, normalizing Touch/Pointer/Mouse events.

Properties

dblClickTime: Number= 300readonlystatic

The time in milliseconds within which a second touch tap event triggers a dblclick event.

longPressTime: Number= 700readonlystatic

The time in milliseconds for a taphold gesture to trigger a contextmenu event.

Functions

Add a listener or listeners to an element The options parameter allows supplying options for the listener(s), for available options see ElementListenerConfig.

Parameter	Type	Description
`element`	EventTarget	The event target to add a listener/listeners to.
`eventName`	String \| Object	Either a string, being the name of the event to listen for, or an options object containing event names and options as keys. See the options parameter for details, or the on method for details.
`handler`	function	If the second parameter is a string event name, this is the handler function.
`options`	ElementListenerConfig	If the second parameter is a string event name, this is the options.

Returns: function -

A detacher function which removes all the listeners when called.

getClientPointstatic

Returns a Point which encapsulates the clientX/Y position of the event. May be used in Rectangle events.

Parameter	Type	Description
`event`	Event	A browser mouse/touch/pointer event.

Returns: Point -

The page point.

getDistanceBetweenstatic

Returns the pixel distance between two mouse/touch/pointer events.

Parameter	Type	Description
`event1`	Event	The first event.
`event2`	Event	The second event.

Returns: Number -

The distance in pixels between the two events.

getPagePointstatic

Returns a Point which encapsulates the pageX/Y position of the event. May be used in Rectangle events.

Parameter	Type	Description
`event`	Event	A browser mouse/touch/pointer event.

Returns: Point -

The page point.

getXYstatic

Returns the [x, y] coordinates of the event in the viewport coordinate system.

Parameter	Type	Description
`event`	Event	The event

Returns: Number[] -

The coordinate.

onstatic

Adds a listener or listeners to an element. all property names other than the options listed below are taken to be event names, and the values as handler specs.

A handler spec is usually a function reference or the name of a function in the thisObj option.

But a handler spec may also be an options object containing a handler property which is the function or function name, and local options, including element and thisObj which override the top level options.

The options parameter allows supplying options for the listener(s), for available options see ElementListenerConfig.

Usage example

construct(config) {
    super.construct(config);

    // Add auto detaching event handlers to this Widget's reference elements
    EventHelper.on({
        element : this.iconElement,
        click   : '_handleIconClick',
        thisObj : this,
        contextmenu : {
            element : document,
            handler : '_handleDocumentContextMenu'
        }
    });
}

The click handler on the iconElement calls this._handleIconClick.

The contextmenu handler is added to the document element, but the thisObj is defaulted in from the top options and calls this._handleDocumentContextMenu.

Note that on touch devices, dblclick and contextmenu events are synthesized. Synthesized events contain a browserEvent property containing the final triggering event of the gesture. For example a synthesized dblclick event would contain a browserEvent property which is the last touchend event. A synthetic contextmenu event will contain a browserEvent property which the longstanding touchstart event.

Parameter	Type	Description
`options`	ElementListenerConfig	The full listener specification.

Returns: function -

A detacher function which removes all the listeners when called.

onTransitionEndstatic

Calls a callback when the described animation completes.

Parameter	Type	Description
`detail`	Object
`detail.element`	HTMLElement	The element which is being animated.
`detail.animationName`	String \| RegExp	The name of the animation to wait for.
`detail.property`	String	If no `animationName` specified, the CSS property which is being animated.
`detail.handler`	function	The function to call on animation end.
`detail.duration`	Number	Optional fallback time to wait until calling the callback.
`detail.thisObj`	Object	The `this` reference to call the callback with.
`detail.args`	Array	Optional arguments to call the callback with.
`detail.timerSource`	Delayable	A Delayable to provide the fallback timeout.
`detail.runOnDestroy`	Boolean	If `timerSource` is a Delayable, `true` to invoke the callback if it is destroyed during the animation.

Returns: function -

a function which detaches the animation end listener.

waitForTransitionEndstatic

Waits for the described animation completes.

Parameter	Type	Description
`config`	Object
`config.element`	HTMLElement	The element which is being animated.
`config.animationName`	String \| RegExp	The name of the animation to wait for.
`config.property`	String	If no `animationName` specified, the CSS property which is being animated.
`config.duration`	Number	Optional fallback time to wait until calling the callback.
`config.timerSource`	Delayable	A Delayable to provide the fallback timeout.
`config.runOnDestroy`	Boolean	If `timerSource` is a Delayable, `true` to invoke the callback if it is destroyed during the animation.

Typedefs

Parameter	Type	Description
`element`	EventTarget	The element or document to add the listener to.
`thisObj`	Object	The default `this` reference for all handlers added in this call.
`autoDetach`	Boolean	The listeners are automatically removed when the `thisObj` is destroyed.
`delegate`	String	A CSS selector string which only fires the handler when the event takes place in a matching element.
`once`	Boolean	Specify as `true` to have the listener(s) removed upon first invocation.
`delay`	Number	The number of milliseconds to delay the handler call after the event fires.
`capture`	Boolean	Specify as `true` to add the listener in the capture phase.
`passive`	Boolean	Specify as `true` to add the listener as a passive listener.
`throttled`	Number \| Object	Specify as a number of milliseconds to throttle repeated handler calls to or an object.
`throttled.buffer`	number	Specify as a number of milliseconds to throttle repeated handler calls to.
`throttled.alt`	function	Specify an alternative function to call if called between throttled calls.
`expires`	Number \| Object	The listener only waits for a specified time before being removed. The value may be a number or an object containing an expiry handler.
`expires.delay`	Number	How long to wait for the event for.
`expires.alt`	String \| function	The function to call when the listener expires without having been triggered.
`raw`	Boolean	Specify as `true` to receive the raw DOM event instead of the browser-normalized event.