Updated Branches: refs/heads/master 209409c94 -> 175748fdf
[CB-657] Update geolocation documentation based on geo plugin rewrite. Full W3C adherence, yay. Project: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/commit/175748fd Tree: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/tree/175748fd Diff: http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/diff/175748fd Branch: refs/heads/master Commit: 175748fdfc843ac6735d0e4c4299315ecf43d38e Parents: 209409c Author: Fil Maj <maj....@gmail.com> Authored: Tue May 8 13:53:56 2012 -0700 Committer: Fil Maj <maj....@gmail.com> Committed: Tue May 8 13:53:56 2012 -0700 ---------------------------------------------------------------------- .../cordova/geolocation/Coordinates/coordinates.md | 2 +- .../edge/cordova/geolocation/Position/position.md | 17 +----------- .../geolocation/PositionError/positionError.md | 19 ++++++++++++++- .../cordova/geolocation/geolocation.clearWatch.md | 15 +++++++---- .../geolocation/geolocation.getCurrentPosition.md | 5 ++- docs/en/edge/cordova/geolocation/geolocation.md | 2 +- .../geolocation/geolocation.watchPosition.md | 15 ++++++----- .../geolocation/parameters/geolocation.options.md | 8 +++--- .../geolocation/parameters/geolocationSuccess.md | 4 +- 9 files changed, 48 insertions(+), 39 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/175748fd/docs/en/edge/cordova/geolocation/Coordinates/coordinates.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/cordova/geolocation/Coordinates/coordinates.md b/docs/en/edge/cordova/geolocation/Coordinates/coordinates.md index 20c64d5..5325364 100644 --- a/docs/en/edge/cordova/geolocation/Coordinates/coordinates.md +++ b/docs/en/edge/cordova/geolocation/Coordinates/coordinates.md @@ -43,7 +43,7 @@ Supported Platforms - Android - BlackBerry WebWorks (OS 5.0 and higher) -- iPhone +- iOS - Windows Phone 7 ( Mango ) - Bada 1.2 & 2.x - webOS http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/175748fd/docs/en/edge/cordova/geolocation/Position/position.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/cordova/geolocation/Position/position.md b/docs/en/edge/cordova/geolocation/Position/position.md index e90f9e3..04c5950 100644 --- a/docs/en/edge/cordova/geolocation/Position/position.md +++ b/docs/en/edge/cordova/geolocation/Position/position.md @@ -20,7 +20,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one Position ======== -Contains `Position` coordinates that are created by the geolocation API. +Contains `Position` coordinates and timestamp, created by the geolocation API. Properties ---------- @@ -38,7 +38,7 @@ Supported Platforms - Android - BlackBerry WebWorks (OS 5.0 and higher) -- iPhone +- iOS - Windows Phone 7 ( Mango ) - Bada 1.2 & 2.x - webOS @@ -116,16 +116,3 @@ Full Example <p id="geolocation">Finding geolocation...</p> </body> </html> - -iPhone Quirks -------------- - -- __timestamp:__ Uses seconds instead of milliseconds. - -A workaround is to manually convert the timestamp to milliseconds (x 1000): - - var onSuccess = function(position) { - alert('Latitude: ' + position.coords.latitude + '\n' + - 'Longitude: ' + position.coords.longitude + '\n' + - 'Timestamp: ' + new Date(position.timestamp * 1000) + '\n'); - }; http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/175748fd/docs/en/edge/cordova/geolocation/PositionError/positionError.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/cordova/geolocation/PositionError/positionError.md b/docs/en/edge/cordova/geolocation/PositionError/positionError.md index aa64fe1..5fda2f5 100755 --- a/docs/en/edge/cordova/geolocation/PositionError/positionError.md +++ b/docs/en/edge/cordova/geolocation/PositionError/positionError.md @@ -20,7 +20,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one PositionError ======== -A `PositionError` object is returned to the geolocationError callback when an error occurs. +A `PositionError` object is returned to the `geolocationError` callback when an error occurs. Properties ---------- @@ -40,3 +40,20 @@ Description The `PositionError` object is returned to the user through the `geolocationError` callback function when an error occurs with geolocation. +### `PositionError.PERMISSION_DENIED` + +Returned when the user does not allow your application to retrieve +position information. This is dependent on the platform. + +### `PositionError.POSITION_UNAVAILABLE` + +Returned when the device was unable to retrieve a position. In general +this means the device has no network connectivity and/or cannot get a +satellite fix. + +### `PositionError.TIMEOUT` + +Returned when the device was unable to retrieve a position within the +time specified in the `geolocationOptions`' `timeout` property. When using +in conjunction with `geolocation.watchPosition`, this error could be +called into the `geolocationError` callback every `timeout` milliseconds. http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/175748fd/docs/en/edge/cordova/geolocation/geolocation.clearWatch.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/cordova/geolocation/geolocation.clearWatch.md b/docs/en/edge/cordova/geolocation/geolocation.clearWatch.md index 8940635..5259707 100644 --- a/docs/en/edge/cordova/geolocation/geolocation.clearWatch.md +++ b/docs/en/edge/cordova/geolocation/geolocation.clearWatch.md @@ -32,23 +32,25 @@ Parameters Description ----------- -Function `geolocation.clearWatch` stops watching changes to the device's location by clearing the `geolocation.watchPosition` referenced by `watchID`. +`geolocation.clearWatch` stops watching changes to the device's location by clearing the `geolocation.watchPosition` referenced by `watchID`. Supported Platforms ------------------- - Android - BlackBerry WebWorks (OS 5.0 and higher) -- iPhone +- iOS - Windows Phone 7 ( Mango ) - Bada 1.2 & 2.x +- webOS Quick Example ------------- - // Options: retrieve the location every 3 seconds + // Options: watch for changes in position, and use the most + // accurate position acquisition method available. // - var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 }); + var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true }); // ...later on... @@ -75,8 +77,9 @@ Full Example // Cordova is ready // function onDeviceReady() { - // Update every 3 seconds - var options = { frequency: 3000 }; + // Get the most accurate position updates available on the + // device. + var options = { enableHighAccuracy: true }; watchID = navigator.geolocation.watchPosition(onSuccess, onError, options); } http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/175748fd/docs/en/edge/cordova/geolocation/geolocation.getCurrentPosition.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/cordova/geolocation/geolocation.getCurrentPosition.md b/docs/en/edge/cordova/geolocation/geolocation.getCurrentPosition.md index e68aca9..b8f3500 100644 --- a/docs/en/edge/cordova/geolocation/geolocation.getCurrentPosition.md +++ b/docs/en/edge/cordova/geolocation/geolocation.getCurrentPosition.md @@ -36,7 +36,7 @@ Parameters Description ----------- -Function `geolocation.getCurrentPositon` is an asynchronous function. It returns the device's current position to the `geolocationSuccess` callback with a `Position` object as the parameter. If there is an error, the `geolocationError` callback is invoked with a `PositionError` object. +`geolocation.getCurrentPositon` is an asynchronous function. It returns the device's current position to the `geolocationSuccess` callback with a `Position` object as the parameter. If there is an error, the `geolocationError` callback is invoked with a `PositionError` object. Supported Platforms @@ -44,9 +44,10 @@ Supported Platforms - Android - BlackBerry WebWorks (OS 5.0 and higher) -- iPhone +- iOS - Windows Phone 7 ( Mango ) - Bada 1.2 & 2.x +- webOS Quick Example ------------- http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/175748fd/docs/en/edge/cordova/geolocation/geolocation.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/cordova/geolocation/geolocation.md b/docs/en/edge/cordova/geolocation/geolocation.md index 743644e..c28e0aa 100644 --- a/docs/en/edge/cordova/geolocation/geolocation.md +++ b/docs/en/edge/cordova/geolocation/geolocation.md @@ -24,7 +24,7 @@ Geolocation Geolocation provides location information for the device, such as latitude and longitude. Common sources of location information include Global Positioning System (GPS) and location inferred from network signals such as IP address, RFID, WiFi and Bluetooth MAC addresses, and GSM/CDMA cell IDs. No guarantee is given that the API returns the device's actual location. -This API is based on the [W3C Geo location API Specification](http://dev.w3.org/geo/api/spec-source.html). Some devices already provide an implementation of this spec. For those devices, the built-in support is used instead of replacing it with Cordova's implementation. For devices that don't have geolocation support, Cordova's implementation should be compatible with the W3C specification. +This API is based on the [W3C Geolocation API Specification](http://dev.w3.org/geo/api/spec-source.html). Some devices (Android, BlackBerry, Bada, Windows Phone 7 and webOS, to be specific) already provide an implementation of this spec. For those devices, the built-in support is used instead of replacing it with Cordova's implementation. For devices that don't have geolocation support, the Cordova implementation adheres to the W3C specification. Methods ------- http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/175748fd/docs/en/edge/cordova/geolocation/geolocation.watchPosition.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/cordova/geolocation/geolocation.watchPosition.md b/docs/en/edge/cordova/geolocation/geolocation.watchPosition.md index a5edb17..daa2f4f 100644 --- a/docs/en/edge/cordova/geolocation/geolocation.watchPosition.md +++ b/docs/en/edge/cordova/geolocation/geolocation.watchPosition.md @@ -36,21 +36,22 @@ Parameters Returns ------- -- __String__: returns a watch id that references the watch position interval. The watch id can be used with `geolocation.clearWatch` to stop watching for changes in position. +- __String__: returns a watch id that references the watch position interval. The watch id should be used with `geolocation.clearWatch` to stop watching for changes in position. Description ----------- -Function `geolocation.watchPosition` is an asynchronous function. It returns the device's current position when a change in position has been detected. When the device has retrieved a new location, the `geolocationSuccess` callback is invoked with a `Position` object as the parameter. If there is an error, the `geolocationError` callback is invoked with a `PositionError` object. +`geolocation.watchPosition` is an asynchronous function. It returns the device's current position when a change in position has been detected. When the device has retrieved a new location, the `geolocationSuccess` callback is invoked with a `Position` object as the parameter. If there is an error, the `geolocationError` callback is invoked with a `PositionError` object. Supported Platforms ------------------- - Android - BlackBerry WebWorks (OS 5.0 and higher) -- iPhone +- iOS - Windows Phone 7 ( Mango ) - Bada 1.2 & 2.x +- webOS Quick Example ------------- @@ -73,9 +74,9 @@ Quick Example 'message: ' + error.message + '\n'); } - // Options: retrieve the location every 3 seconds + // Options: throw an error if no update is received every 30 seconds. // - var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 }); + var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 }); Full Example @@ -98,8 +99,8 @@ Full Example // Cordova is ready // function onDeviceReady() { - // Update every 3 seconds - var options = { frequency: 3000 }; + // Throw an error if no update is received every 30 seconds + var options = { timeout: 30000 }; watchID = navigator.geolocation.watchPosition(onSuccess, onError, options); } http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/175748fd/docs/en/edge/cordova/geolocation/parameters/geolocation.options.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/cordova/geolocation/parameters/geolocation.options.md b/docs/en/edge/cordova/geolocation/parameters/geolocation.options.md index ce2cf69..d822d24 100644 --- a/docs/en/edge/cordova/geolocation/parameters/geolocation.options.md +++ b/docs/en/edge/cordova/geolocation/parameters/geolocation.options.md @@ -20,16 +20,16 @@ license: Licensed to the Apache Software Foundation (ASF) under one geolocationOptions ================== -Optional parameters to customize the retrieval of the geolocation. +Optional parameters to customize the retrieval of the geolocation +`Position`. { maximumAge: 3000, timeout: 5000, enableHighAccuracy: true }; Options ------- -- __frequency:__ How often to retrieve the position in milliseconds. This option is not part of the W3C spec and will be removed in the future. maximumAge should be used instead. _(Number)_ (Default: 10000) -- __enableHighAccuracy:__ Provides a hint that the application would like to receive the best possible results. _(Boolean)_ -- __timeout:__ The maximum length of time (msec) that is allowed to pass from the call to `geolocation.getCurrentPosition` or `geolocation.watchPosition` until the corresponding `geolocationSuccess` callback is invoked. _(Number)_ +- __enableHighAccuracy:__ Provides a hint that the application would like to receive the best possible results. By default, the device will attempt to retrieve a `Position` using network-based methods. Setting this property to `true` tells the framework to use more accurate methods, such as satellite positioning. _(Boolean)_ +- __timeout:__ The maximum length of time (milliseconds) that is allowed to pass from the call to `geolocation.getCurrentPosition` or `geolocation.watchPosition` until the corresponding `geolocationSuccess` callback is invoked. If the `geolocationSuccess` callback is not invoked within this time, the `geolocationError` callback will be invoked with a `PositionError.TIMEOUT` error code. NOTE: when used in conjunction with `geolocation.watchPosition`, the `geolocationError` callback could be called on an interval every `timeout` milliseconds! _(Number)_ - __maximumAge:__ Accept a cached position whose age is no greater than the specified time in milliseconds. _(Number)_ Android Quirks http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/175748fd/docs/en/edge/cordova/geolocation/parameters/geolocationSuccess.md ---------------------------------------------------------------------- diff --git a/docs/en/edge/cordova/geolocation/parameters/geolocationSuccess.md b/docs/en/edge/cordova/geolocation/parameters/geolocationSuccess.md index 4c8b8fa..798c58c 100644 --- a/docs/en/edge/cordova/geolocation/parameters/geolocationSuccess.md +++ b/docs/en/edge/cordova/geolocation/parameters/geolocationSuccess.md @@ -20,7 +20,7 @@ license: Licensed to the Apache Software Foundation (ASF) under one geolocationSuccess ================== -The user's callback function that is called when a geolocation position is available. +The user's callback function that is called when a geolocation position becomes available (when using with `geolocation.getCurrentPosition`), or when the position changes (when using with `geolocation.watchPosition`). function(position) { // Do something @@ -43,4 +43,4 @@ Example 'Heading: ' + position.coords.heading + '\n' + 'Speed: ' + position.coords.speed + '\n' + 'Timestamp: ' + new Date(position.timestamp) + '\n'); - } \ No newline at end of file + }
