| <!-- |
| 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. |
| --> |
| |
| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no, width=device-width"> |
| <meta name="generator" content="joDoc"> |
| <link rel="stylesheet" type="text/css" href="index.css"> |
| <title>PhoneGap API Documentation</title> |
| </head> |
| <body> |
| |
| <div id="header"> |
| <h1>Phone<strong>Gap</strong> Documentation</h1> |
| <small></small> |
| </div> |
| <div id="subheader"> |
| <h1>Accelerometer</h1> |
| <small>[ SELECT BOX PLACEHOLDER ]</small> |
| </div> |
| |
| <div id="sidebar"> |
| <div class="vertical_divider"></div> |
| <h1>API Reference</h1> |
| <ul> |
| <li><a href="phonegap_accelerometer_accelerometer.md.html">Accelerometer</a></li> |
| <li><a href="phonegap_camera_camera.md.html">Camera</a></li> |
| <li><a href="phonegap_device_device.md.html">Device</a></li> |
| <li><a href="phonegap_events_events.md.html">Events</a></li> |
| <li><a href="phonegap_geolocation_geolocation.md.html">Geolocation</a></li> |
| <li><a href="phonegap_notification_notification.md.html">Notification</a></li> |
| </ul> |
| </div> |
| |
| <div id="content"> |
| <h1><a name="Accelerometer">Accelerometer</a></h1> |
| |
| <blockquote> |
| <p>Captures device motion in the x, y, and z direction.</p> |
| </blockquote> |
| |
| <h2>Methods</h2> |
| |
| <ul> |
| <li><a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.getCurrentAcceleration">accelerometer.getCurrentAcceleration</a></li> |
| <li><a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.watchAcceleration">accelerometer.watchAcceleration</a></li> |
| <li><a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.clearWatch">accelerometer.clearWatch</a></li> |
| </ul> |
| <h2>Arguments</h2> |
| |
| <ul> |
| <li><a href="phonegap_accelerometer_accelerometer.md.html#accelerometerSuccess">accelerometerSuccess</a></li> |
| <li><a href="phonegap_accelerometer_accelerometer.md.html#accelerometerError">accelerometerError</a></li> |
| <li><a href="phonegap_accelerometer_accelerometer.md.html#accelerometerOptions">accelerometerOptions</a></li> |
| </ul> |
| <h2>Objects (Read-Only)</h2> |
| |
| <ul> |
| <li><a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a></li> |
| </ul> |
| <hr> |
| <h1><a name="accelerometer.getCurrentAcceleration">accelerometer.getCurrentAcceleration</a></h1> |
| |
| <p>Get the current acceleration along the x, y, and z axis.</p> |
| |
| <pre><code>navigator.accelerometer.getCurrentAcceleration(<a href="phonegap_accelerometer_accelerometer.md.html#accelerometerSuccess">accelerometerSuccess</a>, <a href="phonegap_accelerometer_accelerometer.md.html#accelerometerError">accelerometerError</a>); |
| </code></pre> |
| |
| <h2>Description</h2> |
| |
| <p>The accelerometer is a motion sensor that detects the change (delta) in movement relative to the current position. The accelerometer can detect 3D movement along the x, y, and z axis.</p> |
| |
| <p>The acceleration is returned using the <code><a href="phonegap_accelerometer_accelerometer.md.html#accelerometerSuccess">accelerometerSuccess</a></code> callback function.</p> |
| |
| <h2>Supported Platforms</h2> |
| |
| <ul> |
| <li>iPhone</li> |
| </ul> |
| <h2>Quick Example</h2> |
| |
| <pre><code>function onSuccess(acceleration) { |
| alert('<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> X: ' + acceleration.x + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Y: ' + acceleration.y + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Z: ' + acceleration.z + '\n'; |
| }; |
| |
| function onError() { |
| alert('onError!'); |
| }; |
| |
| navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.getCurrentAcceleration">accelerometer.getCurrentAcceleration</a>(onSuccess, onError); |
| </code></pre> |
| |
| <h2>Full Example</h2> |
| |
| <pre><code><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| "http://www.w3.org/TR/html4/strict.dtd"> |
| <html> |
| <head> |
| <title><a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Example</title> |
| |
| <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> |
| <script type="text/javascript" charset="utf-8"> |
| |
| // Wait for PhoneGap to load |
| // |
| function onLoad() { |
| document.addEventListener("<a href="phonegap_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false); |
| } |
| |
| // PhoneGap is ready |
| // |
| function onDeviceReady() { |
| navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.getCurrentAcceleration">accelerometer.getCurrentAcceleration</a>(onSuccess, onError); |
| } |
| |
| // onSuccess: Get a snapshot of the current acceleration |
| // |
| function onSuccess(acceleration) { |
| alert('<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> X: ' + acceleration.x + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Y: ' + acceleration.y + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Z: ' + acceleration.z + '\n'); |
| } |
| |
| // onError: Failed to get the acceleration |
| // |
| function onError() { |
| alert('onError!'); |
| } |
| |
| </script> |
| </head> |
| <body onload="onLoad()"> |
| <h1>Example</h1> |
| <p>getCurrentAcceleration</p> |
| </body> |
| </html> |
| </code></pre> |
| |
| <h2>iPhone Quirks</h2> |
| |
| <ul> |
| <li>iPhone doesn't have the concept of getting the current acceleration at any given point.</li> |
| <li>You must watch the acceleration and capture the data at given time intervals.</li> |
| <li>Thus, the <code>getCurrentAcceleration</code> function will give you the last value reported from a phoneGap <code>watchAccelerometer</code> call.</li> |
| </ul> |
| <hr> |
| <h1><a name="accelerometer.watchAcceleration">accelerometer.watchAcceleration</a></h1> |
| |
| <p>At a regular interval, get the acceleration along the x, y, and z axis.</p> |
| |
| <pre><code>var watchID = navigator.accelerometer.watchAcceleration(<a href="phonegap_accelerometer_accelerometer.md.html#accelerometerSuccess">accelerometerSuccess</a>, |
| <a href="phonegap_accelerometer_accelerometer.md.html#accelerometerError">accelerometerError</a>, |
| [<a href="phonegap_accelerometer_accelerometer.md.html#accelerometerOptions">accelerometerOptions</a>]); |
| </code></pre> |
| |
| <h2>Description</h2> |
| |
| <p>The accelerometer is a motion sensor that detects the change (delta) in movement relative to the current position. The accelerometer can detect 3D movement along the x, y, and z axis.</p> |
| |
| <p>The <code><a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.watchAcceleration">accelerometer.watchAcceleration</a></code> gets the device's current acceleration at a regular interval. Each time the <code><a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a></code> is retrieved, the <code><a href="phonegap_accelerometer_accelerometer.md.html#accelerometerSuccess">accelerometerSuccess</a></code> callback function is executed. Specify the interval in milliseconds via the <code>frequency</code> parameter in the <code>acceleratorOptions</code> object.</p> |
| |
| <p>The returned watch ID references references the accelerometer watch interval. The watch ID can be used with <code><a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.clearWatch">accelerometer.clearWatch</a></code> to stop watching the accelerometer.</p> |
| |
| <h2>Supported Platforms</h2> |
| |
| <ul> |
| <li>iPhone</li> |
| </ul> |
| <h2>Quick Example</h2> |
| |
| <pre><code>function onSuccess(acceleration) { |
| alert('<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> X: ' + acceleration.x + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Y: ' + acceleration.y + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Z: ' + acceleration.z + '\n'); |
| }; |
| |
| function onError() { |
| alert('onError!'); |
| }; |
| |
| var options = { frequency: 3000 }; // Update every 3 seconds |
| |
| var watchID = navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.watchAcceleration">accelerometer.watchAcceleration</a>(onSuccess, onError, options); |
| </code></pre> |
| |
| <h2>Full Example</h2> |
| |
| <pre><code><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| "http://www.w3.org/TR/html4/strict.dtd"> |
| <html> |
| <head> |
| <title><a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Example</title> |
| |
| <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> |
| <script type="text/javascript" charset="utf-8"> |
| |
| // The watch id references the current `watchAcceleration` |
| var watchID = null; |
| |
| // Wait for PhoneGap to load |
| // |
| function onLoad() { |
| document.addEventListener("<a href="phonegap_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false); |
| } |
| |
| // PhoneGap is ready |
| // |
| function onDeviceReady() { |
| startWatch(); |
| } |
| |
| // Start watching the acceleration |
| // |
| function startWatch() { |
| |
| // Update acceleration every 3 seconds |
| var options = { frequency: 3000 }; |
| |
| watchID = navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.watchAcceleration">accelerometer.watchAcceleration</a>(onSuccess, onError, options); |
| } |
| |
| // Stop watching the acceleration |
| // |
| function stopWatch() { |
| if (watchID) { |
| navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.clearWatch">accelerometer.clearWatch</a>(watchID); |
| watchID = null; |
| } |
| } |
| |
| // onSuccess: Get a snapshot of the current acceleration |
| // |
| function onSuccess(acceleration) { |
| var element = document.getElementById('accelerometer'); |
| element.innerHTML = '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> X: ' + acceleration.x + '<br />' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Y: ' + acceleration.y + '<br />' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Z: ' + acceleration.z + '<br />'; |
| } |
| |
| // onError: Failed to get the acceleration |
| // |
| function onError() { |
| alert('onError!'); |
| } |
| |
| </script> |
| </head> |
| <body onload="onLoad()"> |
| <div id="accelerometer">Waiting for accelerometer...</div> |
| </body> |
| </html> |
| </code></pre> |
| |
| <h2> iPhone Quirks</h2> |
| |
| <ul> |
| <li>At the interval requested, PhoneGap will call the success callback function and pass the accelerometer results.</li> |
| <li>However, in requests to the device PhoneGap restricts the interval to minimum of every 40ms and a maximum of every 1000ms. |
| <ul> |
| <li>For example, if you request an interval of 3 seconds (3000ms), PhoneGap will request an interval of 1 second from the device but invoke the success callback at the requested interval of 3 seconds.</li> |
| </ul> |
| </li> |
| </ul> |
| <hr> |
| <h1><a name="accelerometer.clearWatch">accelerometer.clearWatch</a></h1> |
| |
| <p>Stop watching the <code><a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a></code> referenced by the watch ID parameter.</p> |
| |
| <pre><code>navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.clearWatch">accelerometer.clearWatch</a>(watchID); |
| </code></pre> |
| |
| <ul> |
| <li> |
| <strong>watchID</strong>: The ID returned by <code><a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.watchAcceleration">accelerometer.watchAcceleration</a></code>.</li> |
| </ul> |
| <h2>Supported Platforms</h2> |
| |
| <ul> |
| <li>iPhone</li> |
| </ul> |
| <h2>Quick Example</h2> |
| |
| <pre><code>var watchID = navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.watchAcceleration">accelerometer.watchAcceleration</a>(onSuccess, onError, options); |
| |
| // ... later on ... |
| |
| navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.clearWatch">accelerometer.clearWatch</a>(watchID); |
| </code></pre> |
| |
| <h2>Full Example</h2> |
| |
| <pre><code><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| "http://www.w3.org/TR/html4/strict.dtd"> |
| <html> |
| <head> |
| <title><a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Example</title> |
| |
| <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> |
| <script type="text/javascript" charset="utf-8"> |
| |
| // The watch id references the current `watchAcceleration` |
| var watchID = null; |
| |
| // Wait for PhoneGap to load |
| // |
| function onLoad() { |
| document.addEventListener("<a href="phonegap_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false); |
| } |
| |
| // PhoneGap is ready |
| // |
| function onDeviceReady() { |
| startWatch(); |
| } |
| |
| // Start watching the acceleration |
| // |
| function startWatch() { |
| |
| // Update acceleration every 3 seconds |
| var options = { frequency: 3000 }; |
| |
| watchID = navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.watchAcceleration">accelerometer.watchAcceleration</a>(onSuccess, onError, options); |
| } |
| |
| // Stop watching the acceleration |
| // |
| function stopWatch() { |
| if (watchID) { |
| navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.clearWatch">accelerometer.clearWatch</a>(watchID); |
| watchID = null; |
| } |
| } |
| |
| // onSuccess: Get a snapshot of the current acceleration |
| // |
| function onSuccess(acceleration) { |
| var element = document.getElementById('accelerometer'); |
| element.innerHTML = '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> X: ' + acceleration.x + '<br />' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Y: ' + acceleration.y + '<br />' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Z: ' + acceleration.z + '<br />'; |
| } |
| |
| // onError: Failed to get the acceleration |
| // |
| function onError() { |
| alert('onError!'); |
| } |
| |
| </script> |
| </head> |
| <body onload="onLoad()"> |
| <div id="accelerometer">Waiting for accelerometer...</div> |
| <button onclick="stopWatch();">Stop Watching</button> |
| </body> |
| </html> |
| </code></pre> |
| |
| <hr> |
| <h1><a name="Acceleration">Acceleration</a></h1> |
| |
| <p>Contains <code><a href="phonegap_accelerometer_accelerometer.md.html#Accelerometer">Accelerometer</a></code> data captured at a specific point in time.</p> |
| |
| <h2>Properties</h2> |
| |
| <ul> |
| <li> |
| <strong>x:</strong> Amount of motion on the x-axis. Range [0, 1] (<code>Number</code>)</li> |
| <li> |
| <strong>y:</strong> Amount of motion on the y-axis. Range [0, 1] (<code>Number</code>)</li> |
| <li> |
| <strong>z:</strong> Amount of motion on the z-axis. Range [0, 1] (<code>Number</code>)</li> |
| <li> |
| <strong>timestamp:</strong> Creation timestamp in milliseconds. (<code>DOMTimeStamp</code>)</li> |
| </ul> |
| <h2>Description</h2> |
| |
| <p>This object is created and populated by PhoneGap, and returned by an <code><a href="phonegap_accelerometer_accelerometer.md.html#Accelerometer">Accelerometer</a></code> method.</p> |
| |
| <h2>Supported Platforms</h2> |
| |
| <ul> |
| <li>Untested</li> |
| </ul> |
| <h2>Quick Example</h2> |
| |
| <pre><code>function onSuccess(acceleration) { |
| alert('<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> X: ' + acceleration.x + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Y: ' + acceleration.y + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Z: ' + acceleration.z + '\n'; |
| }; |
| |
| function onError() { |
| alert('onError!'); |
| }; |
| |
| navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.getCurrentAcceleration">accelerometer.getCurrentAcceleration</a>(onSuccess, onError); |
| </code></pre> |
| |
| <h2>Full Example</h2> |
| |
| <pre><code><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| "http://www.w3.org/TR/html4/strict.dtd"> |
| <html> |
| <head> |
| <title><a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Example</title> |
| |
| <script type="text/javascript" charset="utf-8" src="phonegap.js"></script> |
| <script type="text/javascript" charset="utf-8"> |
| |
| // Wait for PhoneGap to load |
| // |
| function onLoad() { |
| document.addEventListener("<a href="phonegap_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false); |
| } |
| |
| // PhoneGap is ready |
| // |
| function onDeviceReady() { |
| navigator.<a href="phonegap_accelerometer_accelerometer.md.html#accelerometer.getCurrentAcceleration">accelerometer.getCurrentAcceleration</a>(onSuccess, onError); |
| } |
| |
| // onSuccess: Get a snapshot of the current acceleration |
| // |
| function onSuccess() { |
| alert('<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> X: ' + acceleration.x + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Y: ' + acceleration.y + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Z: ' + acceleration.z + '\n'; |
| } |
| |
| // onError: Failed to get the acceleration |
| // |
| function onError() { |
| alert('onError!'); |
| } |
| |
| </script> |
| </head> |
| <body onload="onLoad()"> |
| <h1>Example</h1> |
| <p>getCurrentAcceleration</p> |
| </body> |
| </html> |
| </code></pre> |
| |
| <hr> |
| <h1><a name="accelerometerSuccess">accelerometerSuccess</a></h1> |
| |
| <p>onSuccess callback function that provides the <a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> information.</p> |
| |
| <pre><code>function(acceleration) { |
| // Do something |
| } |
| </code></pre> |
| |
| <h2>Parameters</h2> |
| |
| <ul> |
| <li> |
| <strong>acceleration:</strong> The acceleration at a single moment in time. (<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a>)</li> |
| </ul> |
| <h2>Example</h2> |
| |
| <pre><code>function onSuccess(acceleration) { |
| alert('<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> X: ' + acceleration.x + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Y: ' + acceleration.y + '\n' + |
| '<a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a> Z: ' + acceleration.z + '\n'; |
| }; |
| </code></pre> |
| |
| <hr> |
| <h1><a name="accelerometerError">accelerometerError</a></h1> |
| |
| <p>onError callback function for acceleration functions.</p> |
| |
| <pre><code>function() { |
| // Handle the error |
| } |
| </code></pre> |
| |
| <hr> |
| <h1><a name="accelerometerOptions">accelerometerOptions</a></h1> |
| |
| <p>An optional parameter to customize the retrieval of the accelerometer.</p> |
| |
| <h2>Options</h2> |
| |
| <ul> |
| <li> |
| <strong>frequency:</strong> How often to retrieve the <code><a href="phonegap_accelerometer_accelerometer.md.html#Acceleration">Acceleration</a></code> in milliseconds. <em>(Number)</em> (Default: 10000)</li> |
| </ul> |
| </div> |
| |
| </body> |
| </html> |