Table of contents

Appendices

1.5 Event listener registration

NOTE: 

This section is informative.

There are mainly two ways to associate an event listener to a node in the tree:

1. at the programming level using the EventTarget methods.

2. at the document level using [XMLEvents] or an ad-hoc syntax, as the ones provided in [XHTML10] or [SVG1].

Using the EventTarget methods[top]

The user can attach an event listener using the methods on the EventTarget interface:

myCircle.addEventListenerNS("http://www.w3.org/2001/xml-events",
                            "DOMActivate",
                            myListener,
                            true,
                            myEvtGroup);

The methods do not provide the ability to register the same event listener more than once for the same event type and the same phase. The target phase and the bubbling phase are coupled during the registration, i.e. it is not possible to register an event listener for only one of these two phases (but the listener itself could ignore events during one of these phases if desired). It is also not possible to register an event listener for a specific event target and have it only triggered for this event target during the bubbling or capture phases (but again, the listener itself could ignore events with other event targets if desired).

To register an event listener, DOM applications must use the methods EventTarget.addEventListener and EventTarget.addEventListenerNS.

An EventListener being registered on an EventTarget may choose to have that EventListener triggered during the capture phase by specifying the useCapture parameter of the EventTarget.addEventListener or EventTarget.addEventListenerNS methods to be true. If false, the EventListener will be triggered during the target and bubbling phases.

Using XML Events[top]

In [XMLEvents], event listeners are attached using elements and attributes:

<listener event="DOMActivate" observer="myCircle" handler="#myListener"
          phase="capture" propagate="stop"/>

Event listeners can only be registered on Element nodes, i.e. other Node types are not addressable, and cannot be registered for a specific group either, i.e. they are always attached to the default group. [XMLEvents] does not address namespaces in event types. If the value of the event attribute of the listener element contains a colon (':'), it should be interpreted as a QName as defined in [XMLSchema2].

Using XML or HTML attributes[top]

In languages such as [HTML40], [XHTML10], or [SVG1], event listeners are specified as attributes:

<circle id="myCircle" onactivate="myListener(evt)"
        cx="300" cy="225" r="100" fill="red"/>

Since only one attribute with the same name can appear on an element, it is therefore not possible to register more than one event listener on a single EventTarget for the event type. Also, event listeners can only be registered on Element nodes for the target phase and bubbling phase, i.e. other Node types and the capture phase are not addressable with these languages. Event listeners cannot be registered for a specific group either, i.e. they are always attached to the default group.

In order to achieve compatibility with those languages, implementors may view the setting of attributes which represent event handlers as the creation and registration of an EventListener on the EventTarget. The value of useCapture defaults to false. This EventListener behaves in the same manner as any other EventListeners which may be registered on the EventTarget. If the attribute representing the event listener is changed, this may be viewed as the removal of the previously registered EventListener and the registration of a new one. Furthermore, no specification is made as to the order in which event attributes will receive the event with regards to the other EventListeners on the EventTarget.