dom-architecture.bs

<h1>DOM Event Architecture</h1>

<pre class="metadata">
Shortname: uievents-algo
Level:
Group:
Status: DREAM
Editor: No One
Abstract:
    This document provides a non-normative description of the DOM Event architecture.
        It was previously part of the UI Events spec.
</pre>

<section>
<h2 id="dom-event-architecture">DOM Event Architecture</h2>


<em>This section is non-normative. Refer to [[DOM]] for a normative description
of the DOM event architecture</em>

This information in this document was previously included in the UIEvents spec, but
has been removed to this document so avoid confusion. As noted above, the proper
definitions are part of the [[DOM]] specification.

<h3 id="event-flow">Event dispatch and DOM event flow</h3>

    This section gives a brief overview of the event <a>dispatch</a> mechanism
    and describes how events propagate through the DOM tree. Applications can
    dispatch event objects using the {{EventTarget/dispatchEvent()}} method, and
    the event object will propagate through the DOM tree as determined by the
    DOM event flow.

    <figure id="figure-dom-event-flow">
        <img src='images/eventflow.svg' height="560" alt="Graphical representation of an event dispatched in a DOM tree using the DOM event flow">
        <figcaption>Graphical representation of an event dispatched in a DOM tree using the DOM event flow</figcaption>
    </figure>

    Event objects are dispatched to an <a>event target</a>. But before dispatch
    can begin, the event object's <a>propagation path</a> must first be
    determined.

    The <a>propagation path</a> is an ordered list of <a>current event
    targets</a> through which the event passes. This propagation path reflects
    the hierarchical tree structure of the document. The last item in the list
    is the <a>event target</a>, and the preceding items in the list are referred
    to as the <em>target's ancestors</em>, with the immediately preceding item
    as the <em>target's parent</em>.

    Once the <a>propagation path</a> has been determined, the event object
    passes through one or more <a>event phases</a>. There are three event
    phases: <a>capture phase</a>, <a>target phase</a> and <a>bubble phase</a>.
    Event objects complete these phases as described below. A phase will be
    skipped if it is not supported, or if the event object's propagation has
    been stopped. For example, if the {{Event/bubbles}} attribute is set to
    false, the bubble phase will be skipped, and if {{Event/stopPropagation()}}
    has been called prior to the dispatch, all phases will be skipped.

    *   The <strong>capture phase</strong>: The event object propagates
        through the target's ancestors from the <a>Window</a> to the target's
        parent. This phase is also known as the <em>capturing phase</em>.

    *   The <strong>target phase</strong>: The event object arrives at the event
        object's <a>event target</a>. This phase is also known as the
        <em>at-target phase</em>. If the <a>event type</a> indicates that the
        event doesn't bubble, then the event object will halt after completion
        of this phase.

    *   The <strong>bubble phase</strong>: The event object propagates through
        the target's ancestors in reverse order, starting with the target's
        parent and ending with the <a>Window</a>. This phase is also known as
        the <em>bubbling phase</em>.


<h3 id="event-flow-default-cancel">Default actions and cancelable events</h3>

    Events are typically dispatched by the implementation as a result of a user
    action, in response to the completion of a task, or to signal progress
    during asynchronous activity (such as a network request). Some events can be
    used to control the behavior that the implementation may take next (or undo
    an action that the implementation already took). Events in this category are
    said to be <em>cancelable</em> and the behavior they cancel is called their
    <em><a>default action</a></em>. Cancelable event objects can be associated
    with one or more 'default actions'. To cancel an event, call the
    {{Event/preventDefault()}} method.

    <p class="example">
    A EVENT{mousedown} event is dispatched immediately after the user presses
    down a button on a pointing device (typically a mouse). One possible
    <a>default action</a> taken by the implementation is to set up a state
    machine that allows the user to drag images or select text. The <a>default
    action</a> depends on what happens next &mdash; for example, if the user's
    pointing device is over text, a text selection might begin. If the user's
    pointing device is over an image, then an image-drag action could begin.
    Preventing the <a>default action</a> of a EVENT{mousedown} event prevents
    these actions from occurring.
    </p>

    <a>Default actions</a> are usually performed after the event dispatch has
    been completed, but in exceptional cases they may also be performed
    immediately before the event is dispatched.

    <p class="example">
    The default action associated with the EVENT{click} event on <code>&lt;input
    type="checkbox"&gt;</code> elements toggles the <code>checked</code> IDL
    attribute value of that element. If the EVENT{click} event's default action
    is cancelled, then the value is restored to its former state.
    </p>

    When an event is canceled, then the conditional <a>default actions</a>
    associated with the event is skipped (or as mentioned above, if the
    <a>default actions</a> are carried out before the dispatch, their effect
    is undone). Whether an event object is cancelable is indicated by
    the {{Event/cancelable}} attribute. Calling {{Event/preventDefault()}} stops all
    related <a>default actions</a> of an event object. The
    {{Event/defaultPrevented}} attribute indicates whether an event has already
    been canceled (e.g., by a prior <a>event listener</a>). If the <a>DOM
    application</a> itself initiated the dispatch, then the return value of the
    {{EventTarget/dispatchEvent()}} method indicates whether the event object
    was cancelled.

    <p class="note">Many implementations additionally interpret an <a>event
    listener</a>'s return value, such as the value <code>false</code>, to mean that
    the <a>default action</a> of cancelable events will be cancelled (though
    <code>window.onerror</code> handlers are cancelled by returning
    <code>true</code>).
    </p>

