netfunctional.mapoverlay Module

Description

The netfunctional.mapoverlay module extends the functionality of the Titanium.Map module with the geometric shape and image overlay capabilities introduced with iOS 4.0.

netfunctional.mapoverlay enables the superimposition of opaque and translucent geometric shapes and image file data over specific geographic locations within native map views for iPad and iPhone devices. Polygon, polyline, circle and raster image overlays are possible, with color, transparency and other style information specified from your Titanium project's javascript code. Overlay graphical atmospheric data, custom business region maps, or broadcast/service coverage areas within a slick native iOS map view, all through a few simple javascript statements.

Accessing the netfunctional.mapoverlay Module

To access this module from JavaScript, you would do the following:

var nfm = require("netfunctional.mapoverlay");

The nfm variable is a reference to the Module object.

You can then create a netfunctional.mapoverlay.MapView object in the same way you would create a Titanium.Map.MapView object, through the module's createMapView function:

var myMapView = nfm.createMapView({});

Note: Before a project can make use of this module, the module's zip archive must be added to the global titanium modules directory ("/Library/Application Support/Titanium") and unpacked, and a reference to the netfunctional.mapoverlay module must be created in each dependent project's tiapp.xml file. The module section of tiapp.xml should look something like this:

<modules>
    <module version="1.0">netfunctional.mapoverlay</module>
</modules>

Reference

netfunctional.mapoverlay.createMapView(args)

Description:

This function behaves exactly the same as the Titanium.Map.createMapView function. It returns a netfunctional.mapoverlay.MapView object which has the same api and behaves identically to a Titanium.Map.MapView object with the addition of the polygon, circle and image overlay functionality documented here.

Parameters:

args: A dictionary object defining the characteristics of the map view. See the documentation for Titanium.Map.MapView for information on the parameters that can be set.

netfunctional.mapoverlay.MapView.addOverlay(args)

Description:

This function adds an overlay to the map view based on the overlay definition specified in the args dictionary object. An application programmer can use this method to add polygon, circle and image overlays to the MapView object they created using the netfunctional.mapoverlay.createMapView() method.

Parameters:

args: A dictionary object defining the overlay to be created in the mapview. Below we will describe each of the different parameters within args used to specify details of an overlay.

name: The name that will be used to reference the overlay within this mapview object. If an overlay needs to be removed, you will reference it using this name, and if a new overlay is added to the mapview with the same name as a previously added overlay, the old overlay will be removed and a new one created using the newer data. This is a required parameter.

type: Programmers specify what type of overlay they wish to create by setting the type key in the args dictionary object. Valid values are 'polygon', 'circle' and 'image'. Depending on whether the programmer specifies the type as polygon, circle or image, the other parameters expected in args will differ. See the Usage section below for examples on how to create overlays of each type.

width: The line width to use for drawing the outline of the overlay. Real/Floating point number. Only valid for polygon and circle type overlays.

strokeColor: The color to use when drawing the outline of an overlay. Defaults to "blue". Only valid for polygon and circle type overlays.

strokeAlpha: The real number alpha transparency value to use when drawing the outline of an overlay. Defaults to 1.0. Only valid for polygon and circle type overlays.

fillColor: The color to use when drawing the interior of an overlay. Defaults to whatever strokeColor has been set to. Only valid for polygon and circle type overlays.

fillAlpha: The real number alpha transparency value to use when drawing the outline of an overlay. Defaults to 0.5. Only valid for polygon and circle type overlays.

radius: The radius in meters to use for a circular overlay. Only valid for circle type overlays.

center: A dictionary object specifying the latitude and longitude of the origin point for a circular overlay. Only valid for circle type overlays.

points: An array of tuples, each containing a longitude and latitude pair, specifying a vertex of the polygon overlay to be displayed. The array has each vertex in the order that the polygon edges should be drawn, and the last vertex specified should be the same as the starting point coordinates so that the polygon is closed. Only valid for polygon type overlays.

northWestCoord: A longitude/latitude coordinate pair which specifies the coordinates on the map where the top left/north west corner of the image overlay graphic data should be placed. The image will be stretched from this point such that it's bottom right corner meets the coordinates specified by southEastCoord. Only valid for image type overlays.

southEastCoord: A longitude/latitude coordinate pair which specifies the coordinates on the map where the bottom right/south east corner of the image overlay graphic data should be placed. The image will be stretched from this point such that it's top left corner meets the coordinates specified by northWestCoord. Only valid for image type overlays.

alpha: The real numbered alpha transparency value to use for an image overlay. Defaults to 0.9. Only valid for image type overlays.

img: String value. The resource path to the image file to be used for an image overlay. The path should be relative to your project's Resources directory. Must include full image file name. Only valid for image type overlays.

Usage

Example Tasks

Create a netfunctional.mapoverlay.MapView

#initialize the module  
var nfm = require('netfunctional.mapoverlay');  

