|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-D4E06508-4346-5294-995A-64B403467EC5" xml:lang="en"><title>Light |
|
13 API Tutorial</title><shortdesc>This tutorial describes how to use the Light API of HWRM. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-275E5AC3-0D51-5783-8E3F-DCEE6B37970B"><title>Introduction</title> <p>To |
|
15 use the Light API, the client must first create an instance of <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>CHWRMLight</apiname></xref> class. <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>CHWRMLight</apiname></xref> can be used in two modes: </p> <ul> |
|
16 <li id="GUID-BB6B2D97-C797-5C5C-9CB4-0DA5F7682814"><p>With notify handling. </p> </li> |
|
17 <li id="GUID-A22F084E-2204-5589-B664-053EC50DEE0C"><p>Without notify handling. </p> </li> |
|
18 </ul> <p>An instance with notify handling is created if the client requires |
|
19 up-to-date status information. Else, an instance without a callback pointer |
|
20 is created. After an instance is created, lights can be directly controlled |
|
21 through the provided class methods. </p> <p>There are three light control |
|
22 methods, each with several overloads: </p> <ul> |
|
23 <li id="GUID-FE777756-F97C-5B4E-8334-C061FFCC0EBB"><p> <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightOnL()</apiname></xref> to |
|
24 turn ON the lights. </p> </li> |
|
25 <li id="GUID-FC98BD11-09E2-574D-9A05-5C48B39A6C7E"><p> <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightBlinkL()</apiname></xref> to |
|
26 make lights blink. </p> </li> |
|
27 <li id="GUID-EA1C4E36-1B59-57AC-B282-91FACF32A3E3"><p> <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightOffL()</apiname></xref> to |
|
28 turn OFF the lights. </p> </li> |
|
29 </ul> <p>Light intensity can be optionally controlled by the <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightOnL()</apiname></xref> and <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightBlinkL()</apiname></xref> methods. Intensity is controlled |
|
30 as a percentage. <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>KHWRMDefaultIntensity</apiname></xref> can |
|
31 use default intensity or ambient light sensor controlled intensity, depending |
|
32 on general settings. </p> <p>Light fade can be optionally controlled by the <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightOnL()</apiname></xref> and <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightOffL()</apiname></xref> methods. |
|
33 Fade simply means that lights are turned ON or OFF over a short period of |
|
34 time with multiple gradual intensity changes instead of single instant change. </p> <p> <b>Note</b>: |
|
35 All devices do not support this functionality. The current status of any light |
|
36 target can be obtained with the <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>LightStatus()</apiname></xref> method. </p> <p>All |
|
37 control methods require at least a target mask as a parameter. Devices can |
|
38 have multiple independent lights, called targets, such as device primary display |
|
39 light or keyboard light. All devices do not support all possible light targets. |
|
40 Supported targets may be queried with the <xref href="GUID-3B241B7B-C5D3-33AE-9D51-3F3B78530F60.dita"><apiname>SupportedTargets()</apiname></xref> method. </p> <p>All |
|
41 control methods accept optional duration parameter also. Any infinite duration |
|
42 call sets session base light state for targets it affects. This base state |
|
43 is what the target is set to when any duration timer affecting it expires. |
|
44 If there are no infinite duration calls for a target session, any timer expiry |
|
45 for that target sets the target to the default state (which is either ON or |
|
46 OFF), depending on the device inactivity time and the inactivity time-limit |
|
47 defined by general settings. </p> <p>Each target can have only one duration |
|
48 timer. Hence, if a target with ongoing timer is issued with new orders, the |
|
49 ongoing timer is cancelled and a new one is set. </p><p>Using Light API, you |
|
50 can perform any of the tasks listed in the Procedure section.</p> </section> |
|
51 <section><title>Procedure</title> <ul id="GUID-95D4E107-AA25-51F0-B081-6889586420F8"> |
|
52 <li id="GUID-25998A3D-1DE9-52FA-8CC7-26657DF8724C"><p><xref href="GUID-CD87FAF6-A11D-4260-9472-CABA18BF86B1.dita">Creating |
|
53 a light instance</xref> </p> </li> |
|
54 <li id="GUID-8567BEBC-4992-5F8F-B9E2-EE1D20C120A8"><p><xref href="GUID-4860A4E6-1641-47D9-8243-C03779276C6D.dita">Retrieving |
|
55 the supported light targets of a device</xref> </p> </li> |
|
56 <li id="GUID-4A985353-C4E0-5ABA-AB97-49E24B99B924"><p><xref href="GUID-D21191CC-965A-4F92-9792-4B34D54114DA.dita">Retrieving |
|
57 the current light status</xref> </p> </li> |
|
58 <li id="GUID-A22870FD-1722-5DCA-BA29-19C66792F148"><p><xref href="GUID-6DA81F01-FBD7-4167-B722-832888DEC0AD.dita">Reserving |
|
59 light targets</xref> </p> </li> |
|
60 <li id="GUID-C136D460-E987-5A04-B6BE-0AB25115623E"><p><xref href="GUID-4FE4B515-EE2B-47DB-BECE-E390E4EB2C3E.dita">Switching |
|
61 ON the lights</xref> </p> </li> |
|
62 <li id="GUID-125018AA-1FAC-5EB2-A6A9-F0A7E01A2484"><p><xref href="GUID-056736E0-3DF0-49FE-A44D-1A8E47FE45A0.dita">Switching |
|
63 OFF the lights</xref> </p> </li> |
|
64 <li id="GUID-B68A413F-892D-5F5A-8EF9-58C9549050A8"><p><xref href="GUID-3715E8EE-FF0A-4344-90F1-1609D54C166B.dita">Blinking |
|
65 lights</xref> </p> </li> |
|
66 <li id="GUID-125ED39B-08F1-5AE6-8664-93EFC03E6016"><p><xref href="GUID-CF6C76A5-AC87-4EBD-AECF-35B456219B94.dita">Releasing |
|
67 the reserved lights</xref> </p> </li> |
|
68 <li id="GUID-3F750C8E-6668-52A5-A7C5-DDD960DECD6E"><p><xref href="GUID-2382F758-35CF-4378-A5D5-183121E3BF6A.dita">Releasing |
|
69 the instance</xref> </p> </li> |
|
70 </ul> </section> |
|
71 <section><title>See also</title> <p><xref href="GUID-1969956D-CDA0-5DA0-ACF8-69AFBBEC1408.dita">Light |
|
72 API</xref> </p> </section> |
|
73 </conbody></concept> |