Adding a map to an application

Search This Document

Download PDF

You can add a map to an application by using the MapField class and RichMapField class, which are provided in the net.rim.device.api.lbs.maps.ui package. For example, you can create an application that displays a map that shows the BlackBerry device user's current location and points of interest in the surrounding area.

The MapField class extends the net.rim.device.api.ui.Field class. You can use MapField to add the following functionality to your application:

Rendering a map in a UI field
Panning and zooming the map by using the keyboard, trackpad, trackball, or touch screen

The RichMapField class extends the functionality of MapField. You can use RichMapField to add the following features to your application:

Utility fields on the map, such as a center target, zoom indicator, and a hint field
Fields that overlay a map
Shared focus with other UI components on a screen to allow users to navigate through map field components to other components on the screen

You can specify the behavior for a map when it displays in a map field by using the methods defined in the MapAction class. For example, when the application opens and displays the map, you can invoke setCentreAndZoom(MapPoint centre, int zoom) to set the center and the zoom level of the map. By default, the center coordinates are (0,0) and the zoom level is set to the maximum value of 15.

You can identify and respond to the actions the user performs in a map field by invoking addChangeListener() to register the map field as a listener and then using the constants that are defined in the MapAction class. For example, MapAction.ACTION_ZOOM_CHANGE indicates that the user changed the zoom level.

Each MapField or RichMapField instance uses a thread to render a map. For example, if an application has two MapField instances running at the same time, two threads are used. The thread ends when the MapField instance is processed for garbage collection. You should make sure the application does not exceed the limit of available threads. To end the thread for the MapField or RichMapField instance, you must invoke close(), which removes the field as a listener from specific classes and allows all appropriate classes to be processed for garbage collection.

Code sample: Adding a map by using the MapField class

MapField map = new MapField();
add(map);

Code sample: Adding a map by using the RichMapField class

RichMapField map = MapFactory.getInstance().generateRichMapField();
add(map);

Code sample: Responding to changes in a MapField

class MapFieldListener implements FieldChangeListener
{
    public MapFieldListener ()
    {
        MapField map = new MapField();
        map.addChangeListener(this);
    }

    public void fieldChanged( Field field, int actionId )
    {
        switch ( actionId )
        {
            case MapAction.ACTION_CENTRE_CHANGE:
                break;
            case MapAction.ACTION_ZOOM_CHANGE:
                break;
        }
    }
}

Add a map to an application

The following steps describe how to add a map to an application by using the RichMapField class, and how to set the center and zoom level of the map. The resulting map in the application is shown in the following image:

This screen shows a RichMapField with a specified center and zoom level.

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.*;

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 MapScreen class, which is described in step 3, represents the custom screen.
```
public class RichMapFieldDemo extends UiApplication
{
    public static void main(String[] args)
    {
        RichMapFieldDemo theApp = new RichMapFieldDemo();
        theApp.enterEventDispatcher();
    }
    public RichMapFieldDemo()
    {
        pushScreen(new MapScreen());
    }
}
```

Create the framework for the custom screen by extending the FullScreen class. In the constructor, invoke super() to create a default menu.

class MapScreen extends FullScreen
{
    public MapScreen() 
    {
        super( FullScreen.DEFAULT_CLOSE | FullScreen.DEFAULT_MENU );
    }
}

In the screen constructor, invoke MapFactory.getInstance() to create an instance of the MapFactory class and then invoke generateRichMapField() to generate the RichMapField.
```
RichMapField map = MapFactory.getInstance().generateRichMapField();
```
In the screen constructor, invoke getAction() to create an instance of the MapAction class. Invoke setCentreAndZoom() to specify the center and zoom level of the map. Invoke add() to add the field to the screen.
```
MapAction action = map.getAction();
action.setCentreAndZoom(new MapPoint(43.47462, -80.53820), 2);
add(map);
```

Code sample: Adding a map to an application

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.*;

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

class MapScreen extends FullScreen
{
    public MapScreen() 
    {
        super( FullScreen.DEFAULT_CLOSE | FullScreen.DEFAULT_MENU );
        RichMapField map = MapFactory.getInstance().generateRichMapField();
        MapAction action = map.getAction();
        action.setCentreAndZoom(new MapPoint(43.47462, -80.53820), 2);   
        add(map);
    }
}

Next topic: Navigation

Previous topic: Displaying KML overlays on a map

Was this information helpful? Send us your comments.

Global Navigation

Development Guide

Local Navigation