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:

• GLargeMapControl3D - a large pan/zoom control as now used on Google Maps. Appears in the top left corner of the map by default.
• GLargeMapControl - a simpler large pan/zoom control. Appears in the top left corner of the map by default.
• GSmallMapControl - a smaller pan/zoom control. Appears in the top left corner of the map by default.
• GSmallZoomControl3D - a small zoom control (with no panning controls) as now used on Google Maps.
• 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
• GNavLabelControl - a dynamic label indicating the "address" of the current viewport, appropriate to zoom level.

All of these controls are based on the GControl object.

MapType Controls

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.

By default, a GMapTypeControl displays a set of standard map types:

• 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)

For additional map types, see the Map Types section.

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)

Specifying Sets of UI Behavior

The Google Maps API allows you to specify a set of UI behavior to your map all at once, rather than specify controls or behaviors individually. You can deploy these sets in one of two ways:

• Setting up a map to use the default UI as shown on http://maps.google.com
• Using a GMapUIOptions object to set up a custom set of controls.

The first case is the simplest, as it doesn't involve manipulation of an object. The latter process requires modification of a GMapUIOptions object, which contains a set of properties that specify the UI behavior of the map.

Using the Default Maps UI

Rather than specifying and setting up individual controls, you may wish to specify that your map exhibit the look and feel of the http://maps.google.com interface. You can do so using the GMap2.setUIToDefault() method. This method adds a set of controls and user input behavior to your map corresponding to what's available in the UI on Google Maps. This behavior is also dynamic; if the UI to http://maps.google.com changes, you'll automatically get any new UI behavior once the API updates to reflect those changes.

Note: the UI available to API applications via this method may not always reflect all features available on Google Maps as there will usually be a delay between when a feature shows up on http://maps.google.com and when it is added to the API.

The following code shows how simple it is to add this functionality to a map:

var map = new GMap2(document.getElementById("map_canvas"),
    { size: new GSize(400,299) } );
map.setCenter(new GLatLng(42.366662,-71.106262), 11);
map.setUIToDefault();

The behavior of setUIToDefault() differs slightly based on the size of the map. Larger maps use the standard complement of controls, while smaller maps use a subset of smaller controls. These differences are shown below:

For large maps of 400x300 pixels or larger, the following controls are added to the map:

• A GMapTypeControl holding the set of G_DEFAULT_MAP_TYPES map types
• A GLargeMapControl3D enabling full zoom/pan functionality
• A GScaleControl that displays the scale in use by the map

View example (control-defaultUI-large.html)

For smaller maps which are either less than 400 pixels wide or less than 300 pixels tall, setUIToDefault() instead adds the following controls to the map:

• A GMenuMapTypeControl holding a drop-down menu of the G_DEFAULT_MAP_TYPES map types
• A GSmallZoomControl3D enabling zoom functionality (no pan control is added)

Such a set of controls is more economical in screen real estate for small maps.

View example (control-defaultUI-small.html)

Regardless of which control set is in use, setUIToDefault() also adds the following functionality which is available in http://maps.google.com:

• Scrollwheel zooming
• Double-click zooming
• Keyboard handling

If you wish to modify any of this behavior, you should instead use a GMapUIOptions object, as shown in the following section.

Using the GMapUIOptions Object

The GMapUIOptions object contains a set of properties that specify control placement and UI behavior, which you may modify. For a full set of properties, see the GMapUIOptions reference.

Rather than write a GMapUIOptions structure from scratch, you may wish to prepopulate it with the UI behavior available on Google Maps. To do so, use the GMap2.getDefaultUI() method. Once populated, you can modify individual properties to tweak the behavior and initialize the map's UI controls using the GMap2.setUI() method.

The following code retrieves the default UI on a "large" map, removes the GScaleControl and resets the map to use the modified UI.

map = new GMap2(document.getElementById("map_canvas"),
    { size: new GSize(400,300) } );
map.setCenter(new GLatLng(41.897997,-87.790203), 11);
var customUI = map.getDefaultUI();
customUI.controls.scalecontrol = false;
map.setUI(customUI);

View example (control-uiOptions.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)