Controls

Controls Overview

The maps on http://maps.google.com contain UI elements for allowing user interaction through the map. These elements are known as controls and you can include variations of these controls in your Google Maps API application. You can also build your own custom controls by subclassing the GControl class.

The Maps API comes with a handful of built-in controls you can use in your maps:

• GLargeMapControl - a large pan/zoom control used on Google Maps. Appears in the top left corner of the map by default.
• GSmallMapControl - a smaller pan/zoom control used on Google Maps. Appears in the top left corner of the map by default.
• GSmallZoomControl - a small zoom control (no panning controls) used in the small map blowup windows used to display driving directions steps on Google Maps.
• GScaleControl - a map scale
• GMapTypeControl - buttons that let the user toggle between map types (such as Map and Satellite)
• GHierarchicalMapTypeControl - a selection of nested buttons and menu items for placing many map type selectors.
• GOverviewMapControl - a collapsible overview map in the corner of the screen

All of these controls are based on the GControl object.

The GMapTypeControl and GHierarchicalMapTypeControl are special cases because they are also configurable. These controls add functionality to change the GMapType currently used by the map within the Google Maps API. For more information on configuring these controls, see Modifying the Makeup of Standard Controls.

A list of currently supported map types appears below:

• G_NORMAL_MAP displays the normal, default 2D tiles of Google Maps
• G_SATELLITE_MAP displays photographic tiles
• G_HYBRID_MAP displays a mix of photographic tiles and a tile layer for prominent features (roads, city names)
• G_PHYSICAL_MAP displays physical map tiles based on terrain information

You may also define your own custom map types if you have imagery or overlays you have defined.

By default, the Google Maps API provides three map types: G_NORMAL_MAP, G_SATELLITE_MAP, and G_HYBRID_MAP. You may alter the map types available to a map by removing them via GMap2.removeMapType() or adding them via GMap2.addMapType(). Whenever you create a map type control, it uses the currently attached map types and makes them available via the control. Note that you must specify any relationships between map types before you add the control in order for the map type control to pick up those relationships.

The code below removes G_HYBRID_MAP from the available map types attached to a map, leaving only two map types. Once we add the GMapTypeControl, only those two map types are available.

var map = new GMap2(document.getElementById("map_canvas"),
  { size: new GSize(640,320) } );
map.removeMapType(G_HYBRID_MAP);
map.setCenter(new GLatLng(42.366662,-71.106262), 11);
var mapControl = new GMapTypeControl();
map.addControl(mapControl);
map.addControl(new GLargeMapControl());

View example (control-maptypes.html)

Adding Controls to the Map

You add controls to the map with the GMap2 method addControl(). For example, to add the panning/zooming control you see on Google Maps to your map, you would include the following line in your map initialization:

map.addControl(new GLargeMapControl());

You can add multiple controls to a map. In this case, we add the built-in GSmallMapControl and GMapTypeControl controls, which let us pan/zoom the map and switch between Map and Satellite modes, respectively. The standard controls are fully operational once they are included on a map.

var map = new GMap2(document.getElementById("map"));
map.addControl(new GSmallMapControl());
map.addControl(new GMapTypeControl());
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

View example (control-simple.html)

Positioning Controls on the Map

The addControl method takes an optional second GControlPosition parameter that lets you specify the position of the control on your map. This value can be one of the following values, each specifying a corner of the map in which to place the control:

• G_ANCHOR_TOP_RIGHT
• G_ANCHOR_TOP_LEFT
• G_ANCHOR_BOTTOM_RIGHT
• G_ANCHOR_BOTTOM_LEFT

If this argument is excluded, the Maps API uses the default position specified by the control.

The GControlPosition may optionally specify an offset indicating how many pixels from the edge of the map to place the control. These offsets are specified using a GSize object.

This example adds the GMapTypeControl to the top right corner of the map with 10 pixels of padding. Double-clicking anywhere on the map removes that control and places it in the bottom right corner of the map.

var map = new GMap2(document.getElementById"map_canvas"));
var mapTypeControl = new GMapTypeControl();
var topRight = new GControlPosition(G_ANCHOR_TOP_RIGHT, new GSize(10,10));
var bottomRight = new GControlPosition(G_ANCHOR_BOTTOM_RIGHT, new GSize(10,10));
map.addControl(mapTypeControl, topRight);
GEvent.addListener(map, "dblclick", function() {
  map.removeControl(mapTypeControl);
  map.addControl(new GMapTypeControl(), bottomRight);
});
map.addControl(new GSmallMapControl());
map.setCenter(new GLatLng(37.4419, -122.1419), 13);

View example (control-positioning.html)

