OpenLayers.Map

Instances of OpenLayers.Map are interactive maps embedded in a web page.  Create a new map with the OpenLayers.Map constructor.

On their own maps do not provide much functionality.  To extend a map it’s necessary to add controls (OpenLayers.Control) and layers (OpenLayers.Layer) to the map.

Summary
OpenLayers.MapInstances of OpenLayers.Map are interactive maps embedded in a web page.
Constants
Z_INDEX_BASE{Object} Base z-indexes for different classes of thing
Properties
id{String} Unique identifier for the map
fractionalZoom{Boolean} For a base layer that supports it, allow the map resolution to be set to a value between one of the values in the resolutions array.
dragging{Boolean} The map is currently being dragged.
size{OpenLayers.Size} Size of the main div (this.div)
viewPortDiv{HTMLDivElement} The element that represents the map viewport
layerContainerOrigin{OpenLayers.LonLat} The lonlat at which the later container was re-initialized (on-zoom)
layerContainerDiv{HTMLDivElement} The element that contains the layers.
popups{Array(OpenLayers.Popup)} List of popups associated with the map
center{OpenLayers.LonLat} The current center of the map
resolution{Float} The resolution of the map.
zoom{Integer} The current zoom level of the map
panRatio{Float} The ratio of the current extent within which panning will tween.
panTween{OpenLayers.Tween} Animated panning tween object, see panTo()
panDuration{Integer} The number of steps to be passed to the OpenLayers.Tween.start() method when the map is panned.
zoomTween{OpenLayers.Tween} Animated zooming tween object, see zoomTo()
zoomDuration{Integer} The number of steps to be passed to the OpenLayers.Tween.start() method when the map is zoomed.
paddingForPopups{OpenLayers.Bounds} Outside margin of the popup.
layerContainerOriginPx{Object} Cached object representing the layer container origin (in pixels).
minPx{Object} An object with a ‘x’ and ‘y’ values that is the lower left of maxExtent in viewport pixel space.
maxPx{Object} An object with a ‘x’ and ‘y’ values that is the top right of maxExtent in viewport pixel space.
Functions
OpenLayers.MapConstructor for a new OpenLayers.Map instance.
unloadDestroyFunction that is called to destroy the map on page unload.
updateSizeDestroyWhen the map is destroyed, we need to stop listening to updateSize events: this method stores the function we need to unregister in non-IE browsers.
setLayerZIndex
resetLayersZIndexReset each layer’s z-index based on layer’s array index
addControlToMap
getCurrentSize{OpenLayers.Size} A new OpenLayers.Size object with the dimensions of the map div
calculateBounds
getCachedCenter{OpenLayers.LonLat}
moveByPxDrag the map by pixels.
adjustZoom
moveTo
centerLayerContainerThis function takes care to recenter the layerContainerDiv.
isValidZoomLevel
isValidLonLat
getLonLatFromViewPortPx
getZoomTargetCenter
getGeodesicPixelSize
getLonLatFromLayerPx
applyTransformApplies the given transform to the layerContainerDiv.
Constants
TILE_WIDTH{Integer} 256 Default tile width (unless otherwise specified)
TILE_HEIGHT{Integer} 256 Default tile height (unless otherwise specified)

Constants

Z_INDEX_BASE

{Object} Base z-indexes for different classes of thing

Properties

id

{String} Unique identifier for the map

fractionalZoom

{Boolean} For a base layer that supports it, allow the map resolution to be set to a value between one of the values in the resolutions array.  Default is false.

When fractionalZoom is set to true, it is possible to zoom to an arbitrary extent.  This requires a base layer from a source that supports requests for arbitrary extents (i.e. not cached tiles on a regular lattice).  This means that fractionalZoom will not work with commercial layers (Google, Yahoo, VE), layers using TileCache, or any other pre-cached data sources.

If you are using fractionalZoom, then you should also use <getResolutionForZoom> instead of layer.resolutions[zoom] as the former works for non-integer zoom levels.

dragging

{Boolean} The map is currently being dragged.

size

{OpenLayers.Size} Size of the main div (this.div)

viewPortDiv

{HTMLDivElement} The element that represents the map viewport

layerContainerOrigin

{OpenLayers.LonLat} The lonlat at which the later container was re-initialized (on-zoom)

layerContainerDiv

{HTMLDivElement} The element that contains the layers.

popups

{Array(OpenLayers.Popup)} List of popups associated with the map

center

{OpenLayers.LonLat} The current center of the map

resolution

{Float} The resolution of the map.

zoom

{Integer} The current zoom level of the map

