Google Maps API for Flash Overlays

Map Overlays Overview

Overlays are objects on the map that are tied to latitude/longitude coordinates, so they move when you drag or zoom the map. Overlays reflect objects that you "add" to the map to designate points, lines, or areas.

The Maps API has several types of overlays:

• Points on the map are displayed using markers, and often display a custom icon. Markers are objects of type Marker and may use custom visual objects as icons.
• Lines on the map are displayed using polylines (representing a collection of points). Lines are objects of type Polyline.
• Areas on the map are displayed either as polygons if they are areas of an arbitrary shape or as ground overlays if they are rectangular. Polygons are similar to polylines in that they consist of a collection of points with a closed loop and may take any shape. Ground overlays are often used for areas that map either directly or indirectly to tiles on the map.
• The map itself is displayed using a tile overlay. You can modify this with your own set of tiles by using a TileLayerOverlay or even by creating your map type using a MapType.
• The info window is also a special kind of overlay. Note, however, that the info window is added to the map automatically, and that there can only be one object of type InfoWindow attached to a map.

Each overlay extends the IOverlay interface. Overlays can be added to a map using the Map.addOverlay() method and removed using the Map.removeOverlay() method. (Note that the info window is added by default to the map, though it is not initially visible.)

Markers

Markers identify points on the map. The Marker constructor takes a LatLng and an optional MarkerOptions object as arguments. This MarkerOptions objects allows you to override default implementations for markers.

Markers are designed to be interactive. By default, they receive MapMouseEvent.CLICK events, for example, and are often used within event listeners to bring up info windows.

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

  var markerA:Marker = new Marker(
      new LatLng(48.858842, 2.346997),
      new MarkerOptions({
		  strokeStyle: new StrokeStyle({color: 0x987654}),
		  fillStyle: new FillStyle({color: 0x223344, alpha: 0.8}),
		  radius: 12,
		  hasShadow: true
      }));
  addOverlay(markerA);
}

View example (MarkerSimple.html)

View ActionScript code (MarkerSimple.as)

Draggable Markers

Markers are interactive objects that can be clicked on and dragged to a new location. In this example, we place a draggable marker on the map, and listen to a few of its simpler events. Draggable markers implement four events to indicate their drag status: CLICK, DRAG_START, DRAG and DRAG_END. By default, markers are clickable but not draggable, so they need to be initialized with the additional MarkerOption property draggable set to true.

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

  var marker:Marker = new Marker(getCenter(), new MarkerOptions({draggable: true}));
  var map:Map = this;
  marker.addEventListener(MapMouseEvent.DRAG_START, function(event:Event):void {
    map.closeInfoWindow();
  });

  marker.addEventListener(MapMouseEvent.DRAG_END, function(event:Event):void {
    marker.openInfoWindow(new InfoWindowOptions({content:"Just bouncing along..."}));
  });

  addOverlay(marker);
}

View example (MarkerDrag.html)

View ActionScript code (MarkerDrag.as)

Icons

By default, markers use the standard Google mini-balloon shown on maps.google.com to indicate placements. You may modify the standard display of a Marker by specifying MarkerOptions upon construction of the marker. For example, if the Marker is constructed with a MarkerOptions.label property, the marker will also show that alpha-numeric character within the marker geometry.

Markers may also define a graphic DisplayObject to show in place of the default icon. Icons are generally defined by setting the following properties:

• icon defines the icon as a DisplayObject.
• iconAlignment defines how the icon is anchored to the reference point for the marker's location. The following values are valid:
  • ALIGN_TOP
  • ALIGN_BOTTOM
  • ALIGN_RIGHT
  • ALIGN_LEFT
  • ALIGN_HORIZONTAL_CENTER
  • ALIGN_VERTICAL_CENTER
• iconOffset defines an offset (used in tandem with the iconAlignment above) as a Point {x,y} pixel value.

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

  var markerA:Marker = new Marker(
      new LatLng(48.858842, 2.346997),
      new MarkerOptions({
		  strokeStyle: new StrokeStyle({color: 0x987654}),
		  fillStyle: new FillStyle({color: 0x223344, alpha: 0.8}),
		  radius: 12,
		  hasShadow: true
      })
  );
  addOverlay(markerA);
}

View example (IconSimple.html)

View ActionScript code (IconSimpleSimple.as)

Polylines

Polyline objects create a linear overlay on the map. A Polyline consists of a series of points and creates a series of line segments that connect those points in an ordered sequence.

Drawing Polylines

Polylines are drawn as a series of straight segments on the map. You can specify custom colors, weights, and opacities for the line. Colors should be in hexadecimal numeric HTML style, e.g., use #ff0000 instead of red. Polyline does not understand named colors.

The following code snippet creates a 4-pixel-wide red polyline between two points:

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

  // Polyline overlay.
  var polyline:Polyline = new Polyline([
      new LatLng(37.4419, -122.1419),
      new LatLng(37.4519, -122.1519)
      ], new PolylineOptions({ strokeStyle: new StrokeStyle({
	    color: 0xFF0000,
	    thickness: 4,
	    alpha: 0.7})
  }));
    	
  addOverlay(polyline);
}

View example (PolylineSimple.html)

