How To Embed GoogleEarth in your Delphi Application (part 1 of 5)

Introduction: The GoogleEarth Plug-in and the GEDemo program

An article by David Hawk, Landenberg, Pennsylvania, USA.

This article was originally written for v1 of the Google Maps API. v3 introduced a breaking-change with the removal of the ClientGeocoder object and its replacement with the Geocoder object. The new JavaScript Geocode function shown in Section 3, listing 9 updates GEDemo for v3.
Google is discontinuing support for the Google Earth Plug-in on 15 December 2015. After that date GEDemo and its derivatives will cease to function.



This article describes an easy way to embed GoogleEarth in a Delphi application. Before proceeding too far, you should study Google's Terms of Service. Just because GoogleEarth can be freely downloaded doesn't mean there aren't any restrictions on what you can do with it.

You should be aware that there are actually two APIs for GoogleEarth. The first, a relatively rudimentary COM API, was released in Beta form in 2006. The earth.idl COM interface allows GoogleEarth.exe to be scripted by an external application. This API is still supported and has some documentation.

A heroic programming effort by Luca Rocchi (Rome, Italy) produced GEPanel for Delphi, a TPanel descendant, which Luca has made freely available (see the source tab on his website). GEPanel starts the GoogleEarth.exe process and employs various Windows tricks to capture GoogleEarth's render window within the GEPanel client area in order to allow it to be displayed as part of a Delphi application. The COM interface allows control of GoogleEarth, and the TPanel ancestor allows the mouse-down event to be captured for calculating coordinates. This approach was used in the author's first attempt at incorporating GoogleEarth into a Delphi application and was fairly successful, however there are some inherent limitations. GoogleEarth.exe only allows a single instance to run on a given machine. Also the GEPanel code seems to depend on some implementation details of GoogleEarth.exe which aren't part of Google's specifications, and future changes by Google could conceivably break it. Luca Rocchi has also released a browser plug-in for GoogleEarth on his website that has received good reviews, but it has not been evaluated by this author.

Google has recently released its own GoogleEarth Plug-in which is much easier to use but has a completely different API. This plug-in is extensively documentated on Google's website. The GoogleEarth Plug-in allows multiple instances to run on a machine and allows more control over the application. The plug-in is supplied in various versions to support different browsers, and the Internet Explorer version is an ActiveX control.

A brief unsuccessful attempt to use the ActiveX control directly from Delphi was made, but was abandoned after researching other people's attempts to do this. Their efforts had foundered on poorly documented and changing ActiveX interfaces for the Plug-in that made it apparent that this approach was going against the grain of how Google's engineers intended for it to be used.

This article describes the easy way to incorporate this GoogleEarth Plug-in into a Delphi application. It involves placing a TWebBrowser component on a form and running the plug-in within it. An HTML file is loaded that embeds the plug-in and supplies the JavaScript to interact with it. Google's website has excellent documentation on the necessary JavaScript for controlling the Plug-in as well as numerous examples. The critical missing link was bridging the JavaScript with the Delphi code. The necessary techniques and code for this was found in two articles by Peter Johnson on this website: How to call JavaScript functions in a TWebBrowser from Delphi and How to call Delphi code from scripts running in a TWebBrowser.

GEDemo Program

A Delphi GoogleEarth demo program was developed for this article. On start-up, after the initialization streaming has completed, the program displays the familiar GoogleEarth globe.

Demo program on start-up showing Google Earth globe

The user enters an address, for example the White House in Washington, DC, and clicks the Geocode Address button. Clicking this button causes the address to be sent to Google to be "geocoded", whereby Google returns a fairly close longitude and latitude for that address. The GoogleEarth plug-in is then directed to zoom in to approximately 200 meters above these approximate coordinates. If the desired house is not in view (usually it is), the user can slide the terrain around until the house appears. The user then clicks on the house itself and precise longitude and latitude are displayed.

Demo program displaying the USA White House

The demo implements a handshake between the Delphi and JavaScript code since the plug-in proceeds asynchronously and operations are somewhat lengthy. An event mechanism was implemented so that the Delphi code can be notified by the JavaScript when either initialization completes or a previously issued command completes. In the demo, the Geocode Address button on the Delphi form is initially disabled but is enabled when an event signals that initialization has completed. The button is disabled again after being clicked and is re-enabled when the Geocode Address command completes and the display has zoomed to the desired location.

Subsequent sections of this article provide a walk-though of the MainForm Delphi code, the HTML file and it's JavaScript, and the JavaScript bridge code that implements the communication between the Delphi code and the JavaScript code.