Opening BlackBerry Maps by using a location document

Development Guide

Search This Document

Download PDF

You can open BlackBerry Maps to display map locations and routes by passing in a location document. A location document is a String object that contains XML elements with attributes that can specify the location and route information. The XML elements that you can use include <lbs>, <getRoute> and <location>.

XML element: <lbs>

The opening and closing <lbs> elements wrap the location document elements.

Valid parents

None

Valid children

<location>, <getRoute>

Attributes

Attribute	Type	Description	Supported in
`id`	`String`	This value specifies the ID of a location document.	BlackBerry Java Development Environment 4.5.0 or later
`clear`	`String`	This value specifies the clearing action to perform on the information in a map. The value is a list of location document IDs separated by commas, or one of the following values: `NONE`: does not clear any information `DOCS`: clears location and route information from all location documents that have a specific `id` attribute `LOCATIONS`: clears all the location information from the map `ROUTES`: clears all route the information from the map `ALL`: clears all the location and route information from the map	BlackBerry JDE 4.5.0 or later

Attribute

Type

Description

Supported in

id

String

This value specifies the ID of a location document.

BlackBerry Java Development Environment 4.5.0 or later

clear

String

This value specifies the clearing action to perform on the information in a map. The value is a list of location document IDs separated by commas, or one of the following values:

NONE: does not clear any information
DOCS: clears location and route information from all location documents that have a specific id attribute
LOCATIONS: clears all the location information from the map
ROUTES: clears all route the information from the map
ALL: clears all the location and route information from the map

BlackBerry JDE 4.5.0 or later

Code sample

<lbs clear='WatLocation'></lbs>
<lbs clear='WatLocation,OttLocation'></lbs>
<lbs clear='WatRoute'></lbs>
<lbs clear='WatRoute,OttRoute'></lbs>
<lbs clear='NONE'></lbs>
<lbs clear='DOCS'></lbs>
<lbs clear='LOCATIONS'></lbs>
<lbs clear='ROUTES'></lbs>
<lbs clear='ALL'></lbs>

<lbs clear='ALL' id='Wat'>
    <location x='-8052237' y='4346518' label='Waterloo, ON' description='Waterloo' zoom='10' />
</lbs>

XML element: <location>

The <location> element contains information for a specific location. The description, label, x and y are required attributes.

Valid parents

<lbs>, <getRoute>

Valid children

None

Attributes

Attribute	Type	Description	Supported in
`address`	`String`	This attribute specifies the street address.	BlackBerry Java Development Environment 4.2.1 or later
`categories`	`String`	This attribute specifies the category.	BlackBerry JDE 4.2.1 or later
`city`	`String`	This attribute specifies the city.	BlackBerry JDE 4.2.1 or later
`country`	`String`	This attribute specifies the country.	BlackBerry JDE 4.2.1 or later
`description`	`String`	This attribute specifies the description information for a location. This is a required attribute.	BlackBerry JDE 4.2.0 or later
`email`	`String`	This attribute specifies the email address.	BlackBerry JDE 4.2.1 or later
`fax`	`String`	This attribute specifies the fax number.	BlackBerry JDE 4.2.1 or later
`label`	`String`	This attribute specifies the label that is displayed beside a location on a map. This is a required attribute.	BlackBerry JDE 4.2.0 or later
`phone`	`String`	This attribute specifies the phone number.	BlackBerry JDE 4.2.1 or later
`postalCode`	`String`	This attribute specifies the postal code or zip code.	BlackBerry JDE 4.2.1 or later
`rating`	`double`	This attribute specifies the rating information in the range of 0 to 5.	BlackBerry JDE 4.2.1 or later
`region`	`String`	This attribute specifies the province or state.	BlackBerry JDE 4.2.1 or later
`url`	`String`	This attribute specifies the URL.	BlackBerry JDE 4.2.1 or later
`x` or the alias, `lon`	`integer`	This attribute specifies the longitude in decimal degrees with five decimal accuracy multiplied by 100,000. This is a required attribute.	BlackBerry JDE 4.2.0 or later
`y` or the alias, `lat`	`integer`	This attribute specifies the latitude in decimal degrees with five decimal accuracy multiplied by 100,000. This is a required attribute.	BlackBerry JDE 4.2.0 or later
`zoom`	`integer`	This attribute specifies the zoom level from `0` to `15`.	BlackBerry JDE 4.2.0 or later

Code sample

<lbs id='Waterloo'>
    <location x='-8052237' y='4346518'
      label='Waterloo, ON' description='Waterloo' zoom='10' />
</lbs>

XML element: <getRoute>

The <getRoute> element contains the route information. To display route information in a map, you must place the starting and ending locations in two <location> elements in the <getRoute> block. You can use the x and y attributes, or the aliases lon and lat, in a <location> element that you nest within the <getRoute> block.

Valid parents

<lbs>

Valid children

<location>

Attributes

None

Code sample

<lbs>
    <getRoute>
        <location x='-8052237' y='4346518'
         label='Waterloo, ON' description='Waterloo, Ontario, Canada' />
        <location lon='-7569792' lat='4542349'
         label='Ottawa, ON' description='Ottawa, Ontario, Canada' />
    </getRoute>
</lbs>

Display and clear locations on a map by using a location document

You can use a location document to display a location on a map in BlackBerry Maps. You can also clear locations from a map after they are displayed.