View ActionScript code (PolylineSimple.as)

Encoded Polylines

The Polyline object within a Google map denotes a line as a series of points, making it easy to use but not necessarily compact. Long and complicated lines require a fair amount of memory, and often may take longer to draw. Also, the individual segments within an unencoded polyline are drawn on the map regardless of their resolution at larger zoom levels.

The Google Maps API for Flash allows you to represent paths using encoded polylines, which specify a series of points within a Polyline using a compressed format of ASCII characters.

An encoded Polyline appears below (for now, don't worry about particulars of the encoding algorithm).

// Add an encoded polyline.
var encodedPoints:String = "iuowFf{kbMzH}N`I@yzCv^k@?mI";
var encodedLevels:String = "B?B";
 
var encodedPolyline:Polyline = Polyline.fromEncoded(
    new EncodedPolylineData(encodedPoints, 32, encodedLevels, 4), 
    new PolylineOptions({ strokeStyle: new StrokeStyle({
        color: 0x0000ff,
        thickness: 4,
        alpha: 0.7})
    }));
addOverlay(encodedPolyline);
}

There are two things to notice about this code.

1. First, the series of points is represented as a series of ASCII characters in the encoded polyline, while familiar latitude and longitudes are used in the basic Polyline. The algorithm for creating these points as a series of encoded ASCII values is documented here. This algorithm is needed if you wish to calculate encoded polylines on the fly via a server process, for example..
2. Second, the encoded polyline also allows you to specify the maximum zoom level for each line segment to draw itself on a Google map. If a point is not shown on a higher zoom level, the path is simply drawn from the previous displayable point to the next displayable point. Note that this feature is not available within non-encoded Polylines and is especially useful for allowing fast drawing at high zoom levels, where the details of some line segments may not be relevant. For example, an encoded polyline representing a drive from New York City to Chicago should not care about the line segments representing particular streets in Manhattan when the map is zoomed out to the state level.

View example (PolylineEncoding.html)

View ActionScript code (PolylineEncoding.as)

See Polyline Algorithm for information on the underlying encoded polyline algorithm.

Polygons

Polygon objects are similar to Polyline objects in that they consist of a series of points in an ordered sequence. However, instead of being open-ended, polygons are designed to define regions within a closed loop. As with polylines, you can define custom colors, weights, and opacities for the edge of the polygon (the "line") and custom colors and opacities for the fill area within the enclosed region. Colors should be in hexadecimal numeric HTML style.

The following code snippet creates a 10-pixel-wide box around four points. Note that this polygon is "closed" by returning the segment path to its initial point; you should always close polygons to avoid undefined behavior.

private function onMapReady(event:MapEvent):void {
  setCenter(new LatLng(37.4419, -122.1419), 13, MapType.NORMAL_MAP_TYPE);
  addControl(new ZoomControl());
  var latlng:LatLng = getCenter();
  var lat:Number = latlng.lat();
  var lon:Number = latlng.lng();
  var latOffset:Number = 0.01;
  var lonOffset:Number = 0.01;
  var polygon:Polygon = new Polygon([
      new LatLng(lat, lon - lonOffset),
      new LatLng(lat + latOffset, lon),
      new LatLng(lat, lon + lonOffset),
      new LatLng(lat - latOffset, lon),
      new LatLng(lat, lon - lonOffset)
      ], 
      new PolygonOptions({ 
      strokeStyle: new StrokeStyle({
          color: 0x0000ff,
          thickness: 4,
          alpha: 0.7}), 
      fillStyle: new FillStyle({
          color: 0x0000ff,
          alpha: 0.7})
  }));
  addOverlay(polygon);      
}

View example (PolygonSimple.html)

View ActionScript code (PolygonSimple.as)

Ground Overlays

Polygons are useful overlays to represent arbitrarily-sized areas, but they cannot display images. If you have an image that you wish to place on a map, you can use a GroundOverlay object. The constructor for a GroundOverlay takes a URL of an image and the LatLngBounds of the image as parameters.

The following example places an antique map of Newark, NJ on the map as an overlay:

private function onMapReady(event:MapEvent):void {
  setCenter(new LatLng(37.4419, -122.1419), 13, MapType.NORMAL_MAP_TYPE);
  addControl(new ZoomControl());
  addControl(new MapTypeControl());
        
  var map:Map = this;
  // GroundOverlay overlay.
  var testLoader:Loader = new Loader();
  var urlRequest:URLRequest = new URLRequest(
      "http://www.lib.utexas.edu/maps/historical/newark_nj_1922.jpg");
  testLoader.contentLoaderInfo.addEventListener(
      Event.COMPLETE,
      function(e:Event):void {
          var groundOverlay:GroundOverlay = new GroundOverlay(
              testLoader,
              new LatLngBounds(new LatLng(40.716216,-74.213393), new LatLng(40.765641,-74.139235)),
              0,
              new GroundOverlayOptions(
                  { name: "TestGroundOverlay",
                  description: "Test of GroundOverlay functionality" }));
          map.addOverlay(groundOverlay);
  });
  testLoader.load(urlRequest);
}

View example (GroundOverlaySimple.html)

View ActionScript code (GroundOverlaySimple.as)