cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From agri...@apache.org
Subject [3/5] git commit: CB-5658 Add doc.index.md for Compass plugin
Date Thu, 02 Jan 2014 18:07:18 GMT
CB-5658 Add doc.index.md for Compass plugin


Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation/commit/958ada72
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation/tree/958ada72
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation/diff/958ada72

Branch: refs/heads/master
Commit: 958ada72d79d1ec5499ac3b84934ec829d220aa1
Parents: f0ae9c8
Author: Andrew Grieve <agrieve@chromium.org>
Authored: Wed Dec 18 14:10:28 2013 -0500
Committer: Andrew Grieve <agrieve@chromium.org>
Committed: Wed Dec 18 14:10:28 2013 -0500

----------------------------------------------------------------------
 README.md    |  25 ++++++--
 doc/index.md | 184 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 204 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation/blob/958ada72/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index a82f0a9..a1b57b6 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,22 @@
-cordova-plugin-device-orientation
-============================
+<!---
+ license: Licensed to the Apache Software Foundation (ASF) under one
+         or more contributor license agreements.  See the NOTICE file
+         distributed with this work for additional information
+         regarding copyright ownership.  The ASF licenses this file
+         to you under the Apache License, Version 2.0 (the
+         "License"); you may not use this file except in compliance
+         with the License.  You may obtain a copy of the License at
 
-Also known as compass. Need to break aparat CDVLocation as geolocation and this plugin both
use it. 
-To install this plugin, follow the [Command-line Interface Guide](http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface).
+           http://www.apache.org/licenses/LICENSE-2.0
 