<h3 id="sync-async">Synchronous and asynchronous events</h3>

    Events may be dispatched either synchronously or asynchronously.

    Events which are synchronous (<em><q>sync events</q></em>) are treated
    as if they are in a virtual queue in a first-in-first-out model, ordered by
    sequence of temporal occurrence with respect to other events, to changes in
    the DOM, and to user interaction.  Each event in this virtual queue is
    delayed until the previous event has completed its propagation behavior, or
    been canceled.  Some sync events are driven by a specific device or process,
    such as mouse button events. These events are governed by the <a>event
    order</a> algorithms defined for that set of events, and user agents will
    dispatch these events in the defined order.

    Events which are asynchronous (<em><q>async events</q></em>) may be
    dispatched as the results of the action are completed, with no relation to
    other events, to other changes in the DOM, nor to user interaction.

    <p class="example">
    During loading of a document, an inline script element is parsed and
    executed. The EVENT{load} event is queued to be fired
    asynchronously at the script element. However, because it is an async event,
    its order with relation to other synchronous events fired during document
    load (such as the <code class="eventtype">DOMContentLoaded</code> event from
    [[!HTML5]]) is not guaranteed.
    </p>

<h3 id="trusted-events">Trusted events</h3>

    Events that are generated by the <a>user agent</a>, either as a result of user
    interaction, or as a direct result of changes to the DOM, are trusted by the
    <a>user agent</a> with privileges that are not afforded to events generated by
    script through the {{Document/createEvent()}} method, modified
    using the {{Event/initEvent()}} method, or dispatched via the
    {{EventTarget/dispatchEvent()}} method.  The {{Event/isTrusted}} attribute
    of trusted events has a value of <code>true</code>, while untrusted events
    have a {{Event/isTrusted}} attribute value of <code>false</code>.

    Most untrusted events will not trigger <a>default actions</a>, with the
    exception of the EVENT{click} event. This event always
    triggers the <a>default action</a>, even if the {{Event/isTrusted}}
    attribute is <code>false</code> (this behavior is retained for
    backward-compatibility). All other untrusted events behave as if the
    {{Event/preventDefault()}} method had been called on that event.


<h3 id="event-flow-activation">Activation triggers and behavior</h3>

    Certain <a>event targets</a> (such as a link or button element) may have
    associated <a>activation behavior</a> (such as following a link) that
    implementations perform in response to an <em><a>activation
    trigger</a></em> (such as clicking a link).

    <p class="example" id="example-activation">
    Both HTML and SVG have an <code>&lt;a&gt;</code> element which indicates a
    link.  Relevant <a>activation triggers</a> for an <code>&lt;a&gt;</code>
    element are a EVENT{click} event on the text or image content
    of the <code>&lt;a&gt;</code> element, or a EVENT{keydown}
    event with a {{KeyboardEvent/key}} attribute value of KEY{Enter} key when
    the <code>&lt;a&gt;</code> element has focus.  The activation behavior for
    an <code>&lt;a&gt;</code> element is normally to change the content of the
    window to the content of the new document, in the case of external links,
    or to reposition the current document relative to the new anchor, in the
    case of internal links.
    </p>

    An <a>activation trigger</a> is a user action or an event which indicates
    to the implementation that an activation behavior should be initiated.
    User-initiated <a>activation triggers</a> include clicking a mouse button
    on an activatable element, pressing the KEYCAP{Enter} key when an activatable
    element has focus, or pressing a key that is somehow linked to an
    activatable element (a <q>hotkey</q> or <q>access key</q>) even when that
    element does not have focus.  Event-based <a>activation triggers</a> may
    include timer-based events that activate an element at a certain clock time
    or after a certain time period has elapsed, progress events after a certain
    action has been completed, or many other condition-based or state-based
    events.


