Object: blackberry.location
The blackberry.location object is a property of the blackberry object. It provides access to the GPS location of the BlackBerry device. The GPS location refers to the geographical co-ordinates, latitude and longitude, of the BlackBerry device.
blackberry.location properties
Property name |
Type |
Description |
Status |
Availability |
|---|---|---|---|---|
GPSSupported |
boolean |
When true, this property indicates that GPS positioning is supported by the BlackBerry® device. |
read only |
4.1 or later |
latitude |
double |
Returns the current latitude, in degrees, of the BlackBerry device. Positive values indicate northern latitude, negative values indicate southern latitude. To ensure that the most accurate co-ordinate is returned, you should register a listener using blackberry.location.onLocationUpdate() and acquire the location information within the callback. |
read only |
4.1 or later |
longitude |
double |
Returns the current longitude, in degrees, of the BlackBerry device. Positive values indicate eastern longitude, negative values indicate western longitude. To ensure that the most accurate co-ordinate is returned, you should register a listener using blackberry.location.onLocationUpdate() and read acquire the location information within the callback. |
read only |
4.1 or later |
timestamp |
unsigned long |
Returns time (in milliseconds since epoch) at which the blackberry.location object was updated. This property is only supported on BlackBerry devices running BlackBerry® Device Software version 4.6 or later. |
read only |
4.6 or later |
blackberry.location methods
Method: blackberry.location.onLocationUpdate()
The onLocationUpdate() method registers a listener that evaluates a string or calls a function whenever the BlackBerry® device receives updated location information.
On BlackBerry devices running versions of BlackBerry® Device Software earlier than version 4.6, this method must be passed as a string that is evaluated each time the location is refreshed. On BlackBerry devices running BlackBerry Device Software version 4.6 or later, you can pass a string, or use the method to register a callback function.
Once onlocationUpdate() has been invoked, the callback occurs whenever there is an update to the location information. This can be as frequent as once every several seconds. If you have passed the method a function, you can cancel the callback using blackberry.location.removeLocationUpdate(). If you have passed a string, the callback cannot be removed.
Parameters
Method: blackberry.location.refreshLocation()
The refreshLocation() method requests an update of the location of the BlackBerry® device.
This method is asynchronous, so the script continues regardless of whether updated location information has been received. To ensure that location information is updated before reading it, you should first register a listener using blackberry.location.onLocationUpdate() that reads blackberry.location.latitude and blackberry.location.longitude , and then call refreshLocation() afterwards.
Method: blackberry.location.removeLocationUpdate()
The removeLocationUpdate() method removes a previously registered callback method.
This method is only supported on BlackBerry® devices running BlackBerry® Device Software version 4.6 or later.
Parameters
Parameter |
Type |
Description |
|---|---|---|
callbackFunction |
Function |
A JavaScript® function previously registered by blackberry.location.onLocationUpdate(). |
Method: blackberry.location.setAidMode()
The setAidMode() method specifies which method the BlackBerry® device will use to obtain the GPS location.
The device can obtain location information in one of three ways.