kony.accelerometer Namespace
The kony.accelerometer namespace provides the following API elements for managing and retrieving data from the device's accelerometer.
Accelerometer Functions
The kony.accelerometer namespace provides the following functions.
Registers event handlers for acceleration events, such as 'shake'.
Syntax
kony.accelerometer.registerAccelerationEvents(events);
Input Parameters
Parameter | Description |
---|---|
events | An object that specifies a hash table containing the events. This table has the key-value pairs that specify the event and the event handler. |
Example
//Defining the shake event handler function function onshake() { kony.print("Shake called"); } function registerAccelerationEvents() { // Register acceleration events. //Define the event object. var events = { shake: onshake }; //Register the shake event handler function. kony.accelerometer.registerAccelerationEvents(events); }
Return Values
None.
Remarks
Event handlers that you set with this function are called asynchronously whenever an accelerometer event occurs. The event handler is triggered only at the end of the event. For example, a shake
event handler is called after the shaking has stopped, indicating that device motion has occurred. The precision with which a shake
event can be recognized may vary per platform and depends on the device capability.
The table contained in the event parameter has the following format: {<event>:<event-handler-function>}
where <event>
is the name of the event and <event-handler-function>
is the name of the event handler function for that specific event. For example, to set an event handler for the shake
event, the table would look similar to the following.
{shake:onshake}
NOTE: Currently, shake is the only event that is supported.
Platform Availability
Available on all platforms except Desktop Web.
Sets callback functions for retrieving the current device acceleration.
Syntax
kony.accelerometer.retrieveCurrentAcceleration (onSuccessCallback, onFailureCallback);
Input Parameters
Parameter | Description |
---|---|
onSuccessCallback | The callback function that is executed when retrieving the current device acceleration is successful. For details, see the Remarks section below. |
onFailureCallback | The callback that is executed when an error occurs while retrieving the current device acceleration. For details, see the Remarks section below. |
Example
Example 1:
// Retrieve the current acceleration data // onsuccesscallback // This method accepts an 'accelerometerdata' object, which contains the current device acceleration values function onsuccesscallback(accelerometerdata) { kony.print("X: " + accelerometerdata.x + "Y: " + accelerometerdata.y + "Z: " + accelerometerdata.z + "Timestamp: " + accelerometerdata.timestamp); } // onfailurecallback function onfailurecallback(error) { kony.print("code: " + error.code + "message: " + error.message); } function retrieveCurrentAcceleration() { // Set the callbacks for getting the acceleration information. kony.accelerometer.retrieveCurrentAcceleration(onsuccesscallback, onfailurecallback); }
Example 2:
//Displays the accelerometer data in form frmAclMeter1. This is callback function is set by the kony.accelerometer.retrievecurrentacceleration function and invoked automatically by the Quantum Visualizer API framework when the retrieval of the current device acceleration is successful. function onsuccesscallbackretCurrentAcc(accelerometerdata) { frmAclMeter1.lblX.text = accelerometerdata.x; frmAclMeter1.lblY.text = accelerometerdata.y; frmAclMeter1.lblZ.text = accelerometerdata.z; frmAclMeter1.lblT.text = accelerometerdata.timestamp; } //To display an error alert if retrievecurrentacceleration fails. This callback function is set by the accelerometer.retrievecurrentacceleration function and invoked automatically by the Quantum Visualizer API Framework when the retrieval of the current device acceleration is unsuccessful/failed. function onfailurecallbackretCurrentAcc(error) { alert("Accelerometer is not supported in the device."); } //Calls the accelerometer.retrievecurrentacceleration. Function to retrieve the current device acceleration. function retrieveCurrentAcceleration() { try { kony.accelerometer.retrieveCurrentAcceleration( onsuccesscallbackretCurrentAcc, onfailurecallbackstartmonitoringAcc); frmAclMeter1.btnStopAcc.setVisibility(false); } catch(e) { alert("Accelerometer not supported."); } }
Return Values
None.
Remarks
This function sets twp callback that your app uses for retrieving the current acceleration information from the device. One is called if the acceleration was successfully retrieved, while the other is called if it was not.
The onSuccessCallback parameter contains a callback function that is invoked upon success has the following syntax:
onSuccessCallback(accelerometerdata);
The accelerometerdata parameter to the onSuccessCallback
function is a table containing key-value pairs, as explained in the following.
Key | Type | Description |
---|---|---|
x | Floating Point Number | The acceleration in the X direction. |
y | Floating Point Number | The acceleration in the Y direction. |
z | Floating Point Number | The acceleration in the Z direction. |
timestamp | Floating Point Number | The number of milli seconds elapsed since the start of the Unix Epoch. The standard Unix Epoch is 00:00:00 UTC on 1 January 1970. The timestamp does not reflect the frequency at which the device can retrieve the accelerometer data, because the device capability (in terms of frequency) can vary from one platform to the other. |
The onFailureCallback parameter contains callback function that is invoked if an error occurs has the following syntax:
onFailureCallback();
The onFailureCallback
function has no parameters. It enables your app to handle the error however you want it to.
The two callback functions are invoked asynchronously and this function returns the value immediately without waiting for actual retrieval of the device acceleration data.
Platform Availability
Available on all platforms except Desktop Web.
Starts monitoring the device's acceleration on a continuous basis.
Syntax
kony.accelerometer.startMonitoringAcceleration(onSuccessCallback, onFailureCallback, configData);
Input Parameters
Parameter | Description |
---|---|
onSuccessCallback | The callback function that is executed when retrieving the current device acceleration is successful. For details, see the Remarks section below. |
onFailureCallback | The callback that is executed when an error occurs while retrieving the current device acceleration. For details, see the Remarks section below. |
configData | A JavaScript object that specifies the configuration parameters for the monitoring operation. For details, see the Remarks section below. |
Example
Example 1:
//Start monitoring acceleration // onSuccessCallback // This function accepts an 'accelerometerdata' object, which contains the current device acceleration values function onSuccessCallback(accelerometerdata) { kony.print("X: " + accelerometerdata.x + "Y: " + accelerometerdata.y + "Z:" + accelerometerdata.z + "Timestamp: " + accelerometerdata.timestamp); } //onFailureCallback callback function onFailureCallback(error) { kony.print("code: " + error.code + "message: " + error.message); } function startMonitoringAcceleration() { // Start monitor acceleration. kony.accelerometer.startMonitoringAcceleration(onSuccessCallback, onFailureCallback, { frequency: 10, onchange: false }); }
Example 2:
/*To display the accelerometerdata in form frmAclMeter1. This callback function is set by the kony.accelerometer.startmonitoringacceleration function and invoked automatically by the Quantum Visualizer API Framework when the retrieval of the current device acceleration is successful and there is a change in the device acceleration values because the device has moved.*/ function onsuccesscallbackstartmonitoringAcc(startmonitoringdata) { frmAclMeter1.lblX.text = startmonitoringdata.x; frmAclMeter1.lblY.text = startmonitoringdata.y; frmAclMeter1.lblZ.text = startmonitoringdata.z; frmAclMeter1.lblT.text = startmonitoringdata.timestamp; } /*To display an error alert if startMonitoringAccelerationfails. This callback function is set by the kony.accelerometer.startMonitoringAcceleration function and invoked automatically by the Quantum Visualizer API Framework when the retrieval of the current device acceleration is unsuccessful/failed.*/ function onfailurecallbackstartmonitoringAcc(error) { alert("Accelerometer is not supported in the device."); } // To call accelerometer.startmonitoringacceleration API to start monitoring the device acceleration or motion. function startmonitoringAcc() { try { kony.accelerometer.startMonitoringAcceleration( onsuccesscallbackstartmonitoringAcc, onfailurecallbackstartmonitoringAcc, { frequency: 200, onChange: true }); frmAclMeter1.btnStopAcc.setVisibility(true); } catch (e) { alert("Accelerometer is not supported."); } }
Return Values
None.
Remarks
By calling this function, your app can start monitoring the device acceleration or motion continuously. When there is a change in the device acceleration values because the device moves, the callback functions passed in through this function's parameters are invoked asynchronously. This function returns immediately without waiting for the device initialization for accelerometer.
The onSuccessCallback parameter contains a callback function that is invoked upon success has the following syntax:
onSuccessCallback(accelerometerdata);
The accelerometerdata parameter to the onSuccessCallback
function is a table containing key-value pairs, as explained in the following.
Key | Type | Description |
---|---|---|
x | Floating Point Number | The acceleration in the X direction. |
y | Floating Point Number | The acceleration in the Y direction. |
z | Floating Point Number | The acceleration in the Z direction. |
timestamp | Floating Point Number | The number of milli seconds elapsed since the start of the Unix Epoch. The standard Unix Epoch is 00:00:00 UTC on 1 January 1970. The timestamp does not reflect the frequency at which the device can retrieve the accelerometer data, because the device capability (in terms of frequency) can vary from one platform to the other. |
The callback function that is invoked if an error occurs has the following syntax:
onFailureCallback();
The onFailureCallback
function has no parameters. It enables your app to handle the error however you want it to.
The two callback functions are invoked asynchronously and this function returns the value immediately without waiting for actual retrieval of the device acceleration data.
When your app invokes the kony.accelerometer.startMonitoringAcceleration
function, the third parameter that your app must pass is configData. The configData parameter contains a JavaScript object that holds a set of key-value pairs that must be in the following format.
Key | Type | Description |
---|---|---|
frequency | Floating Point Number | The time interval, in milliseconds, in which accelerometer data needs to be retrieved. The default value of frequency must be "200" milliseconds minimum. Any negative value specified in the frequency reverts to the default value i.e., 200ms. |
onchange | Boolean | A value that determines whether or not to trigger an event whenever the device is moving regardless of the value specified in frequency . If onchange is set to true , the number set in frequency is not respected and the onSuccessCallback event is invoked whenever the device is in motion. If this value is set to false, the onSuccessCallback event is invoked in the time interval specified in the frequency parameter is used. The default value for onchange is false. |
NOTE: If you set onchange
to false
, it is necessary to specify a frequency
value or the onSuccessCallback function is never invoked.
Platform Availability
Available on all platforms except Desktop Web.
Stops the device monitoring activity if it is active.
Syntax
kony.accelerometer.stopMonitoringAcceleration();
Example
function stopMonitoringAcceleration() { // Stop the device monitoring activity if it is active. kony.accelerometer.stopMonitoringAcceleration(); }
Input Parameters
None.
Return Values
None.
Remarks
If your app has been continuously monitoring the device's motion, it calls the kony.accelerometer.stopMonitoringAcceleration
to stop. Apps can start monitoring the device motion using the accelerometer.startmonitoringacceleration function.
Platform Availability
Available on all platforms except Desktop Web.
Unregisters event handlers for the specified acceleration event types.
Syntax
kony.accelerometer.unregisterAccelerationEvents(eventTypes);
Input Parameters
Parameter | Description |
---|---|
eventTypes | An array of events. |
Example
function unregisteraccelerationevents() { // Unregister for acceleration events. kony.accelerometer.unregisteraccelerationevents({ "shake" }); }
Return Values
None.
Remarks
After this function returns, the event specified in the eventTypes parameter no longer have event handlers registered for them. As a result, your app no longer receives notifications of those events.
Platform Availability
Available on all platforms except Desktop Web.