Google Maps API for Flash Basics

Latitudes and Longitudes

In the tutorials, we showed you how to initialize a map so that it is centered on a location using a LatLng object. This LatLng object provides the fundamental way to refer to locations on the map within the Google Maps API for Flash. You construct a LatLng object by passing its parameters in the order { latitude, longitude } as is customary in cartography:

var myGeographicCoordinates:LatLng = new LatLng(myLatitude, myLongitude);

Note: the process of turning an address into a geographic point is known as geocoding and is discussed in detail in the Google Maps API for Flash Services section.

Just as it is useful to easily refer to a geographic point, it is also useful to define the geographic bounds of an object. For example, a map displays a current "window" of the entire world within what is known as a viewport. This viewport can be defined by the rectangular points at its corners. The LatLngBounds object provides this functionality, defining a rectangular region using two LatLng objects representing the southwest and northeast corners of the bounding box, respectively.

LatLng objects have many uses within this API. The com.google.maps.overlays.Marker object takes a LatLng in its constructor, for example, and places a marker overlay on the map at the given geographic location.

The following example uses getLatLngBounds() to return the current viewport, and then randomly places 10 markers on the map within those bounds:

private function onMapReady(event:MapEvent):void {
  map.setCenter(new LatLng(37.4419, -122.1419), 13, MapType.NORMAL_MAP_TYPE);

  // Add 10 markers to the map at random locations
  var bounds:LatLngBounds = getLatLngBounds();
  var southWest:LatLng = bounds.getSouthWest();
  var northEast:LatLng = bounds.getNorthEast();
  var lngSpan:Number = northEast.lng() - southWest.lng();
  var latSpan:Number = northEast.lat() - southWest.lat();
  for (var i:int = 0; i < 10; i++) {  
      var newLat:Number = southWest.lat() + (latSpan * Math.random());
      var newLng:Number = southWest.lng() + (lngSpan * Math.random());
      var latlng:LatLng = new LatLng(newLat, newLng);
      map.addOverlay(new Marker(latlng));
  }
}

View example (MapMarkers.html)

View Source (MapMarkers.mxml)

Note: more information on Marker objects is within the Overlays section.

Initializing Your Map with MapOptions

In the previous tutorials, we've shown you how to initialize a map within a MapEvent.MAP_READY event handler. However, this event is not ideal for setting common initialization parameters such as a map's center, zoom level, or MapType as this event is only triggered after a default map has already been drawn. Setting those map parameters within this handler requires the map to reposition and redraw itself, which is inefficient.

The Google Maps API for Flash provides an alternative event exclusively for handling and setting up common map options: MapEvent.MAP_PREINITIALIZE. This event is triggered after a map is ready to receive initialization parameters, but before the map is ready for general use. In fact, only one Map method is allowed within this event handler: the Map.setInitOptions() method, which passes a MapOptions object.

To initialize a Map using a MapOptions object, follow these steps:

1. Declare a MapEvent.MAP_PREINITIALIZE event handler, either within ActionScript code, or within the MXML mapevent_mappreinitialize parameter.
2. Define the event handler itself, generally as a private function.
3. Within that event handler, create a MapOptions object and assign its properties.
4. Call the setInitOptions() method on the Map, passing in the defined MapOptions. Note that setInitOptions should only be called within this MapEvent.MAP_MAPPREINITIALIZE event.

The MapOptions object supports a set of initialization parameters for your Map object. A full list of parameters is available within the MapOptions API Reference.

The following code sets up a map with a variety of options. Note that we set up the center, zoom, and MapType entirely within the onMapInitialization() event.

	
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
  <maps:Map xmlns:maps="com.google.maps.*" mapevent_mappreinitialize="onMapPreinitialize(event)" 
	 id="map" width="100%" height="100%" key="your_api_key"/>
  <mx:Script>
	<![CDATA[

	import com.google.maps.LatLng;
	import com.google.maps.Map;
	import com.google.maps.MapEvent;
	import com.google.maps.MapType;
	import com.google.maps.MapOptions;

	private function onMapPreinitialize(event:Event):void {
	  var myMapOptions:MapOptions = new MapOptions();
	  myMapOptions.zoom = 14;
	  myMapOptions.center = new LatLng(40.736072,-73.992062);
	  myMapOptions.mapType = MapType.NORMAL_MAP_TYPE;
	  this.map.setInitOptions(myMapOptions);
	}
	
	]]>
  </mx:Script>
