Opening BlackBerry Maps by using a location document

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

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>
Back To Top

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>
Back To Top

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>
Back To Top

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.
  1. Import the required classes.
    import net.rim.blackberry.api.invoke.*;
  2. Create a class and a constructor to use to invoke BlackBerry Maps.
    public class invokeMaps
    {
       public invokeMaps ()
       {
       }
    }
  3. 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>";
  4. 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));
  5. 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>";
    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));
   }
}
Back To Top

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.
  1. Import the required classes.
    import net.rim.blackberry.api.invoke.*;
  2. Create a class and constructor to use to invoke BlackBerry Maps.
    public class invokeMaps
    {
       public invokeMaps ()
       {
       }
    }
  3. 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>";
  4. 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));
  5. 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));
    }
}
Back To Top

Was this information helpful? Send us your comments.