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.
| 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
- Ripple Emulator
| API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
|---|---|---|---|---|---|
| clearWatch | Y | Y | Y | Y | Y |
| getCurrentPosition | Y | Y | Y | Y | Y |
| watchPosition | Y | Y | Y | Y | Y |
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.You must declare the permission element(s) below in your configuration document:
| Permission Elements (PlayBook Only) |
|---|
|
- <rim:permit>read_geolocation</rim:permit> Permits your app to access geolocation information
|
clearWatch
| static void clearWatch(watchId : long) |
Supported Platform(s)
- BlackBerry OS 5.0+- BlackBerry PlayBook
- Ripple Emulator
Description
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.
| Parameter | Type | Description |
|---|---|---|
| watchId | long | A unique identifier return from watchPosition. |
getCurrentPosition
| static void getCurrentPosition(positionCallback : function, [positionErrorCallback: function], [options: PositionOptions]) |
Supported Platform(s)
- BlackBerry OS 5.0+- BlackBerry PlayBook
- Ripple Emulator
Description
Attempt to obtain the current location of the device.
| Parameter | Type | Description |
|---|---|---|
| positionCallback | function(position : Position) |
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 |
function([error: PositionError])
Optional |
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 |
PositionOptions
Optional |
return PositionOptions of a current position. |
Code Example(s)
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 PositionError.PERMISSION_DENIED :
alert("Error. PERMISSION_DENIED");
break;
case PositionError.POSITION_UNAVAILABLE:
alert("Error. POSITION_UNAVAILABLE");
break;
case PositionError.TIMEOUT:
alert("Error. TIMEOUT");
break;
default:
alert("unknow error code");
}
}
);
watchPosition
| static Long watchPosition(positionCallback : function, [positionErrorCallback: function], [options: PositionOptions]) |
Supported Platform(s)
- BlackBerry OS 5.0+- BlackBerry PlayBook
- Ripple Emulator
Description
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.
Returns
Return a watchId so that it can be use in function clearWatch.| Parameter | Type | Description |
|---|---|---|
| positionCallback | function(position : Position) |
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 |
function([error: PositionError])
Optional |
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 |
PositionOptions
Optional |
Return PositionOptions of a watch position. |