Using BlackBerry Maps - BLACKBERRY

We’ve covered basic GPS location functionality. Now let’s see how you can use BlackBerry Maps to display location in a more visual way. BlackBerry Maps is included on devices running OS 4.2 and later, so it is available to most users. The API to interact with BlackBerry Maps is also available on any device that has BlackBerry Maps installed. Prior to OS 4.5 an application could use BlackBerry Maps in a number of ways, including:

  • pen BlackBerry Maps and display the default map view (the last map that the BlackBerry user viewed).
  • pen BlackBerry Maps and display a custom map view (latitude,longitude, and zoom level).
  • open BlackBerry Maps and display a specific location (latitude, longitude, nd zoom level) with a labeled marker.
  • Open BlackBerry Maps and display multiple locations (multiple labeled markers on the same map).
  • open BlackBerry Maps to display a route between locations on a map.

With OS 4.5 and later, the API provides the capability to embed a map control into the UI of a BlackBerry application.

The Invoke API

The net.rim.blackberry.api.invoke package contains classes that let an application interact with some of the BlackBerry system applications, such as email, phone, and BlackBerry Maps. Interaction is managed through the invokeApplication method of the Invoke class. This method takes two arguments: a flag indicating which application is to be invoked and an instance of an ApplicationArguments subclass specific to that application.To launch Maps, you use something like the following:

MapsArguments args = new MapsArguments(); Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, args);

Launching the Default BlackBerry Maps View

The previous code will in fact launch the BlackBerry Maps application with the default (last used) view opened. Let’s add a new menu item and method to LocationMainScreen to do just that. Add the following imports to the top of

import net.rim.blackberry.api.invoke.Invoke;
import net.rim.blackberry.api.invoke.MapsArguments;

Then, make the following changes to LocationMainScreen to add a menu item and a map method containing the previous code:

