Nokia Maps API Reference

Contents

Class nokia.maps.dom.EventTarget

Class Summary

This class implements the W3C DOM Level 3 interface EventTarget and extends it with a number of features. It can be used 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. 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.

MooTools compatibility notes

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.

Event flow in a nutshell

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.

Method Summary
addListener (type, callback, useCapture) : Object This method registers an event listener.
addListenerNS (namespaceURI, type, callback, useCapture) : nokia.maps.dom.EventTarget This method registers an event listener for events originating from a specific namespace.
addListeners (obj) Nonstandard method to register multiple event listeners.
static catchException (enable) This method enables exception catching in the event dispatcher to make it possible to ignore errors in event handlers or it disables exception catching in the event dispatcher for debugging purposes.
disableDrag () : nokia.maps.dom.EventTarget This method disables dragging of this event target, causing this event target not to receive dragstart, drag and dragend events.
disableUserSelect () : nokia.maps.dom.EventTarget This method prevents user selection of text and elements within the event target and prevents the magnifier on the iPhone or other similar mobile devices.
dispatch (evt) : Boolean This method dispatches an event.
static dispatchEvent (target, event, [dispatchPath]) : Boolean This method dispatches an event to the given event target.
enableDrag () : nokia.maps.dom.EventTarget This method enables dragging of this event target and disables the user selection, allowing this event target to receive dragstart, drag and dragend events.
enableUserSelect () : nokia.maps.dom.EventTarget This method allows the user to select text and elements within the event target and allows the magnifier on the iPhone or other similar mobile devices.
hitTest (pageX, pageY) : Boolean This method tests if the given x/y position relative to the document lies within the outer bounding box of the node corresponding to the given EventTarget object.
insertListener (type, callback, useCapture) : Object This method registers an event listener as the first listener in the listener chain.
insertListenerNS (namespaceURI, type, callback, useCapture) : nokia.maps.dom.EventTarget This method registers an event listener for events originating from a specific namespace as the first in the listener chain.
removeListener (type, listener, useCapture) : nokia.maps.dom.EventTarget This method removes an event listener.
removeListenerNS (namespaceURI, type, listener, useCapture) : nokia.maps.dom.EventTarget This method removes an event listener for events originating from a specific namespace.
Field Summary
Boolean draggable This property indicates if the given event target is draggable and may receive a dragstart, drag and dragend events (true); false otherwise.
Object eventListener This property is either undefined or holds a hash table that, for every event type, contains an array with the elements: [(listener, useCapture, namespaceURI)(listener, useCapture, namespaceURI)(…)]
Boolean isEventTarget This property indicates whether an object implements the nokia.maps.dom.EventTarget interface (true) or not (false).
nokia.maps.dom.EventTarget parentNode This property holds a reference to the parent node of the event target (if set).
Object parentNodes If this property is set it holds a hash table that contains the "namespaceURI" as key and the corresponding value is the parent node of the given event target.
Constructor Detail

This class implements the W3C DOM Level 3 interface EventTarget and extends it with a number of features.

new nokia.maps.dom.EventTarget(obj)
Parameters:
{Object} obj - the object to be extended with EventTarget functionality
Method Detail
addListener (type, callback, useCapture) : Object
This method registers an event listener. The caller can specify whether the listener is to be invoked in the capture phase only or only in the target and bubbling phases.
Parameters:
{String} type Specifies the event type for which the listener is to be registered
{Function} callback The function to be called if the event occurs; the function receives the following argument:
{Boolean} useCapture Indicates if the event listener is to be used for the capture phase only (true - the listerener is not invoked during the target and bubbling phases), or for target and bubbling phases (false)
Returns:
{Object} A reference to the given nokia.maps.dom.EventTarget object
addListenerNS (namespaceURI, type, callback, useCapture) : nokia.maps.dom.EventTarget
This method registers an event listener for events originating from a specific namespace. The caller can specify whether the listener is to be invoked in the capture phase only or only in the target and bubbling phases.
Parameters:
{String} namespaceURI Specifies the Event.namespaceURI associated with the event for which the user is registering
{String} type Specifies the event type for which the listener is to be registered
{Function} callback The function to be called if the event occurs; the function receives the following argument:
{Boolean} useCapture Indicates if the event listener is to be used for the capture phase only (true - the listerener is not invoked during the target and bubbling phases), or for target and bubbling phases (false)
Returns:
{nokia.maps.dom.EventTarget} A reference to the given event target object
addListeners (obj)
Nonstandard method to register multiple event listeners.
Parameters:
{Object} obj Hash map object where key is name of event and value is an array that contains callback function which should be called if the event occurs and boolean value that indicates if the event listener have to be used only for the capture phase.
		{
		"eventName": [callback, useCapture], 
		"eventName2": [callback, useCapture]
		}
		
