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

Backlight Module

The Backlight Module is used to illuminate / extinguish the display backlight as well as setting the intensity of the backlight.

Syntax

backlight (Module) <META> Syntax

<META HTTP-Equiv="backlight" content="[parameter]">
Backlight JavaScript Object Syntax:
By default the JavaScript Object 'backlight' will exist on the current page and can be used to interact directly with the backlight.
To Invoke backlight methods via JavaScript use the following syntax: backlight.method();

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

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

e.g. backlight.backlightSettingsEvent = '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: backlight.setEMML("[Your EMML Tags]");

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

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

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

e.g. Backlight.backlightSettingsEvent = url_for(:action => :backlight_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
on Turn on the screen backlight. N/A for Android devices, please use the wake module to keep the screen ON. N/A
off Turn off the screen backlight N/A
getBacklightSettings Returns the backlight settings via a 'backlightSettingsEvent' N/A

Parameters

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

Name Possible Values Description Default Value
intensity:[Value] Positive Number, see remarks for range Sets the screen backlight to the specified intensity. Device Dependant

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.

backlightSettingsEvent

The backlight display settings.

ID Name Description
1 intensity The current backlight intensity value E.g. 2. On Android a negative value indicates the default system value.
2 intensityRange A JavaScript array of integers containing the valid range of intensity values. e.g. ['0','1','2'].
3 state The current backlight state "on" or "off" or "timeout"

Multi Instance

When multiple RhoElememts applications are running the following considerations should be made: The backlight settings are application specific. Switching to another application which uses the backlight module will cause the screen illumination settings to change to those of the application with focus. Only the application with Focus will have the ability to change the backlight settings.

Remarks

General

The intensity tag will only have an observable effect if the screen backlight is turned on, setting the intensity by its self is insufficient to illuminate the backlight.

Device Limits

The levels of supported screen backlight intensity are device dependent. You can determine the levels on your device using the backlightSettingsEvent and getBacklightSettings method.

‘Auto’ and ‘Manual’ Backlight Intensity

Windows Mobile 6.5 Devices with a light sensor, such as the ES400 will support two modes for the Backlight: Auto Mode (default) where the light sensor input affects the backlight intensity and Manual Mode where the user sets the backlight manually. In order to use the Intensity setting in RhoElements the device must be put into Manual Mode, most easily achieved via the ‘Backlight & Keylight’ applet accessed via Start->Settings->System.

Enterprise Tablet

Unlike all other devices, changes made to the backlight intensity are made only to RhoElements. Switching native applications or quitting RhoElements will revert the backlight intensity to the system’s default level until RhoElements is resumed. Also the method “on” does not work as the backlight settings are application specific, please use the Wake module to keep the screen on.

Requirements

RhoElements Version 1.0.0 or above
Supported Devices All supported devices.
Minimum Requirements None
Persistence Persistent - Changes to this module will persist when navigating to a new page.

HTML/JavaScript Examples

The following turns on the screen backlight and sets the intensity to level 2

<META HTTP-Equiv="Backlight-On" Content="Intensity:2">

The following example retrieves the backlight settings

<META HTTP-EQUIV="backlight" content="backlightSettingsEvent:url('javascript:fnBacklightJSON(%json);')">

<SCRIPT>
    function fnBacklightJSON(jsonObject){
        var theOutput = "<B>Backlight State:</B>" + jsonObject.state + "<P>";
        theOutput = theOutput + "<B>Backlight Intensity:</b> " + jsonObject.intensity + "<P>";
        theOutput = theOutput + "<b>Backlight Intensity Range:</b><P>";

        for (var i=0; i<jsonObject.intensityRange.length; i = i + 1){
                theOutput = theOutput + jsonObject.intensityRange[i] + "<BR>";
        }
        theOutput = theOutput + "<P>";
        outputDiv.innerHTML = theOutput;
    }
</SCRIPT>

<div id="outputDiv">Backlight settings go here</div>
<br/>
<INPUT align="center" type="button" value="Retrieve Backlight Settings" onclick="backlight.getBacklightSettings()";>
Back to Top