nokia.maps.map.Display

Extends: nokia.maps.map.Container

Class Summary

This class displays a map and map objects such as markers, polylines, polygons, etc.

[ For full details, see nokia.maps.map.Display ]

Table 1. Property Summary
Properties

animation: {nokia.maps.util.OList}

This property specifies the currently supported map animation types.

availableBaseMapTypes: {nokia.maps.util.OList}

This property holds a list of all available nokia.maps.map.provider.Providers for base map types.

availableOverlays: {nokia.maps.util.OList}

This property holds a list of all available nokia.maps.map.provider.Providers for map overlays.

baseMapType: {nokia.maps.map.provider.Provider}

This property holds the current base map type to be used for display (such as satellite, terrain, hybrid).

bounceEnabled: {Boolean}

This property keeps a flag to signal if the bouncing effect is activated or not

center: {nokia.maps.geo.Coordinate}

This property contains the coordinates of the map center.

components: {nokia.maps.util.OList}

This property holds a list of all components that have been added to the map (to the given instance of nokia.maps.map.Display).

copyrightAlignment: {String}

This property specifies the position of the copyright information relative to the display.

readonly  copyrightHeight: {Number}

This property holds the height in pixels of the frame containing the text "Copyright by .

readonly  copyrightPosition: {nokia.maps.util.IPoint}

This property holds the position of the frame containing the label "Copyright by ".

readonly  copyrightWidth: {Number}

This property holds the width in pixels of the frame containing the text "Copyright by .

fixedCenter: {Boolean}

This property is a flag indicating if the center of the map should remain unchanged if the display is resized or padding changes.

heading: {Number}

This property holds the heading (bearing) of the map in degrees.

readonly  height: {Number}

This property holds the height of the map area in pixels.

margin: {Number}

This property holds the size of the supplemental rendering area.

maxHeading: {Number}

This property holds the maximum supported map heading (bearing).

maxTilt: {Number}

This property holds the maximum supported map tilt.

maxZoomLevel: {Number}

This property holds the maximum zoom level supported by the map (considering the current heading/tilting).

minHeading: {Number}

This property holds the minimum supported map heading (bearing).

minTilt: {Number}

This property holds the minimum supported map tilt.

minZoomLevel: {Number}

This property holds the minimum zoom level supported by the map (considering the current heading/tilting).

static  NORMAL: {nokia.maps.map.provider.TileProvider}

This type indicates a normal street map.

static  NORMAL_COMMUNITY: {nokia.maps.map.provider.TileProvider}

This type indicates a normal street map with community edits.

onError:

Function that is invoked when error condition occurs during baseMapType switching (for example no StreetLevel coverage exists for the given coordinate).

overlays: {nokia.maps.util.OList}

This property holds the list of all map overlays which are currently active for the map.

padding: {nokia.maps.util.IBox}

This property defines the padding in pixels for each side of the map display, thus setting a virtual viewport.

readonly  poweredByHeight: {Number}

This property holds the height in pixels of the frame containing the logo "Powered by .

readonly  poweredByPosition: {nokia.maps.util.IPoint}

This property holds the position of the frame containing the label "Powered by ".

readonly  poweredByWidth: {Number}

This property holds the width in pixels of the frame containing the logo "Powered by .

static  SATELLITE: {nokia.maps.map.provider.TileProvider}

This type indicates a hybrid satellite map with street information on top.

static  SATELLITE_COMMUNITY: {nokia.maps.map.provider.TileProvider}

This type indicates a hybrid satellite map with street information and community edits on top.

static  SATELLITE_PLAIN: {nokia.maps.map.provider.TileProvider}

This type indicates a satellite map.

static  SMART_PT: {nokia.maps.map.provider.TileProvider}

This type indicates a public transport map.

static  SMARTMAP: {nokia.maps.map.provider.TileProvider}

This type indicates a smart map.

static  TERRAIN: {nokia.maps.map.provider.TileProvider}

This type indicates a topographical map, where shading and color convey the shape of the terrain.

tilt: {Number}

This property holds the value of the map tilt in degrees.

static  TRAFFIC: {nokia.maps.map.provider.TileProvider}

This type indicates a traffic info map.

readonly  width: {Number}

This property holds the width of the map area in pixels.

zoomLevel: {Number}

This property holds the zoom level of the current view.

Directly Inherited Properties

Inherited from class nokia.maps.map.Container :

objects

Inherited from class nokia.maps.map.Object :

CHANGE_SPATIAL, CHANGE_VISUAL, CHANGE_ZINDEX, visibility, zIndex

Inherited from class nokia.maps.dom.EventTarget :

draggable, isEventTarget, parentNode, parentNodes

Inherited from class nokia.maps.map.provider.IData :

id

Table 2. Method Summary
Methods

addComponent (component) : {nokia.maps.map.component.Component}