<h3 id="event-constructors">Constructing Mouse and Keyboard Events</h3>

    Generally, when a constructor of an {{Event}} interface, or of an interface
    inherited from the {{Event}} interface, is invoked, the steps described in
    [[!DOM]] should be followed. However the {{KeyboardEvent}} and
    {{MouseEvent}} interfaces provide additional dictionary members for
    initializing the internal state of the {{Event}} object's key modifiers:
    specifically, the internal state queried for using the
    {{KeyboardEvent/getModifierState()}} and {{MouseEvent/getModifierState()}}
    methods. This section supplements the DOM4 steps for intializing a new
    {{Event}} object with these optional modifier states.

    For the purposes of constructing a {{KeyboardEvent}}, {{MouseEvent}}, or
    object derived from these objects using the algorithm below, all
    {{KeyboardEvent}}, {{MouseEvent}}, and derived objects have
    <dfn id="internal-key-modifier-state">internal key modifier state</dfn> which can be set and
    retrieved using the key modifier names described in the
    <a href="http://www.w3.org/TR/uievents-key/#keys-modifier">Modifier Keys table</a>
    in [[UIEvents-Key]].

    The following steps supplement the algorithm defined for constructing
    events in DOM4:

    *   If the {{Event}} being constructed is a {{KeyboardEvent}} or
        {{MouseEvent}} object or an object that derives from either of these,
        and a {{EventModifierInit}} argument was provided to the constructor,
        then run the following sub-steps:

        *   For each {{EventModifierInit}} argument, if the dictionary member
            begins with the string <code>"modifier"</code>, then let the
            <dfn id="modifier-key-name">key modifier name</dfn> be the
            dictionary member's name excluding the prefix
            <code>"modifier"</code>, and set the {{Event}} object's
            <a href="#internal-key-modifier-state">internal key modifier state</a>
            that matches the <a href="#modifier-key-name">key modifier name</a>
            to the corresponding value.

</section>

<section>
<h2 id="glossary">Glossary</h2>

Some of the following term definitions have been borrowed or modified from
similar definitions in other W3C or standards documents. See the links within
the definitions for more information.

: <dfn>activation behavior</dfn>
::  The action taken when an <a>event</a>, typically initiated by users through
    an input device, causes an element to fulfill a defined task.  The task MAY
    be defined for that element by the <a>host language</a>, or by
    author-defined variables, or both.  The default task for any given element
    MAY be a generic action, or MAY be unique to that element.  For example, the
    activation behavior of an HTML or SVG <code>&lt;a&gt;</code> element is to
    cause the <a>user agent</a> to traverse the link specified in the
    <code>href</code> attribute, with the further optional parameter of
    specifying the browsing context for the traversal (such as the current
    window or tab, a named window, or a new window). The activation behavior of
    an HTML <code>&lt;input&gt;</code> element with the <code>type</code>
    attribute value <code>submit</code> is be to send the values of the form
    elements to an author-defined IRI by the author-defined HTTP method.

: <dfn>activation trigger</dfn>
::  An event which is defined to initiate an <a>activation behavior</a>.

: <dfn lt="bubble phase|bubbling phase">bubbling phase</dfn>
::  The process by which an <a>event</a> can be handled by one of the target's
    ancestors <em>after</em> being handled by the <a>event target</a>. See the
    description of the <a>bubble phase</a> in the context of event flow for more
    details.

: <dfn>capture phase</dfn>
::  The process by which an <a>event</a> can be handled by one of the target's
    ancestors <em>before</em> being handled by the <a>event target</a>. See the
    description of the <a href="#capture-phase">capture phase</a> in the context
    of event flow for more details.

: <dfn>current event target</dfn>
::  In an event flow, the current event target is the object associated with the
    <a>event handler</a> that is currently being dispatched. This object MAY be
    the <a>event target</a> itself or one of its ancestors. The current event
    target changes as the <a>event</a> propagates from object to object through
    the various <a>phases</a> of the event flow. The current event target is the
    value of the {{Event/currentTarget}} attribute.

: <dfn>default action</dfn>
::  A <a>default action</a> is an OPTIONAL supplementary behavior that an
    implementation MUST perform in combination with the dispatch of the event
    object.  Each event type definition, and each specification, defines the
    <a>default action</a> for that event type, if it has one.  An instance of an
    event MAY have more than one <a>default action</a> under some circumstances,
    such as when associated with an <a>activation trigger</a>.  A <a>default
    action</a> MAY be cancelled through the invocation of the
    {{Event/preventDefault()}} method.

: <dfn>dispatch</dfn>
::  To create an event with attributes and methods appropriate to its type and
    context, and propagate it through the DOM tree in the specified manner.
    Interchangeable with the term <q><a>fire</a></q>, e.g., <q>fire a
    EVENT{click} event</q> or <q>dispatch a EVENT{load} event</q>.

