Tagging and setting the visibility for locations on a map

You can assign tags to locations that are stored in a MapDataModel class. Each MapField class has an associated MapDataModel instance. The MapDataModel class that is provided in the net.rim.device.api.lbs.maps.model package, represents a container. You can add locations and associated data for the locations to the container by invoking MapDataModel.add(). Any item and its associated data are considered mappable items in the container.

You can group mappable items by assigning tags to the items (for example, all work locations have a "work" tag). You can invoke MapDataModel.add() or MapDataModel.tag()to tag mappable items in a MapDataModel container. The add() method allows you to add a mappable item to the container and it allows you to specify a tag for the item. The tag() method allows you to specify a tag for a single mappable item that is in the container. Multiple locations can have the same tag (for example, all RIM offices can be tagged "RIM"), and a single location can have multiple tags (for example, a residence can have tags for both "Sarah" and "Paul").

You can specify which tagged items that are stored in MapDataModel are visible or hidden on a map. By default, all items in MapDataModel are visible. For example, you can add the tag "park" to several locations and you can specify that only the locations with the tag "park" are displayed on the map. You can specify the items that are visible on the map by first invoking MapDataModel.setVisibleNone() to turn off the visibility for all items, and then invoking MapDataModel.setVisible() to turn on the visibility for the specified items.

Code sample: Tagging locations by using the MapDataModel.add() method

In the following code sample, three locations are defined, and then added and tagged by invoking the MapDataModel.add() method. Only the locations that have a "RIM" tag are visible on the map.

MapDataModel model = map.getModel();
MapLocation office01 = new MapLocation( 43.47550, -80.53900, "Head Office", null );
MapLocation office02 = new MapLocation( 43.48261, -80.54169, "Manufacturing", null );
MapLocation justinHome = new MapLocation( 43.47751, -80.54817, "Justin - Home", null);
model.add( (Mappable) office01, "RIM");
model.add( (Mappable) office02, "RIM");
model.add( (Mappable) justinHome, "home");
model.setVisibleNone();
model.setVisible( "RIM" );

Tag and set the visibility for locations on a map

