Google Maps API for Flash Developer Guide

The Google Maps API for Flash provides a new way to add interactive Google Maps to your website, using Adobe's Flash® plugin to display dynamic map content! This API exists as a fully independent alternative to the existing JavaScript Maps API, and provides many of the features of that API while also adding the ability to mix Flash content with Google Maps.

The Google Maps API for Flash is new, so we'd like to hear your feedback. We encourage you to join the Maps API discussion group to give us feedback.

Audience

This documentation is designed for people familiar with Flash, ActionScript® programming, and object-oriented programming concepts.

This documentation is organized to cover the following key areas:

• Google Maps Flash Basics (and "Hello World" Tutorial)
• Google Maps Flash Events
• Google Maps Flash Controls
• Google Maps Flash Overlays
• Google Maps Flash Services

All new developers should read both this document, which explains how to set up your Google Maps Flash development environment and maintain it, and The "Hello World" of the Google Maps API for Flash , which explains how to write your first Google Maps Flash application.

.

Introduction

Providing a Flash version of the Google Maps API allows current Flash developers to easily integrate Google Maps into their existing Flash development environments. As well, the Google Maps API for Flash opens up a whole world of interactive possibilities for displaying and using map content for those developers not currently using Flash.

This developer guide assumes you are familiar with Flash development and ActionScript programming. It also does not assume usage of any particular development environment, though it uses the freely available Adobe Flex SDK within this tutorial.

Note: this guide uses UNIX-like command line examples, though usage should not appreciably change for either Windows or Macintosh developers.

Setting Up Your Development Environment

Flash development can take many forms. Some developers author purely within the Flash application to create and arrange content, and add ActionScript within that framework. Other developers use a full-featured IDE such as Adobe® Flex® Builder to create robust applications with heavy use of ActionScript. The choice of development environment is up to you. For this tutorial, however, we will concentrate on documenting the simplest and most general solution: usage of the freely available Adobe Flex 3 SDK through the command line.

This section discusses how to obtain and set up the Adobe Flex SDK, how to obtain the Google Maps API for Flash library, and how to set up your development environment to get you ready to program in ActionScript and build your first Google Maps API for Flash map.

Obtaining and Installing the Adobe Flex SDK

Incorporating Google Maps into your Flash application requires integration of the ActionScript code that you write into a Flash framework. For simplicity, the examples in this documentation use the freely available Adobe Flex 3 SDK available at the following URL address:

http://www.adobe.com/products/flex/overview/#section-3

Note: The Flex SDK requires Java 1.4 or 1.5 (depending on the development platform). Full requirements for development with the Flex SDK are available at:

http://www.adobe.com/products/flex/systemreqs/

Once you've downloaded the SDK, unzip it into a working directory and ensure that you can execute the MXML Compiler (mxmlc) from the command line. The mxmlc compiler is located in the Flex SDK's bin directory. Executing the compiler with the -help option should result in the following output.

hostname$ cd flex_sdk/bin
hostname$ mxmlc -help
Adobe Flex Compiler (mxmlc)
Version 3.0.0 build 477
Copyright (c) 2004-2007 Adobe Systems, Inc. All rights reserved.
...

Obtaining the Interface Library

Developing Flash content that integrates Google Maps requires inclusion of the Google Maps API for Flash interface library within your application code. This library consists of a *.swc file which is contained within the Maps API for Flash SDK available at the following URL:

http://maps.googleapis.com/maps/flash/release/sdk.zip

This SWC file contains interfaces for all public classes in the Google Maps API for Flash development environment. Compiling your application with this library ensures that it can utilize and communicate with all public functionality of the runtime Google Maps API for Flash library, which is retrieved from Google's servers whenever a client loads your application.

Note that the bulk of the code for actually running your Maps Flash application remains within the separate runtime Google Maps API for Flash library. This allows us to make enhancements, bug fixes, and modifications to the core library functionality without requiring you to recompile your application. Note that if you ever wish to utilize new functionality that requires new interfaces, you will need to download an updated SWC file and recompile your application.

The interface library filename contains a suffix identifying its version number. (For example, map_flex_1_1 identifies version "1.1" of the interface library. Once you've downloaded the interface library, create a development directory and place that file in the root of that directory.

#
#Create a development directory
#
hostname$ mkdir myflashapp
hostname$ cd myflashapp
#
# Copy the Google Maps API for Flash SDK to the root of your working development directory
#
hostname$ cp ~/sdk.zip .
#
# Unzip the SDK. The SWC interface library is located within the "lib" directory
# Offline ASDoc HTML documentation is available within the "docs" directory
#
hostname$ unzip sdk.zip

Obtaining a Maps API Key

The Google Maps API for Flash, like the Google JavaScript Maps API, requires usage of a freely available developer key. You will need to specify this key within one of three possible locations:

• Your ActionScript code (compiling it into the resulting SWF file)
• A special configuration file called an MXML declaration
• The containing DOM element in your web page.

This document set discusses the latter two techniques.

Setting Up Your Development Directories

Google recommends that you develop your Flash application using a unique namespace which you own, to prevent collisions with other applications, especially if you will have many developers working on multiple flash applications at the same time. Using namespaces also allows you to bundle your application code into packages, which allow easier sharing of common code.

Packages and namespaces should be defined using your top level domain, your organization domain, and sub-domain. For example, the Google Maps namespace is defined as com.google.maps and an examples package within that namespace would be defined as com.google.maps.examples. You can then use this namespace to implicitly define the directory structure of your application (e.g. com/google/maps/examples/).

You will use this namespace to define a package within your ActionScript code, and to define your application within the MXML declaration. Generally, ActionScript code (*.as files) reside within the bottommost directory of whatever namespace is defined, while the MXML declarations (*.mxml files) reside at the "root" of the directory structure.

Versioning

The Google Maps API for Flash interface library contains the ActionScript interfaces that allow you to communicate with the actual components provided through Google's runtime library. Occasionally, we will make updates to these components "under the hood." As long as the interfaces do not change, you don't need to do anything. The interface SWC file will automatically pick up the latest changes.

If we introduce new functionality and features (and therefore need to update the interfaces), we will also need to update the interface SWC file, which we will provide for download. Such versions will be named according to the version scheme. (For example, the interface library associated with version "1.3" will be named "map_flex_1_3.swc." You will need to download a new version of this interface library before you can make use of these latest features. Make sure you monitor the Google Maps API group or blog to ensure you receive announcements for new versions of the Google Maps API for Flash.

You may set your application to use a hard-coded version of the Maps API for Flash library by setting the Map's version property to a specific version. Note that this is not recommended as you will not benefit from any enhancements or bug fixes to the current implementation.