Nokia Maps API Reference

Contents

Class nokia.maps.geo.Strip

Class Summary

This class represents an observable array that stores geographic coordinates in an optimized way and allows specialized operations on them.

The constructor for this class initializes a new instance of Strip.

new nokia.maps.geo.Strip (coords, mode)
Method Summary
add (coord, [idx]) This method adds a single element to the given Strip object.
addAll (coords, [idx, [mode]]) This method adds a collection of coordinates to the given Strip instance.
addAllAsync (coords, [idx, [mode, [callback]]]) This method adds a collection of coordinates to the given Strip instance asynchronously.
addObserver (callback, [context]) This mehtod register a new observer.
asArray () : Array[Number] This method retrieves all elements of the given strip object as an array of latitude, longitude, altitude.
static convertToArray ([coords, [mode]]) : Array[Number] This method converts an array of objects or numbers to an array containing latitude, longitude and altitude, depending on the specified conversion mode.
static fromObject (value) : nokia.maps.geo.Strip This method creates a new Strip instance on the basis of the received value.
get (idx) : nokia.maps.geo.Coordinate This method retrieves an strip element at the specified index.
getLatLng (idx, [count]) : Number[] This method retrieves latitudes and longitudes from strip elements, starting at the caller-specified index.
getLength () : Number This method retrieves the number of elements held in the given strip object.
remove (idx) This method removes a single element at a specified index in the strip.
removeObserver (callback, context) : nokia.maps.util.OObject This mehtod unregisters an observer.
set (idx, coord) This method sets a single object containing geo coordinates of a location at the specified index in the given strip object.
splice (idx, remove, [coords, [mode]]) This method splices a collection of coordinates into the given Strip instance.
Constructor Detail

This class represents an observable array that stores geographic coordinates in an optimized way and allows specialized operations on them.

The constructor for this class initializes a new instance of Strip.

