API Quick Links

Articles and Tutorials

GSMap

GSMap encapsuates functionality for map creation, management of map feature layers, and map navigation.

From Version 0.27 of the API constructor parameters are passed to GSMap as named values in an associative array:

 
 var params = {
   id: "map",
   centerX: 2530000,
   centerY: 5990000,
   width: 600,
   height: 400,
   zoomLevel: 3};
 var map = new GSMap(params);

Field Summary
boolean	centerOnDblClick           When true enables map recentering when double-clicking on map.
boolean	dragToPan           When true enables map panning by moving the mouse while holding down the left mouse button.
boolean	infoWindowEnabled           true if info window is enabled for this map.
boolean	mouseWheelZoomingEnabled           true if info window is enabled for this map.
boolean	scalebarEnabled           true if the scalebar is enabled for the map
<static>  <final> String	COMPACT_ZOOM_CONTROL           Constant for specifying a compact zoom control to be placed on the map
<static>  <final> String	MAP_CONTROL           Constant for specifying a pan control to be placed on the map
<static>  <final> intxb	MAX_HEIGHT           The maximum supported height in pixels for the map
<static>  <final> int	MAX_WIDTH           The maximum supported width in pixels for the map
<static>  <final> String	TEXT_ZOOM_CONTROL           Constant for specifying a text zoom control
<static>  <final> String	ZOOM_CONTROL           Constant for specifying a regular zoom control to be placed on the map

 

Constructor Summary

GSMap (params)             Constructs a new GSMap that is initialized with the properties provided in the params associative array.

 

Method Summary
GSControl	addControl(control)            Adds a control to the map
void	addFeature(feature)            A convenience function for adding a feature to the map without explicitly creating a layer first.
void	centerAndZoom(<GSPoint> coordinate, <int> zoomLevel, <Function> onCenter)            Centers the map on the provided coordinate at the given zoom level
void	centerAtCoordinate(<GSPoint> coordinate, <Function> onCenter, <boolean> suppressMessaging)            Centers the map on the specified coordinate
void	centerOnLayer(<String> name, <Function> onCenter)            Re-centers the map on the named layer.
void	centerOnNewZealand(<Function> onCenter)            Centers the map on the center of New Zealand, Nelson, and at such a scale that the full extent of the country is visible
void	clearLayers()            Removes all user-defined layers from the map
void	closeInfoWindow()            Close the info window if it is open
GSLayer	createLayer(<String> name)            Creates a new layer with the specified name
GSLayer	getLayer(<String> name)            Returns the named map layer
GSPoint	getMapCenter()            Returns the center point of the map as an NZMG coordinate
GSDimension	getSize()            Returns the size, in pixels, of this map
int	getZoomLevel()            Returns the current map zoom level
void	openInfoWindow(<GSPoint> coordinate, html)            Displays the info window at the given coordinate.
Object	panTo(<GSPoint> coordinate, onPan)            Pans the map to the specified coordinate.
void	removeControl(<GSControl> control)            Removes a control from the map
void	removeFeature(feature)            A convenience function for removing a feature that was added directly to the map
void	removeLayer(<String> name)            Removes a feature layer from the map
void	setBounds(bounds, <Function> onBoundsChanged)            Sets the map extents to those specified by the bounds object
void	setSize(<GSDimension> size, resizeable)            Sets the size in pixels of the map to be created.
void	zoom(<int> zoomLevel, <Function> onZoom)            Zooms to the specified zoom level

Field Detail

centerOnDblClick

boolean centerOnDblClick

When true enables map recentering when double-clicking on map. Defaults to true.

dragToPan

boolean dragToPan

When true enables map panning by moving the mouse while holding down the left mouse button. Defaults to true.

infoWindowEnabled

boolean infoWindowEnabled

true if info window is enabled for this map. Defaults to true

mouseWheelZoomingEnabled

boolean mouseWheelZoomingEnabled

true if info window is enabled for this map. Defaults to true

scalebarEnabled

boolean scalebarEnabled

true if the scalebar is enabled for the map

COMPACT_ZOOM_CONTROL

<static> <final> String COMPACT_ZOOM_CONTROL

Constant for specifying a compact zoom control to be placed on the map

 

See Also:

Constant Field Values

MAP_CONTROL

<static> <final> String MAP_CONTROL

Constant for specifying a pan control to be placed on the map

 

See Also:

Constant Field Values

MAX_HEIGHT

<static> <final> intxb MAX_HEIGHT

The maximum supported height in pixels for the map

 

See Also:

Constant Field Values

MAX_WIDTH

<static> <final> int MAX_WIDTH

The maximum supported width in pixels for the map

 

See Also:

Constant Field Values

TEXT_ZOOM_CONTROL

<static> <final> String TEXT_ZOOM_CONTROL

Constant for specifying a text zoom control

 

See Also:

Constant Field Values

ZOOM_CONTROL

<static> <final> String ZOOM_CONTROL

Constant for specifying a regular zoom control to be placed on the map

 

See Also:

Constant Field Values

Constructor Detail

GSMap

GSMap(params)

Constructs a new GSMap that is initialized with the properties provided in the params associative array. At a minimum either the id or container property must be specified so that the new map instance can be initialized with a reference to its DOM container. The other properties may be set on the new map instance after it has been created.

