`event-constructor-polyfill`

- Introduction
- Usage
- Affected browsers
- Notes
- Argument validation
- MouseEvent key modifiers
- Bypassing the check for the new keyword
- List of polyfilled constructors
- List of omitted constructors
- License

Introduction

The original method of dynamically creating events in JavaScript used an API inspired by Java:

``

javascript

var event = document.createEvent('MouseEvent');

event.initMouseEvent('click', false, false, window, null, null, null, 100, 0);





Many event interfaces have their own initializer methods with wildly differing argument lists. For example,

initMouseEvent() takes more arguments than initKeyboardEvent()

.



The new method of creating events (part of the DOM Living Standard) is to use a simple constructor function.

javascript

var event = new MouseEvent('click', {

    clientX: 100,

    clientY: 0

});





The constructor functions work the same way across all event interfaces, each taking only two arguments:



1. A string describing the type of the event, and

2. an optional plain object which provides the values of the event's properties.



This polyfill enables the use of this constructor syntax in browsers that don't natively support it.



Usage



Include the script:



$3

html





Or



$3

shell script

npm i --save @lycoris-nubila/event-constructor-polyfill

$3

javascript

required('@lycoris-nubila/event-constructor-polyfill');

$3

javascript

import '@lycoris-nubila/event-constructor-polyfill';





Then, use the polyfilled constructor functions as documented:

javascript

var simpleEvent = new CustomEvent('foo');

var detailedEvent = new CustomEvent('bar', { / ... / });





Affected browsers



The main goal of this polyfill is to allow the use of event constructors in Chrome 15 and above, Firefox 11 and above, Safari 6 and above, and Internet Explorer 9 and above. It has no effect in IE8 or below.



Notes



$3



In accordance with the spec, the constructor functions created by this polyfill will throw a

TypeError

 under the following scenarios:

- No arguments are provided

- The second argument is not an

Object (and is not null or undefined

)

- The

new

 keyword is not used



$3



When creating a

MouseEvent, KeyboardEvent, or WheelEvent, there are extra key modifiers that can be provided (in addition to altKey, ctrlKey, metaKey, and shiftKey). These are defined in the EventModifierInit dictionary

. For example:

javascript

var k = new KeyboardEvent('keydown', { modifierCapsLock: true });

k.getModifierState('CapsLock');

// => true



These extra modifiers work as expected for the polyfilled

KeyboardEvent and WheelEvent constructors, but are ignored in the polyfilled MouseEvent constructor. This is because initKeyboardEvent() and initWheelEvent() accept these extra modifiers, but initMouseEvent() only accepts altKey, ctrlKey, metaKey, and shiftKey

.



$3



As mentioned above, there are checks in place to ensure that the polyfilled constructors can't be invoked without the

new

 keyword:

javascript

var g = GamepadEvent('gamepadconnected'); // TypeError

var k = KeyboardEvent.call(new KeyboardEvent('keydown'), 'keyup'); // TypeError

var c = CustomEvent.call(CustomEvent.prototype, 'foo') // TypeError



The test for usage of the

new

 keyword can be fooled, but only by statements that are specifically crafted to do so, such as the following:

javascript

var dummy = Object.create(MouseEvent.prototype);

MouseEvent.call(dummy, 'click'); // No TypeError is thrown.



However, the constructor functions always return a new object; they never interact with the

this object on which they are called. In the example above, trying to access dummy.type will throw a TypeError, because dummy was not initialized by the constructor; it's just a copy of MouseEvent.prototype

.



List of polyfilled constructors



Some of the events below don't have any public documentation for their initializer method. These events were still polyfilled because (a) their initializer method would only require a single unique argument, and / or (b) some other evidence was found for the existence of the initializer method.



Event interface | Initializer method | Notes

---|---|---

AnimationEvent | initAnimationEvent()

 (MDN)

ClipboardEvent | initClipboardEvent() (W3C) | In Chrome (tested in 52 & 53), the native constructor throws a TypeError

 ("illegal constructor").

CloseEvent | initCloseEvent()

 (MDN)

CompositionEvent | initCompositionEvent()

 (MDN)

CustomEvent | initCustomEvent()

 (MDN)

DeviceMotionEvent | initDeviceMotionEvent()

 (MSDN)

DeviceOrientationEvent | initDeviceOrientationEvent()

 (MSDN)

DragEvent | initDragEvent()

 (MSDN)

ErrorEvent | initErrorEvent()

 (MSDN)

FocusEvent | initFocusEvent()

 (MSDN)

GamepadEvent | initGamepadEvent()

HashChangeEvent | initHashChangeEvent()

KeyboardEvent | initKeyboardEvent() (MSDN) | initKeyboardEvent() is always used; never initKeyEvent()

MediaStreamEvent | initMediaStreamEvent()

MessageEvent | initMessageEvent()

 (MSDN)

MouseEvent | initMouseEvent()

 (MDN)

PageTransitionEvent | initPageTransitionEvent()

PointerEvent | initPointerEvent() (MSDN) | Accounts for the fact that the interface is prefixed in IE 10 as MSPointerEvent (the constructor is still polyfilled and made available as PointerEvent). As of September 2016, PointerEvent

 is not implemented in Chrome (but is under development).

PopStateEvent | initPopStateEvent()

 (MSDN)

ProgressEvent | initProgressEvent()

 (MDN)

StorageEvent | initStorageEvent()

 (MDN)

TouchEvent | initTouchEvent() (Apple) | Accounts for the fact that Chrome does not follow the W3C spec and expects a different argument list to initTouchEvent

TransitionEvent | initTransitionEvent()

 (MDN)

UIEvent | initUIEvent()

 (MDN)

UserProximityEvent | initUserProximityEvent()

WebGLContextEvent | initWebGLContextEvent()

WheelEvent | initWheelEvent()

 (MSDN)



List of omitted constructors



The following event constructors are not polyfilled by this script.



Event interface | Reason for omission

---|---

GestureEvent

 | Non-standard.

MouseScrollEvent | Non-standard. WheelEvent is the standards-based interface for mouse wheel scrolling events, and initWheelEvent()

 is supported in IE9+.

MouseWheelEvent | Non-standard. WheelEvent is the standards-based interface for mouse wheel scrolling events, and initWheelEvent()

 is supported in IE9+.

MutationEvent | Deprecated; inconsistent implementation across different browsers. Use MutationObserver

 instead.



License

