Search Google Code
Home
   
Basics
   
Events
   
Controls
   
Overlays
   
Services
  

Controls

  1. Map Controls Overview
  2. Adding Controls to the Map
  3. Positioning Controls on the Map
  4. Creating Custom 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:

All of these controls are based on the GControl object.

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:

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.

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)