You are here: Accelerometer APIs
Accelerometer API
Using the Accelerometer API, you can register various gesture events (such as shake), and then detect the change in orientation of a device along three orthogonal axes x, y, and z.
The following diagram shows the standard coordinate system that the Volt MX Accelerometer API uses
This coordinate system is independent of any particular type of device. The following table describes the coordinate system to be used for the accelerometer API:
| Axis | Description | Value | Direction |
|---|---|---|---|
| X | Floating point value indicating the magnitude of the acceleration force along the X-Axis | positive | Towards the right when the device is facing you |
| negative | Towards the left when the device is facing you | ||
| Y | Floating point value indicating the magnitude of the acceleration force along the Y-Axis | positive | Towards the top of the top of the device |
| negative | Towards the bottom of the device | ||
| Z | Floating point value indicating the magnitude of the acceleration force along the Z-Axis | positive | The axis coming out from the device screen (towards you) when the device is facing you |
| negative | The axis coming out from the device back (away from you) when the device is facing you |
The Accelerometer API uses voltmx.accelerometer Namespace and helps you manage and retrieve data from the device's accelerometer. It comprises of the following API elements.
| Function | Description |
|---|---|
| voltmx.accelerometer.registerAccelerationEvents | Registers event handlers for acceleration events, such as 'shake'. |
| voltmx.accelerometer.retrieveCurrentAcceleration | Sets callback functions for retrieving the current device acceleration. |
| voltmx.accelerometer.startMonitoringAcceleration | Starts monitoring the device's acceleration on a continuous basis. |
| voltmx.accelerometer.stopMonitoringAcceleration | Stops the device monitoring activity if it is active. |
| voltmx.accelerometer.unregisterAccelerationEvents | Unregisters event handlers for the specified acceleration event types. |
When you use the Acceleometer API, any changes in gestures are registered by invoking the voltmx.accelerometer.registerAccelerationEvents function. After the change is registered, the current acceleration of the device is determined by using the voltmx.accelerometer.retrieveCurrentAcceleration function. Moniter the acceleration of the device by using the voltmx.accelerometer.startMonitoringAcceleration function. To stop monitoring the device, use the voltmx.accelerometer.stopMonitoringAcceleration function. To unregister event handlers for the specified acceleration event types, you can use the voltmx.accelerometer.unregisterAccelerationEvents function.
Note: The accelerometer APIs are applicable only when
os.platform().hasaccelerometerreturns true.
To view the functionality of the Accelerometer API in action, download the sample application from the link below. Once the application is downloaded, build and preview the application using the Volt MX App.
