Ovi Maps API Reference

Contents

Interface ovi.mapsapi.dom.Page

Interface Summary

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.

Method Summary
createElement (tagName, [style]) : Node This method will create a new DOM node and set the style properties to the given values.
getClientRect (node) : Object Calculates the absolute position of a node relative to the document.
static parseEvent (e) : ovi.mapsapi.dom.Event This method will parse the given native event and return a normalized event object for it.
setStyle (node, style) : Node This method will copy style properties into the style of the given DOM node.
update () : ovi.mapsapi.dom.Page This method will update all volatile properties of the page (e.g.
Field Summary
static Number DOUBLE_CLICK_TIME The time in milliseconds between two "click" events that raises a "dblclick" event.
static Number DOUBLE_TAP_TIME The time in milliseconds between two "tap" events that raises a "dbltap" event.
static Number LONGPRESS_INTERVAL The interval in milliseconds after which a "longpress" event will be fired if a button is pressed down.
static Number MOUSEMOVE_THRESHOLD The minimal delay in milliseconds after a mousemove event was fired in which no further mousemove events are fired.
static Number RESIZE_IDL_TIME The amount of milliseconds that a node must be not resized until the "resizeend" event is fired.
static Number RESIZE_SLEEP_MAX_TIME The maximum time in milliseconds to wait until the watched DOM nodes are checked again for a resize.
static Number RESIZE_SLEEP_MIN_TIME The minimal time in milliseconds to wait until the watched DOM nodes are checked again after a resize started (so after the "resizestart" event) and as long as any node is being resized (so till the "resizeend" event).
Element body The reference to the BODY element of the document of this page.
static browser This static object reflects details of the current browser and user interface.
document document The reference to the document that is rendered into the windows and to which this instance of the page class is bound.
Number documentMode This property is zero unless the current browser is Microsoft Internet Explorer, in that case it contains the document mode in which the document of this page is rendered, possible values are 5 (quirks mode, IE 5 compatible), 7 (IE 6/7 standard compliant mode), 8 (IE 8 standard compliant mode) or 9 (IE 9 HTML 5 mode).
Element head The reference to the HEAD element of the document of this page.
Number height The height of the document in CSS pixels, shall be available in all browsers.
Element html The reference to the HTML element of the document of this page.
Number layoutHeight The layout height is the amount of space measured in CSS pixels into which the document is rendered, without scrollbars.
Number layoutWidth The layout width is the amount of space measured in CSS pixels into which the document is rendered, without scrollbars.
Number orientation The current orientation of the layout viewport (not of the document).
static platform This static object holds information about the current platform (operating system, mobile device, .
Boolean quirksMode True if the document is rendered in quirks mode; false if rendered in CSS compatibility mode.
Number scrollbarsHeight The height of a vertical scrollbar in device pixels.
Number scrollbarsWidth The width of a vertical scrollbar in device pixels.
Number viewportHeight The viewport height is the amount of space measured in device pixels that is available to render the layout.
Number viewportWidth The viewport width is the amount of space measured in device pixels that is available to render the layout.
Number width The width of the document in CSS pixels, this property is only valid for WebKit based browsers like Safari and Chrome, if the width of the document can't be detected the value stays null.
window window The reference to the window in which the document is rendered.
Method Detail
createElement (tagName, [style]) : Node
This method will create a new DOM node and set the style properties to the given values.
 var page = ovi.mapsapi.dom.Page(document);
 var node = page.createElement("DIV", {
   backgroundColor: "rgb(255,0,0)",
   width: "200px",
   height: "200px"
 });
It is as well possible to create a node with specific attributes and style:
 var page = ovi.mapsapi.dom.Page(document);
 var node = page.createElement({
   tagName: "CANVAS",
   width: 200,
   height: 200,
   style: {
     position: "absolute",
     top: "0px",
     left: "0px",
     width: "200px",
     height: "200px"
   }
 });
Parameters:
{String | Object} tagName The tag name of the DOM node to be created or an object where the key tagName contains the tag name of the DOM node to be created and other keys reflect other properties of the node. The property style will be used to declare the style sheet, however, if the additional style parameter is as well supplied this will overwrite an style being defined within the supplied object.
{Object} [style]: The style properties to be set in the node.
Returns:
{Node} The node.
getClientRect (node) : Object
Calculates the absolute position of a node relative to the document. The returned value can be compared with the pageX and pageY property of mouse events.
Parameters:
{Node} node The DOM node for which the document page position should be returned.
Returns:
{Object} The position of the node within the document (left, top, right, bottom, width and height properties for the client bounds) or null if the detection failed or the given node is no valid DOM node.
static parseEvent (e) : ovi.mapsapi.dom.Event
This method will parse the given native event and return a normalized event object for it.
Parameters:
{Object} e The native event object of the browser.
Returns:
{ovi.mapsapi.dom.Event} A normalized DOM level 3 event object.
setStyle (node, style) : Node
This method will copy style properties into the style of the given DOM node.
 var page = ovi.mapsapi.dom.Page(document);
 var node = document.createElement("DIV");
 page.setStyle(node, {
   backgroundColor: "rgb(255,0,0)",
   width: "200px",
   height: "200px"
 });
Note that the above example could have been done more efficient by directly using the createElement method from the page interface.
Parameters:
{Node} node The DOM node for which the style properties should be set.
{Object} style The style properties to be set in the node.
Returns:
{Node} The node.
update () : ovi.mapsapi.dom.Page
This method will update all volatile properties of the page (e.g., the document size).
Returns:
{ovi.mapsapi.dom.Page} Returns the page object itself (this).
Field Detail
static Number DOUBLE_CLICK_TIME
The time in milliseconds between two "click" events that raises a "dblclick" event. This property will only be used for browsers that do not fire native double click events or no double click events under specific circumstances (browser bugs), like e.g. Chrome won't fire a right mouse button double click event at all.
static Number DOUBLE_TAP_TIME
The time in milliseconds between two "tap" events that raises a "dbltap" event.
static Number LONGPRESS_INTERVAL
The interval in milliseconds after which a "longpress" event will be fired if a button is pressed down.
static Number MOUSEMOVE_THRESHOLD
The minimal delay in milliseconds after a mousemove event was fired in which no further mousemove events are fired.
static Number RESIZE_IDL_TIME
The amount of milliseconds that a node must be not resized until the "resizeend" event is fired.
static Number RESIZE_SLEEP_MAX_TIME
The maximum time in milliseconds to wait until the watched DOM nodes are checked again for a resize.
static Number RESIZE_SLEEP_MIN_TIME
The minimal time in milliseconds to wait until the watched DOM nodes are checked again after a resize started (so after the "resizestart" event) and as long as any node is being resized (so till the "resizeend" event).
Element body
The reference to the BODY element of the document of this page.
static browser
This static object reflects details of the current browser and user interface. Most of its fields hold boolean values. If they are set, the corresponding browser/interface has been detected. For example, to check if the current browser is from the Mozilla family, you can use the following code:

HINT: It's always better to look for the feature instead for the browser!
HINT: Do completely disable native drag and drop support, set the property "dnd" to false!
Examples:
if (ovi.mapsapi.dom.Page.browser.mozilla) {
    // code applicable to Mozilla here
} else {
    // Code for non-Mozilla browsers here
}
document document
The reference to the document that is rendered into the windows and to which this instance of the page class is bound.
Number documentMode
This property is zero unless the current browser is Microsoft Internet Explorer, in that case it contains the document mode in which the document of this page is rendered, possible values are 5 (quirks mode, IE 5 compatible), 7 (IE 6/7 standard compliant mode), 8 (IE 8 standard compliant mode) or 9 (IE 9 HTML 5 mode).
Element head
The reference to the HEAD element of the document of this page.
Number height
The height of the document in CSS pixels, shall be available in all browsers.
Element html
The reference to the HTML element of the document of this page.
Number layoutHeight
The layout height is the amount of space measured in CSS pixels into which the document is rendered, without scrollbars.
Number layoutWidth
The layout width is the amount of space measured in CSS pixels into which the document is rendered, without scrollbars.
Number orientation
The current orientation of the layout viewport (not of the document).
The rotation is in degrees clockwise, so a value of 0 means portrait mode with normal device screen, 90 degrees means landscape mode with the device screen turned clockwise by 90 degrees, 180 means portrait mode with the device screen turned around by 180 degrees clockwise and finally 270 degrees means the device screen is in landscape mode with the screen turned around by 270 degrees clockwise.
Note: These values differ from those reported natively (e.g., the iPhone), but they are easier to handle for developers as it's simply the clockwise rotation.
static platform
This static object holds information about the current platform (operating system, mobile device, ...). For example, to check if the operating system is Linux, you can use the following code:
HINT: It's always better to look for the feature instead for the browser!
Examples:
if (ovi.mapsapi.dom.Page.platform.linux) {
    // code applicable to Linux here
} else {
    // non-Linux code here
}
Boolean quirksMode
True if the document is rendered in quirks mode; false if rendered in CSS compatibility mode.
Number scrollbarsHeight
The height of a vertical scrollbar in device pixels.
Number scrollbarsWidth
The width of a vertical scrollbar in device pixels.
Number viewportHeight
The viewport height is the amount of space measured in device pixels that is available to render the layout.
Number viewportWidth
The viewport width is the amount of space measured in device pixels that is available to render the layout.
Number width
The width of the document in CSS pixels, this property is only valid for WebKit based browsers like Safari and Chrome, if the width of the document can't be detected the value stays null.
window window
The reference to the window in which the document is rendered.
Documentation generated on Fri Aug 19 2011 13:36:02 GMT+0200 (CEST).