Class deCarta.Mobile.Map

The Map Class provides the necessary objects for a mobile online mapping application: it provides the map display and interaction. In its simplest form, Map objects provide a draggable map to the end user.

Class Summary
Constructor Attributes	Constructor Name and Description
	deCarta.Mobile.Map() The master map object.

Field Summary
Field Attributes	Field Name and Description
	options These are our default options.

Method Summary
Method Attributes	Method Name and Description
	addControl(control) Adds a deCarta.Mobile.MapControl object dynamically to the map
	addLayer(layer) Add a layer (tile set) to the map.
	addOverlay(overlay) Adds a Map Overlay (which may contain things like Circles, Polylines, Images, Pins, or Polygons) to the map {@see deCarta.Mobile.MapOverlay} {@see deCarta.Mobile.Circle} {@see deCarta.Mobile.Polyline} {@see deCarta.Mobile.Image} {@see deCarta.Mobile.Pin} {@see deCarta.Mobile.Polygon}
	animating() Returns a boolean value indicating if the map is currently animating
	centerOn(p, aniOptions) Centers the map on a specific location.
	getCenter() Returns the map's center position (deCarta.Mobile.Position)
	getHighestZ() Returns the highest css z-index used by the map and it's control and overlay layers.
	getRadius() Get the radius of the visible portion of the map (deCarta.Mobile.Radius)
	getVisibleRect() Returns an array of positions describing the visible area of the map.
	getZoom() Returns the current zoom level
	positionFromXY(x, y) Returns the deCarta.Mobile.Position that corresponds to x,y pixels from the viewport's top left
	removeLayer(layer) Removes a layer (tile set) from the map.
	removeOverlay(overlay) Removes a Map Overlay from the map.
	render(skippable) Redraws/renders the map with the current map settings (such as center, size and zoom values), as well as any updated layers or overlays.
	resize() Resize the map according to the new size of the containing element.
	setBoundary(bound) Sets the map boundary using a deCarta.Mobile.MapBoundary object, which creates a polygon map boundary.
	setDraggable(value) Sets the "draggable" attribute of the map
	zoomIn(d, fixedPos) Zooms in by a specified amount.
	zoomOut(d, fixedPos) Zooms out by a specified amount.
	zoomTo(z, fixedPos, instantaneous) Zooms to a specific zoom level

Class Detail

deCarta.Mobile.Map()

The master map object.

Parameters:

{object} options.

An object containing some (or all) of the following properties:

{HTMLDOMElement} id: DOM id of the map element *required*
(int) zoom: the starting zoom level, 20=maxzoom, 1=minzoom, default=3
deCarta.Mobile.Position center: Geographic position where the map is initially centered
(bool) easing: whether easing (smooth transitions between zoom levels) is enabled (default: true)
(bool) digitalZoom: true enables animated zoom between levels, optional, default=true
(bool) doubleTapZoom: true enables double click (tap) to zoom on position, optional, default=true
(array of deCarta.Mobile.MapLayer) layers: set of tile layers which will be initialized with the map
(array of deCarta.Mobile.MapControl) controls: set of map control objects to add to the map
onReady: a callback function which will be invoked when the map has loaded
(bool) draggable: If true allows map to be draggable. Optional, default="true"
(bool) limitFPS: If true, limits the frames-per-second to the maxFPS value. Optional, default=true
(int) maxFPS: Frames-per-second limit used if limitFPS=true. Optional, default=30
(int) controlZ: css Z-index for map controls. Each new control created will have an increasing css z-index starting from this value, allowing the application to insert page elements above or below the map controls
(bool) resizeable: If true, map is resizeable. Optional, default=true
(int) maxZoom: Maximum zoom level (tighest zoom), in the range 1 (min possible zoom) to 20 (max possible zoom). Optional, default=19.
(int) minZoom: Minimum zoom level (widest zoom), in the range 1 (min possible zoom) to 20 (max possible zoom). Optional, default=2.
skipResources: Set to true to skip loading of resources. Optional, default=false
boundaries: Defines the latitude and longitude limits for the map. The map will not display tiles when outside of these bounds. This object has these fields:
- (float) top: maximum latitude (up to 90), default: 87
- (float) bottom: minimum latitude (down to -90) , default: -87
- (float) left: leftmost longitude (-180 to 180), default: null
- (float) right: right longitude (-180 to 180), default: null
(bool) avoidEvents: If true, the Map does not respond to any input events. optional, default=false