The following steps describe how to assign tags to mappable items that are stored in a MapDataModel class. The visibility is set to display locations that have the "work" tag. The resulting map from the application is shown in the following image:

  1. Import the required classes and interfaces.
    import net.rim.device.api.lbs.maps.*;
    import net.rim.device.api.lbs.maps.model.*;
    import net.rim.device.api.lbs.maps.ui.*;
    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.container.*;
  2. Create the application framework by extending the UiApplication class. In main(), create an instance of the new class and invoke enterEventDispatcher() to enable the application to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the application. The MapTagScreen, which is described in step 3, represents the custom screen.
    public class MapTaggingDemo extends UiApplication
    {
        public static void main(String[] args)
        {
            MapTaggingDemo theApp = new MapTaggingDemo();
            theApp.enterEventDispatcher();
        }
        public MapTaggingDemo()
        {
            pushScreen(new MapTagScreen());
        }
    }
  3. Create the framework for the custom screen by extending the FullScreen class. In the constructor, invoke super() to create a default menu.
    class MapTagScreen extends FullScreen
    {
        public MapTagScreen() 
        {
            super(FullScreen.DEFAULT_CLOSE | FullScreen.DEFAULT_MENU | 
                    FullScreen.VERTICAL_SCROLL | FullScreen.VERTICAL_SCROLLBAR);
  4. In the screen constructor, invoke MapFactory.getInstance() to create an instance of the MapFactory class, and then invoke generateRichMapField() to generate the map field. Invoke add() to add the RichMapField instance to the screen.
    RichMapField map = MapFactory.getInstance().generateRichMapField();
    add(map);
  5. Invoke getModel() to create an instance of the MapDataModel class.
    MapDataModel data = map.getModel();
  6. Create instances of the MapLocation class to define the locations. Pass the latitude, longitude, label, and description of each location to the MapLocation objects.
    MapLocation julieHome = new MapLocation( 43.47751, -80.54817, 
            "Julie - Home", null );
    MapLocation headOffice = new MapLocation( 43.47550, -80.53900, 
            "Head Office", null );
  7. Create an integer identifier to represent a mappable item. Assign the mappable item to the identifier by invoking add() to add a location and pass one of the MapLocation objects and a tag for the location to MapDataModel. You can use the identifier to access the item in MapDataModel and assign another tag to a mappable item by invoking tag(), and passing as arguments the identifier and the tag. In the following code sample, two locations are added to MapDataModel, and each location is assigned two tags.
    int julieHomeId = data.add( (Mappable) julieHome, "julie" );
    data.tag( julieHomeId, "home" );
    int headOfficeId = data.add( (Mappable) headOffice, "julie" );
    data.tag( headOfficeId, "work" );
  8. Define two more locations, and invoke add() to add the locations to MapDataModel. Invoke tag() to assign the appropriate tags for the locations.
    MapLocation paulHome = new MapLocation( 43.49487, -80.55335, 
            "Paul - Home", null );
    int paulHomeId = data.add( (Mappable) paulHome, "paul" );
    data.tag( paulHomeId, "home" );
    data.tag( headOfficeId, "paul" );
             
    data.tag( paulHomeId, "sarah" );
    MapLocation manufacturing = new MapLocation( 43.46514, -80.50506, 
            "Manufacturing", null );
    int manufacturingId = data.add( (Mappable) manufacturing, "sarah" );
    data.tag( manufacturingId, "work" );
  9. Turn on visibility for the locations that have the “work” tag. By default, all the locations are visible on the map. Invoke setVisibleNone() to turn the visibility off for all the locations. Invoke setVisible() and pass the "work" tag as an argument to specify that only the locations with the “work” tag are visible on the map.
    data.setVisibleNone();
    data.setVisible( "work" );
  10. Invoke getMapField().update() to update the map view. Pass the Boolean value true to the update method to recalculate the center and zoom level of the map with the visible locations on the map.
    map.getMapField().update(true);
Back To Top

Code sample: Tagging and setting the visibility for locations on a map

The following code sample creates a map, assigns tags to multiple locations, and displays only the locations that have a "work" tag.

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.lbs.maps.*;
import net.rim.device.api.lbs.maps.model.*;
import net.rim.device.api.lbs.maps.ui.*;

public class MapTaggingDemo extends UiApplication
{
    public static void main(String[] args)
    {
        MapTaggingDemo theApp = new MapTaggingDemo();
        theApp.enterEventDispatcher();
    }
    public MapTaggingDemo()
    {
        pushScreen(new MapTagScreen());
    }
}

class MapTagScreen extends FullScreen
{
    public MapTagScreen() 
    {
        super(FullScreen.DEFAULT_CLOSE | FullScreen.DEFAULT_MENU | 
                FullScreen.VERTICAL_SCROLL | FullScreen.VERTICAL_SCROLLBAR);
           
        RichMapField map = MapFactory.getInstance().generateRichMapField();
        add(map);
        
        MapDataModel data = map.getModel();
            
        MapLocation julieHome = new MapLocation( 43.47751, -80.54817, 
                "Julie - Home", null );
        MapLocation headOffice = new MapLocation( 43.47550, -80.53900, 
                "Head Office", null );
        
        int julieHomeId = data.add( (Mappable) julieHome, "julie" );
        data.tag( julieHomeId, "home" );
        int headOfficeId = data.add( (Mappable) headOffice, "julie" );
        data.tag( headOfficeId, "work" );
        
        MapLocation paulHome = new MapLocation( 43.49487, -80.55335, 
                "Paul - Home", null );
        int paulHomeId = data.add( (Mappable) paulHome, "paul" );
        data.tag( paulHomeId, "home" );
        data.tag( headOfficeId, "paul" );
        
        data.tag( paulHomeId, "sarah" );
        MapLocation manufacturing = new MapLocation( 43.46514, -80.50506, 
                "Manufacturing", null );
        int manufacturingId = data.add( (Mappable) manufacturing, "sarah" );
        data.tag( manufacturingId, "work" );
        
        data.setVisibleNone();
        data.setVisible( "work" );
        map.getMapField().update( true );          
    }
}
Back To Top

Was this information helpful? Send us your comments.