: <dfn>document</dfn>
::  An object instantiating the {{Document}} interface [[DOM-Level-3-Core]],
    representing the entire HTML or XML text document.  Conceptually, it is the
    root of the document tree, and provides the primary access to the document's
    data.

: <dfn>DOM application</dfn>
::  A DOM application is script or code, written by a content author or
    automatically generated, which takes advantage of the interfaces, methods,
    attributes, events, and other features described in this specification in
    order to make dynamic or interactive content, such as Web applications,
    exposed to users in a <a>user agent</a>.

: <dfn>event</dfn>
::  An event is the representation of some occurrence (such as a mouse click on
    the presentation of an element, the removal of child node from an element,
    or any number of other possibilities) which is associated with its <a>event
    target</a>. Each event is an instantiation of one specific <a>event
    type</a>.

: <dfn>event handler</dfn>
: <dfn>event listener</dfn>
::  An object that implements the {{EventListener}} interface and provides an
    {{EventListener/handleEvent()}} callback method. Event handlers are
    language-specific. Event handlers are invoked in the context of a particular
    object (the <a>current event target</a>) and are provided with the event
    object itself.

    <p class="note">
    In JavaScript, user-defined functions are considered to implement the
    {{EventListener}} interface. Thus the event object will be provided as the
    first parameter to the user-defined function when it is invoked.
    Additionally, JavaScript objects can also implement the {{EventListener}}
    interface when they define a {{EventListener/handleEvent()}} method.
    </p>

: <dfn>event order</dfn>
::  The sequence in which events from the same event source or process occur,
    using the same or related event interfaces. For example, in an environment
    with a mouse, a track pad, and a keyboard, each of those input devices would
    constitute a separate event source, and each would follow its own event
    order. A EVENT{mousedown} event from the trackpad followed by a
    EVENT{mouseup} event from the mouse would not result in a EVENT{click} event.

    <p class="note">
    There can be interactions between different event orders. For example, a
    EVENT{click} event might be modified by a concurrent EVENT{keydown} event
    (e.g., via KEYCAP{Shift}<code>+</code>EVENT{click}). However, the event
    orders of these different event sources would be distinct.

    The event order of some interfaces are device-independent. For example, a
    user might change focus using the KEYCAP{Tab} key, or by clicking the new
    focused element with the mouse.  The event order in such cases depends on
    the state of the process, not on the state of the device that initiates the
    state change.

: <dfn>event phase</dfn>
::  See <a>phase</a>.

: <dfn>event target</dfn>
::  The object to which an <a>event</a> is targeted using the event flow.
    The event target is the value of the {{Event/target}} attribute.

: <dfn>fire</dfn>
::  A synonym for <a>dispatch</a>.

: <dfn>host language</dfn>
::  Any language which integrates the features of another language or API
    specification, while normatively referencing the origin specification rather
    than redefining those features, and extending those features only in ways
    defined by the origin specification.  An origin specification typically is
    only intended to be implemented in the context of one or more host
    languages, not as a standalone language.  For example, XHTML, HTML, and SVG
    are host languages for UI Events, and they integrate and extend the objects
    and models defined in this specification.

: <dfn>phase</dfn>
::  In the context of <a>events</a>, a phase is set of logical traversals from
    node to node along the DOM tree, from the <a>Window</a> to the {{Document}}
    object, <a>root element</a>, and down to the <a>event target</a> (<a>capture
    phase</a>), at the <a>event target</a> itself (<a>target phase</a>), and
    back up the same chain (<a>bubbling phase</a>).

: <dfn>propagation path</dfn>
::  The ordered set of <a>current event targets</a> though which an <a>event</a>
    object will pass sequentially on the way to and back from the <a>event
    target</a>.  As the event propagates, each <a>current event target</a> in
    the propagation path is in turn set as the {{Event/currentTarget}}. The
    propagation path is initially composed of one or more <a>event phases</a> as
    defined by the <a>event type</a>, but MAY be interrupted.  Also known as an
    <em>event target chain</em>.

: <dfn>target phase</dfn>
::  The process by which an <a>event</a> can be handled by the <a>event
    target</a>. See the description of the <a>target phase</a> in the context of
    event flow for more details.

: <dfn>user agent</dfn>
::  A program, such as a browser or content authoring tool, normally running on
    a client machine, which acts on a user's behalf in retrieving, interpreting,
    executing, presenting, or creating content.  Users MAY act on the content
    using different user agents at different times, for different purposes.

: <dfn>Window</dfn>
::  The <code>Window</code> is the object referred to by the current <a>document</a>'s
    browsing context's Window Proxy object as defined in
    <a href="http://dev.w3.org/html5/spec/single-page.html#windowproxy" title="HTML5 WindowProxy description">HTML5</a>
    [[HTML5]].

</section>