Creating a hierarchy of geospatial objects

Geospatial objects are a convenient way to either import a KML document into your application, or to group objects together for organizational purposes. If your application needs to convert information from a KML document into mappable objects, you can retain the hierarchy of the elements by using the GsFolder and GsRoot classes. However, if you want to add the objects from the hierarchy to a map, you must add the objects individually. If you attempt to add the root or a folder of a tree to a map's MapDataModel, the objects are not rendered on the map.

The net.rim.device.api.lbs.maps.model.geospatial package contains the following classes that are required for creating a hierarchy of mappable elements.

Class or interface

Description

GsRoot

Represents the top-level container for a hierarchy of GsElement objects and StyleSet objects that are used to render the content.

GsFolder

Represents a folder where you can store GsElement objects, as well as GsRoot objects that contain groups of GsElement objects.

GsElement

Defines the interface that is implemented by all geospatial classes

GsElementEnumeration

Allows you to enumerate through a collection of GsElements objects

Organizing geospatial objects in a folder

The following code sample demonstrates how to create a hierarchy of geospatial objects. The sample has two different GsRoot objects, each of which contains an array of geospatial objects. The GsRoot objects are contained within a folder.

GsPoint[] gsPoints = new GsPoint[3];
gsPoints[0] = new GsPoint(45.05, -75.0, "Point 1", "Description.");
gsPoints[1] = new GsPoint(45.0, -74.95, "Point 2", "Description.");
gsPoints[2] = new GsPoint(44.95, -74.975, "Point 3", "Description.");

GsRoot pointRoot = new GsRoot("Root 1", "This root contains points.", 
        gsPoints);
            
GsMarker[] gsMarkers = new GsMarker[3];
gsMarkers[0] = new GsMarker(44.95, -75.025, "Marker 1", "Description.", 
        "http://www.rim.com/products/appworld_3col.jpg");
gsMarkers[1] = new GsMarker(45.0, -75.05, "Marker 2", "Description.", 
        "http://www.rim.com/products/appworld_3col.jpg");
gsMarkers[2] = new GsMarker(45.05, -75.0, "Marker 3", "Description.", 
        "http://www.rim.com/products/appworld_3col.jpg");
            
GsRoot markerRoot = new GsRoot("Root 2", "This root contains markers", 
        gsMarkers);
            
GsFolder folder = new GsFolder("Folder", "The folder holds the root elements.");
folder.addElement(pointRoot);
folder.addElement(markerRoot);

Was this information helpful? Send us your comments.