Prev: Module graph: Screen Graphics
Module light: Control Device Lighting
| || |
|Compatibility of module light|
|Sony Ericsson phones and Nokia S60 2nd Edition phones lack this module.||Module not found|
Provides functions to control the device display light as well as the keyboard illumination.
The lighting elements are accessed by their target number. These numbers can be bitwise combined to address more than one target in one call. The targets are:
• const disp1 = 1
Primary display of the device.
• const keyb1 = 2
Primary keyboard of the device.
• const disp2 = 4
Secondary display of the device.
• const keyb2 = 8
Secondary keyboard of the device.
Some devices have more than these light targets. They are addressed by higher bit values like 16, 32, 64, etc.
Even devices with two displays or keyboards may only recognize the primary ones, those actually in use.
Turning lights on or off may not always have the desired effect, as the state of the lights may also depend on environmental lighting or user activity (e.g., displays will get brighter in a bright environment, whereas keyboard lights may be automatically turned on in a dark environment). Furthermore, the states and state changes reported by this module do not necessarily reflect the real state of the light, as it may be a combination of desired state and a light sensor dependent state.
The functions in this module throw ErrNotSupported if a target is not supported, or ErrArgument if any duration exceeds exceeds 2147483 (35 minutes and 47.483 seconds).
• function blink(target, duration=null, onduration=null, offduration=null, intensity=null) → null
Blinks the target light(s) of the device for duration milliseconds with intensity intensity. After the duration expires, the light state for target will be changed to whatever state it was before. If duration=null, the light will blink until its state is changed explicitly. onduration indicates the number of milliseconds the light should be on in each cycle, null uses a default value. offduration indicates the number of milliseconds the light should be off in each cycle, null uses a default value. Not all devices support the setting of cycle durations. The intensity must be a value between 1 and 100, or null for the default intensity.
// have the (primary) keyboard blink for 5 seconds,|
// twice per second
light.blink(light.keyb1, 5000, 250, 250)
• function off(target, duration=null, fade=false) → null
Switches the target lights off for duration milliseconds. After the duration expires, the light state for target will be changed to whatever state it was before. If duration=null, the light will stay off until its state is changed explicitly. If fade=true, lights will not turn off instantly, but instead smoothly fade-out. Not all devices support fade-out.
// turn (primary) display and keyboard lights off|
• function on(target, duration=null, intensity=null, fade=false) → null
Switches the target lights on for duration milliseconds with intensity intensity. After the duration expires, the light state for target will be changed to whatever state it was before. If duration=null, the light will stay on until its state is changed explicitly. The intensity must be a value between 1 and 100, or null for the default intensity. If fade=true, lights will not turn on instantly, but instead smoothly fade-in. Not all devices support fade-in.
// set the display light to the maximum, fading-in|
light.on(light.disp1, null, 100, true)
• function reset() → null
Resets all lights to their "normal" state, as imposed by the system.
• function state(target) → Number
Retrieves the current light state. Supports only one single target, as different targets might have different states.
Returns one of the following values:
• const unknown = 0
Signals an error condition.
• const on = 1
The light is on.
• const off = 2
The light is off.
• const blink = 3
The light is blinking.
• function targets() → Number
Returns the bit combination of the available light targets.
// have the secondary keyboard light blink if it exists
if light.targets() & light.keyb2 # 0 then
• function wait(targets, timeout=-1) → Boolean
Waits for a state change of any of the lights in targets, and returns true when at least one of these lights changed. If timeout>=0 and timeout milliseconds have passed without a change, false is returned.
// wait until the display light turns off, which|
// indicates inactivity
while light.state(light.disp1)=light.on do
Next: Module ui: User Interface Functions
© 2004-2011 airbit AG, CH-8008 Zürich