1 |
|
2 | Licensed to the Apache Software Foundation (ASF) under one
|
3 | or more contributor license agreements. See the NOTICE file
|
4 | distributed with this work for additional information
|
5 | regarding copyright ownership. The ASF licenses this file
|
6 | to you under the Apache License, Version 2.0 (the
|
7 | "License"); you may not use this file except in compliance
|
8 | with the License. You may obtain a copy of the License at
|
9 |
|
10 | http://www.apache.org/licenses/LICENSE-2.0
|
11 |
|
12 | Unless required by applicable law or agreed to in writing,
|
13 | software distributed under the License is distributed on an
|
14 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
15 | KIND, either express or implied. See the License for the
|
16 | specific language governing permissions and limitations
|
17 | under the License.
|
18 | -->
|
19 |
|
20 | # org.apache.cordova.device-orientation
|
21 |
|
22 | This plugin provides access to the device's compass. The compass is a sensor
|
23 | that detects the direction or heading that the device is pointed, typically
|
24 | from the top of the device. It measures the heading in degrees from 0 to
|
25 | 359.99, where 0 is north.
|
26 |
|
27 | Access is via a global `navigator.compass` object.
|
28 |
|
29 | Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event.
|
30 |
|
31 | document.addEventListener("deviceready", onDeviceReady, false);
|
32 | function onDeviceReady() {
|
33 | console.log(navigator.compass);
|
34 | }
|
35 |
|
36 | ## Installation
|
37 |
|
38 | cordova plugin add org.apache.cordova.device-orientation
|
39 |
|
40 | ## Supported Platforms
|
41 |
|
42 | - Amazon Fire OS
|
43 | - Android
|
44 | - BlackBerry 10
|
45 | - Browser
|
46 | - Firefox OS
|
47 | - iOS
|
48 | - Tizen
|
49 | - Windows Phone 7 and 8 (if available in hardware)
|
50 | - Windows 8
|
51 |
|
52 | ## Methods
|
53 |
|
54 | - navigator.compass.getCurrentHeading
|
55 | - navigator.compass.watchHeading
|
56 | - navigator.compass.clearWatch
|
57 |
|
58 | ## navigator.compass.getCurrentHeading
|
59 |
|
60 | Get the current compass heading. The compass heading is returned via a `CompassHeading`
|
61 | object using the `compassSuccess` callback function.
|
62 |
|
63 | navigator.compass.getCurrentHeading(compassSuccess, compassError);
|
64 |
|
65 | ### Example
|
66 |
|
67 | function onSuccess(heading) {
|
68 | alert('Heading: ' + heading.magneticHeading);
|
69 | };
|
70 |
|
71 | function onError(error) {
|
72 | alert('CompassError: ' + error.code);
|
73 | };
|
74 |
|
75 | navigator.compass.getCurrentHeading(onSuccess, onError);
|
76 |
|
77 | ## navigator.compass.watchHeading
|
78 |
|
79 | Gets the device's current heading at a regular interval. Each time the heading
|
80 | is retrieved, the `headingSuccess` callback function is executed.
|
81 |
|
82 | The returned watch ID references the compass watch interval. The watch
|
83 | ID can be used with `navigator.compass.clearWatch` to stop watching the navigator.compass.
|
84 |
|
85 | var watchID = navigator.compass.watchHeading(compassSuccess, compassError, [compassOptions]);
|
86 |
|
87 | `compassOptions` may contain the following keys:
|
88 |
|
89 | - __frequency__: How often to retrieve the compass heading in milliseconds. _(Number)_ (Default: 100)
|
90 | - __filter__: The change in degrees required to initiate a watchHeading success callback. When this value is set, __frequency__ is ignored. _(Number)_
|
91 |
|
92 | ### Example
|
93 |
|
94 | function onSuccess(heading) {
|
95 | var element = document.getElementById('heading');
|
96 | element.innerHTML = 'Heading: ' + heading.magneticHeading;
|
97 | };
|
98 |
|
99 | function onError(compassError) {
|
100 | alert('Compass error: ' + compassError.code);
|
101 | };
|
102 |
|
103 | var options = {
|
104 | frequency: 3000
|
105 | }; // Update every 3 seconds
|
106 |
|
107 | var watchID = navigator.compass.watchHeading(onSuccess, onError, options);
|
108 |
|
109 |
|
110 | ### Browser Quirks
|
111 |
|
112 | Values for current heading are randomly generated in order to simulate the compass.
|
113 |
|
114 | ### iOS Quirks
|
115 |
|
116 | Only one `watchHeading` can be in effect at one time in iOS. If a
|
117 | `watchHeading` uses a filter, calling `getCurrentHeading` or
|
118 | `watchHeading` uses the existing filter value to specify heading
|
119 | changes. Watching heading changes with a filter is more efficient than
|
120 | with time intervals.
|
121 |
|
122 | ### Amazon Fire OS Quirks
|
123 |
|
124 | - `filter` is not supported.
|
125 |
|
126 | ### Android Quirks
|
127 |
|
128 | - No support for `filter`.
|
129 |
|
130 | ### Firefox OS Quirks
|
131 |
|
132 | - No support for `filter`.
|
133 |
|
134 | ### Tizen Quirks
|
135 |
|
136 | - No support for `filter`.
|
137 |
|
138 | ### Windows Phone 7 and 8 Quirks
|
139 |
|
140 | - No support for `filter`.
|
141 |
|
142 | ## navigator.compass.clearWatch
|
143 |
|
144 | Stop watching the compass referenced by the watch ID parameter.
|
145 |
|
146 | navigator.compass.clearWatch(watchID);
|
147 |
|
148 | - __watchID__: The ID returned by `navigator.compass.watchHeading`.
|
149 |
|
150 | ### Example
|
151 |
|
152 | var watchID = navigator.compass.watchHeading(onSuccess, onError, options);
|
153 |
|
154 | // ... later on ...
|
155 |
|
156 | navigator.compass.clearWatch(watchID);
|
157 |
|
158 | ## CompassHeading
|
159 |
|
160 | A `CompassHeading` object is returned to the `compassSuccess` callback function.
|
161 |
|
162 | ### Properties
|
163 |
|
164 | - __magneticHeading__: The heading in degrees from 0-359.99 at a single moment in time. _(Number)_
|
165 |
|
166 | - __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)_
|
167 |
|
168 | - __headingAccuracy__: The deviation in degrees between the reported heading and the true heading. _(Number)_
|
169 |
|
170 | - __timestamp__: The time at which this heading was determined. _(milliseconds)_
|
171 |
|
172 |
|
173 | ### Amazon Fire OS Quirks
|
174 |
|
175 | - `trueHeading` is not supported, but reports the same value as `magneticHeading`
|
176 |
|
177 | - `headingAccuracy` is always 0 because there is no difference between the `magneticHeading` and `trueHeading`
|
178 |
|
179 | ### Android Quirks
|
180 |
|
181 | - The `trueHeading` property is not supported, but reports the same value as `magneticHeading`.
|
182 |
|
183 | - The `headingAccuracy` property is always 0 because there is no difference between the `magneticHeading` and `trueHeading`.
|
184 |
|
185 | ### Firefox OS Quirks
|
186 |
|
187 | - The `trueHeading` property is not supported, but reports the same value as `magneticHeading`.
|
188 |
|
189 | - The `headingAccuracy` property is always 0 because there is no difference between the `magneticHeading` and `trueHeading`.
|
190 |
|
191 | ### iOS Quirks
|
192 |
|
193 | - The `trueHeading` property is only returned for location services enabled via `navigator.geolocation.watchLocation()`.
|
194 |
|
195 | - 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.
|
196 |
|
197 | ## CompassError
|
198 |
|
199 | A `CompassError` object is returned to the `compassError` callback function when an error occurs.
|
200 |
|
201 | ### Properties
|
202 |
|
203 | - __code__: One of the predefined error codes listed below.
|
204 |
|
205 | ### Constants
|
206 |
|
207 | - `CompassError.COMPASS_INTERNAL_ERR`
|
208 | - `CompassError.COMPASS_NOT_SUPPORTED`
|
209 |
|