Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Lightsensor Module

The Lightsensor Module is used to retrieve the intensity of the ambient light falling on the device..

Syntax

lightsensor (Module) <META> Syntax

<META HTTP-Equiv="LightSensor" content="[parameter]">

<META HTTP-Equiv="LightSensor" content="LightSensorEvent:url('[jsFunction | url]')">

Lightsensor JavaScript Object Syntax:
By default the JavaScript Object 'lightsensor' will exist on the current page and can be used to interact directly with the lightsensor.
To Invoke lightsensor methods via JavaScript use the following syntax: lightsensor.method();

e.g. lightsensor.getSensorData();
To Set lightsensor parameters via JavaScript use the following syntax: lightsensor.parameter = 'value'; remembering to enclose your value in quotes where appropriate.

e.g. lightsensor.status = 'value';
To Set lightsensor return events via JavaScript use the following syntax: lightsensor.event = JavaScript Function;

e.g. lightsensor.LightSensorEvent = 'doFunction(%json)';

For more details on the event syntax and parameters see the Retrieval Events page.
To set multiple EMML parameters / events on a single line use the following syntax: lightsensor.setEMML("[Your EMML Tags]");

e.g. lightsensor.setEMML("status:value;LightSensorEvent:url('JavaScript:doFunction(%json)');getSensorData");
Lightsensor Ruby Object Syntax:
By default the Ruby Object 'Lightsensor' will exist on the current page and can be used to interact directly with the Lightsensor. All Methods, Parameters and Events are the same as JavaScript, however, notice 'Lightsensor' needs to start with an uppercase letter. Another difference in Ruby is that methods do not end in '()'
To Invoke Lightsensor methods via Ruby use the following syntax: Lightsensor.method()

e.g. Lightsensor.getSensorData
To Set Lightsensor parameters via Ruby use the following syntax: Lightsensor.parameter = 'value' remembering to enclose your value in quotes where appropriate.

e.g. Lightsensor.status = 'value'
To Set Lightsensor return events via Ruby use the following syntax: Lightsensor.event = url_for(:action => :event_callback)

e.g. Lightsensor.LightSensorEvent = url_for(:action => :lightsensor_event_callback)

For more details on the event syntax and parameters see the Retrieval Events page.

To access the event parameters in a Ruby callback function, you reference the @params object within the callback function. This object is simply a ruby hash {"parameter1 name" => "parameter1 value", "parameter2 name" => "parameter2 value", ...}

Methods

Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Name Description Default Value
getSensorData This immediately returns the Ambient Light sensor via the LightSensorEvent N/A

Parameters

Items listed in this section indicate parameters, or attributes which can be set.

Name Possible Values Description Default Value
status:[Value] Enabled, disabled Enables / disables the Light Sensor value retrieval disabled
minimumInterval:[Value] Value in milli seconds The minimum amount of time gap between two sensor update events, specified in milliseconds. The interval cannot be set to less than 200 milliseconds, if a value of less than 200 milli seconds is specified, the interval will be defaulted to 200 milli seconds. 1000 milliseconds

Events

Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a JavaScript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or JavaScript arrays. Event parameters can be accessed either directly or via JSON objects.


LightSensorEvent

The LightSensorEvent gives the LightSensor value. Once registered for you will receive a LightSensorEvent when it gets changed.

ID Name Description
1 LightSensorValue LightSensor value in SI lux units

Remarks

minimum interval

As the light sensor value change rapidly the minimum interval between two updates should be specified as a reasonable value, otherwise there can be a performance impact.

Cross platform consistency

As this plugin returns the raw sensor values reported by the operating system the values might differ between platforms.

Requirements

RhoElements Version 2.1 or above
Supported Devices All supported devices. On Windows this is only supported in MPA3.0 devices.
Minimum Requirements None.
Persistence Non Persistent - Changes to this module will not persist when navigating to a new page.

HTML/JavaScript Examples

The following example retrieves the light sensor value when it is changed

<META HTTP-EQUIV="LightSensor" CONTENT="LightSensorEvent:url('JavaScript:onSensor(%json);');status:enabled; ">

<SCRIPT>
    function onSensor(jsonObject)
    {
        var theOutput = "Light Sensor: " + jsonObject.LightSensorValue;                
        outputDiv.innerHTML = theOutput;
    }
</SCRIPT>
<div id="outputDiv">Light Sensor Output Goes Here</div>
<P>
  <INPUT align="center" type="button" value="Retrieve Light Sensor Data" onclick="LightSensor.getSensorData();"><br>
Back to Top