voltmx.accelerometer Namespace

Registers event handlers for acceleration events, such as ‘shake’.

Syntax

voltmx.accelerometer.registerAccelerationEvents(  
    events)

Input Parameters

Example

//Defining the shake event handler function
function onshake() {
    voltmx.print("Shake called");
}

function registerAccelerationEvents() {
   
    // Register acceleration events.

    //Define the event object.
    var events = {
        shake: onshake
    };

    //Register the shake event handler function.
    voltmx.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 SPA, Desktop Web and Mobile Web.

Sets callback functions for retrieving the current device acceleration.

Syntax

voltmx.accelerometer.retrieveCurrentAcceleration (  
    onSuccessCallback,  
    onFailureCallback);

Input Parameters

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) {
    voltmx.print("X: " + accelerometerdata.x + "Y: " + accelerometerdata.y + "Z: " + accelerometerdata.z + "Timestamp: " + accelerometerdata.timestamp);
}
// onfailurecallback 

function onfailurecallback(error) {
    voltmx.print("code: " + error.code + "message: " + error.message);
}

function retrieveCurrentAcceleration() {
    // Set the callbacks for getting the acceleration information. 
    voltmx.accelerometer.retrieveCurrentAcceleration(onsuccesscallback, onfailurecallback);
}

Example 2:

//Displays the accelerometer data in form frmAclMeter1. This is callback function is set by the voltmx.accelerometer.retrievecurrentacceleration function and invoked automatically by the Volt MX Iris 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 Volt MX Iris 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
    {
        voltmx.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.

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 SPA, Desktop Web and Mobile Web.

Starts monitoring the device’s acceleration on a continuous basis.

Syntax

voltmx.accelerometer.startMonitoringAcceleration(  
    onSuccessCallback,  
    onFailureCallback,  
    configData);

Input Parameters

Example

Example 1:

//Start monitoring acceleration

// onSuccessCallback
// This function accepts an 'accelerometerdata' object, which contains the current device acceleration values 
function onSuccessCallback(accelerometerdata) {
    voltmx.print("X: " + accelerometerdata.x + "Y: " + accelerometerdata.y + "Z:" + accelerometerdata.z + "Timestamp: " + accelerometerdata.timestamp);
}

//onFailureCallback callback 
function onFailureCallback(error) {
    voltmx.print("code: " + error.code + "message: " + error.message);
}

function startMonitoringAcceleration() {
    // Start monitor acceleration.
    voltmx.accelerometer.startMonitoringAcceleration(onSuccessCallback, onFailureCallback, {
        frequency: 10,
        onchange: false
    });
}

Example 2:

//To display the accelerometerdata in form frmAclMeter1. This callback function is set by the voltmx.accelerometer.startmonitoringacceleration function and invoked automatically by the Volt MX Iris 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 voltmx.accelerometer.startMonitoringAcceleration function and invoked automatically by the Volt MX Iris 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 {
        voltmx.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.

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 voltmx.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.

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 SPA, Desktop Web, and Mobile Web.

Stops the device monitoring activity if it is active.

Syntax

voltmx.accelerometer.stopMonitoringAcceleration();

Example

function stopMonitoringAcceleration() {
    // Stop the device monitoring activity if it is active.
    voltmx.accelerometer.stopMonitoringAcceleration();
}

Input Parameters

None.

Return Values

None.

Remarks

If your app has been continuously monitoring the device’s motion, it calls the voltmx.accelerometer.stopMonitoringAcceleration to stop. Apps can start monitoring the device motion using the accelerometer.startmonitoringacceleration function.

Platform Availability

Available on all platforms except SPA, Desktop Web, and Mobile Web.

Unregisters event handlers for the specified acceleration event types.

Syntax

voltmx.accelerometer.unregisterAccelerationEvents(  
    eventTypes);

Input Parameters

Example

function unregisteraccelerationevents() {
    // Unregister for acceleration events. 
    voltmx.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 SPA, Desktop Web, and Mobile Web.