panRatio

{Float} The ratio of the current extent within which panning will tween.

panTween

{OpenLayers.Tween} Animated panning tween object, see panTo()

panDuration

{Integer} The number of steps to be passed to the OpenLayers.Tween.start() method when the map is panned.  Default is 50.

zoomTween

{OpenLayers.Tween} Animated zooming tween object, see zoomTo()

zoomDuration

{Integer} The number of steps to be passed to the OpenLayers.Tween.start() method when the map is zoomed.  Default is 20.

paddingForPopups

{OpenLayers.Bounds} Outside margin of the popup.  Used to prevent the popup from getting too close to the map border.

layerContainerOriginPx

{Object} Cached object representing the layer container origin (in pixels).

minPx

{Object} An object with a ‘x’ and ‘y’ values that is the lower left of maxExtent in viewport pixel space.  Used to verify in moveByPx that the new location we’re moving to is valid.  It is also used in the getLonLatFromViewPortPx function of Layer.

maxPx

{Object} An object with a ‘x’ and ‘y’ values that is the top right of maxExtent in viewport pixel space.  Used to verify in moveByPx that the new location we’re moving to is valid.

Functions

OpenLayers.Map

Constructor for a new OpenLayers.Map instance.  There are two possible ways to call the map constructor.  See the examples below.

Parameters

div{DOMElement|String} The element or id of an element in your page that will contain the map.  May be omitted if the <div> option is provided or if you intend to call the <render> method later.
options{Object} Optional object with properties to tag onto the map.

Valid options (in addition to the listed API properties)

center{<OpenLayers.LonLat>|Array} The default initial center of the map.  If provided as array, the first value is the x coordinate, and the 2nd value is the y coordinate.  Only specify if <layers> is provided.  Note that if an ArgParser/Permalink control is present, and the querystring contains coordinates, center will be set by that, and this option will be ignored.
zoom{Number} The initial zoom level for the map.  Only specify if <layers> is provided.  Note that if an ArgParser/Permalink control is present, and the querystring contains a zoom level, zoom will be set by that, and this option will be ignored.
extent{<OpenLayers.Bounds>|Array} The initial extent of the map.  If provided as an array, the array should consist of four values (left, bottom, right, top).  Only specify if center and zoom are not provided.

Examples

// create a map with default options in an element with the id "map1"
var map = new OpenLayers.Map("map1");

// create a map with non-default options in an element with id "map2"
var options = {
    projection: "EPSG:3857",
    maxExtent: new OpenLayers.Bounds(-200000, -200000, 200000, 200000),
    center: new OpenLayers.LonLat(-12356463.476333, 5621521.4854095)
};
var map = new OpenLayers.Map("map2", options);

// map with non-default options - same as above but with a single argument,
// a restricted extent, and using arrays for bounds and center
var map = new OpenLayers.Map({
    div: "map_id",
    projection: "EPSG:3857",
    maxExtent: [-18924313.432222, -15538711.094146, 18924313.432222, 15538711.094146],
    restrictedExtent: [-13358338.893333, -9608371.5085962, 13358338.893333, 9608371.5085962],
    center: [-12356463.476333, 5621521.4854095]
});

// create a map without a reference to a container - call render later
var map = new OpenLayers.Map({
    projection: "EPSG:3857",
    maxExtent: new OpenLayers.Bounds(-200000, -200000, 200000, 200000)
});

unloadDestroy

Function that is called to destroy the map on page unload. stored here so that if map is manually destroyed, we can unregister this.

updateSizeDestroy

When the map is destroyed, we need to stop listening to updateSize events: this method stores the function we need to unregister in non-IE browsers.

setLayerZIndex

setLayerZIndex: function (layer,
zIdx)

Parameters

layer{OpenLayers.Layer}
zIdx{int}

resetLayersZIndex

resetLayersZIndex: function()

Reset each layer’s z-index based on layer’s array index

addControlToMap

addControlToMap: function (control,
px)

Parameters

control{OpenLayers.Control}
px{OpenLayers.Pixel}

getCurrentSize

getCurrentSize: function()

Returns

{OpenLayers.Size} A new OpenLayers.Size object with the dimensions of the map div

calculateBounds

calculateBounds: function(center,
resolution)

Parameters

center{OpenLayers.LonLat} Default is this.getCenter()
resolution{float} Default is this.getResolution()

Returns

{OpenLayers.Bounds} A bounds based on resolution, center, and current mapsize.

getCachedCenter

getCachedCenter: function()

Returns

{OpenLayers.LonLat}

moveByPx

moveByPx: function(dx,
dy)

Drag the map by pixels.

Parameters

dx{Number}
dy{Number}

adjustZoom

adjustZoom: function(zoom)

Parameters

zoom{Number} The zoom level to adjust

Returns

{Integer} Adjusted zoom level that shows a map not wider than its <baseLayer>’s maxExtent.

moveTo

moveTo: function(lonlat,
zoom,
options)

Parameters

lonlat{OpenLayers.LonLat}
zoom{Integer}
options{Object}

centerLayerContainer

centerLayerContainer: function (lonlat)

This function takes care to recenter the layerContainerDiv.

Parameters

lonlat{OpenLayers.LonLat}

isValidZoomLevel

isValidZoomLevel: function(zoomLevel)

Parameters

zoomLevel{Integer}

Returns

{Boolean} Whether or not the zoom level passed in is non-null and within the min/max range of zoom levels.

isValidLonLat

isValidLonLat: function(lonlat)

Parameters

lonlat{OpenLayers.LonLat}

Returns

{Boolean} Whether or not the lonlat passed in is non-null and within the maxExtent bounds

getLonLatFromViewPortPx

getLonLatFromViewPortPx: function (viewPortPx)

Parameters

viewPortPx{<OpenLayers.Pixel>|Object} An OpenLayers.Pixel or an object with a ‘x’ and ‘y’ properties.

Returns

{OpenLayers.LonLat} An OpenLayers.LonLat which is the passed-in view port OpenLayers.Pixel, translated into lon/lat by the current base layer.

getZoomTargetCenter

getZoomTargetCenter: function (xy,
resolution)

Parameters

xy{OpenLayers.Pixel} The zoom origin pixel location on the screen
resolution{Float} The resolution we want to get the center for

Returns

{OpenLayers.LonLat} The location of the map center after the transformation described by the origin xy and the target resolution.

getGeodesicPixelSize

getGeodesicPixelSize: function(px)

Parameters

px{OpenLayers.Pixel} The pixel to get the geodesic length for.  If not provided, the center pixel of the map viewport will be used.

Returns

{OpenLayers.Size} The geodesic size of the pixel in kilometers.

getLonLatFromLayerPx

getLonLatFromLayerPx: function (px)

Parameters

px{OpenLayers.Pixel}

Returns

{OpenLayers.LonLat}

applyTransform

applyTransform: function(x,
y,
scale)

Applies the given transform to the layerContainerDiv.  This method has a 2-stage fallback from translate3d/scale3d via translate/scale to plain style.left/style.top, in which case no scaling is supported.

Parameters

x{Number} x parameter for the translation.  Defaults to the x value of the map’s layerContainerOriginPx
y{Number} y parameter for the translation.  Defaults to the y value of the map’s layerContainerOriginPx
scale{Number} scale.  Defaults to 1 if not provided.

Constants

TILE_WIDTH

{Integer} 256 Default tile width (unless otherwise specified)

TILE_HEIGHT

{Integer} 256 Default tile height (unless otherwise specified)

Instances of this class represent a width/height pair
This class represents a longitude and latitude pair
A popup is a small div that can opened and closed on the map.
Instances of this class represent bounding boxes.
setLayerZIndex: function (layer,
zIdx)
resetLayersZIndex: function()
Reset each layer’s z-index based on layer’s array index
addControlToMap: function (control,
px)
getCurrentSize: function()
{OpenLayers.Size} A new OpenLayers.Size object with the dimensions of the map div
calculateBounds: function(center,
resolution)
getCachedCenter: function()
{OpenLayers.LonLat}
moveByPx: function(dx,
dy)
Drag the map by pixels.
adjustZoom: function(zoom)
moveTo: function(lonlat,
zoom,
options)
centerLayerContainer: function (lonlat)
This function takes care to recenter the layerContainerDiv.
isValidZoomLevel: function(zoomLevel)
isValidLonLat: function(lonlat)
getLonLatFromViewPortPx: function (viewPortPx)
getZoomTargetCenter: function (xy,
resolution)
getGeodesicPixelSize: function(px)
getLonLatFromLayerPx: function (px)
applyTransform: function(x,
y,
scale)
Applies the given transform to the layerContainerDiv.
{HTMLDivElement} The element that contains the layers.
Constructor for a new OpenLayers.Map instance.
Controls affect the display or behavior of the map.
{OpenLayers.LonLat} The current center of the map
{Integer} The current zoom level of the map
This class represents a screen coordinate, in x and y coordinates
{Object} Cached object representing the layer container origin (in pixels).
Close