</mx:Application>

View example (MapOptionsInit.html)

View Source (MapOptionsInit.mxml)

Setting Your API Key

The tutorials illustrated several ways to declare your maps API key within a Google Maps API for Flash application:

• (Flex) Within the MXML Map's key parameter.
• (Flash CS3) Within ActionScript code by setting the Map's key parameter directly.
• (Flex and Flash) Within HTML <object> and <embed> tags (using the flashVars parameter).

These methods are described below as well.

Setting Your API Key Within Flex Applications

For Flex applications, you should set the Map's key directly within the MXML declaration. The following MXML declaration demonstrates this usage.

<maps:Map xmlns:maps="com.google.maps.*" id="map" mapevent_mapready="onMapReady(event)" 
  width="100%" height="100%" key="your_api_key"/>

Setting the map's key within MXML compiles the API key into the resulting SWF file directly, and is equivalent to setting the key property within the Map constructor; the key will be set before the map receives any events or any actions on the map take place.

Setting Your API Key Within Flash CS3 Applications

For Flash applications, no MXML object is being constructed, so instead you will need to set the Map's key within ActionScript code at the first opportunity to do so, before the map receives any events or any actions take place.

import com.google.maps.LatLng;
import com.google.maps.Map;
import com.google.maps.MapEvent;
import com.google.maps.MapType;

var map:Map = new Map();
map.key = "your_api_key";

map.addEventListener(MapEvent.MAP_PREINITIALIZE, onMapPreinitialize);

function onMappreinitialize(event:MapEvent):void {
  setInitOptions(
    new MapOptions({
      center: new LatLng(40.736072,-73.992062),
      zoom: 14,
      mapType: MapType.NORMAL_MAP_TYPE
    }));
}

Note that we set the API key immediately after defining the map variable. This is highly encouraged, as the key must be set before the map receives any events, or before any actions take place on the map.

Setting the map's key in this manner also compiles the API key directly into the resulting SWF file.

Setting Your API Key Within HTML

If you do not compile the Google Maps API key into your SWF file directly, you will need to provide it within <object> and <embed> flashVars parameters as shown below:

  <div id="map_canvas" name="map_canvas">
    <object
      classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
      codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=6,0,29,0"
      width="800px"
      height="600px">
      <param name="movie" value="MapSimple.swf">
      <param name="quality" value="high">
      <param name="flashVars" value="key=your_api_key">
      <embed
        width="800px"
        height="600px"
        src="MapSimple.swf"
        quality="high"
        flashVars="key=your_api_key"
        pluginspage="http://www.macromedia.com/go/getflashplayer"
        type="application/x-shockwave-flash">
      </embed>
    </object>
  </div>

If key values are specified here, they override any keys compiled within the SWF file. Also note that the API key must match the domain where the SWF file is hosted, not the domain where the HTML file may be hosted.

Providing an API key within HTML has certain advantages: if you change the domain of your SWF file or share it with others, for example, you need only change the key within the host HTML file. As well, this method works for both Flash and Flex SWF files.

Localization

The Google Maps API for Flash uses the browser's preferred language setting when displaying textual information such as the names for controls, copyright notices, and driving directions. If you wish to change this behavior to ignore the browser's language setting and force it to display information in a particular language, you can directly set a language property on the Map object to a supported language code. As with API keys, you can either set the Map.language property within MXML or ActionScript code, or set the language property within the HTML container's flashVars parameter.

For example, to display a Maps API for Flash application in German, set the language property to de as shown below:

<maps:Map xmlns:maps="com.google.maps.*" id="map" mapevent_mapready="onMapReady(event)" 
  width="100%" height="100%" language="de" key="your_api_key"/>

Note: there is currently an Adobe bug affecting language-detection on Flash players in Internet Explorer 6/7. Be aware that language detection in this browser at this time may not work as intended.

See also the FAQ on the supported list of domain languages. Note that we often update supported languages so this list may not be exhaustive.

Map Attributes

By default, maps show up within the Google Maps API for Flash using standard "painted" tiles. However, the Flash API also supports other maps types. The following map types are standard:

