Controlling the behavior of a map

The MapAction class contains the methods and constants that control and modify a map. For example, you can set the initial zoom level of a map, or prevent BlackBerry device users from changing the zoom level.

You can use the methods and constants in the MapAction class to add the following functionality to a map:

  • Initiate actions on a map.
  • Define the behavior for actions that users are allowed to perform on a map.
  • Identify and respond to the events that occur on a map.

Initiating actions on a map

The MapAction class provides a set of methods, each called set<Action>, that you can invoke to perform actions on a map (for example, setRotation). The set methods determine if the action is allowed, and if it's allowed, how the action is performed.

Before you can invoke one of these methods on a map, you must retrieve the MapAction object from the map by calling getAction(). For example, when the application opens and displays the map, you can invoke myMap.getAction().setCenterAndZoom(MapPoint center, int zoom) to set the center and the zoom level of the map.

MapField map = new MapField();
map.getAction().setCenterLatLon( 45.0000, -75.0000 );
map.getAction().setZoom( 0 );

Defining custom behaviors

Each set<Action> method has a corresponding perform<Action> and allow<Action> method. The perform methods customize the behavior that occurs when an action is performed. The allow methods define whether actions are allowed to occur. To use the perform and allow methods, you must extend your class with MapAction and override the appropriate methods.

The following code sample demonstrates how to override the performNavigateNext() and performNavigatePrev() to customize their behavior when a user presses the N (next) or P (previous) keys. The methods invoke super to ensure that the default actions for these methods are still invoked, in addition to the custom actions that are added. This code sample also demonstrates how to prevent the user from zooming by overriding allowSetZoom(int zoom) and returning false.

public class NewMapActions extends MapAction
{
    protected boolean performNavigateNext()
    {
        super.performNavigateNext();
        // Add custom behavior here.

        return true;	
    }
    		
    protected boolean performNavigatePrev()
    {
        super.performNavigatePrev();
        // Add custom behavior here.

        return true;	
    }
    		
    protected boolean allowSetZoom(int zoom)
    {
        return false;	
    }
}

Adding a custom MapAction object to a map

After you create a new MapAction object, you can invoke setAction() on your map to apply the customized MapAction object.

NewMapActions action = new NewMapActions();
map.getMapField().setAction(action);

Responding to changes in a MapField

If you want to identify and respond to the actions that the user performs in a map field, you can invoke addChangeListener() to register the map field as a listener, and then use the constants that are defined in the MapAction class. For example, MapAction.ACTION_ZOOM_CHANGE indicates that the zoom level was changed.

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;
        }
    }
}

Was this information helpful? Send us your comments.