HTML5 Geolocation

The Geolocation object is used by scripts to programmatically determine the location information associated with the hosting device. The location information is acquired by applying a user-agent specific algorithm, creating a Position object, and populating that object with appropriate data accordingly.


Learning Resources:

Sample - Using HTML5 Geolocation Sample that demonstrates how to use the HTML5 Geolocation API [BlackBerry Developer Resource Center].
How To - Enable GPS on PlayBook How to enable GPS capability when using the BlackBerry WebWorks SDK for Tablet OS [BlackBerry Developer Resource Center].

Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook 1.0+
- BlackBerry 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
navigator.geolocation.clearWatch Y Y Y Y Y YY
navigator.geolocation.getCurrentPosition Y Y Y Y Y YY
navigator.geolocation.watchPosition Y Y Y Y Y YY

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

This API does not require a <feature> element to be declared in the configuration document of your BlackBerry WebWorks Application.
Permission Elements (PlayBook and BlackBerry 10+)
You must declare the permission element(s) below in your configuration document:
- <rim:permit>access_location_services</rim:permit>
Permits your app to access geolocation information (BB10)
- <rim:permit>read_geolocation</rim:permit>
Permits your app to access geolocation information (PlayBook)

Functions

static void navigator.geolocation.clearWatch (watchId : long)


Like getCurrentPosition continue to monitor the position of the device and invoke the appropriate callback every time this position changes. It continues until the clearWatch method is called with the corresponding identifier.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
watchId A unique identifier return from navigator.geolocation.watchPosition.

static void navigator.geolocation.getCurrentPosition (positionCallback: function(position : Position), [positionErrorCallback: function([error: PositionError])], [options : PositionOptions])


Attempt to obtain the current location of the device.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
positionCallback This method is called if the attempt is successful i.e. the handleEvent operation must be called on the Position object

position: Object that contains the position that was just received
positionErrorCallback This optional method is called if the attempt fails, the errorCallback must be invoked with a new PositionError object, reflecting the reason for the failure.

error: Error call if there is an error.
options return PositionOptions of a current position.

Code Example:
To get current position

 var startPos;
 navigator.geolocation.getCurrentPosition(function(position) {
    startPos = position;
    latitude = startPos.coords.latitude;
    longitude = startPos.coords.longitude;
 });

Handle Errors

 var startPos;
 navigator.geolocation.getCurrentPosition(
     function(position) {
        startPos = position;
        latitude = startPos.coords.latitude;
        longitude = startPos.coords.longitude;
     },
     function(error) {
         switch(error.code) {
              case error.PERMISSION_DENIED :
                alert("Error. PERMISSION_DENIED");
                break;
              case error.POSITION_UNAVAILABLE:
                alert("Error. POSITION_UNAVAILABLE");
                break;
              case error.TIMEOUT:
                alert("Error. TIMEOUT");
                break;
              default:
                alert("unknown error code");
          }
     }
);

static Long navigator.geolocation.watchPosition (positionCallback: function(position : Position), [positionErrorCallback: function([error: PositionError])], [options : PositionOptions])


Like getCurrentPosition continue to monitor the position of the device and invoke the appropriate callback every time this position changes. It continues until the clearWatch method is called with the corresponding identifier.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+
 - BlackBerry 10
 - Ripple Emulator


Parameters
positionCallback This method is called if the attempt is successful i.e. the handleEvent operation must be called on the Position object

position: Object that contains the position that was just received
positionErrorCallback This optional method is called if the attempt fails, the errorCallback must be invoked with a new PositionError object, reflecting the reason for the failure.

error: Error call if there is an error.
options Return PositionOptions of a watch position.

Return:

Return a watchId so that it can be use in function navigator.geolocation.clearWatch.


Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:07 GMT-0500 (EST)