private void map() {
MapsArguments args = new MapsArguments();
Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, args);
protected void makeMenu(Menu menu, int instance) {
super.makeMenu(menu, instance);
menu.add(new MenuItem("Update", 10, 10) {
public void run() {
menu.add(new MenuItem("Map", 10, 10) {
public void run() {

Run the application and click Map to see the default BlackBerry Maps view pop up.

Invoking the default BlackBerry Maps view

Invoking the default BlackBerry Maps view

This actually runs the Maps application and pushes the screen on top of y application. When you close Maps, you are back at the Location application’s main screen.

Location Documents

BlackBerry Maps defines an XML document format that you can use to specify view information, location markers, and route information while invoking BlackBerry maps. The basic format of a document showing one or more locations is:

<location y='latitude' x='longitude' label='Location_Label' description='Description'/>
<location y='latitude' x='longitude' label='Location_Label' description='Description'/>
<location y='latitude' x='longitude' label='Location_Label' description='Description'/>

Each of the latitude and longitude values is an integer; you can multiply the decimal latitude and longitude by 100,000 to get the integer value.Modify the Location application to take the list of coordinates in LocationHandler’s history and map them when you select Map from the menu.First, you need a way to get the list of coordinates. Add the following method to LocationHandler:

public Coordinates[] getCoordinateHistory() {
Coordinates[] coordinates = new Coordinates[coordinateHistory.size()];
return coordinates;

LocationMainScreen needs to have access to the location handler you invoke in the update method. You make it into a member variable by adding the following declaration to the top of the class:

private LocationHandler locationHandler = new LocationHandler(this, true);

Then, modify LocationHandler’s update method to refer to this variable:

private void update() {

Next, you modify the map method to construct a map XML document using coordinates from LocationHandler.Remember that the x and y values for the locations are integers that you get by multiplying the decimal latitude and longitude by 100000:

private void map(){
String document = "<lbs>";
Coordinates[] coordinates = locationHandler.getCoordinateHistory();
for (int i = 0; i < coordinates.length; i++) {
document += "<location x='"
+ (int) (coordinates[i].getLongitude() * 100000) + "'
+ "' label='Location " + i
+ "' description='Marker for history coordinate " + i
+ "'/>";
document += "</lbs>";
MapsArguments args = new
MapsArguments(MapsArguments.ARG_LOCATION_DOCUMENT, document);
Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, args);

One final thing before you try this; increase the time interval for location notifications to a couple of minutes or else you’ll have a huge number of points located close together on the map. Change the appropriate line in to something like the following:

if (periodicUpdates) {
// Update every 3 minutes
provider.setLocationListener(this, 180, -1, 10);

Now, if you’re up for it, load this on to your device, click Update, and then go outside and walk around for a bit. Then, click Map and you should see all your points displayed in BlackBerry Maps. The map view is automatically sized to display all of the points you give it.

Displaying a few locations in BlackBerry Maps

Displaying a few locations in BlackBerry Maps

Displaying a Custom Map View

In addition to letting BlackBerry Maps automatically position and zoom the view, you can specify a view in terms of a latitude, longitude, and zoom level. To create a custom map view, you create an instance of net.rim.blackberry.api.maps.MapView with a latitude, longitude, and zoom. The zoom level ranges from 0 (zoomed all the way in) to MapView.MAX_ZOOM (zoomed all the way out). The view will be centered on the given latitude and longitude. Let’s add this functionality to our Location program. You’ll first add a menu item to open a view zoomed in to 0 (all the way in)on the last updated coordinate.Add the following import to the top of LocationMainScreen:

import net.rim.blackberry.api.maps.MapView;

Create a method called customView in LocationMainScreen; the code follows:

private void customView() {
Coordinates[] coordinates = locationHandler.getCoordinateHistory();
if (coordinates.length > 0) {
MapView view = new MapView();
Coordinates lastCoordinates = coordinates[coordinates.length -
view.setLatitude((int)(lastCoordinates.getLatitude() * 100000));
view.setLongitude((int)(lastCoordinates.getLongitude() *
MapsArguments args = new MapsArguments(view);
Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, args);

MapView expects latitude and longitude in the same format as the location XML documents—an integer that is the latitude or longitude from the GPS location multiplied by 100000. We use another constructor for MapsArguments, which takes an instance of MapView and invokes the BlackBerry Maps application the same way. Finally, modify makeMenu to add a new menu item to invoke the customView method:

menu.add(new MenuItem("Custom View", 10, 10) {
public void run(){

Now try it out and you should see a zoomed-in view of your last location.

BlackBerry Maps zoomed all the way in to our last location

BlackBerry Maps zoomed all the way in to our last location

MapField: Embedding BlackBerry Maps in Your UI

From OS 4.5 and above, the BlackBerry platform provides the capability to embed a BlackBerry Maps view into your application’s user interface. You will add a map field to the user interface and have it update whenever a new location update happens. Because this works only with JDE v4.5 and higher, be sure that you’re running an appropriate version of the JDE or that you’ve set your Eclipse workspace to use JDE v4.5 or higher.

The MapField lets you set a map position, but it doesn’t support adding location markers to a map. So, you need to center the map on the new longitude and latitude and zoom in to maximum (level 0). Add the following import to the top of

import net.rim.device.api.lbs.MapField;

Add a new member variable for the MapField at the top of LocationMainScreen:

private MapField mapField;

In the constructor, initialize MapField. MapField enables you to set a preferred width and height using the setPreferredSize method. If you don’t use this, the MapField’s preferred size will be the size of the display, so just choose 200 x 100 and center it horizontally. Make the following modifications to the bottom of LocationMainField’s constructor to place the MapField just above the RichTextField:

mapField = new MapField(MapField.FIELD_HCENTER);
mapField.setPreferredSize(200, 150);
messageField = new RichTextField();

Finally, modify LocationMainScreen.setLocation to set the mapField’s location and zoom level whenever you get a location update. Remember, you have to multiply latitude and longitude by 100000:

public void setLocation(double longitude, double latitude){
synchronized(UiApplication.getEventLock()) {
mapField.moveTo((int)(latitude * 100000), (int)(longitude *

Now run the application. Before the first location update, you’ll see a map field with diagonal lines, indicating that it’s set to an invalid location. Click the Update menu item, and when the location comes through, the map field should be centered on that location.

Embedded map field before

Embedded map field before

The embedded map field after getting a setting a location location update

The embedded map field after getting a setting a location location update

Unlike BlackBerry Maps, the MapField doesn’t support location makers. You can replicate this functionality (and do a lot more) by subclassing MapField and overriding the paint method. The convertWorldToField and convertFieldToWorld methods let you convert between latitude/longitude and pixels onscreen.

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd Protection Status