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