static catchException (enable)
This method enables exception catching in the event dispatcher to make it possible to ignore errors in event handlers or it disables exception catching in the event dispatcher for debugging purposes. By default, exceptions are caught and written to the debug console.
Parameters:
{Boolean} enable true to enable exception catching; false otherwise
disableDrag () : nokia.maps.dom.EventTarget
This method disables dragging of this event target, causing this event target not to receive dragstart, drag and dragend events.

Note: Although enableDrag disable user selection, this method does not enable it.

Returns:
{nokia.maps.dom.EventTarget} The event target itself
disableUserSelect () : nokia.maps.dom.EventTarget
This method prevents user selection of text and elements within the event target and prevents the magnifier on the iPhone or other similar mobile devices.

Note: If you want to listen to the longpress event you should disable the user selection, because otherwise the iPhone and other mobile devices may show a magnifier, making it harder for you to interpret the longpress event.

Returns:
{nokia.maps.dom.EventTarget} The event target itself
dispatch (evt) : Boolean
This method dispatches an event.

The default implementation depends on whether the event has a namespaceURI property set or not. If this property is not set, the default implementation searches for a parent object using the property parentNode.

If the event has namespaceURI set, then the property parentNodes is checked, which contains a hash table with "namespaceURI" as key and the parent object for this namespace as value. If no match is found using the "namespaceURI" mechanism, then the parentNode property is checked as an alternative parent.

Parameters:
{nokia.maps.dom.Event | Object} evt An object representing the event to be dispatched; it is either an instance of nokia.maps.dom.Event or a native browser event.
Returns:
{Boolean} Indicates whether any of the listeners which handled the event called Event.preventDefault(). If Event.preventDefault() was called, the return value is false, otherwise it is true
static dispatchEvent (target, event, [dispatchPath]) : Boolean
This method dispatches an event to the given event target.

The default implementation depends on whether the event has a namespaceURI property set or not. If this property is not set, then the default implementation searches for a parent object using the property parentNode.

If the event has namespaceURI set, then the property parentNodes is checked, which contains a hash table with "namespaceURI" as key and the parent object for this namespace as value. If no match is found using the "namespaceURI" mechanism, then the parentNode property is checked as an alternative parent.

Parameters:
{nokia.maps.dom.EventTarget} target The event target to which the event is to be dispatched
{nokia.maps.dom.Event | Object} event The event to be dispatched; it is either a nokia.maps.dom.Event object or a native browser event
{Array} [dispatchPath]: List of elements like from nokia.maps.dom.EventTarget#getDispatchPath method
Returns:
{Boolean} Indicates whether any of the listeners which have handled the event called preventDefault; if preventDefault was called false is returned, otherwise true
enableDrag () : nokia.maps.dom.EventTarget
This method enables dragging of this event target and disables the user selection, allowing this event target to receive dragstart, drag and dragend events.
Returns:
{nokia.maps.dom.EventTarget} The event target itself
enableUserSelect () : nokia.maps.dom.EventTarget
This method allows the user to select text and elements within the event target and allows the magnifier on the iPhone or other similar mobile devices.
Returns:
{nokia.maps.dom.EventTarget} The event target itself
hitTest (pageX, pageY) : Boolean
This method tests if the given x/y position relative to the document lies within the outer bounding box of the node corresponding to the given EventTarget object.

