map

Extends dispatch.

---

po.map()

Constructs a new map with default settings.

map.center([x])

Sets or gets the location of the map center. If the argument x is specified, it sets the new map center, and returns this. If no arguments are specified, it returns the current map center.

map.centerRange([x])

Sets or gets the constraints on the map center. If the argument x is specified, it sets the new center range, and returns this. If no arguments are specified, it returns the current center range.

The constraints are defined as a two-element location array: the locations of the south-west and north-east corners of the visible region. If the center range is null, then no constraints are enforced on the center. The default center range is:

[{lat: -85.05112877980659, lon: -Infinity},
 {lat: +85.05112877980659, lon: +Infinity}]

The default behavior thus ensures that one row of tiles is visible at zoom level zero, with infinite wrapping of longitudes. The latitude range of [-85.0…, +85.0…] is based on the Spherical Mercator projection. Latitudes of -90 or less, and +90 or greater, are treated as unbounded.

The constraint enforces that some part of the map (as defined by the center range) is visible within the viewport. This visible region may be infinitely small, as when the map is pushed entirely off-screen. However, because the map is immediately off-screen, it is easy to pull back into view. This behavior also ensures that any visible location on the map can be zoomed in or out without changing its point on-screen.

map.zoom([x])

Sets or gets the map zoom level; a nonnegative number. If the argument x is specified, it sets the new map zoom level, and returns this. If no arguments are specified, it returns the current zoom level.

The loaded tiles’ zoom level (assuming the layer is not transformed) will be the rounded map zoom level. Thus, at zoom level 0.49, tiles at zoom level 0 will be loaded and magnified; at zoom level 0.51, tiles at zoom level 1 will be loaded and minified.

map.zoomRange([x])

Sets or gets the constraints on the map zoom level; a two-element array of nonnegative numbers representing the minimum and maximum (both inclusive) zoom levels. If the argument x is specified, it sets the new zoom range, and returns this. If no arguments are specified, it returns the current zoom range.

If the zoom range is null, then no constraints are enforced on the zoom level. The default zoom range is [1, 18], but may change in subsequent releases.

map.zoomBy(z[, x0[, l]])

Zooms the map by the specified zoom level delta z, and returns this. The new zoom level after this method returns is the old zoom level plus z.

Two optional arguments may be specified. The second argument x0 specifies a position in the map’s coordinate space. The location at the given position will be preserved after the zoom. For example, to zoom in on the location under the cursor, specify map.mouse(e), where e is a mouse event. The third argument l specifies the location at x0 explicitly; thus, this method may also be used to zoom and set the location at the given point simultaneously, which is faster than setting the zoom and map sequentially.

map.panBy(x)

Pans the map by the specified pixel delta; returns this. The argument x is a point with number attributes x and y corresponding to pixel delta in two dimensions. The delta is specified in screen pixels (and not the map’s coordinate space).

map.extent([x])

Sets or gets the extent of the map. If the argument x is specified, it sets the new extent, and returns this. If no arguments are specified, it returns the current extent.

The extent is defined as a two-element location array, similar to the center range: the locations of the south-west and north-east corners of the visible region. The current extent is computed as:

[map.pointLocation({x:      0, y: size.y}),
 map.pointLocation({x: size.x, y:      0})]

where size is the current map size.

If the aspect ratio of the specified extent does not match the aspect ratio of the current map size, then the extent is expanded to match the current aspect ratio; the extent is fully-visible after this method returns. Note that the zoom level may not be an integer after setting the extent.

map.angle([x])

Sets or gets the map rotation angle in radians; a number. If the argument x is specified, it sets the map rotation and returns this. If no arguments are specified, it returns the current rotation angle. The map center and zoom level are unaffected by the rotation.

map.tileSize([x])

Sets or gets the tile size, in pixels. If the argument x is specified, it sets the tile size and returns this. If no arguments are specified, it returns the current tile size. The tile size is represented as an object with x and y positive number attributes. The default tile size is {x: 256, y: 256}.

Note: currently the tile size must be set before any tiles are loaded, and may not be changed after tiles are loaded. Tiles may be reloaded using layer.reload, but changing tile size is not yet supported.