Import the required classes.
```
import net.rim.blackberry.api.invoke.*;
```
Create a class and a constructor to use to invoke BlackBerry Maps.
```
public class invokeMaps
{
   public invokeMaps ()
   {
   }
}
```
In the constructor, create a String variable to use for the location document. Add an <lbs> element. Configure a <location> element with the location that you want to display.
```
String document = "<lbs id='Waterloo'>
     <location x='-8052237' y='4346518'
        label='Waterloo, ON' description='Waterloo' zoom='10' />
     </lbs>";
```
In the constructor, invoke Invoke.invokeApplication() using the APP_TYPE_MAPS constant and a new MapsArguments object as parameters to open BlackBerry Maps. Pass in the ARG_LOCATION_DOCUMENT property and the String variable that represents the location document as parameters for the MapsArguments class to display the location provided in the location document.
```
Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments
    (MapsArguments.ARG_LOCATION_DOCUMENT, document));
```

Perform one of the following tasks to clear location information from a map after it has been displayed :

Task	Steps
Clear a location from a map.	Create a `String` that configures the `clear` attribute to be the `id` of the location document that contains the location information. String document = "<lbs clear='Waterloo'></lbs>";
Clear all locations from a map.	Create a `String` that configures the `clear` attribute to be `LOCATIONS`. String document = "<lbs clear='LOCATIONS'></lbs>";
Clear all locations and routes from a map.	Create a `String` that configures the `clear` attribute to be `ALL`. String document = "<lbs clear='ALL'></lbs>";

Task

Steps

Clear a location from a map.

Create a String that configures the clear attribute to be the id of the location document that contains the location information.

 String document = "<lbs clear='Waterloo'></lbs>";

Clear all locations from a map.

Create a String that configures the clear attribute to be LOCATIONS.

String document = "<lbs clear='LOCATIONS'></lbs>";

Clear all locations and routes from a map.

Create a String that configures the clear attribute to be ALL.

String document = "<lbs clear='ALL'></lbs>";

Clearing map content occurs before any new map content is displayed on the map. You can combine the actions of displaying and clearing map content into one location document.

String document = "<lbs clear='Waterloo' id='NewZone'>
     <location x='-8050000' y='4340000'
        label='NewZone' description='NewZone' zoom='10' />
     </lbs>";

Code sample: Displaying locations on a map by using a location document

import net.rim.blackberry.api.invoke.*;

public class invokeMaps
{
    public invokeMaps ()
    {
        String document = "<lbs id='WatRoute'><getRoute>" +
          "<location x='-8052237' y='4346518' " +
           "label='Waterloo, ON' description='Waterloo, Ontario, Canada' />" +
          "<location x='-7569792' y='4542349' " +
           "label='Ottawa, ON' description='Ottawa, Ontario, Canada' />" +
          "</getRoute></lbs>"; 
        Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments
         (MapsArguments.ARG_LOCATION_DOCUMENT, document));
   }
}

Display and clear a route on a map by using a location document

You can use a location document to display a route on a map in BlackBerry Maps. You can also clear a route from a map after it is displayed.

Import the required classes.
```
import net.rim.blackberry.api.invoke.*;
```
Create a class and constructor to use to invoke BlackBerry Maps.
```
public class invokeMaps
{
   public invokeMaps ()
   {
   }
}
```

In the constructor, create a String variable to use for the location document. Add an <lbs> and a <getRoute> element. Add <location> elements to specify the starting location and ending location of the route that you want to display.

String document = "<lbs id='WatRoute'><getRoute>
    <location x='-8052237' y='4346518'
       label='Waterloo, ON' description='Waterloo, Ontario, Canada' />
    <location x='-7569792' y='4542349'
       label='Ottawa, ON' description='Ottawa, Ontario, Canada' />
    </getRoute></lbs>";

In the constructor, invoke Invoke.invokeApplication() using the APP_TYPE_MAPS constant and a new MapsArguments object as parameters to open BlackBerry Maps. Pass in the ARG_LOCATION_DOCUMENT property and the String variable that represents the location document as parameters for the MapsArguments class to display the route provided in the location document.
```
invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments
    (MapsArguments.ARG_LOCATION_DOCUMENT, document));
```

Perform one of the following tasks to clear route location information from a map after it has been displayed:

Task	Steps
Clear a route from a map.	Create a `String` that configures the `clear` attribute to be the `id` of the location document that contains the route information. String document = "<lbs clear='WatRoute'></lbs>";
Clear all routes from a map.	Create a `String` that configures the `clear` attribute to be `ROUTES`. String document = "<lbs clear='ROUTES'></lbs>";
Clear all routes and location information from a specific location documents with an id attribute.	Create a `String` that configures the `clear` attribute to be `DOCS`. String document = "<lbs clear='DOCS'></lbs>";
Clear all routes and location information from a map.	Create a `String` that configures the `clear` attribute to be `ALL`. String document = "<lbs clear='ALL'></lbs>";

Clearing map content occurs before any new map content is displayed on the map. You can combine the actions of displaying and clearing map content into one location document.

String document = "<lbs clear='WatRoute' id='NewRoute'><getRoute>
    <location x='-8051111' y='4341111'
       label='NewRoute #1' description='New Route #1' />
    <location x='-7562222' y='4542222'
       label='NewRoute #2' description='New Route #2' />
    </getRoute></lbs>";

Code sample: Displaying a route using a location document

import net.rim.blackberry.api.invoke.*;

public class invokeMaps
{
    public invokeMaps ()
    {
        String document = "<lbs id='WatRoute'><getRoute>
            <location x='-8052237' y='4346518'
              label='Waterloo, ON' description='Waterloo, Ontario, Canada' />
            <location x='-7569792' y='4542349'
              label='Ottawa, ON' description='Ottawa, Ontario, Canada' />
            </getRoute></lbs>";
        Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments
            (MapsArguments.ARG_LOCATION_DOCUMENT, document));
    }
}

Next topic: Open BlackBerry Maps by using a local search

Previous topic: Open BlackBerry Maps by using a landmark

Was this information helpful? Send us your comments.

Global Navigation

Development Guide

Local Navigation