Updating and re-rendering objects on a map

You often need to update information about a mappable object and re-render the object on a map. For example, the name, description, or coordinates of a MapLocation object might change, or you might want to change the appearance of an item on a map in response to a BlackBerry device user's action. You might also want to display the location of a user's BlackBerry Messenger contact, and update the map as the location changes. By creating a class that implements the DynamicMappable interface, you can create mappable objects that are updated dynamically on a map when they change. In addition to the DynamicMappable class, the net.rim.device.api.lbs.maps.model package contains the following set of classes that allow you to create dynamic mappable objects.

Class or interface

Description

DynamicMappable

By implementing this interface on a class that you create, you can create mappable objects with changeable properties that can be updated dynamically on a map.

MappableEventManager

When you create a class that implements DynamicMappable, it must implement the getMappableEventManager method, which returns an object of this class. This class manages the events and listeners for dynamic mappable objects, and initiates updates to maps.

MappableEventListener

You can use this interface to listen for changes to a dynamic mappable object.

MappableChangeEvent

When you want to push updates to a map, you can create an instance of this class which captures the contents of a change event that has occurred with a dynamic mappable object.

To create a dynamic mappable object, you must create a class that implements the DynamicMappable interface. This class stores the old state and the new state for all information that can change. For example, if your application displays the prices of gas at various gas stations, your dynamic mappable class stores the old and new gas price.

Your dynamic mappable class must implement the getEventManager method. When you invoke getEventManager from your main application, the method returns a MappableEventManager object. After you add a dynamic mappable object to a map, the MappableEventManager object is the component that notifies the map when a change occurs, forcing the map to re-render the object. To initiate the update, you must create and trigger a MappableChangeEvent that contains the old state and the new state for the content that is changing.

Creating a class that implements DynamicMappable

The following code sample demonstrates how to create a class that can update the location of an object on a map. The class is called UpdatableMappable, and it extends the MapLocation class and implements the DynamicMappable. In the UpdatableMappable constructor, super() is called to initialize the object in the same way as a MapLocation object is initialized. The MappableEventManager property that is required to implement the DynamicMappable interface, is initialized. It is this instance of the MappableEventManager that enables the UpdatableMappable class to push updates about itself to the map that you add it to.

This class also overrides setLon() and setLat() . When you call one of these methods from your application, the method takes the existing latitude or longitude and stores it as an old value before the class invokes super to set the new value.

public class UpdatableMappable extends MapLocation implements DynamicMappable 
{    
    public MappableEventManager eventManager; 
    public double oldLat;
    public double oldLon;
    
    public UpdatableMappable(double lat, double lon, String name, String description) 
    {
        super(lat, lon, name, description);
        eventManager = new MappableEventManager();
    }
    
    public void setLon(final double lon) 
    {
        oldLon = getLon();
        super.setLon(lon);
    }
    
    public void setLat(final double lat) 
    {
        oldLat = getLat();
        super.setLat(lat);
    }
    
    public MappableEventManager getEventManager() 
    {
        return eventManager;
    }
}

Adding a dynamic mappable object to a map

The following code sample demonstrates how to create a RichMapField object and add a dynamic mappable object to the map's data model.

RichMapField map = MapFactory.getInstance().generateRichMapField();
map.getMapField().getAction().setCenter(new MapPoint( 45.0, -75.0));
add(map);
            
UpdatableMappable mappableObject = new UpdatableMappable(45.0, -75.0, 
        "Map Location", "Dynamic Updates"); 
    
MapDataModel model = map.getModel();
model.add(mappableObject, "dynamic", true);

Updating the dynamic mappable object

The following code sample demonstrates how to set the new values for the latitude and longitude of the dynamic mappable object and initiate an update to re-render the object on a map. You can set the new values for the latitude and longitude by calling the UpdatableMappable.setLat() and UpdatableMappable.setLon() . To push the updates to the map, you can call UpdatableMappable.getEventManager() and trigger a MappableChangeEvent, which contains both the new and old state of the object.

In this example, the old state is represented by a MapPoint that contains the old coordinates. The new state is a reference to updated mappable object. In cases where dynamic mappable objects are frequently an updated with new information (such as when you're tracking a location in near real-time), a dynamic mappable object might be overwritten with new values before the event manager can trigger an event. In these cases, you might want to create and send a copy of the object to ensure that all updates are re-rendered on the map.

The newLat and newLon variables represent the new coordinates for the dynamic mappable object, which are obtained through a separate operation (for example, a request that you send for a user's location, or a web service that pushes location information).

mappableObject.setLat(newLat);
mappableObject.setLon(newLon);

MappableChangeEvent event = new MappableChangeEvent();
event.setOldState(new MapPoint(mappableObject.oldLat, mappableObject.oldLon));
event.setNewState(mappableObject);
mappableObject.getEventManager().triggerEvent(event);

Was this information helpful? Send us your comments.