Structure

map.add(x)

Adds the given object x to the map, and returns this. The given object must have a method named map, which is passed this.

map.remove(x)

Removes the given object x from the map, and returns this. The given object must have a method named map, which is passed null.

map.container([x])

Sets or gets the map container element. If the argument x is specified, it sets the map container, and returns this. If no arguments are specified, it returns the current container. The map container must be either an SVG svg element or an SVG g element. The class attribute of the container element will be set to “map”.

Note: currently the container must be set before any objects are added to the map, and may not be changed after objects are added. This restriction may be removed in a future release.

map.size([x])

Sets or gets the map size. If the argument x is specified, it sets the map size, and returns this. If no arguments are specified, it returns the current container. The map size is represented as an object with x and y positive number attributes.

The default map size is null, which causes the map to infer its size from the bounds of the container. If the container is an SVG g element, the owner svg element is used to compute the inferred size. In addition, if the map size is set to null, the map listens to the window for resize events, updating the map size automatically. When the map size is null, calling this method with no arguments will return the inferred size of the map, rather than null.

map.resize()

Tells the map to recompute its inferred size from its container. This method is not normally needed, but can be useful if the container size changes for reasons other than a window resize event, such as when the DOM is mutated.

Events

Maps use the dispatch mechanism to notify interested parties of events. Maps currently support two types of events: “move” and “resize”. The move event is dispatched whenever the map center or zoom level changes. The resize event is dispatched whenever the map size changes. Listeners that depend on the visible region should typically listen for both move and resize events, while static overlays (such as the compass control) only need to listen for resize events. These events currently have no additional metadata describing the event, though that additional descriptive information may be added in a future release.

map.mouse(e)

Returns the position of the mouse, as determined from the given mouse event e, in the map’s coordinate space. The returned position is an object with x and y number attributes. Typically, this method returns the pageX and pageY attributes of the event e, minus the top-left position of the map container; however, this method takes into consideration any custom transforms that have been applied to the map container through SVG.

This method is based on the W3C specification for getScreenCTM.

map.focusableParent()

Returns the focusable parent element containing the map. Typically this method returns the containing window; however, if the map is contained inside of an element with a tabindex attribute, that element is returned instead.

Projection

map.locationPoint(l)

Returns the pixel position of the given location l. The returned point is an object with x and y number attributes, denoting the position relative to the top-left corner of the map container. The position is in the map container’s coordinate space, compatible with map.mouse.

map.pointLocation(p)

Returns the location of the given pixel position p. The returned location is an object with lat and lon number attributes, and the given position p is relative to the top-left corner of the map container. The position is in the map container’s coordinate space, compatible with map.mouse.

map.locationCoordinate(l)

Returns the tile coordinate for the specified location l. Unlike the static version of this method, the tile coordinate’s zoom level will match the map’s rounded zoom level, Math.round(map.zoom()). The coordinate is represented as an object with zoom, column and row number attributes. The row and column values are typically fractional (floating point); use Math.floor to determine the tile at the given coordinate.

map.coordinateLocation(c)

Returns the location for the specified tile coordinate c. The location is represented as an object with lat and lon number attributes, and the coordinate is represented as an object with zoom, column and row number attributes.

map.pointCoordinate(x, p)

Returns the tile coordinate for the specified pixel position p, relative to the precomputed map center coordinate x. The tile center should be computed as map.locationCoordinate(map.center()). This method is typically not needed unless implementing a custom layer.

map.coordinatePoint(x, c)

Returns the pixel position for the specified tile coordinate c, relative to the precomputed map center coordinate x. The tile center should be computed as map.locationCoordinate(map.center()). This method is typically not needed unless implementing a custom layer.

po.map.locationCoordinate(l)

Returns the tile coordinate for the specified location l. The returned tile coordinate’s zoom level is zero. The location is represented as an object with lat and lon number attributes, and the coordinate is represented as an object with zoom, column and row number attributes.

po.map.coordinateLocation(c)

Returns the location for the specified tile coordinate c. The location is represented as an object with lat and lon number attributes, and the coordinate is represented as an object with zoom, column and row number attributes.