Programming Virtual Earth: Writing a Vista Gadget

This article is based on a previous article published in the MP2K Magazine.

Download the gadget complete with source code: VE_Sample.gadget.zip (3KB).

Introduction

Although Microsoft's Virtual Earth is usually used in web applications, it can also be used on the desktop. This article shows you how to use Virtual Earth in a Windows Vista Gadget. It is the first of a two part series. The second part extends the gadget into a Real Time Tracker for the International Space Station.

The sample Virtual Earth gadget and the system clock gadget

Windows Vista re-introduces the concept of "Gadgets". Vista Gadgets are small programs that sit on the desktop. Samples that come with Vista include RSS feeds, a clock, and simple games. This article is the first of two articles. In this first part, I will show you how to write your own Vista Gadgets that use Microsoft's Virtual Earth platform. The second part will build on this to produce a gadget that continuously tracks the position of the International Space Station over the Earth's surface.

This screenshot shows two Gadgets installed on a Vista desktop running the Aero visual interface. The gadgets appear in the Windows sidebar on the right of the desktop. The lower gadget is the standard Vista clock. The upper gadget is the Virtual Earth gadget that we will create in this article. If your sidebar is disabled, it can be enabled by clicking "Windows Sidebar" in Start->All Programs->Accessories.

Writing the Vista Gadget

Vista gadgets are simply HTML files, hence all you need to write them is a text editor. These examples also use JScript (Microsoft's version of JavaScript/ECMAScript). Many of the gadgets are located in the Program Files folder, but we will create our gadget in our personal gadget storage area. Press the Windows Key + R to get the 'Run' prompt. Type:

%userprofile%\AppData\Local\Microsoft\Windows Sidebar\Gadgets

This will open your personal gadgets folder. To avoid having to re-type this folder, I usually create a shortcut. Create a new folder for your gadget in your Gadgets folder. It must have the suffix ".gadget". Use "VE_Sample.gadget" for this example. Here is an example with two custom gadgets defined:

Two custom gadgets in a user's gadgets folder

Open your new VE_Sample.gadget folder. This will store all the files required for your gadget. You can add icons, graphics, JScript, HTML, etc. This example uses the bare minimum: a manifest file, and a HTML file. The manifest file tells Vista about the Gadget. Start Notepad (or your text editor of choice), and write the following:

<?xml version="1.0" encoding="utf-8" ?>
<gadget>
<name>VE Sample</name>
<namespace>Example.You</namespace>
<version>1.0</version>
<author name ="Richard Marsden">
   <info url="http://www.mapping-tools.com" />
</author>
<copyright>2007</copyright>
<description>Simple Virtual Earth Sample Gadget</description>
<hosts>
  <host name="sidebar">
     <base type="HTML" apiVersion="1.0.0" src="VE_Sample.html" />
     <permissions>full</permissions>
     <platform minPlatformVersion="0.3" />
  </host>
</hosts>
</gadget>

Save this to the file "gadget.xml" in your new gadgets directory. Notice that this manifest includes the gadget's name, HTML file name (VE_Sample.html), and some descriptive information (author, URL, etc).

Next we shall write the actual Gadget. Write the following to a new file called "VE_Sample.html" in the gadget directory:

<html>
<head>
<title>VE Sample</title>
<!-- Richard Marsden, http://www.mapping-tools.com -->

<script src="http://dev.virtualearth.net/mapcontrol/v3/mapcontrol.js">
</script>

<script>
var map=null;

// Page Load Callback:  Create map
function onPageLoad()
{
	// Display the map: Choose a location near the Greenwich Observatory, London
	// Map type is zoomed in using aerial imagery

	map = new VEMap('myMap');
	map.LoadMap(new VELatLong( 51.4777, -0.0015 ),17, 'h', false);
	map.HideDashboard();

}

// Button Call-backs
function ZoomInButton()
{
	map.ZoomIn();
}

function ZoomOutButton()
{
	map.ZoomOut();
}
</script>
</head>

<body style="width:140;height:270;" onload="onPageLoad();">

<input type="button" value=" + " style="float:left;" onclick="ZoomInButton()" ID="ZoomInButton" Name="ZoomInButton" />
<input type="button" value=" - " style="float:left;" onclick="ZoomOutButton()" ID="ZoomOutButton" Name="ZoomOutButton" />

<br/>

<div id='myMap' style="position:relative; width:140px; height:250px;"></div>

</body>
</html>

As you can see, the gadget code resembles a conventional web page. The header includes our JScript code. First we include the Virtual Earth v3 script. This is followed by three callbacks. The first (onPageLoad) is called by the body tag when the page loads. This creates the Virtual Earth map object, sets it to display aerial photography, hides the control dashboard, and centers the map on the Royal Greenwich Observatory in London. The dashboard is hidden due to the general shortage of space in gadgets such as this.

The observant reader will notice that we do not centre the map exactly on the Prime Meridian. This is because the observatory is not positioned symmetrically about the Greenwich Meridian. Also, Virtual Earth uses the relatively modern WGS84 geoid which has its Prime Meridian approximately 102 metres to the east of the Greenwich Meridian.

The remaining two callbacks are for the "+" and "-" buttons that we shall create. These simply change the zoom level of the map. The user can also pan the map by dragging with the mouse in the conventional manner.

The body of the gadget is also relatively simple. The gadget size is defined in the main body element. We define three elements: the Zoom buttons are at the top. After a page break, an empty div called myMap is defined to hold the map.

And that is it! Only two files are required to create a simple Vista Gadget. Next we need to tell Vista to use our new gadget. Do this by clicking on the "+" symbol at the top of the Sidebar. This will display your Gadget Gallery, which will look something like the image to the right.

We have not defined a custom gadget icon, so our new gadget appears with the generic Windows gadget icon. Double click on the VE_Sample gadget, and it will be inserted into the Windows Sidebar.

In the second part of this article, I shall extend the gadget to automatically track the International Space Station.

Download the gadget complete with source code: VE_Sample.gadget.zip (3KB).

Return to the Main MapPoint Articles Page.