# 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.Map | Instances 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.Map | Constructor for a new OpenLayers.Map instance.
unloadDestroy | Function that is called to destroy the map on page unload.
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 |
resetLayersZIndex | Reset 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}
moveByPx | Drag the map by pixels.
adjustZoom |
moveTo |
centerLayerContainer | This function takes care to recenter the layerContainerDiv.
isValidZoomLevel |
isValidLonLat |
getLonLatFromViewPortPx |
getZoomTargetCenter |
getGeodesicPixelSize |
getLonLatFromLayerPx |
applyTransform | Applies 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