As described in the Architecture section, The VGMap library consists of Javascript code libraries, a compiled Flash component with utility functions, a set of Flash callback functions to implement.

Javascript VGMap Class

The VGMap Javascript class handles the actual DHTML instantiation of your VGMap overlay, and the communication between the GMap API and your VGMap Flash component.

• VGMap (map, mapNodeId, overlayNodeId, vgmPath, debugNodeId)
  Constructor, takes the following parameters:
  • map: reference to already-created GMap object.
  • mapNodeId: XHTML DOM Id that was given in the constructor of the GMap object.
  • overlayNodeId: XHTML DOM Id of the <DIV> element that will house your VGMap overlay.
  • vgmPath: relative URL path to the directory housing your installation of the VGMap library. Most commonly will be 'vgmap/'
  • debugNodeId: XHTML DOM Id of the element where debug messages from the Flash components will be printed. This parameter is Optional
• go (offset, flashFile, flashVars)
  Method to go ahead and write/run your VGMap overlay. Takes the following parameters:
  • offset: size (in pixels) of the area between the border of the GMap and the VGMap overlay. This exists because the VGMap overlay prevents standard mouse events from getting through to the GMap. Typical setting, which is maximally sized but does not overlap any of the GMap controls is 46.
  • flashFile: URL path to the flash file that will handle the V/GMap callbacks and do all the fun data-drawing.
  • flashVars: URL-encoded parameters to be passed to the above Flash component when it is instantiated.

VGMap Flash Component

• Map State:

  The VGMap Flash components give your ActionScript access to the GMap's current state. It maintains a nested data structure that has the same following attributes as the get* methods of the GMap object: http://www.google.com/apis/maps/documentation/#State

  • centerLatLng
    Same values as would be returned by the getCenterLatLng method in the GMap API
    An object with x and y attributes representing the longitude and latitude, respectively.
  • boundsLatLng
    Same values as would be returned by the getBoundsLatLng method in the GMap API
    An object with [min|max]X and [min|max]Y elements representing the minimum and maximum longitude and latitude, respectively.
  • spanLatLng
    Same values as would be returned by the getSpanLatLng method in the GMap API
    An object with width and height elements representing the longitude and latitude spans, respectively.
  • zoomLevel
    Same value as would be returned by the getZoomLevel method in the GMap API
    The current zoomLevel from 0 to 17.

  In the VGMap Flash component, all references to a 'map' variable refer to an object with the above structure.

• VGMap GMap API Event Callbacks:

  Your custom Flash component that is dynamically loaded by the VGMap Flash component will get callbacks corresponding to (most of) the Event callbacks in the GMAp API: http://www.google.com/apis/maps/documentation/#Events_GMap.
  All of the parameters are the same as in the GMap API, except that your callbacks all have an additional 'map' parameter (as described above) as the first argument.

  • GMap_click(map, point, overlay)
  • GMap_movestart(map)
  • GMap_move(map)
  • GMap_moveend(map)
  • GMap_zoom(map, oldzoomlevel, newzoomlevel)
• VGMap Flash Component Utility Functions:

  The VGMap Flash Component has a number of 'methods' that are available to be called directly on the component itself. Typically these will be called on the _root or _parent movie clip.

  • Math/Mapping:

    To do your mapping correctly, there is always some math that has to get done. We have tried to simplify this process by providing utility functions and libraries, but the documentation for how to use them will be woefully inadequate here. Your best bet is just to look at the code in the vgmap/example/ directory, specifically the ll.as file.

    A note on geographic projections: the VGMap includes libraries for handling 3 geographic projections:

    • merc: converts between lat/long and the Mercator Projection.
    • projmerc: converts between lat/long and the Mercator Projection as used in the Proj4 library.
    • latlon: the null transformation.

    For more on these projections, please see the code in the vgmap/flash/lib/gis/projections/ directory.

    Michal Migurski of Stamen Design has put together a great presentation that explains a lot of the GIS projection/transformation issues. Highly recommended, it is available at http://clients.stamen.com/talks/ffnyc/.

    Enough blabbing, on with the documentation:

    • getCurrentMap()
      Get the current 'map' (as described above).
    • getGMapImgBounds()
      Get the bounds of the underlying Google Map image, in the coordinate system of the Flash component
      Returns: object with [min|max]X, [min|max]Y attributes.
    • getGMapProjectedBounds(map, proj)
      Get the bounds of a map in a specified geographic projection.
    • createProjector(proj)
      Create an object for a specified geographic projection. This object will implement the ILinearProjection interface which, as defined in vgmap/flash/lib/gis/projections/ILinearProjection.as, consists of two methods:
      • GPSToMapCoords(lat, long)
        Takes Latitude and Longitude as parameters, and returns an object with x and y attributes.
      • MapToGPSCoords(x, y)
        Takes X and Y as parameters, and returns an object with lat and long attributes.
    • solve2D(e1, e2)
      Solve the 2D linear equation to scale/translate from one linear system to another.
      Parameters: 2 objects, each with a from and to attibute.
      Returns: object with scale, translation, and func attributes which are the scale, translation, and functional transformation between the from system and the to system.
  • Flash/Javascript Communications:
    • createJavascriptProxy(lcId)
      Create a JavascriptProxy object from the Flash/Javascript Integration Kit. Use this if you want to communicate between your Flash Component and Javascript executing in the browser in ways that are separate from the GMap API. Since this requires an lcId, you will want to create that in Javascript and pass it in as part of the flashVars parameter of the go method on the VGMap Javascript object.
  • Debugging:
    • debugMsg(msg, clear)
      Send a the msg string out to the XHTML element specified by the debugId parameter to the VGMap Javascript Class' constructor. The optional clear parameter will cause the debug element to be cleared before adding this message.
    • traceObject(obj)
      Recurse over a nested data structure and trace it out, also return it as a string.