The Page class is a special abstract interface, it must be used as a query for a document or a DOM node and will return an object that implements the Page interface and is bound to the supplied document or to the document of the supplied DOM node. Example:

 // Query page support for the document.
 var page = ovi.mapsapi.dom.Page(document);
 
 // Query page support for the document of a DOM node.
 var node = document.getElementById("foo");
 page = ovi.mapsapi.dom.Page( node );

The page interface itself offers access to the document. It supplies a large amount of helper methods and enables the ovi.mapsapi.dom aligned event handling for all DOM nodes attached to the document for which it's support is queried. Therefore, before casting a DOM node into an ovi.mapsapi.dom.EventTarget it is recommented to at least once query the page interface for this document.

Note: Unlike the ovi.mapsapi.dom.EventTarget this class will not modify any DOM node it is queried upon and it will only attach one property to the document to which it is bound with the name $jslPage. This means as well that you'll always have to query a document or DOM node for the object implementing the Page interface.

However, the query is very fast, except being done the first time, because the first time a corresponding object implementing the Page inteface must be created and bound to the document, which means that certain listeners must be registered with the document and some methods will be created internally. Every further cast to the Page interface will be no more then just returning this existing object.

Details

The dom package facilitates the cross browser event handling and simplifies the creation of custom events as well as that it supplies information about the browser, operating system and offers a set of helper methods.

The package persists out of the four main classes ovi.mapsapi.dom.Page, ovi.mapsapi.dom.Event, ovi.mapsapi.dom.EventTarget and ovi.mapsapi.dom.DataTransfer. The major class within the package is the the ovi.mapsapi.dom.Page class which offers the abstraction of native browser events and offers the most of the functionality of the package. The other classes are mostly helper classes. The package offers cross browser W3C standard compliant event handling including some de facto standards like touch and gesture events.

Which events are supported and what there meaning is, is documented within the different abstract pseudo event target classes:
* ovi.mapsapi.dom.TouchEventTarget
* ovi.mapsapi.dom.DragEventTarget
* ovi.mapsapi.dom.MouseEventTarget
* ovi.mapsapi.dom.KeyboardEventTarget
* ovi.mapsapi.dom.FocusEventTarget

Note: These interfaces do not exist, they are for documentational purpose only and they will be used by classes to document which event the objects of this class support. However, it should be clear that because of the design of the event handling it is always possible that an object receives additional undocumented events.

Event handling

The event handling itself is very simple and mostly W3C compatible, but it must be activated for native DOM nodes before being used. The reason is to prevent collisions with other frameworks that might been used together with this API. To add the support for aligned events to a DOM node the ovi.mapsapi.dom.EventTarget interface must be applied upon this DOM node. This can be done by simply casting the DOM node into an ovi.mapsapi.dom.EventTarget, as the following example shows:

 // Create a few shortcuts.
 var Page = ovi.mapsapi.dom.Page,
     EventTarget = ovi.mapsapi.dom.EventTarget;

 // Query page support for the document. This is very important, but needs only 
 // to be done once. However, doing it multiple times will not harm.
 Page(document);

 // Attach EventTarget interface to the document to allow aligned events at the document.
 EventTarget(document);

 // Add a listener for the click event to the document and show an alert, 
 // if the document is clicked.
 document.addListener("click", function(evt) {
   alert( evt.type );
   
   // Unregister ourself, so that only once an alert is shown.
   document.removeListener("click", arguments.callee, false);
 }, false);

The most events are quite self explaining and the syntax to register or unregister listeners is simlar to the W3C standard methods addEventListener, removeEventListener and dispatchEvent, except that the aligned methods will not contain the "event" word, so they are called addListener, removeListener and dispatch.