This method adds a new component to the given Display instance.

blur ()

Removes keyboard focus from the display.

bounce (direction, atX, atY)

Method is responsible for map bouncing effect if one is supported with the current baseMapType.

destroy ()

This method destroys the map Display instance and frees the resources.

focus ()

Gives keyboard focus to the display.

geoToPixel (coord) : {nokia.maps.util.Point}

This method translates the received point object containing WGS84 coordinates into pixel coordinates relative to the top left corner of the map view.

getBestZoomLevel (bBoxes) : {Number}

This method computes the minimum zoom level at which each of the given bounding boxes fit into the display area.

getBoundingBox () : {nokia.maps.geo.BoundingBox}

This method calculates the outer bounding box of all map objects in the given Display instance, including all child containers.

getCam () : {nokia.maps.map.ICam}

This method returns the map camera

getComponentById (id) : {nokia.maps.map.component.Component}

This method returns the first component with the given identifier or null if no component with such an identifier is currently attached to the Display instance.

getObjectAt (x, y) : {nokia.maps.map.Object | undefined}

A method to obtain the topmost visible object at the given position relative to the viewport's origin.

getObjectsAt (x, y) : {nokia.maps.map.Object[]}

A method to obtain all objects that are visible at the given pixel position relative to the viewport's origin.

getObjectsWithin (left, top, right, bottom) : {nokia.maps.map.Object[]}

This method returns all objects found within a rectangle defined in terms of the pixel coordinates of its top left and bottom right corners.

getView () : {nokia.maps.map.IView}

This method returns the map view

getViewBounds () : {nokia.maps.geo.BoundingBox}

This method retrieves the outer bounding box of the map view (the smallest bounding box covering all visible points).

getZoom (x, y) : {Number}

This methode returns zoom level at provided screen position.

pan (startX, startY, endX, endY, animation)

This mehtod pans the map from the start point to the end point specified by the caller.

pixelToGeo (x, y) : {nokia.maps.geo.Coordinate}

This method translates a pixel position within the viewport to geo coordinates.

removeComponent (component) : {Number}

This method decrements the reference counter of the supplied component and if the counter has reached zero, the method removes the component from display.

setAttributes (animation, center, level, tilt, heading)

This method sets a number of properties of the map.

setBaseMapType (provider, animate, view)

This method sets base map type provider and optional transition between old and new provider can be involved.

setCam (cam, animation) : {nokia.maps.map.ICam}

This method sets the new camera for the map.

setCenter (coord, animation)

This method centers the map on the location specified by the caller.

setCopyrightAlignment (alignment)

This method sets the position of the copyright information.

setHeading (heading, animation)

This method sets the heading (bearing) of the map.

setPadding (padding1, padding2, padding3, padding4)

This method sets the property nokia.maps.map.Display#padding.

setTilt (tilt, animation)

This method sets the tilt of the map.

setView (view, animation) : {nokia.maps.map.IView}

This method sets the new view for the map.

setZoomLevel (level, animation, toX, toY)

This method sets the zoom level to the value specified by the caller.

update (delay, quick) : {nokia.maps.map.Display}

This method causes the current map view to be re-rendered.

zoomTo (boundingBox, keepCenter, animation)

This method zooms the map to ensure that the bounding box provided by the caller is visible in its entirety in the map viewport.

Directly Inherited Methods

Inherited from class nokia.maps.map.Container :

contains, getBoundingBox

Inherited from class nokia.maps.map.Object :

destroy, getBoundingBox, getDisplay, getParent, getProvider, getRoot, isVisible

Inherited from class nokia.maps.util.OObject :

addObserver, get, remove, removeObserver, set

Inherited from class nokia.maps.dom.EventTarget :

addListener, addListenerNS, addListeners, disableDrag, disableUserSelect, dispatch, enableDrag, enableUserSelect, hitTest, insertListener, insertListenerNS, removeAllListeners, removeListener, removeListenerNS

Inherited from class nokia.maps.map.provider.IData :

getInvalidations

Table 3. Event Summary
Events

basemapchangeend

This event is fired to mark the end of a change from one base map type to another (for example NORMAL to SATELLITE).

basemapchangestart

This event is fired to mark the start of a change from one base map type to another (for example NORMAL to SATELLITE).

displayready

This event is fired when the map ha been initialized and is ready to support interactive events, transitions and animations.

mapvalueexceeded

This event is fired if a received value exceeds the permitted range.

mapviewchange

This event is fired each time after the map has been rendered in response to a mapviewchange event (see nokia.maps.map.Display.MapViewChangeEvent).

mapviewchangeend

This event is fired when the map display has been rendered and all map view changes have been processed (see also nokia.maps.map.Display.MapViewChangeEvent).

mapviewchangestart

This event is fired immediately after the map view has been changed (see nokia.maps.map.Display.MapViewChangeEvent).

