Events

Introduction
Event listeners
Removing event listeners
DOM events
Examples

Introduction

The Google Earth API provides a number of different events, which can be used with google.earth.addEventListener to provide additional interactivity in your applications. Using event listeners, you can create actions that are triggered on mouse events (such as clicks, movement, or dragging) or screen events (such as changes to the view).

Adding an Earth API event listener requires three arguments, and accepts an optional fourth: the object on which to add the listener, the event to listen for, the function to call when the event is fired, and (optionally) whether or not this listener should initiate capture (refer to the relevant W3C DOM documentation for details of event capture). The default value for this fourth argument is false.

google.earth.addEventListener(placemark10, 'click', doSomething);

addEventListener() and removeEventListener() live in the google.earth namespace.

Event listeners

Mouse events can be attached to most geometries in the plugin (the exception is 3D models), to the entire viewport, or to the globe only. There are listeners for most mouse events, including clicks and movements. For a full list of mouse events, refer to the GEEventEmitter Interface Reference.

View events are fired when the view begins to change, while it is changing, and when it has ended . Listeners for view events must be attached to the viewport object of the plugin instance (ge.getView()). viewchangeend may fire in the middle of a view change, if the plugin pauses for a brief period during the change. If you are relying on viewchangeend to indicate the absolute end of a view change, it's recommended that you include a brief timeout to ensure that no further view changes are to follow:

google.earth.addEventListener(ge.getView(), 'viewchangeend', function(){
  if(timer){
    clearTimeout(timer);
  }
    timer = setTimeout(eventHandler, 100);
  }
);

For a full list of view events, refer to the GEView Interface Reference.

A frameend event is fired when Earth has finished rendering the viewport. This event will be called many times in succession when the viewport is changing. Add a listener for this event and make incremental changes to the viewport for smooth animation. A frameend listener must be attached to the Google Earth Plugin instance.

The balloonclose event is fired when the current description balloon is closed. Its listener must be attached to the plugin instance.

Removing event listeners

You can remove event listeners using removeEventListener(). You must pass the same object, event type, and function name to removeEventListener() as were specified when creating the event listener.

var eventHandler = function(){ ... };

// Add an event listener
google.earth.addEventListener(ge.getGlobe(), 'mousemove', eventHandler);
// Remove this event listener
google.earth.removeEventListener(ge.getGlobe(), 'mousemove', eventHandler);

DOM events

To add listeners to HTML elements on the page, outside of the plugin, you can use this helper function that will work across all modern browsers:

function addDomListener(element, eventName, listener) {
   if (element.addEventListener) // most browsers
      element.addEventListener(eventName, listener, false);
   else if (element.attachEvent) // IE
      element.attachEvent('on' + eventName, listener);

This accounts for the different methods of attaching handlers in Internet Explorer and most other browsers; IE uses attachEvent and onclick, while others use addEventListener and click.

Examples

mousemove

The following example adds an event listener to the globe object to listen for mousemove events.

Source: http://developers.google.com/earth/documentation/samples/mousemove_listener_example.html

ge = instance;
ge.getWindow().setVisibility(true);

// Define what happens when a mousemove is detected on the globe.
var maxAlt = -1000000;
function recordAltitude(event) {
   var currentAlt = event.getAltitude();
   maxAlt = Math.max(maxAlt, currentAlt);
   document.getElementById('altitude').innerHTML =
      '<p>Current altitude: ' + currentAlt + '<br />Max altitude: '
      + maxAlt + '</p>';
}

// Listen to the mousemove event on the globe.
google.earth.addEventListener(ge.getGlobe(), 'mousemove', recordAltitude);

Draggable placemark

The following example comes from earth-api-samples.googlecode.com. It uses three event listeners:

The first listens for mousedown events anywhere in the window. If the target of the mousedown event is a point placemark, dragInfo is set to true.
The second listens for mousemove events anywhere on the globe. If dragInfo is true, the latitude and longitude of the point placemark is updated as the mouse is moved.
The last listener listens for mouseup events. It prevents any feature balloons from popping when the mouse button is released, and sets dragInfo to null so that the placemark's longitude and latitude are no longer updated.

Source: http://earth-api-samples.googlecode.com/svn/trunk/examples/placemark-dragdrop.html

var ge;
var placemark;
var dragInfo = null;

google.load("earth", "1");

function init() {
  google.earth.createInstance('map3d', initCallback, failureCallback);
}

function initCallback(instance) {
  ge = instance;
  ge.getWindow().setVisibility(true);

  // Create the placemark and add it to Earth.
  placemark = ge.createPlacemark('');
  var point = ge.createPoint('');
  point.setLatitude(37);
  point.setLongitude(-122);
  placemark.setGeometry(point);
  placemark.setName('Drag Me!');
  ge.getFeatures().appendChild(placemark);

  // Look at the placemark we created.
  var la = ge.createLookAt('');
  la.set(37, -122, 0, ge.ALTITUDE_RELATIVE_TO_GROUND, 0, 0, 5000);
  ge.getView().setAbstractView(la);

  // Listen for mousedown on the window (look specifically for point placemarks).
  google.earth.addEventListener(ge.getWindow(), 'mousedown', function(event) {
    if (event.getTarget().getType() == 'KmlPlacemark' &&
        event.getTarget().getGeometry().getType() == 'KmlPoint') {
      var placemark = event.getTarget();
      dragInfo = {
        placemark: event.getTarget(),
        dragged: false
      };
    }
  });

  // Listen for mousemove on the globe.
  google.earth.addEventListener(ge.getGlobe(), 'mousemove', function(event) {
    if (dragInfo) {
      event.preventDefault();
      var point = dragInfo.placemark.getGeometry();
      point.setLatitude(event.getLatitude());
      point.setLongitude(event.getLongitude());
      dragInfo.dragged = true;
    }
  });

  // Listen for mouseup on the window.
  google.earth.addEventListener(ge.getWindow(), 'mouseup', function(event) {
    if (dragInfo) {
      if (dragInfo.dragged) {
        // If the placemark was dragged, prevent balloons from popping up.
        event.preventDefault();
      }

      dragInfo = null;
    }
  });

}

function failureCallback(errorCode) {
}

Other examples

There are a number of event listener examples in the earth-api-samples.googlecode.com project, including: