This class defines the interface that must be supported by all events fired by a nokia.maps.map.Object or its derived classes, including the nokia.maps.map.Display class. These classes therefore implement this interface.

This class does not exist, but is documented here to record the event properties. All events are ultimately instances of the class nokia.maps.dom.Event and have the properties described here.

Before you continue reading, please ensure that you are familiar with the normal DOM event behavior as explained, for example, in the documentation for the class nokia.maps.dom.EventTarget or in the corresponding W3C DOM Event Level 3 specification

Dispatch

Map objects do not follow the event dispatch pattern common in the DOM tree, because unlike normal DOM objects, they can be part of multiple map containers and so it can have multiple parents. For this reason a nokia.maps.map.Object.Event has the property display to identify the nokia.maps.map.Display instance in which the event occurred to help establish the correct propagation path. For example, if the user clicks on a marker, a DOM click event with the map.Display instance as target is generated by the browser, but because the browser does not know about the markers (at least in some rendering engines), the display itself must find the map objects under the mouse cursor and modify the propagation path. Furthermore, it needs to apply the nokia.maps.map.Object.Event interface to that DOM event with the special properties display, displayX, displayY and displayObjects.

The nokia.maps.dom.EventTarget#dispatch() method does not generate the propagation path simply by following the property parentNode. Instead, it intercepts the dispatched events, allows the class nokia.maps.map.Display to find the target and build the propagation path so that map objects under the cursor are treated like normal DOM nodes.

Separate the data model from the view tree

The modified event dispatch model permits dispatch of visual events that are separate from the data model events. In addition to the hierarchy of map objects within instances of map.Display, a further document hierarchy for all map objects may be present and these objects can act as event targets. Therefore, a single data model can be maintained alongside different display-related view models. This is a strength of the event model. While remaining compatible with the DOM event system, it allows you to maintain a document data model alongside the visual representation, using the same objects for the view trees as well as for the data model.

In addition, events can flow over into the normal DOM tree so that you can capture events fired by the display as well as those fired within the normal DOM tree. For example, if a div element holds both the map and the UI components, you can use the same listeners to process map events and UI events.

Listener notes

Registering listeners on map objects is simlar to registering listeners on DOM nodes, using the class nokia.maps.dom.EventTarget. Note that the listeners are called for all events that reach the map objects. Therefore you must check the property display to see if an event is related to a display or a DOM event, and to which map.Display instance it belongs.