new nokia.maps.geo.Strip(coords, mode)
Parameters:
{Number[] | nokia.maps.geo.Coordinate[]} coords Either an array of geographic coordinates following the pattern [lat, lng, alt, ..., lat, lng, alt] or an array of instances of nokia.maps.geo.Coordinate
{String} mode A string indicating how the array is to be interpreted, for details, please see nokia.maps.geo.Strip.convertToArray().
Method Detail
add (coord, [idx])
This method adds a single element to the given Strip object.
Parameters:
{nokia.maps.geo.Coordinate} coord An object representing an element to be added to the Strip
{Number} [idx]: An optional index at which the element is to be inserted
addAll (coords, [idx, [mode]])
This method adds a collection of coordinates to the given Strip instance.
Parameters:
{Array} coords A collection containing coordinates to be added to the Strip; it can be either an array of latitude and longitude values or an array of objects that can be converted to instances of nokia.maps.geo.Coordinate.
{Number} [idx]: The optional index at which the collection is to be inserted
{String} [mode]: The optional mode of how the given coordinate array should be interpreted (for details, please see nokia.maps.geo.Strip.convertToArray())
addAllAsync (coords, [idx, [mode, [callback]]])
This method adds a collection of coordinates to the given Strip instance asynchronously.
Parameters:
{Array} coords The collection of coordinates to be added to the Strip; it can be either an array of latitude and longitude values or an array of objects that can be converted to instances of nokia.maps.geo.Coordinate
{Number} [idx]: The optional index at which the collection is to be inserted
{String} [mode]: The optional mode of how the given coordinate array should be interpreted (for details please see nokia.maps.geo.Strip.convertToArray())
{Function} [callback]: The optional callback function to be called after when the operation is complete
addObserver (callback, [context])
This mehtod register a new observer.
Parameters:
{Function} callback A callback to be invoked (after the list has been modified) with following arguments:
  • (Strip) strip - the Strip instance itself
  • (String) idx - the start index of the change
  • (Number) inserted - the number of elements that have been inserted
  • (Array[Number]) removed - the coordinates that have been removed as an array of the form [lat, lng, alt, ..., lat, lng, alt]
{Object} [context]: null The context to use when the callback is invoked
asArray () : Array[Number]
This method retrieves all elements of the given strip object as an array of latitude, longitude, altitude. The array has the form [lat, lng, alt, ..., lat, lng, alt].
Returns:
{Array[Number]} An array of coordinate values (a copy of the given stip object's internal array)
static convertToArray ([coords, [mode]]) : Array[Number]
This method converts an array of objects or numbers to an array containing latitude, longitude and altitude, depending on the specified conversion mode. The array has the form [lat, lng, alt, ..., lat, lng, alt].
Parameters:
{Array} [coords]: An optional collection of geographic coordinates to be inserted into the Strip after the start index; this argument can be either an array of latitude and longitude values or an array of objects that can be converted to instances of nokia.maps.geo.Coordinate
{String} [mode]: An optional string indicating how the received array should be interpreted. The default value is "auto". The possible values are:
  • "auto" - if the array consists of numbers, it is interpreted as an array of the form [lat, lng, ..., lat, lng]; if the caller passes in an instance of Strip, the object's internal array of geographic points is used; otherwise, the method attempts to convert each element of the received array to instances of nokia.maps.geo.Coordinate, using the method nokia.maps.geo.Coordinate() Coord objects
  • "coords" - the method attempts to convert each element of the received array to instances of nokia.maps.geo.Coordinate, using the method nokia.maps.geo.Coordinate() Coord objects
  • "values lat lng alt" - the method interprets the received array as a array of values, where latitude, longitude and altitude are given in the order in which "lat", "lng" and "alt" appear in the mode string; "alt" is optional in the mode string; for example, "values lat lng alt" is interpreted to mean that the array has the format [lat, lng, alt, ..., lat, lng, alt]
  • "arrays lat lng alt" - the method interprets the received array as containing sub-arrays, one with latitude values, one with longitude values and one with altitude values; these sub-arrays are ordered to mirror the order in which "lat", "lng" and "alt" appear in the mode string; "alt" is optional; for example, "arrays lat lng alt" is interpreted to mean that the array has the format [[lat, lat, ...], [lng, lng, ...], [alt, alt, ...]]

Additionally, mode can be prefixed with the keyword "unsafe" to help avoids some time-consuming sanity checks that are not needed if the given set of coordinates comes a trusted source. If "unsafe" prefixes "auto" or "coords", nokia.maps.geo.Coordinate.fromObject() is not called. The objects are then directly interpreted as objects with the properties latitude, longitude and altitude (as in nokia.maps.geo.Coordinate). The fastest mode to use is "unsafe values lat lng alt".

Returns:
{Array[Number]} An array in the form [lat, lng, alt, ..., lat, lng, alt].
static fromObject (value) : nokia.maps.geo.Strip
This method creates a new Strip instance on the basis of the received value. If the caller provides an existing instance Strip, the same object is returned. If the caller provides an array, the array is converted to a Strip -- mode must be the first item in array (for details of mode, please see nokia.maps.geo.Strip.convertToArray()). When it receives any other type of value/object, it returns an empty Strip.
Parameters:
{Object} value An object or a value from which to create a Strip instance if possible
Returns:
{nokia.maps.geo.Strip} An instance of this class created on the basis of the object supplied by the caller
get (idx) : nokia.maps.geo.Coordinate
This method retrieves an strip element at the specified index.
Parameters:
{Number} idx The index from which the element should be retrieved
Returns:
{nokia.maps.geo.Coordinate} An object containing the geographic coordinates of a location
getLatLng (idx, [count]) : Number[]
This method retrieves latitudes and longitudes from strip elements, starting at the caller-specified index.
Parameters:
{Number} idx The index from which the coordinates should be retrieved.
{Number} [count]: 1 The number of elements whose coordinates are to be retrieved; if the value is negative, the returned coordinates are presented in reverse order
Returns:
{Number[]} An array of coordinates in the form [lat, lng, lat, lng, ...]
getLength () : Number
This method retrieves the number of elements held in the given strip object.
Returns:
{Number} The length of the stripi as a number of elements
remove (idx)
This method removes a single element at a specified index in the strip.
Parameters:
{Number} idx The index at which the element is to be removed
removeObserver (callback, context) : nokia.maps.util.OObject
This mehtod unregisters an observer.
Parameters:
{Function} callback The observer callback function to be removed
{Object} context The context for the callback
Returns:
{nokia.maps.util.OObject} A reference to this OObject instance
set (idx, coord)
This method sets a single object containing geo coordinates of a location at the specified index in the given strip object. A pre-existing element at the specified index is replaced. To extend the strip, the insertion index must be equal to the index of the last element plus one - assuming a strip of n elements, the index must be n+1. An attempt use an index greater than n+1 causes an an exception to be thrown.
Parameters:
{Number} idx The index at which the element is to be inserted; if a strip element already exists at that index, it is replaced
{nokia.maps.geo.Coordinate} coord An object representing a location defined in terms of latitude and longitude to be added to the strip
splice (idx, remove, [coords, [mode]])
This method splices a collection of coordinates into the given Strip instance.
Parameters:
{Number} idx The start index after which elements should be removed and/or the collection is to be inserted
{Number} remove A value indicating how many elements should be removed after the start index
{Array} [coords]: An optional collection of coordinates to be inserted into the Strip; it can be either be an array of latitude and longitude values or an array of objects that can be converted to instances of nokia.maps.geo.Coordinate
{String} [mode]: An optional string indicating how the received array should be interpreted; for details, please see nokia.maps.geo.Strip.convertToArray() regarding further details.
Documentation generated on Tue May 08 2012 10:23:36 GMT+0200 (CEST).