-If you are not using the Cordova Command-line Interface, follow [Using Plugman to Manage
Plugins](http://cordova.apache.org/docs/en/edge/plugin_ref_plugman.md.html).
+         Unless required by applicable law or agreed to in writing,
+         software distributed under the License is distributed on an
+         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+         KIND, either express or implied.  See the License for the
+         specific language governing permissions and limitations
+         under the License.
+-->
+
+# org.apache.cordova.device-orientation
+
+Plugin documentation: [doc/index.md](doc/index.md)

http://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation/blob/958ada72/doc/index.md
----------------------------------------------------------------------
diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 0000000..64cae88
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,184 @@
+<!---
+ license: Licensed to the Apache Software Foundation (ASF) under one
+         or more contributor license agreements.  See the NOTICE file
+         distributed with this work for additional information
+         regarding copyright ownership.  The ASF licenses this file
+         to you under the Apache License, Version 2.0 (the
+         "License"); you may not use this file except in compliance
+         with the License.  You may obtain a copy of the License at
+
+           http://www.apache.org/licenses/LICENSE-2.0
+
+         Unless required by applicable law or agreed to in writing,
+         software distributed under the License is distributed on an
+         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+         KIND, either express or implied.  See the License for the
+         specific language governing permissions and limitations
+         under the License.
+-->
+
+# org.apache.cordova.device-orientation
+
+This plugin provides access to the device's compass. The compass is a sensor
+that detects the direction or heading that the device is pointed, typically
+from the top of the device.  It measures the heading in degrees from 0 to
+359.99, where 0 is north.
+
+## Installation
+
+    cordova plugin add org.apache.cordova.device-orientation
+
+## Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- iOS
+- Tizen
+- Windows Phone 7 and 8 (if available in hardware)
+- Windows 8
+
+## Methods
+
+- navigator.compass.getCurrentHeading
+- navigator.compass.watchHeading
+- navigator.compass.clearWatch
+
+## navigator.compass.getCurrentHeading
+
+Get the current compass heading. The compass heading is returned via a `CompassHeading`
+object using the `compassSuccess` callback function.
+
+    navigator.compass.getCurrentHeading(compassSuccess, compassError);
+
+### Example
+
+    function onSuccess(heading) {
+        alert('Heading: ' + heading.magneticHeading);
+    };
+
+    function onError(error) {
+        alert('CompassError: ' + error.code);
+    };
+
+    navigator.compass.getCurrentHeading(onSuccess, onError);
+
+## navigator.compass.watchHeading
+
+Gets the device's current heading at a regular interval. Each time the heading
+is retrieved, the `headingSuccess` callback function is executed.
+
+The returned watch ID references the compass watch interval. The watch
+ID can be used with `navigator.compass.clearWatch` to stop watching the navigator.compass.
+
+    var watchID = navigator.compass.watchHeading(compassSuccess, compassError, [compassOptions]);
+
+`compassOptions` may contain the following keys:
+
+- __frequency__: How often to retrieve the compass heading in milliseconds. _(Number)_ (Default:
100)
+- __filter__: The change in degrees required to initiate a watchHeading success callback.
When this value is set, __frequency__ is ignored. _(Number)_
+
+### Example
+
+    function onSuccess(heading) {
+        var element = document.getElementById('heading');
+        element.innerHTML = 'Heading: ' + heading.magneticHeading;
+    };
+
+    function onError(compassError) {
+        alert('Compass error: ' + compassError.code);
+    };
+
+    var options = {
+        frequency: 3000
+    }; // Update every 3 seconds
+
+    var watchID = navigator.compass.watchHeading(onSuccess, onError, options);
+
+
+### iOS Quirks
+
+Only one `watchHeading` can be in effect at one time in iOS.  If a
+`watchHeading` uses a filter, calling `getCurrentHeading` or
+`watchHeading` uses the existing filter value to specify heading
+changes. Watching heading changes with a filter is more efficient than
+with time intervals.
+
+### Amazon Fire OS Quirks
+
+- `filter` is not supported.
+
+### Android Quirks
+
+- No support for `filter`.
+
+### Tizen Quirks
+
+- No support for `filter`.
+
+### Windows Phone 7 and 8 Quirks
+
+- No support for `filter`.
+
+## navigator.compass.clearWatch
+
+Stop watching the compass referenced by the watch ID parameter.
+
+    navigator.compass.clearWatch(watchID);
+
+- __watchID__: The ID returned by `navigator.compass.watchHeading`.
+
+### Example
+
+    var watchID = navigator.compass.watchHeading(onSuccess, onError, options);
+
+    // ... later on ...
+
+    navigator.compass.clearWatch(watchID);
+
+## CompassHeading
+
+A `CompassHeading` object is returned to the `compassSuccess` callback function.
+
+### Properties
+
+- __magneticHeading__: The heading in degrees from 0-359.99 at a single moment in time. _(Number)_
+
+- __trueHeading__: The heading relative to the geographic North Pole in degrees 0-359.99
at a single moment in time. A negative value indicates that the true heading can't be determined.
 _(Number)_
+
+- __headingAccuracy__: The deviation in degrees between the reported heading and the true
heading. _(Number)_
+
+- __timestamp__: The time at which this heading was determined.  _(milliseconds)_
+
+
+### Amazon Fire OS Quirks
+
+- `trueHeading` is not supported, but reports the same value as `magneticHeading`
+
+- `headingAccuracy` is always 0 because there is no difference between the `magneticHeading`
and `trueHeading`
+
+### Android Quirks
+
+- The `trueHeading` property is not supported, but reports the same value as `magneticHeading`.
+
+- The `headingAccuracy` property is always 0 because there is no difference between the `magneticHeading`
and `trueHeading`.
+
+### iOS Quirks
+
+- The `trueHeading` property is only returned for location services enabled via `navigator.geolocation.watchLocation()`.
+
+- For iOS 4 devices and above, heading factors in the device's current orientation, and does
not reference its absolute position, for apps that supports that orientation.
+
+## CompassError
+
+A `CompassError` object is returned to the `compassError` callback function when an error
occurs.
+
+### Properties
+
+- __code__: One of the predefined error codes listed below.
+
+### Constants
+
+- `CompassError.COMPASS_INTERNAL_ERR`
+- `CompassError.COMPASS_NOT_SUPPORTED`
+


Mime
View raw message