If this object is not a DOM node, the method must be overloaded to ensure that mouseleave events are fired correctly.

Parameters:
{Number} pageX The horizontal position of the CSS pixel relative to the document to test.
{Number} pageY The vertical position of the CSS pixel relative to the document to test.
Returns:
{Boolean} true if the pixel lies within the node; false otherwise.
insertListener (type, callback, useCapture) : Object
This method registers an event listener as the first listener in the listener chain. The caller can specified whether the listener is to be registered for the capture phase only, or for target and bubbling phases.
Parameters:
{String} type Specifies the event type for which the listener is to be registered
{Function} callback The function to be called if the event occurs; the function receives the following argument:
{Boolean} useCapture Indicates if the event listener is to be used for the capture phase only (true - the listerener is not invoked during the target and bubbling phases), or for target and bubbling phases (false)
Returns:
{Object} A reference to the given nokia.maps.dom.EventTarget object
insertListenerNS (namespaceURI, type, callback, useCapture) : nokia.maps.dom.EventTarget
This method registers an event listener for events originating from a specific namespace as the first in the listener chain. The caller can specify whether the listener is to be invoked in the capture phase only or only in the target and bubbling phases.
Parameters:
{String} namespaceURI Specifies the Event.namespaceURI associated with the event for which the listener is to be registered
{String} type Specifies the event type for which the listener is to be registered
{Function} callback The function to be called if the event occurs; the function receives the following argument:
{Boolean} useCapture Indicates if the event listener is to be used for the capture phase only (true - the listerener is not invoked during the target and bubbling phases), or for target and bubbling phases (false)
Returns:
{nokia.maps.dom.EventTarget} A reference to the given event target object
removeListener (type, listener, useCapture) : nokia.maps.dom.EventTarget
This method removes an event listener.
Parameters:
{String} type Specifies the event type for which the listener was registered
{Function} listener The function to be removed
{Boolean} useCapture Indicates if the event listener was to be used for the capture phase only (true - the listener is not invoked during the target and bubbling phases), or for target and bubbling phases (false)
Returns:
{nokia.maps.dom.EventTarget} A reference to the given event target object
removeListenerNS (namespaceURI, type, listener, useCapture) : nokia.maps.dom.EventTarget
This method removes an event listener for events originating from a specific namespace.
Parameters:
{String} namespaceURI Specifies the Event.namespaceURI associated with the event for which the listener was registered
{String} type Specifies the event type for which the listener was registered
{Function} listener The function to be removed
{Boolean} useCapture Indicates if the event listener was to be used for the capture phase only (true - the listerener is not invoked during the target and bubbling phases), or for target and bubbling phases (false)
Returns:
{nokia.maps.dom.EventTarget} A reference to the given event target object
Field Detail
readonly Boolean draggable
This property indicates if the given event target is draggable and may receive a dragstart, drag and dragend events (true); false otherwise.
See:
nokia.maps.dom.EventTarget#enableDrag
nokia.maps.dom.EventTarget#disableDrag
Object eventListener
This property is either undefined or holds a hash table that, for every event type, contains an array with the elements: [(listener, useCapture, namespaceURI)(listener, useCapture, namespaceURI)(…)]
Deprecated:
see nokia.maps.dom.EventTarget#addListener, nokia.maps.dom.EventTarget#removeListener
readonly Boolean isEventTarget
This property indicates whether an object implements the nokia.maps.dom.EventTarget interface (true) or not (false).
This property holds a reference to the parent node of the event target (if set).
Object parentNodes
If this property is set it holds a hash table that contains the "namespaceURI" as key and the corresponding value is the parent node of the given event target.
Documentation generated on Wed Jun 27 2012 16:54:30 GMT+0200 (CEST).