EventHelper

A static utility class for adding, removing, and normalizing DOM events across browsers. It provides a unified API for mouse, touch, and pointer events via on and handles event delegation, throttling, expiration, and auto-detaching of listeners.

const detacher = EventHelper.on({
    element : myElement,
    click   : 'onClick',
    thisObj : myWidget
});

// Remove listeners later
detacher();

Useful functions

Function	Description
on	Add DOM event listeners with options
getXY	Get `[x, y]` coordinates from an event
getPagePoint	Get a page-level Point from an event

Properties

Properties are getters/setters or publicly accessible variables on this class

dblClickTime : Number300

READONLY

static

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

internal

READONLY

static

DOM event to trigger name mapping.
longPressTime : Number700

READONLY

static

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

Functions

Functions are methods available for calling on the class

addElementListener( element, eventName, handlerSpec, defaults )

private

static

Used internally to add a single event handler to an element.
addListener( element, eventName, handler, options )
: Function

static

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

internal

static

For use when synthesizing events from native DOM events. Copies valid properties from the passed event into the destination object;
createDblClickWrapper( element, handler, thisObj )

private

static

Private function to wrap the passed function. The returned wrapper function to be used as a touchend handler which will call the passed function passing a fabricated dblclick event if there is a click within 300ms.
getClientPoint( event )
: Point

static

Returns a Point which encapsulates the clientX/Y position of the event. May be used in Rectangle events.
getDistanceBetween( event1, event2 )
: Number

static

Returns the pixel distance between two mouse/touch/pointer events.
getPagePoint( event )
: Point

static

Returns a Point which encapsulates the pageX/Y position of the event. May be used in Rectangle events.
getXY( event )
: Number[]

static

Returns the [x, y] coordinates of the event in the viewport coordinate system.
on( options )
: Function

static
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.
onTransitionEnd( detail )
: Function

static

Calls a callback when the described animation completes.
removeEventListener( element, eventName, handler )

private

static

Used internally to remove a single event handler from an element.
specialKeyFromEventKey( code )
: String

internal

static

If keyup event is triggered when special key is pressed, we don't get special key value from properties like ctrlKey. Instead we need to read event.key. That property uses full name and we use abbreviations, so we need to convert the key.

toSpecialKey( value, defaultValuectrlKey )

: Boolean/String

internal

static

Handles various inputs to figure out the name of the special key of the event.

EventHelper.toSpecialKey('ctrl') // 'ctrlKey'
EventHelper.toSpecialKey(true)   // 'ctrlKey'
EventHelper.toSpecialKey(false)  // false
EventHelper.toSpecialKey('foo')  // false

waitForTransitionEnd( config )
: Promise

ASYNC

static

Waits for the described animation completes.

Type definitions

ElementListenerConfig : Object<String, Function | Boolean | Object | Object[] | Number | String>
Properties
- 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 : Booleantrue
  
  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.
- buffer : Number
  
  Specify as a number of milliseconds to throttle repeated handler calls to.
- 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.
- delay : Number
  
  How long to wait for the event for.
- 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.

Source path

Core/helper/EventHelper.js

Inheritance tree1

EventHelper

EventHelper

Useful functions

See also

Properties

Functions

Type definitions

Properties

Source path

Inheritance tree1

Contents