The interface class EventTarget can be implemented as a mixin for any JavaScript class or it can be applied at runtime to any DOM node or JavaScript object by simply casting the node/object to EventTarget. It implements the W3C DOM Level 3 interface EventTarget and extends it with a number of useful features. Note that for the sake of compatibility the W3C, some methods have been renamed. For example, addEventListener() becomes addListener().

Usage example:

 // Shortcut for easier code.
 var EventTarget = nokia.maps.dom.EventTarget;
 
 // Cast a DOM node into an valid nokia.maps.dom.EventTarget
 // Note: The DOM node is modified by the EventTarget interface,  
 // therefore a second cast is not necessary.
 var node = document.getElementById("whatever");
 EventTarget(node);

 // You can also cast normal JavaScript objects including bubbling
 // and capture phases and all that DOM supports:
 var myObject = {},
	  myParentObject = {};
 EventTarget(myObject).parentNode = EventTarget(myParentObject); 
 
 // Now you can fire an event at "myObject" that will 
 // bubble to "myParentObject":
 myParentObject.addListener("customEvent", function (evt) {
	alert( evt.type );
 });
 myObject.dispatch(
	new nokia.maps.dom.Event({
	  type: "customEvent"
	})
 );
 
 // Note: It is also possible to set the parentNode property of 
 // a JavaScript object to a DOM node. Events then flow 
 // into the DOM tree, although not at native level.

EventTarget offers access to the nokia.maps DOM helpers and normalizes browser event handling for this target. By default an event target is not draggable, but selectable. If this interface is implemented as a mixin, it the property isEventTarget must be added and set to true.

If you have problems with MooTools then a possible fix is to include MooTools after this API is fully loaded and to replace every occurrence of "addListener" in the MooTools library with, for example, "mooAddListener", and every occurrence of "removeListener" with, for example, "mooRemoveListener". You need to do this also in all libraries that are based on MooTools. The reason is that MooTools modifies the prototypes of some native JavaScript and DOM objects and therefore causes a collision with extensions used by this API.

Note: The name clash arises, because MooTools modifies not only those DOM nodes that it uses, but patches all instances of all objects, including native browser objects. To avoid the name clashes, you must rename the MooTools methods "addListener" and "removeListener", and load MooTools after this API so that this API can keep references to the original native browser methods instead of referring to the methods modified by MooTools.

The listener queue

The listeners to events are called in reverse registration order, which means that the listener registered last is the first to be notified of an event. Therefore, if you want a listener to be notified last in an existing queue, you must register it as the first listener in the chain. This can be done by using the arbitrary non-standard method insertListener() or insertListenerNS() defined on this interface (EventTarget).

Note: Applying this interface to a DOM node, causes methods and properties to be copied to the DOM node that might cause collisions with other frameworks. Therefore before combining nokia.maps.dom.EventTarget with any other framework, check carefully that name conflicts do not arise.

Events normally trickle and bubble through the hierarchy in a DOM tree, where each node can only have one parent node (referenced by the property parentNode). For example, if the user clicks on a DOM node, then the browser builds a propagation path by going from the node that was the target of the click via the parentNode up to the root node (the HTML tag), which does not have a parent node assigned to propagation path. The browser uses the propagation path to dispatch the event to each of the nodes in it. First, in the capture phase, the chain is iterated from the root node (the HTML node) down to the target node (which the user has hit with it's click). Subsequently, in the bubbling phase, the event is dispatched to each node again, this time starting from the target node, working back up to the root node. Thus, each node receives the event twice, once within the capture phase and once within the bubbling phase. Normally events are processed within the bubbling phase, but there might been reasons to process them in the capture phase, for example to stop the events from reaching other listeners, because all events can be stopped by any listener at any node within the propagation path.

The registered event listeners must be limited to specific event types either in the capture phase or the bubbling phase. Additionally, they can be registered for all events of a certain type or limited to events of a certain type that originate from a specific namespace (see nokia.maps.dom.EventTarget#addListenerNS). In the latter case, the listener is notified only if the namespaceURI of the event is set to the desired namespace. This can be used to separate arbitrary application events from other events, such as standard W3C events.

For a more comprehensive description of how events are dispatched, please the W3C documentation DOM level 3 event flow.