Creating custom shapes and objects

Creating custom shapes and objects on top of maps is crucial to building integrated BlackBerry applications. For example, you could create an application that integrates with BlackBerry Messenger, and displays a BlackBerry device user's profile picture on a map when the user is near a location. You could also create an application and display a polygon that marks a perimeter for a geofenced area that your application is monitoring. Like any other mappable object, you can customize the appearance of your custom shapes and objects with styles.

The net.rim.device.api.lbs.maps.model package contains the following classes that correspond to basic shapes and objects that you can use as building blocks to create your own objects.

Class

Description

MapPoint

This class represents the coordinates for a location on a map. Sets of MapPoint objects are required for building lines, polylines, and polygons.

MapMarker

This class represents a marker point on the map, similar to a MapPoint object. You can use an image as a MapMarker object.

PeerPoint

This class represents a static location on a map, with accuracy. For example, you can use a PeerPoint object to mark a BlackBerry device user's last location with the accuracy in meters.

MapLine

This class represents a line segment on the map. To create a MapLine object, you must specify MapPoint objects for the start and the end of the line.

MapPolyLine

This class represents a continuous line that is composed of mulitple line segments between an ordered set of MapPoint objects.

MapSimplePolygon

This class represents a simple polygon that is defined by an ordered set of MapPoint objects. The last MapPoint object in the array joins the first object to close the polygon. Simple polygons render faster than complex polygons.

MapComplexPolygon

This class represents a polygon that is composed of an outer boundary (defined as an ordered series of MapPoints), and an inner boundary (zero or more MapSimplePolygons).

MapImage

This class represents an image for a location on a map. You can specify an image, a thumbnail, or a URI for the location. When you specify a thumbnail, the thumbnail displays directly on the map. When the user clicks on the thumbnail and requests more details, the larger image displays.

For some of the classes mentioned in the previous table, a set of corresponding shapes are available in the net.rim.device.api.lbs.maps.model.geospatial package. The difference between the shapes in the net.rim.device.api.lbs.maps.model.geospatial package (called with Gs<shape>) and the basic shapes (called Map<shape>) is that the geospatial shapes can be organized in a tree structure using the GsFolder and GsRoot classes. The geospatial objects can also be assigned names and descriptions.

Creating a MapSimplePolygon object

MapPoint[] points = new MapPoint[6];
points[0] = new MapPoint(45.05, -75.0);
points[1] = new MapPoint(45.0, -74.95);
points[2] = new MapPoint(44.95, -74.975);
points[3] = new MapPoint(44.95, -75.025);
points[4] = new MapPoint(45.0, -75.05);
points[5] = new MapPoint(45.05, -75.0);
MapSimplePolygon poly = new MapSimplePolygon(points);

Creating a GsImage object

GsImage gsImg = new GsImage();
img.setIconUri("http://www.rim.com/products/appworld_3col.jpg");
img.setLat(44.5);
img.setLon(-75.0);
img.setName("App World!");
img.setDescription("BlackBerry App World icon");

Was this information helpful? Send us your comments.