Method Detail

addControl

GSControl addControl(control)

Adds a control to the map

•  
  control - the control object, or a String constant identifying the type of control to add to the map.
Parameters:

•  
  the map control that was added
Returns:

•  
  - ZOOM_CONTROL
  - COMPACT_ZOOM_CONTROL
  - TEXT_ZOOM_CONTROL
  - MAP_CONTROL
See:

addFeature

void addFeature(feature)

A convenience function for adding a feature to the map without explicitly creating a layer first. Features added in this way are owned by the map's 'base' layer.

•  
  - removeFeature()
See:

centerAndZoom

void centerAndZoom(<GSPoint> coordinate, <int> zoomLevel, <Function> onCenter)

Centers the map on the provided coordinate at the given zoom level

•  
  coordinate - the real world coordinate (NZMG) to center the map on
  zoomLevel - an integer value from 0 (maximum zoom in) to 11 (maximum zoom out)
  onCenter - an optional function that will be invoked when the map has been centered on the specified coordinate
Parameters:

centerAtCoordinate

void centerAtCoordinate(<GSPoint> coordinate, <Function> onCenter, <boolean> suppressMessaging)

Centers the map on the specified coordinate

•  
  coordinate - the real world coordinate (NZMG) to center the map on
  onCenter - an optional function that will be invoked when the map
  suppressMessaging - set to true to prevent this function from notifying listeners upon completion has been centered on the specified coordinate
Parameters:

centerOnLayer

void centerOnLayer(<String> name, <Function> onCenter)

Re-centers the map on the named layer. Specifically the minimum bounding box required to display all features in the layer is calculated and the map is resized to match the extents of this bounding box.

In many cases the features belonging to the layer that the map is being centered on should not be visible until after the map has been re-centered. To do this call GSLayer.setVisible() with an argument of false before adding the feature data to it. centerOnLayer() will automatically set the layer features to be visible after the map has been recentered.

•  
  name - the name of the layer to center the map on
  onCenter - an optional function that will be invoked when the map has been re-centered
Parameters:

centerOnNewZealand

void centerOnNewZealand(<Function> onCenter)

Centers the map on the center of New Zealand, Nelson, and at such a scale that the full extent of the country is visible

•  
  onCenter - an optional function that will be invoked when the map has been centered
Parameters:

clearLayers

void clearLayers()

Removes all user-defined layers from the map

closeInfoWindow

void closeInfoWindow()

Close the info window if it is open

•  
  coordinate - the point which the info window refers to
  html - the HTML content of the info window
Parameters:

createLayer

GSLayer createLayer(<String> name)

Creates a new layer with the specified name

•  
  name - the layer name
Parameters:

•  
  the layer that was created
Returns:

getLayer

GSLayer getLayer(<String> name)

Returns the named map layer

•  
  name - of the layer to return
Parameters:

•  
  the named layer
Returns:

getMapCenter

GSPoint getMapCenter()

Returns the center point of the map as an NZMG coordinate

•  
  the map center point as an NZMG coordinate
Returns:

getSize

GSDimension getSize()

Returns the size, in pixels, of this map

•  
  the size of the map
Returns:

•  
  - setSize()
See:

getZoomLevel

int getZoomLevel()

Returns the current map zoom level

•  
  the current map zoom level
Returns:

openInfoWindow

void openInfoWindow(<GSPoint> coordinate, html)

Displays the info window at the given coordinate. If the window is already open at some other location it will be closed and thereafter reopened at the new location.

•  
  coordinate - the point which the info window refers to
  html - the HTML content of the info window
Parameters:

panTo

Object panTo(<GSPoint> coordinate, onPan)

Pans the map to the specified coordinate. If the coordinate is within the visible part of the map panning is animated, otherwise the map is directly centered on the coordinate.

•  
  coordinate - the real world coordinate (NZMG) to pan the map to
  onCenter - an optional function that will be invoked when the map has been panned to the specified coordinate
Parameters:

removeControl

void removeControl(<GSControl> control)

Removes a control from the map

•  
  control - the control object
Parameters:

removeFeature

void removeFeature(feature)

A convenience function for removing a feature that was added directly to the map

•  
  - addFeature()
See:

removeLayer

void removeLayer(<String> name)

Removes a feature layer from the map

•  
  name - the layer name
Parameters:

setBounds

void setBounds(bounds, <Function> onBoundsChanged)

Sets the map extents to those specified by the bounds object

•  
  onBoundsChanged - an optional function that will be invoked when the map bounds have been set
  the - new map bounds
Parameters:

•  
  - getBounds()
See:

setSize

void setSize(<GSDimension> size, resizeable)

Sets the size in pixels of the map to be created. Note this method doesn't update the map to match the new size, call one of the map positioning methods to do this.

•  
  size - the size of the map to be created in pixels
  resizable - if true the map can be resized in response to changes in the size of its container
Parameters:

•  
  - getSize()
See:

zoom

void zoom(<int> zoomLevel, <Function> onZoom)

Zooms to the specified zoom level

•  
  zoomLevel - an integer value from 0 (maximum zoom in) to 11 (maximum zoom out)
  onZoom - an optional function that will be invoked when the map has been zoomed to the new zoom level
Parameters: