Event developer guide

Draft
This page is not complete.

Events refers both to a design pattern used for the asynchronous handling of various incidents which occur in the lifetime of a web page and to the naming, characterization, and use of a large number of incidents of different types.

The overview page provides an introduction to the design pattern and a summary of the types of incidents which are defined and reacted to by modern web browsers.

The custom events page describes how the event code design pattern can be used in custom code to define new event types emitted by user objects, register listener functions to handle those events, and trigger the events in user code.

The remaining pages describe how to use events of different kinds defined by web browsers. Unfortunately, these events have been defined piece by piece as web browsers have evolved so that there is no satisfying systematic characterization of the events built-in or defined by modern web browsers.

The device on which the web browser is running can trigger events, for example due to a change in its position and orientation in the real world, as discussed partially by the page on orientation coordinate systems and the page on the use of 3D transforms. That is different, but similar, to the change in device vertical orientation. 

The window in which the browser is displayed can trigger events; for example, change size if the user maximizes the window or otherwise changes it.

The process loading of a web page can trigger events in response to the completion of different steps in the downloading, parsing, and rendering of the web page for display to the user.

The user interaction with the web page contents can trigger events. The events triggered by user interaction evolved during the early years of browser design and include a complicated system defining the sequence in which events will be called and the manner in which that sequence can be controlled. The different types of user interaction-driven events include:

The modification of the web page in structure or content might trigger some events, as explained in the mutation events page, but the use of these events has been deprecated in favour of the lighter Mutation Observer approach.

The media streams embedded in the HTML documents might trigger some events, as explained in the media events page.

The network requests made by a web page might trigger some events.

There are many other sources of events defined by web browsers for which pages are not yet available in this guide.

Note: This Event Developer Guide needs substantial work. The structure needs to be reorganized and the pages rewritten. Our hope is that everything you need to know about events will go under here.

Docs

Creating and triggering events
This article demonstrates how to create and dispatch DOM events. Such events are commonly called synthetic events, as opposed to the events fired by the browser itself.
DOM on-event handlers
The Web platform provides several ways to get notified of DOM events.  Two common styles are: the generalized addEventListener() and a set of specific on-event handlers. This page focuses on the details of how the latter work.
Media events
Various events are sent when handling media that are embedded in HTML documents using the <audio> and <video> elements; this section lists them and provides some helpful information about using them.
Mouse gesture events
Gecko 1.9.1 added support for several Mozilla-specific DOM events used to handle mouse gestures. These are special movements that can be made with a mouse or trackpad and can be interpreted to perform specific tasks.
Mutation events
Mutation events provide a mechanism for a web page or an extension to get notified about changes made to the DOM. Use Mutation Observers instead if possible.
Orientation and motion data explained
When using orientation and motion events, it's important to understand what the values you're given by the browser mean. This article provides details about the coordinate systems at play and how you use them.
Overview of Events and Handlers
Events and event handling provide a core technique in JavaScript for reacting to incidents occurring when a browser accesses a web page, including events from preparing a web page for display, from interacting with the content of the web page,  relating to the device on which the browser is running, and from many other causes such as media stream playback or animation timing.
Touch events (Mozilla experimental)
The experimental touch events API described on this page was available from Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) to Gecko/Firefox 17. You should instead use the standard touch events API, supported since Gecko/Firefox 6 with multi-touch support added in Gecko/Firefox 12.
Using device orientation with 3D transforms
This article provides tips on how to use device orientation information in tandem with CSS 3D transforms.

Document Tags and Contributors

 Contributors to this page: gportioli, Jeremie, Sheppy, acuster
 Last updated by: gportioli,