See the GControlPosition class reference for more information.

Modifying the Makeup of Standard Controls

Most of the controls within the Google Maps API provide a simple control with standard behavior. Some controls, however, require initialization for proper usage. For example, the GHierarchicalMapTypeControl generally requires some initialization to show map types within a cascading "menu" in the correct order.

This example adds the a G_PHYSICAL_MAP map type with a crosshair tile layer overlay to the map, and then creates a GHierarchicalMapTypeControl to arrange the additional map types added to the map.

// define the crosshair tile layer and its required functions
var crossLayer = new GTileLayer(new GCopyrightCollection(""), 0, 15);

crossLayer.getTileUrl =  function(tile, zoom) {
  return "./include/tile_crosshairs.png";
}
crossLayer.isPng = function() {return true;}

// Create a new map type incorporating the tile layer
var layerTerCross = [ G_PHYSICAL_MAP.getTileLayers()[0], crossLayer ];
var mtTerCross = new GMapType(layerTerCross,
  G_PHYSICAL_MAP.getProjection(), "Ter+");

var map = new GMap2(document.getElementById("map_canvas"), 
  { size: new GSize(640,320) } );
map.addMapType(G_PHYSICAL_MAP);
map.addMapType(mtTerCross);
map.setCenter(new GLatLng(37.4419, -122.1419), 4);
var mapControl = new GHierarchicalMapTypeControl();

// Set up map type menu relationships
mapControl.clearRelationships();
mapControl.addRelationship(G_SATELLITE_MAP, G_HYBRID_MAP, "Labels", false);
mapControl.addRelationship(G_PHYSICAL_MAP, mtTerCross, "Crosshairs");

// Add control after you've specified the relationships
map.addControl(mapControl);

map.addControl(new GLargeMapControl());

View example (control-initialization.html)

Custom Map Controls

The Google Maps API also allows you to create custom map controls by subclassing GControl. (Technically, you don't "subclass" an object in JavaScript but instead assign a prototype object to an instance of the GControl object.)

To create a usable custom control, you are required to define handlers for at least two methods on the class: initialize() and getDefaultPosition(). The initialize() method must return a DOM element, while the getDefaultPosition() method must return an object of type GControlPosition.

All map controls should be added to the map container which can be accessed with GMap2's getContainer() method.

In this example, we create a simple zoom control that has textual links rather than the graphical icons used in the standard Google Maps zoom control.

// A TextualZoomControl is a GControl that displays textual "Zoom In"
// and "Zoom Out" buttons (as opposed to the iconic buttons used in
// Google Maps).

// We define the function first
function TextualZoomControl() {
}

// To "subclass" the GControl, we set the prototype object to
// an instance of the GControl object
TextualZoomControl.prototype = new GControl();

// Creates a one DIV for each of the buttons and places them in a container
// DIV which is returned as our control element. We add the control to
// to the map container and return the element for the map class to
// position properly.
TextualZoomControl.prototype.initialize = function(map) {
  var container = document.createElement("div");

  var zoomInDiv = document.createElement("div");
  this.setButtonStyle_(zoomInDiv);
  container.appendChild(zoomInDiv);
  zoomInDiv.appendChild(document.createTextNode("Zoom In"));
  GEvent.addDomListener(zoomInDiv, "click", function() {
    map.zoomIn();
  });

  var zoomOutDiv = document.createElement("div");
  this.setButtonStyle_(zoomOutDiv);
  container.appendChild(zoomOutDiv);
  zoomOutDiv.appendChild(document.createTextNode("Zoom Out"));
  GEvent.addDomListener(zoomOutDiv, "click", function() {
    map.zoomOut();
  });

  map.getContainer().appendChild(container);
  return container;
}

// By default, the control will appear in the top left corner of the
// map with 7 pixels of padding.
TextualZoomControl.prototype.getDefaultPosition = function() {
  return new GControlPosition(G_ANCHOR_TOP_LEFT, new GSize(7, 7));
}

// Sets the proper CSS for the given button element.
TextualZoomControl.prototype.setButtonStyle_ = function(button) {
  button.style.textDecoration = "underline";
  button.style.color = "#0000cc";
  button.style.backgroundColor = "white";
  button.style.font = "small Arial";
  button.style.border = "1px solid black";
  button.style.padding = "2px";
  button.style.marginBottom = "3px";
  button.style.textAlign = "center";
  button.style.width = "6em";
  button.style.cursor = "pointer";
}

var map = new GMap2(document.getElementById("map"));
map.addControl(new TextualZoomControl());
map.setCenter(new GLatLng(37.441944, -122.141944), 13);

View example (control-custom.html)