#create the map view
var mapview = nfm.createMapView({  
    top:44,  
    left:250,  
    bottom:44,  
    right:0,  
    mapType: Titanium.Map.HYBRID_TYPE,  
    animate:true,  
    region: {  
         latitude:33.126865,  
         longitude:-117.266847,  
         latitudeDelta:100,  
         longitudeDelta:100  
    },  
});

#add the mapview to your window
win1.add(mapview);

Add a polygon overlay to your netfunctional.mapoverlay.MapView

#First create an object defining the properties of our overlay
var polyOverlayDef = {
    name:"pOverlay1",
    type:"polygon",
    points:[
        {latitude: 32.259265  ,longitude:-64.863281},
        {latitude: 18.354526  ,longitude:-66.049805},
        {latitude: 25.839449  ,longitude:-80.244141}
    ],
    strokeColor: "purple",
    strokeAlpha: 0.9,
    fillColor: "blue",
    fillAlpha: 0.5
};

#Call the addOverlay function of our `netfunctional.mapoverlay.MapView` object with the data for our polygon overlay as parameter
mapview.addOverlay(polyOverlayDef);

Add a circle overlay to your netfunctional.mapoverlay.MapView

//#First create an object defining the properties of our overlay
var circleOverlayDef = {
    name:"broadcastRange",
    type:"circle",
    center:{latitude:42.814243,
        longitude:-73.939569
    },
    radius:160000, //approximates 1000 miles
    strokeColor: "red",
    strokeAlpha: 0.9,
    fillColor: "orange",
    fillAlpha: 0.5,
    width:1
};

#Call the addOverlay function of our `netfunctional.mapoverlay.MapView` object with the data for our circle overlay as parameter
mapview.addOverlay(circleOverlayDef);

Add an image overlay to your netfunctional.mapoverlay.MapView

//#First create an object defining the properties of our overlay
var imageOverlayDef = {name:'floridaWeatherMap',
    type:'image',
    northWestCoord:{latitude:30,longitude:-85},
    southEastCoord:{latitude:27.5,longitude:-80},
    alpha:0.9,
    img:'data/mapImageOverlay.png'  //the path to the image file within and relative to our project's Resources directory.
});

#Call the addOverlay function of our `netfunctional.mapoverlay.MapView` object with the data for our image overlay as parameter
mapview.addOverlay(imageOverlayDef);

Remove an overlay from your netfunctional.mapoverlay.MapView

Removing an overlay is as simple as calling the netfunctional.mapoverlay.MapView's removeOverlay method with the dictionary object you used to create the overlay. For instance, to remove the overlays created in the usage examples for addOverlay, issue the following statements:

mapview.removeOverlay(imageOverlayDef);
mapview.removeOverlay(circleOverlayDef);
mapview.removeOverlay(polyOverlayDef);

removeOverlay can also be called with a dictionary object containing only the name key to specify the name of the overlay to be removed. e.g.

mapview.removeOverlay({name:"floridaWeatherMap"});
mapview.removeOverlay({name:"broadcastRange"});
mapview.removeOverlay({name:"pOverlay1"});

will similarly remove the three overlays created in the usage examples for addOverlay

Add a polyline to your netfunctional.mapoverlay.MapView

//#First create an object defining the properties of our polyline
var polylineDef = {
        name:'tripRoute',
            points : [
                    {longitude:-73.939569, latitude : 42.814243},
                    {longitude:-74.970703, latitude :39.842286},
                    {longitude:-74.970703, latitude :38.548165},
                    {longitude:-74.355469, latitude :36.809285},
                    {longitude:-73.916016, latitude :35.173808},
                    {longitude:-73.300781, latitude :33.28462},
                    {longitude:-73.212891, latitude :31.877558},
                    {longitude:-72.421875, latitude :29.53523},
                    {longitude:-71.542969, latitude :28.767659},
                    {longitude:-71.191406, latitude :27.371767}],
            color : "purple",
            width:3,
            alpha:0.9

});

#Call the addPolyline function of our `netfunctional.mapoverlay.MapView` object with the data for our polyline as parameter
mapview.addPolyline(polylineDef);

Remove a polyline from your netfunctional.mapoverlay.MapView

Removing an overlay is as simple as calling the netfunctional.mapoverlay.MapView's removePolyline method with the dictionary object you used to create the polyline. For instance, to remove the polyline created in the usage example above, issue the following statement:

mapview.removePolyline(polylineDef);

mapview.removePolyline can also be called with a dictionary object containing only the name key to specify the name of the polyline to be removed. e.g.

mapview.removePolyline({name:"tripRoute");

will similarly remove the polyline with name "tripRoute" defined above.

Note that adding a polyline with the same name as a previously added polyline will result in the old polyline being removed before the new definition is added.

Author

NetFunctional Inc. Michael Matan - apps@netfunctional.ca

License

See LICENSE file included in this distribution.