Map Events: Your application can add listeners for specific map events. This can be done through the EventManager, or through proxy methods available on the Map object. For example, to install a callback for a zoomStart event, you can proceed in two ways: map.zoomstart(function(){//your code}); or deCarta.Mobile.EventManager.listen('zoomstart', function(){//your code});

Field Detail

options

These are our default options.

Method Detail

addControl(control)

Adds a deCarta.Mobile.MapControl object dynamically to the map

Parameters:
control: (deCarta.Mobile.MapControl)

addLayer(layer)

Add a layer (tile set) to the map. {@see deCarta.Mobile.MapLayer}

Parameters:
{deCarta.Mobile.MapLayer} layer: The MapLayer object you wish to add.

addOverlay(overlay)

Adds a Map Overlay (which may contain things like Circles, Polylines, Images, Pins, or Polygons) to the map {@see deCarta.Mobile.MapOverlay} {@see deCarta.Mobile.Circle} {@see deCarta.Mobile.Polyline} {@see deCarta.Mobile.Image} {@see deCarta.Mobile.Pin} {@see deCarta.Mobile.Polygon}

Parameters:
{deCarta.Mobile.MapOverlay} overlay: A Map Overlay to add

animating()

Returns a boolean value indicating if the map is currently animating

Returns:: (bool)

centerOn(p, aniOptions)

Centers the map on a specific location.

Parameters:
p: (deCarta.Mobile.Position) new center position
aniOptions: (Object) animation options (Optional. Defaults: {animated: true, duration 500})

getCenter()

Returns the map's center position (deCarta.Mobile.Position)

{int} getHighestZ()

Returns the highest css z-index used by the map and it's control and overlay layers. This allows the user to place page elements above the map and all its layers.

Returns:: {int} The highest z-index used by the map

getRadius()

Get the radius of the visible portion of the map (deCarta.Mobile.Radius)

getVisibleRect()

Returns an array of positions describing the visible area of the map.

getZoom()

Returns the current zoom level

positionFromXY(x, y)

Returns the deCarta.Mobile.Position that corresponds to x,y pixels from the viewport's top left

Parameters:
x
y

removeLayer(layer)

Removes a layer (tile set) from the map. {@see deCarta.Mobile.MapLayer}

Parameters:
layer

removeOverlay(overlay)

Removes a Map Overlay from the map. {@see deCarta.Mobile.MapOverlay}

Parameters:
{deCarta.Mobile.MapOverlay} overlay: A Map Overlay to remove

render(skippable)

Redraws/renders the map with the current map settings (such as center, size and zoom values), as well as any updated layers or overlays.

Parameters:
{boolean} skippable: : set to true if this is not a required render.

resize()

Resize the map according to the new size of the containing element. The map will adapt to fill 100% of the containing element when this function is called

setBoundary(bound)

Sets the map boundary using a deCarta.Mobile.MapBoundary object, which creates a polygon map boundary. The map will not display tiles outside of that polygon.

Parameters:
{deCarta.Mobile.MapBoundary} bound: An instance of a deCarta.Mobile.MapBoundary object that sets the map boundaries to an arbitrary polygon.

setDraggable(value)

Sets the "draggable" attribute of the map

Parameters:
{boolean} value: true

zoomIn(d, fixedPos)

Zooms in by a specified amount.

Parameters:
d: (float) delta to be added to the current zoom
fixedPos: (deCarta.Mobile.Position) a position which should maintain the same position in the viewport when the zoom is complete.

zoomOut(d, fixedPos)

Zooms out by a specified amount.

Parameters:
d: (float) delta to be subtracted from the current zoom
fixedPos: (deCarta.Mobile.Position) a position which should maintain the same position in the viewport when the zoom is complete.

zoomTo(z, fixedPos, instantaneous)

Zooms to a specific zoom level

Parameters:
{int} z: A valid zoom level (20=maxzoom, 1=minzoom)
{deCarta.Mobile.Position} fixedPos: A geographic position on the map which should maintain the same position in the viewport when the zoom is complete.
instantaneous

Classes

Class deCarta.Mobile.Map