This tutorial describes how to use the Light API of HWRM.
To
use the Light API, the client must first create an instance of CHWRMLight class. CHWRMLight can be used in two modes:
An instance with notify handling is created if the client requires up-to-date status information. Else, an instance without a callback pointer is created. After an instance is created, lights can be directly controlled through the provided class methods.
There are three light control methods, each with several overloads:
LightOnL() to
turn ON the lights.
LightBlinkL() to
make lights blink.
LightOffL() to
turn OFF the lights.
Light intensity can be optionally controlled by the LightOnL() and LightBlinkL() methods. Intensity is controlled
as a percentage. KHWRMDefaultIntensity can
use default intensity or ambient light sensor controlled intensity, depending
on general settings.
Light fade can be optionally controlled by the LightOnL() and LightOffL() methods.
Fade simply means that lights are turned ON or OFF over a short period of
time with multiple gradual intensity changes instead of single instant change.
Note:
All devices do not support this functionality. The current status of any light
target can be obtained with the LightStatus() method.
All
control methods require at least a target mask as a parameter. Devices can
have multiple independent lights, called targets, such as device primary display
light or keyboard light. All devices do not support all possible light targets.
Supported targets may be queried with the SupportedTargets() method.
All control methods accept optional duration parameter also. Any infinite duration call sets session base light state for targets it affects. This base state is what the target is set to when any duration timer affecting it expires. If there are no infinite duration calls for a target session, any timer expiry for that target sets the target to the default state (which is either ON or OFF), depending on the device inactivity time and the inactivity time-limit defined by general settings.
Each target can have only one duration timer. Hence, if a target with ongoing timer is issued with new orders, the ongoing timer is cancelled and a new one is set.
Using Light API, you can perform any of the tasks listed in the Procedure section.