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>