• NORMAL_MAP_TYPE- the default view
• SATELLITE_MAP_TYPE - showing Google Earth satellite images
• HYBRID_MAP_TYPE - showing a mixture of normal and satellite views
• PHYSICAL_MAP_TYPE - showing a physical relief map of the surface of the Earth
• DEFAULT_MAP_TYPES - an array of these four types, useful for iterative processing

You can set the map type using the MapOptions' mapType property. For example, the following code sets the map to use the satellite view from Google Earth:

private function onMapPreinitialize(event:Event):void {
  var myMapOptions:MapOptions = new MapOptions();
  myMapOptions.zoom = 14;
  myMapOptions.center = new LatLng(40.736072,-73.992062);
  myMapOptions.mapType = MapType.SATELLITE_MAP_TYPE;
  this.map.setInitOptions(myMapOptions);
}

A map also contains a number of attributes that are useful to ascertain. For example, to find the dimensions of the current viewport, use the Map interface's getLatLngBounds() method to return a LatLngBounds value.

Each map also contains a zoom level, which defines the resolution of the current view. Zoom levels between 0 (the lowest zoom level, in which the entire world can be seen on one map) to 19 (the highest zoom level, down to individual buildings) are possible within the normal maps view. Zoom levels vary depending on where in the world you're looking, as data in some parts of the globe is more defined than in others. Zoom levels up to 20 are possible within satellite view.

You can retrieve the current zoom level in use by the map by using the Map interface's getZoom() method.

Map Interactions

Now that you have an implementation of the Map interface, you can interact with it. The basic map object looks and behaves a lot like the map you interact with on the Google Maps website and comes with a lot of built-in behavior. The Map interface also provides a number of configuration methods to alter the behavior of the map object itself.

By default, map objects tend to react to user activity as they do on http://maps.google.com. You can alter this behavior with a number of utility methods, however. For example, the Map.disableDragging() method disables the ability to click and drag the map to a new location.

You can also interact with the map programmatically. The Map interface provides a number of methods that alter the map state directly. For example, the setCenter(), panTo(), and zoomIn() methods operate on the map programatically, rather than through user interaction.

The following example displays a map, waits two seconds, and then pans to a new center point. The panTo method centers the map at a given point. If the specified point is in the visible part of the map, then the map pans smoothly to the point; if not, the map jumps to the point.

// Note: this example uses the best practice of using a Timer object
private function onMapReady(event:MapEvent):void {
  map.setCenter(new LatLng(37.4419, -122.1419), 13, MapType.NORMAL_MAP_TYPE);
  myTimer = new Timer(1000, 1);
  myTimer.addEventListener("timer", timedFunction);
  myTimer.start();
}

private function timedFunction(eventArgs:TimerEvent):void {
  map.panTo(new LatLng(37.4569, -122.1569));
  trace("Timer fired " + myTimer.currentCount + " times.");
}

View example (MapAnimate.html)

View Source (MapAnimate.mxml)

Info Windows

Each map within the Google Maps API for Flash may show a single "info window" of type InfoWindow, which displays text or HTML. The info window looks a little like a comic-book word balloon; it has a content area and a tapered stem, where the tip of the stem is at a specified point on the map. You can see the info window in action by clicking a marker in Google Maps.

The InfoWindow object has no constructor. An info window is automatically created and attached to the map when you create the map. You can't show more than one info window at a time for a given map, but you can move the info window and change its contents as needed.

The Map object provides an openInfoWindow() method, which takes a LatLng and InfoWindowOptions used to populate the InfoWindow with content. The openInfoWindow() object appends a DisplayObject to the info window container, and the info window window tip is anchored to the given latitude and longitude.

The following example code displays an info window anchored to the center of the map with a simple "Hello, world" message.

private function onMapReady(event:MapEvent):void {
  map.setCenter(new LatLng(37.4419, -122.1419), 13, MapType.NORMAL_MAP_TYPE);
  map.openInfoWindow(getCenter(), new InfoWindowOptions({title: "Hello", content: "World"}));
}

View example (MapInfoWindow.html)

View Source (MapInfoWindow.mxml)

For full documentation on info windows, consult the Google Maps API for Flash Reference