| ||||||
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).
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) |
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 light.off(light.disp1|light.keyb1) |
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) |
Resets all lights to their "normal" state, as imposed by the system.
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.
Returns the bit combination of the available light targets.
|
print light.targets() → 11
// have the secondary keyboard light blink if it existsif light.targets() & light.keyb2 # 0 then light.blink(light.keyb2) end |
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 light.wait(light.disp1) end |