event-constructor-polyfill` uses the MIT License.

`event-constructor-polyfill`

Introduction

The original method of dynamically creating events in JavaScript used an API inspired by Java:

``

javascript

var event = document.createEvent('MouseEvent');

event.initMouseEvent('click', false, false, window, null, null, null, 100, 0);





Many event interfaces have their own initializer methods with wildly differing argument lists. For example,

initMouseEvent() takes more arguments than initKeyboardEvent()

.



The new method of creating events (part of the DOM Living Standard) is to use a simple constructor function.

javascript

var event = new MouseEvent('click', {

    clientX: 100,

    clientY: 0

});





The constructor functions work the same way across all event interfaces, each taking only two arguments:



1. A string describing the type of the event, and

2. an optional plain object which provides the values of the event's properties.



This polyfill enables the use of this constructor syntax in browsers that don't natively support it.



Usage



Include the script:



$3

html





Or



$3

shell script

npm i --save @lycoris-nubila/event-constructor-polyfill

$3

javascript

required('@lycoris-nubila/event-constructor-polyfill');

$3

javascript

import '@lycoris-nubila/event-constructor-polyfill';





Then, use the polyfilled constructor functions as documented:

javascript

var simpleEvent = new CustomEvent('foo');

var detailedEvent = new CustomEvent('bar', { / ... / });





Affected browsers



The main goal of this polyfill is to allow the use of event constructors in Chrome 15 and above, Firefox 11 and above, Safari 6 and above, and Internet Explorer 9 and above. It has no effect in IE8 or below.



Notes



$3



In accordance with the spec, the constructor functions created by this polyfill will throw a

TypeError

 under the following scenarios:

- No arguments are provided

- The second argument is not an

Object (and is not null or undefined

)

- The

new

 keyword is not used



$3



When creating a

. For example:

javascript

var k = new KeyboardEvent('keydown', { modifierCapsLock: true });

k.getModifierState('CapsLock');

// => true



These extra modifiers work as expected for the polyfilled

.



$3



As mentioned above, there are checks in place to ensure that the polyfilled constructors can't be invoked without the

new

 keyword:

javascript

var g = GamepadEvent('gamepadconnected'); // TypeError

var k = KeyboardEvent.call(new KeyboardEvent('keydown'), 'keyup'); // TypeError

var c = CustomEvent.call(CustomEvent.prototype, 'foo') // TypeError



The test for usage of the

new

 keyword can be fooled, but only by statements that are specifically crafted to do so, such as the following:

javascript

var dummy = Object.create(MouseEvent.prototype);

MouseEvent.call(dummy, 'click'); // No TypeError is thrown.



However, the constructor functions always return a new object; they never interact with the

.



List of polyfilled constructors



Some of the events below don't have any public documentation for their initializer method. These events were still polyfilled because (a) their initializer method would only require a single unique argument, and / or (b) some other evidence was found for the existence of the initializer method.



Event interface | Initializer method | Notes

---|---|---

AnimationEvent | initAnimationEvent()

 (MDN)

ClipboardEvent | initClipboardEvent() (W3C) | In Chrome (tested in 52 & 53), the native constructor throws a TypeError

 ("illegal constructor").

CloseEvent | initCloseEvent()

 (MDN)

CompositionEvent | initCompositionEvent()

 (MDN)

CustomEvent | initCustomEvent()

 (MDN)

DeviceMotionEvent | initDeviceMotionEvent()

 (MSDN)

DeviceOrientationEvent | initDeviceOrientationEvent()

 (MSDN)

DragEvent | initDragEvent()

 (MSDN)

ErrorEvent | initErrorEvent()

 (MSDN)

FocusEvent | initFocusEvent()

 (MSDN)

GamepadEvent | initGamepadEvent()

HashChangeEvent | initHashChangeEvent()

KeyboardEvent | initKeyboardEvent() (MSDN) | initKeyboardEvent() is always used; never initKeyEvent()

MediaStreamEvent | initMediaStreamEvent()

MessageEvent | initMessageEvent()

 (MSDN)

MouseEvent | initMouseEvent()

 (MDN)

PageTransitionEvent | initPageTransitionEvent()

 is not implemented in Chrome (but is under development).

PopStateEvent | initPopStateEvent()

 (MSDN)

ProgressEvent | initProgressEvent()

 (MDN)

StorageEvent | initStorageEvent()

 (MDN)

TouchEvent | initTouchEvent() (Apple) | Accounts for the fact that Chrome does not follow the W3C spec and expects a different argument list to initTouchEvent

TransitionEvent | initTransitionEvent()

 (MDN)

UIEvent | initUIEvent()

 (MDN)

UserProximityEvent | initUserProximityEvent()

WebGLContextEvent | initWebGLContextEvent()

WheelEvent | initWheelEvent()

 (MSDN)



List of omitted constructors



The following event constructors are not polyfilled by this script.



Event interface | Reason for omission

---|---

GestureEvent

 | Non-standard.

MouseScrollEvent | Non-standard. WheelEvent is the standards-based interface for mouse wheel scrolling events, and initWheelEvent()

 is supported in IE9+.

MouseWheelEvent | Non-standard. WheelEvent is the standards-based interface for mouse wheel scrolling events, and initWheelEvent()

 is supported in IE9+.

MutationEvent | Deprecated; inconsistent implementation across different browsers. Use MutationObserver

 instead.



License

event-constructor-polyfill` uses the MIT License.

@lycoris-nubila/event-constructor-polyfill

`event-constructor-polyfill`

Table of Contents

Introduction

Usage

$3

$3

$3

$3

Affected browsers

Notes

$3

$3

$3

List of polyfilled constructors

List of omitted constructors

License

@lycoris-nubila/event-constructor-polyfill

`event-constructor-polyfill`

Table of Contents

Introduction

Usage

$3

$3

$3

$3

Affected browsers

Notes

$3

$3

$3

List of polyfilled constructors

List of omitted constructors

License