resize

This event is fired each time a change of the size of the display is detected.

resizeend

This event is fired when a resizing operation has finished (when no more changes to the size of the display have been detected for a certain amount of time).

resizestart

This event is fired immediately after the process of resizing the display has begun and then periodically until the process has completed, when resizeend is fired.

transitionend

This event is fired immediately after a map animation has finished or a transition from one base map type to another (in the latter case the event precedes nokia.maps.map.Display#basemapchangeend).

transitionstart

This event is fired immediately after a map animation starts or a transition from one base map type to another (in the latter case the event follows nokia.maps.map.Display#basemapchangestart).

Directly Inherited Events

Inherited from class nokia.maps.dom.MouseEventTarget :

click, dblclick, longpress, mousedown, mouseenter, mouseleave, mousemove, mouseout, mouseover, mouseup, mousewheel

Inherited from class nokia.maps.dom.DragEventTarget :

drag, dragend, dragenter, dragleave, dragover, dragstart, drop

Inherited from class nokia.maps.dom.TouchEventTarget :

dbltap, gesturechange, gestureend, gesturestart, longpress, tap, touchend, touchmove, touchstart

Class Description

This class displays a map, allowing multiple optional layers (containers) and objects such as markers, polylines, polygons, cirles, etc., to be added to it.

Constructor Details

nokia.maps.map.Display(container, props)

This method displays a map, allowing multiple containers and objects to be added to it.

Parameters:
 
container:
{HTMLElement}
 
The DOM node where the map should be displayed
props:
{nokia.maps.map.Display.Properties} [optional]
 
An object containing initialization properties

Property Details

animation: {nokia.maps.util.OList}

This property specifies the currently supported map animation types.

Animations depend on the platform and the rendering engine used, therefore this property must be checked at run-time to see if a specific animation is supported by the current rendering engine on the current platform.

In all cases, the following values for this property are supported:

  • "none" - no animation
  • "default" - default animation

Note 1: The default animation may be set to "none", which means that the rendering engine on the current platform does not support animation.

Note 2: If you specify an incorrect animation name, the animation type automatically reverts to "default".

 

availableBaseMapTypes: {nokia.maps.util.OList}

This property holds a list of all available nokia.maps.map.provider.Providers for base map types.

 

availableOverlays: {nokia.maps.util.OList}

This property holds a list of all available nokia.maps.map.provider.Providers for map overlays.

 

baseMapType: {nokia.maps.map.provider.Provider}

This property holds the current base map type to be used for display (such as satellite, terrain, hybrid). The given type must be one of the supported types. See nokia.maps.map.Display#availableBaseMapTypes

 

bounceEnabled: {Boolean}

This property keeps a flag to signal if the bouncing effect is activated or not

Default Value:
true

 

center: {nokia.maps.geo.Coordinate}

This property contains the coordinates of the map center.

 

components: {nokia.maps.util.OList}

This property holds a list of all components that have been added to the map (to the given instance of nokia.maps.map.Display).

 

copyrightAlignment: {String}

This property specifies the position of the copyright information relative to the display. The allowed values are:
  • topleft
  • topcenter
  • topright
  • middleleft
  • middlecenter
  • middleright
  • bottomleft
  • bottomcenter
  • bottomright
Default Value:
"bottomleft"

 

readonly  copyrightHeight: {Number}

This property holds the height in pixels of the frame containing the text "Copyright by ...".

 

readonly  copyrightPosition: {nokia.maps.util.IPoint}

This property holds the position of the frame containing the label "Copyright by ".

 

readonly  copyrightWidth: {Number}

This property holds the width in pixels of the frame containing the text "Copyright by ...".

 

fixedCenter: {Boolean}

This property is a flag indicating if the center of the map should remain unchanged if the display is resized or padding changes.

Default Value:
true

 

heading: {Number}

This property holds the heading (bearing) of the map in degrees. The property depends on the platform used and is only available if maxHeading is greater than 0.

 

readonly  height: {Number}

This property holds the height of the map area in pixels.

 

margin: {Number}

This property holds the size of the supplemental rendering area. The renderer must be prepared to allow rapid mouse panning within the displayed area extended on each side by the given margin (in pixels).

Default Value:
0

 

maxHeading: {Number}

This property holds the maximum supported map heading (bearing). You can obtain the maximum supported heading by invoking the method get() on an instance of Display, with the name of this property as the only argument. For example, if "myMap" is an instance of map.Display, then the code myMap.get("maxHeading") obtains the current value of maxHeading.

 

maxTilt: {Number}

This property holds the maximum supported map tilt. You can obtain the maximum supported tilt by invoking the method get() on an instance of Display, with the name of this property as the only argument. For example, if "myMap" is an instance of map.Display, then the code myMap.get("maxTilt") obtains the current value of maxTilt.

 

maxZoomLevel: {Number}

This property holds the maximum zoom level supported by the map (considering the current heading/tilting). You can obtain the maximum supported zoom level by invoking the method get() on an instance of Display, with the name of this property as the only argument. For example, if "myMap" is an instance of map.Display, then the code myMap.get("maxZoomLevel") obtains the current value of maxZoomLevel.

 

minHeading: {Number}

This property holds the minimum supported map heading (bearing). You can obtain the minimum supported heading by invoking the method get() on an instance of Display, with the name of this property as the only argument. For example, if "myMap" is an instance of map.Display, then the code myMap.get("minHeading") obtains the current value of minHeading.

 

minTilt: {Number}

This property holds the minimum supported map tilt. You can obtain the minimum supported tilt by invoking the method get() on an instance of Display, with the name of this property as the only argument. For example, if "myMap" is an instance of map.Display, then the code myMap.get("minTilt") obtains the current value of minTilt.

 

minZoomLevel: {Number}

This property holds the minimum zoom level supported by the map (considering the current heading/tilting). You can obtain the minimum supported zoom level by invoking the method get() on an instance of Display, with the name of this property as the only argument. For example, if "myMap" is an instance of map.Display, then the code myMap.get("minZoomLevel") obtains the current value of minZoomLevel.

 

static  NORMAL: {nokia.maps.map.provider.TileProvider}

This type indicates a normal street map.

 

static  NORMAL_COMMUNITY: {nokia.maps.map.provider.TileProvider}

This type indicates a normal street map with community edits.

 

onError:

Function that is invoked when error condition occurs during baseMapType switching (for example no StreetLevel coverage exists for the given coordinate). By default does nothing.

 

overlays: {nokia.maps.util.OList}

This property holds the list of all map overlays which are currently active for the map.

 

padding: {nokia.maps.util.IBox}

This property defines the padding in pixels for each side of the map display, thus setting a virtual viewport. The virtual viewport does not affect the placing or the size of the visible map in the DOM node, but defines an area which excludes strips along the edges of the map that contain the UI elements zoom bar, copyright and map-type selector (if these elements are displayed). The virtual viewport is taken into consideration when setting the map center, when obtaining the map view bounds and when zooming to a bounding box. Its other purpose is to help prevent objects from overlapping very close to the edges of the visible map.

The map viewport determined by padding is taken into account when setting the map center, which is the center of the virtual viewport, not of the visible map. Furthermore, the viewport is used by the following methods:

padding cannot be changed directly. Please use the methods nokia.maps.map.Display#setPadding or the inherited nokia.maps.util.OObject#set instead. For example, you can call the method set() as follows:

set("padding", aPadding);

 

readonly  poweredByHeight: {Number}

This property holds the height in pixels of the frame containing the logo "Powered by ...".

 

readonly  poweredByPosition: {nokia.maps.util.IPoint}

This property holds the position of the frame containing the label "Powered by ".

 

readonly  poweredByWidth: {Number}

This property holds the width in pixels of the frame containing the logo "Powered by ...".

 

static  SATELLITE: {nokia.maps.map.provider.TileProvider}

This type indicates a hybrid satellite map with street information on top.

 

static  SATELLITE_COMMUNITY: {nokia.maps.map.provider.TileProvider}

This type indicates a hybrid satellite map with street information and community edits on top.

 

static  SATELLITE_PLAIN: {nokia.maps.map.provider.TileProvider}

This type indicates a satellite map.

 

static  SMART_PT: {nokia.maps.map.provider.TileProvider}

This type indicates a public transport map. It is uses the smart map color scheme with additional public transport route lines on top. Availability of public transport information may vary.

 

static  SMARTMAP: {nokia.maps.map.provider.TileProvider}

This type indicates a smart map. It is similar to normal street map, but uses an optimized color set ready to show additional overlay information.

 

static  TERRAIN: {nokia.maps.map.provider.TileProvider}

This type indicates a topographical map, where shading and color convey the shape of the terrain.

 

tilt: {Number}

This property holds the value of the map tilt in degrees. The property is platform dependent and is available only if maxTilt is greater than 0.

 

static  TRAFFIC: {nokia.maps.map.provider.TileProvider}

This type indicates a traffic info map. Since version 2.5.3 it can be used as a base map. Availability of traffic information may vary.

 

readonly  width: {Number}

This property holds the width of the map area in pixels.

 

zoomLevel: {Number}

This property holds the zoom level of the current view.

Method Details

addComponent(component): {nokia.maps.map.component.Component}

This method adds a new component to the given Display instance. If a component with the same id already exists (has been added previously), the method returns that component after incrementing its reference counter (the method does not create/add multiple instances of the same component).

Parameters:
 
component:
{nokia.maps.map.component.Component}
 

A reference to the component to be added

Returns:
 
{nokia.maps.map.component.Component}
 
 
A reference to the newly added component or to the existing component with the same identifier

Example:

 var component = display.addComponent(new nokia.maps.map.component.zoom.DoubleClick());

 

blur()

Removes keyboard focus from the display.

Since:
2.5

 

bounce(direction, atX, atY)

Method is responsible for map bouncing effect if one is supported with the current baseMapType.

Parameters:
 
direction:
{Boolean} [optional]
 

if value is true map bounces in opposite direction

atX:
{Number} [optional]
 

screen X coordinate at which bounce effect takes place (defaults to screen center)

atY:
{Number} [optional]
 

screen Y coordinate at which bounce effect takes place (defaults to screen center)

 

destroy()

This method destroys the map Display instance and frees the resources. The method may take up to a minute to complete, but afterwards, all of Display's properties are set to null and its methods are bound to an empty function.

 

focus()

Gives keyboard focus to the display.

Since:
2.5

 

geoToPixel(coord): {nokia.maps.util.Point}

This method translates the received point object containing WGS84 coordinates into pixel coordinates relative to the top left corner of the map view. The coordinates of the top left corner of the map are (0,0).

Note that the result values outside the visible map area are likely to be very unreliable.

Parameters:
 
coord:
{nokia.maps.geo.Coordinate}
 

A point object containing WGS84 coordinates to be translated into a pixel position

Returns:
 
{nokia.maps.util.Point}
 
 
An object containing the x and y pixel coordinates relative to the top left corner of the current viewport

 

getBestZoomLevel(bBoxes): {Number}

This method computes the minimum zoom level at which each of the given bounding boxes fit into the display area.

Parameters:
 
bBoxes:
{nokia.maps.geo.BoundingBox[]}
 

A list of bounding boxes.

Returns:
 
{Number}
the computed zoom level

 

getBoundingBox(): {nokia.maps.geo.BoundingBox}

This method calculates the outer bounding box of all map objects in the given Display instance, including all child containers. If the display does not contain any objects or child containers, the method returns null. If the display contains only one object that has no geographical dimensions such as a nokia.maps.map.Marker or nokia.maps.map.StandardMarker, then the returned bounding box may have the size of zero.

Note that the method does not return the bounding box of the current viewport. For this purpose, please use the method nokia.maps.map.Display#getViewBounds.

Returns:
 
{nokia.maps.geo.BoundingBox}
 
 
The calculated geographic outer bounding box of all map objects in the display or null, if the display does not contain any map objects

 

getCam(): {nokia.maps.map.ICam}

This method returns the map camera

Returns:
 
{nokia.maps.map.ICam}
 

 

getComponentById(id): {nokia.maps.map.component.Component}

This method returns the first component with the given identifier or null if no component with such an identifier is currently attached to the Display instance.

Parameters:
 
id:
{String}
 

The identifier of the component to retrieve

Returns:
 
{nokia.maps.map.component.Component}
 
 
The first component from the list of components with the given identifier or null if no component with such an identifier is currently attached to the Display instance

 

getObjectAt(x, y): {nokia.maps.map.Object | undefined}

A method to obtain the topmost visible object at the given position relative to the viewport's origin.

Parameters:
 
x:
{Number}
 

The X coordinate of the pixel position

y:
{Number}
 

The Y coordinate of the pixel position

Returns:
 
{nokia.maps.map.Object | undefined}
 
 
the top most object found at the given position or undefined if no object has been found

 

getObjectsAt(x, y): {nokia.maps.map.Object[]}

A method to obtain all objects that are visible at the given pixel position relative to the viewport's origin. The list is sorted according to the drawing order of the objects. The top most object has an index of 0 in returned array.

Parameters:
 
x:
{Number}
 

The X-coordinate of the pixel position

y:
{Number}
 

The Y-coordinate of the pixel position

Returns:
 
{nokia.maps.map.Object[]}
 
 
the list of map objects found at the given pixel position

 

getObjectsWithin(left, top, right, bottom): {nokia.maps.map.Object[]}

This method returns all objects found within a rectangle defined in terms of the pixel coordinates of its top left and bottom right corners.

Parameters:
 
left:
{Number}
 

The left edge of the rectangle as a number of pixels relative to viewport origin

top:
{Number}
 

The top edge of the rectangle as a number of pixels relative to viewport origin

right:
{Number}
 

The right edge of the rectangle as a number of pixels relative to viewport origin

bottom:
{Number}
 

The bottom edge of the rectangle as a number of pixels relative to viewport origin

Returns:
 
{nokia.maps.map.Object[]}
 
 
A list of map objects found within the given rectangle

 

getView(): {nokia.maps.map.IView}

This method returns the map view

Returns:
 
{nokia.maps.map.IView}
 

 

getViewBounds(): {nokia.maps.geo.BoundingBox}

This method retrieves the outer bounding box of the map view (the smallest bounding box covering all visible points).

Returns:
 
{nokia.maps.geo.BoundingBox}
 
 
The outer bounding box of the map view.

 

getZoom(x, y): {Number}

This methode returns zoom level at provided screen position.

Parameters:
 
x:
{Number} [optional]
 

The x-component of the screen coordinate.

y:
{Number} [optional]
 

The y-component of the screen coordinate.

Returns:
 
{Number}
a zoom level at the given screen position

 

pan(startX, startY, endX, endY, animation)

This mehtod pans the map from the start point to the end point specified by the caller. Both points are defined in terms of screen coordinates. The effect is that the location under the end point moves to the screen coordinates given by the start point. This operation may use a platform specific animation if indicated by the corresponding optional animation string.

Parameters:
 
startX:
{Number}
 

The x-position of the pixel relative to the top-left corner of the current view, indicating the x-coordinate of the point from which to to start panning

startY:
{Number}
 

The y-position of the pixel relative to the top-left corner of the current view, indicating the y-coordinate of the point from which to start panning

endX:
{Number}
 

The x-position of the pixel relative to the top-left corner of the current view, indicating the x-coordinate of the point to which to pan

endY:
{Number}
 

The y-position of the pixel relative to the top-left corner of the current view, indicating the y-coordinates of the point to which to pan

animation:
{String} [optional]
 

The animation to be used while modifying the view, must be a value from the list of animation types nokia.maps.map.Display#animation

 

pixelToGeo(x, y): {nokia.maps.geo.Coordinate}

This method translates a pixel position within the viewport to geo coordinates. The pixel position is relative to the top left corner of the viewport, (0,0), which is also the top left corner of the visible map. Note: Result values outside the visible map area are likely to be very unreliable.

Parameters:
 
x:
{Number}
 

The x-coordinate of the pixel position to be translated into longitude.

y:
{Number}
 

The y-coordinate of the pixel position to be translated into latitude.

Returns:
 
{nokia.maps.geo.Coordinate}
 
 
A point object containing the WGS84 coordinates of the caller-supplied pixel position.

 

removeComponent(component): {Number}

This method decrements the reference counter of the supplied component and if the counter has reached zero, the method removes the component from display.

Parameters:
 
component:
{nokia.maps.map.component.Component}
 

A reference to the component to be removed.

Returns:
 
{Number}
The value of the reference counter of the component after the remove call (the element is not removed if this value is greater than zero)

Example:

 		display.removeComponent(display.getComponentById("zoom.DoubleClick"));

 

setAttributes(animation, center, level, tilt, heading)

This method sets a number of properties of the map. The properties include animation, map center, zoom level, map tilt, and map bearing. You must provide actual values only for those properties you wish to change, and undefined for those that should not be altered.

Parameters:
 
animation:
{String}
 

The animation to be used while modifying the map attributes; must be a value from the list of animation types nokia.maps.map.Display#animation

center:
{nokia.maps.geo.Coordinate}
 

The new map center given as an object containing geographical coordinates

level:
{Number}
 

The new zoom level given as a value between nokia.maps.map.Display#minZoomLevel and nokia.maps.map.Display#maxZoomLevel

tilt:
{Number}
 

The new value of map tilt in degrees given as a value between nokia.maps.map.Display#minTilt and nokia.maps.map.Display#maxTilt

heading:
{Number}
 

The new map heading (bearing) given as a value between nokia.maps.map.Display#minHeading and nokia.maps.map.Display#maxHeading

 

setBaseMapType(provider, animate, view)

This method sets base map type provider and optional transition between old and new provider can be involved. There should be also defined view or camera for new base map type so together with animation there should be smooth transition between old base map type and old view/camera and new ones.

Parameters:
 
provider:
{nokia.maps.map.provider.Provider}
 

One of the available providers at nokia.maps.map.Display.availableBaseMapTypes

animate:
{String} [optional]
 

the animation to be used while modifying the view; must be a value from the list of animation types nokia.maps.map.Display#animation

view:
{nokia.maps.map.IView} [optional]
 

New view for new base map type

 

setCam(cam, animation): {nokia.maps.map.ICam}

This method sets the new camera for the map.

Parameters:
 
cam:
{nokia.maps.map.ICam}
 

New camera

animation:
{String} [optional]
 

The animation to be used while modifying the camera; must be a value from the list of animation types nokia.maps.map.Display#animation

Returns:
 
{nokia.maps.map.ICam}
 
 
Returns adjusted camera to closest available camera.

 

setCenter(coord, animation)

This method centers the map on the location specified by the caller. The method may use a platform specific animation if indicated by the corresponding optional animation string.

Parameters:
 
coord:
{nokia.maps.geo.Coordinate}
 

The location on which to center the map specified in terms of WGS84 coordinates

animation:
{String} [optional]
 

The animation to be used while modifying the map center; must be a value from the list of animation types nokia.maps.map.Display#animation

 

setCopyrightAlignment(alignment)

This method sets the position of the copyright information.

Parameters:
 
alignment:
{String}
 

The alignment relative to the map viewport, where the copyright is to be placed.

 

setHeading(heading, animation)

This method sets the heading (bearing) of the map. The method may use a platform-specific animation if this is indicated by the corresponding optional animation string.

Parameters:
 
heading:
{Number}
 

The new value of map heading (bearing) as a number of degrees; a value between nokia.maps.map.Display#minHeading and nokia.maps.map.Display#maxHeading

animation:
{String} [optional]
 

The animation to be used while modifying the heading; must be a value from the list of animation types nokia.maps.map.Display#animation.

 

setPadding(padding1, padding2, padding3, padding4)

This method sets the property nokia.maps.map.Display#padding. The method accepts up to four arguments which provide padding values in the following order: top, right, bottom, left.

The caller must supply at least one argument and optionally up to four as shown in these examples:

  • setPadding(topRightBottomLeft); - one argument/value, indicates identical padding all round
  • setPadding(topAndBottom, rightAndLeft); - the fist argument sets top and bottom padding, the second right and left padding
  • setPadding(top, rightAndLeft, bottom); - the second argument sets right and left padding, the first and third arguments set top and bottom padding, respectively
  • setPadding(top, right, bottom, left); - the first argument sets top padding, the second right padding, the third bottom padding, and the fourth left padding
Parameters:
 
padding1:
{Number}
 

Top padding in pixels; if this is the only argument provided, it is used also to set right, bottom and left padding (padding is identical all round); if the caller provides only two arguments, padding1 sets both top and bottom padding

padding2:
{Number} [optional]
 

Right padding in pixels; if padding4 (left padding) is not specified by the caller, this argument determines both right and left padding

padding3:
{Number} [optional]
 

Bottom padding in pixels; if not provided, its value is the same as that of padding1 (top padding)

padding4:
{Number} [optional]
 

Left padding in pixels; if not provided, its value is supplied by padding2 (right padding) or padding1 (top padding) if padding2 is not provided

 

setTilt(tilt, animation)

This method sets the tilt of the map. It may use a platform-specific animation if indicated by the corresponding optional animation string.

Parameters:
 
tilt:
{Number}
 

The new value of map tilt in degrees, a value between nokia.maps.map.Display#minTilt and nokia.maps.map.Display#maxTilt.

animation:
{String} [optional]
 

The animation to be used while modifying the tilt; must be a value from the list of animation types nokia.maps.map.Display#animation.

 

setView(view, animation): {nokia.maps.map.IView}

This method sets the new view for the map.

Parameters:
 
view:
{nokia.maps.map.IView}
 

New view

animation:
{String} [optional]
 

The animation to be used while modifying the view; must be a value from the list of animation types nokia.maps.map.Display#animation

Returns:
 
{nokia.maps.map.IView}
 
 
Returns adjusted view to closest available view.

 

setZoomLevel(level, animation, toX, toY)

This method sets the zoom level to the value specified by the caller. The caller must provide the zoom level and can also supply the animation type and the screen coordinates of a point on which to zoom in (via the arguments toX and toY). This point may correspond, for example, to the mouse position at the time when the user scrolls the mouse wheel to zoom in or out.

Parameters:
 
level:
{Number}
 

The new zoom level to be set, a value between nokia.maps.map.Display#minZoomLevel and nokia.maps.map.Display#maxZoomLevel

animation:
{String} [optional]
 

The animation to be used while modifying the zoom level; must be a value from the list of animation types nokia.maps.map.Display#animation

toX:
{Number} [optional]
 

The x-position of the pixel relative to the top-left corner of the current view to stay fixed

toY:
{Number} [optional]
 

The y-position of the pixel relative to the top-left corner of the current view to stay fixed

 

update(delay, quick): {nokia.maps.map.Display}

This method causes the current map view to be re-rendered.

Parameters:
 
delay:
{Number} [optional]
 

The maximum acceptable delay before the next frame is rendered as a number of milliseconds; if the value is zero or less, rendering occurs synchronously or at the earliest opportunity; if the argument is omitted or undefined, the system determines when to carry out re-rendering

quick:
{Boolean} [optional, default: false]
 

A Boolean to indicate whether full rendering (false) or only quick rendering (true is to be performed; quick rendering uses only cached data, while full rendering may request new data and cause new or modified objects to be rendered; the argument is ignored if delay is omitted or undefined

Returns:
 
{nokia.maps.map.Display}
 
 
A reference to the given instance of Display (this).

 

zoomTo(boundingBox, keepCenter, animation)

This method zooms the map to ensure that the bounding box provided by the caller is visible in its entirety in the map viewport. The caller has the option of retaining the current map center, which may cause the zoom to be adjusted so that the bounding box is visible while the map center remains unchanged. The method may use a platform specific animation if this is indicated by the corresponding optional animation string.

Parameters:
 
boundingBox:
{nokia.maps.geo.BoundingBox}
 

The bounding box that is to be visible in its entirety in the map viewport

keepCenter:
{Boolean}
 

A Boolean indicating whether to keep the map center unchanged (true) or if the view center may change (false);

animation:
{String} [optional]
 

The animation to be used; must be a value from the list of animation types nokia.maps.map.Display#animation.

Event Details

basemapchangeend

This event is fired to mark the end of a change from one base map type to another (for example NORMAL to SATELLITE). Until this event has been detected, the map should ignore calls to methods that alter the map view. See also nokia.maps.map.Display.TransitionEvent.

Event Handler Parameters:
 
event
{nokia.maps.map.Display.TransitionEvent}

 

basemapchangestart

This event is fired to mark the start of a change from one base map type to another (for example NORMAL to SATELLITE). After this event has been fired and until nokia.maps.map.Display#basemapchangeend has been detected, the map should ignore calls to methods that alter the map view. See also nokia.maps.map.Display.TransitionEvent.

Event Handler Parameters:
 
event
{nokia.maps.map.Display.TransitionEvent}

 

displayready

This event is fired when the map ha been initialized and is ready to support interactive events, transitions and animations. No code related to map view manipulation, such as calls to nokia.maps.map.Display#setZoomLevel, nokia.maps.map.Display#setCenter, nokia.maps.map.Display#setBaseMapType, etc., must be allowed to run (although components or markers can be added to the map and other operations that do not affect the map view can be performed). See also nokia.maps.map.Display.TransitionEvent.

Event Handler Parameters:
 
event
{nokia.maps.map.Display.TransitionEvent}

 

mapvalueexceeded

This event is fired if a received value exceeds the permitted range. (see nokia.maps.map.Display.MapValueExceededEvent).

Event Handler Parameters:
 
event
{nokia.maps.map.Display.MapValueExceededEvent}

 

mapviewchange

This event is fired each time after the map has been rendered in response to a mapviewchange event (see nokia.maps.map.Display.MapViewChangeEvent).

The data property of the event object provides information on all the changes that have been effected. (see nokia.maps.map.Display.MapViewChangeEvent#data).

Note that a large number of mapviewchange events can be fired within the space of a second, therefore it is advisable to avoid time-consuming operations within mapviewchange listeners.

Event Handler Parameters:
 
event
{nokia.maps.map.Display.MapViewChangeEvent}

 

mapviewchangeend

This event is fired when the map display has been rendered and all map view changes have been processed (see also nokia.maps.map.Display.MapViewChangeEvent). It indicates that you can safely execute more expensive operations to respond to a map view change (for example UI updates).

Event Handler Parameters:
 
event
{nokia.maps.map.Display.MapViewChangeEvent}

 

mapviewchangestart

This event is fired immediately after the map view has been changed (see nokia.maps.map.Display.MapViewChangeEvent). It is fired only for the first change of the map view after the rendering of the map display has been completed.

Event Handler Parameters:
 
event
{nokia.maps.map.Display.MapViewChangeEvent}

 

resize

This event is fired each time a change of the size of the display is detected. It is fired multiple times during a continuos resize operation (for example, if the display is being resized due to user input).

Note that resizing a map also triggers mapviewchange events.

Event Handler Parameters:
 
event
{nokia.maps.dom.Event}

 

resizeend

This event is fired when a resizing operation has finished (when no more changes to the size of the display have been detected for a certain amount of time).

Note that resizing a map also triggers mapviewchange events.

Event Handler Parameters:
 
event
{nokia.maps.dom.Event}

 

resizestart

This event is fired immediately after the process of resizing the display has begun and then periodically until the process has completed, when resizeend is fired.

Note that resizing a map also triggers mapviewchange events.

Event Handler Parameters:
 
event
{nokia.maps.dom.Event}

 

transitionend

This event is fired immediately after a map animation has finished or a transition from one base map type to another (in the latter case the event precedes nokia.maps.map.Display#basemapchangeend). Until this event has been detected, the map should ignore calls to methods that alter the map view. See also nokia.maps.map.Display.TransitionEvent.

Event Handler Parameters:
 
event
{nokia.maps.map.Display.TransitionEvent}

 

transitionstart

This event is fired immediately after a map animation starts or a transition from one base map type to another (in the latter case the event follows nokia.maps.map.Display#basemapchangestart). After this event was fired and until nokia.maps.map.Display#transitionend has been detected, the map should ignore calls to methods that alter the map view. See also nokia.maps.map.Display.TransitionEvent.

Event Handler Parameters:
 
event
{nokia.maps.map.Display.TransitionEvent}