Symbian3/SDK/Source/GUID-E26E46AE-914E-5F21-AB44-10F926BAA8AC.dita
changeset 0 89d6a7a84779
child 13 48780e181b38
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-E26E46AE-914E-5F21-AB44-10F926BAA8AC.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License 
+"Eclipse Public License v1.0" which accompanies this distribution, 
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+    Nokia Corporation - initial contribution.
+Contributors: 
+-->
+<!DOCTYPE reference
+  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
+<reference id="GUID-E26E46AE-914E-5F21-AB44-10F926BAA8AC" xml:lang="en"><title>EUserHlExample:
+EUser High Level example</title><shortdesc>This example demonstrates how to use the EUser High Level library
+and includes the ceratian features supported by the library. It also demonstrates
+the usage of specific APIs associated with the EUser High Level Library. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody>
+<section id="GUID-EB6346F5-1C3C-5DEB-AD3A-36474C372E1C"><title>Purpose</title> <p>This
+example demonstrates the following features of EUserHL: </p> <ul>
+<li id="GUID-31A8E1A2-F2A9-5DDB-A880-FF27A41F1C3B"><p>String handling </p> </li>
+<li id="GUID-C09DC120-E1B8-5F60-9E90-2078E122C8EF"><p>Object creation and
+automatic resource management </p> </li>
+<li id="GUID-D7F1F68F-B9FC-524C-8B3B-D987582AEE76"><p>Memory usage by EUserHL
+classes </p> </li>
+</ul> </section>
+<section id="GUID-4BE93C59-6FBA-5F1B-90AE-1A8D30FB084C"><title>Download</title> <p>Click
+on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-66d31721-b6a6-4c84-b51d-c92f3927df4c.zip" scope="external">EUserHlExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-66d31721-b6a6-4c84-b51d-c92f3927df4c.html" scope="peer">browse</xref> to view the example code. </p> </section>
+<section id="GUID-62A4FC58-6832-5282-9E14-DCAB88913E8F"><title>Design and
+implementation</title> <p>The example implements three main functions: </p> <ul>
+<li id="GUID-5B20BDEE-B5A1-5D07-A19A-5CA298D1CEAA"><p> <codeph>WalkthroughStringsL()</codeph> demonstrates
+string handling. </p> </li>
+<li id="GUID-FC833C89-5A32-52E6-93D3-F45DC0A7E865"><p> <codeph>WalkthroughManagedL()</codeph> demonstrates
+object creation and resource management. </p> </li>
+<li id="GUID-7914F607-47BC-557A-B7F4-1432A294F743"><p> <codeph>WalkthroughUsageL()</codeph> demonstrates
+memory usage by EUserHL library classes. </p> </li>
+</ul> <p><b>String handling</b> </p> <p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> is designed
+to be a self-managing, resizable alternative to some of the existing descriptor
+types. </p> <p> <codeph>WalkthroughStringsL()</codeph> demonstrates how <codeph>LString</codeph> can
+be used in similar ways to the existing <codeph>TDesC</codeph> and <codeph>TDes</codeph> descriptor
+classes, as well as showing some additional functions, including: </p> <ul>
+<li id="GUID-DA576055-E813-51DE-8232-9E961596E34D"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-3A7A28FA-6647-3F51-A628-7857898E5090"><apiname>LString::SetMaxlengthL()</apiname></xref>  </p> </li>
+<li id="GUID-7A845FEC-A1B6-592F-A4E4-B93F301E3E1A"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-D7071D5E-E3EA-35ED-9A8F-D330162493A7"><apiname>LString::ReserveFreeCapacityL()</apiname></xref>  </p> </li>
+<li id="GUID-3883BD67-A7AA-5E55-8281-D41BC5871815"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-48151B50-C8C4-3011-9A76-8242EB7E1DDC"><apiname>LString::Compress()</apiname></xref>  </p> </li>
+<li id="GUID-F7BC1D06-38E9-582A-870F-CE38A6DC4FD5"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-7A5C522F-9B29-3443-A853-EF06BAD08352"><apiname>LString::Reset()</apiname></xref>  </p> </li>
+</ul> <p> <codeph>CStringUserTwoPhase</codeph> is used to demonstrate the
+use of <codeph>LString</codeph> s in the two-phase construction pattern. <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref> is
+used in place of the <xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref> in the <codeph>NewL()</codeph> function. </p> <p> <codeph>CStringUserSinglePhase</codeph> is
+used to demonstrate the use of <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> s in the single
+phase construction pattern. A macro <codeph>CONSTRUCTORS_MAY_LEAVE</codeph> is
+declared to ensure cleanup is correctly handled if the constructor leaves. </p> <p><b>Object
+creation and automatic resource management</b> </p> <p>The <codeph>LCleanedUpXxx</codeph> classes <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref>, <xref href="GUID-9ECEAE0C-3D5A-3B1F-88DD-28B37CE9950D.dita"><apiname>LCleanedupHandle</apiname></xref>, <xref href="GUID-A7B3BEBB-3805-3149-A9DB-075FFF3DED3F.dita"><apiname>LCleanedupArray</apiname></xref>, <xref href="GUID-E6D04730-8064-3846-99E4-FB638C5EAA65.dita"><apiname>LCleanedupGuard</apiname></xref> and <xref href="GUID-83938A18-23EF-301A-9D40-C89AEDB5DFF0.dita"><apiname>LCleanedupRef</apiname></xref> classes
+provide automatic resource management that avoids the need for the programmer
+to use the cleanup stack. </p> <p> <codeph>WalkthroughManagedL()</codeph> shows
+how the various <codeph>LCleanedUpXxx</codeph> classes are used. It shows
+how objects declared locally to a function (a pointer, a resource handle,
+an array, and an object cleaned up using a <xref href="GUID-CD0A798E-7E42-3689-8E86-F5FD43C758FC.dita"><apiname>TCleanupItem</apiname></xref>)
+are deleted automatically when they go out of scope. </p> <p> <codeph>CManagedUserTwoPhase</codeph> demonstrates
+the use of the management classes in the two-phase construction pattern. <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref> is
+used in the <codeph>NewL()</codeph> function in place of the <xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref>. <codeph>LManagedXxx</codeph> classes
+(for example <xref href="GUID-166B7262-50A5-3C2E-B7DD-3291F96B31AA.dita"><apiname>LManagedPtr</apiname></xref> and <xref href="GUID-FCBCB7A9-AF28-3591-A54D-8AF354E01D11.dita"><apiname>LManagedHandle</apiname></xref>)
+are used to handle cleanup of member data. </p> <p><b>Related APIs</b></p><p><xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref></p><p><xref href="GUID-A7B3BEBB-3805-3149-A9DB-075FFF3DED3F.dita"><apiname>LCleanedupArray</apiname></xref></p><p><xref href="GUID-E6D04730-8064-3846-99E4-FB638C5EAA65.dita"><apiname>LCleanedupGuard</apiname></xref></p><p><xref href="GUID-9ECEAE0C-3D5A-3B1F-88DD-28B37CE9950D.dita"><apiname>LCleanedupHandle</apiname></xref></p><p><xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref></p><p><xref href="GUID-83938A18-23EF-301A-9D40-C89AEDB5DFF0.dita"><apiname>LCleanedupRef</apiname></xref></p><p><xref href="GUID-FCBCB7A9-AF28-3591-A54D-8AF354E01D11.dita"><apiname>LManagedHandle</apiname></xref></p><p><xref href="GUID-166B7262-50A5-3C2E-B7DD-3291F96B31AA.dita"><apiname>LManagedPtr</apiname></xref></p><p><xref href="GUID-CD0A798E-7E42-3689-8E86-F5FD43C758FC.dita"><apiname>TCleanupItem</apiname></xref></p><p><b>Memory
+usage</b> </p> <p> <codeph>WalkthroughUsageL()</codeph> API demonstrates the
+memory overhead of using EUserHL. </p> </section>
+<section id="GUID-1BB8D12F-2303-5F46-BF3F-78416EAB2DBE"><title>Building and
+configuring</title> <p>To build the example: </p> <ul>
+<li id="GUID-324858E0-CD22-533E-A291-4CD4C88935BC"><p>You can build the example
+from your IDE or the command line. </p> <p>If you use an IDE, import the <filepath>bld.inf</filepath> file
+of the example into your IDE, and use the build command of the IDE. </p> <p>If
+you use the command line, open a command prompt, and set the current directory
+to the source code directory of the example. You can then build the example
+with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake
+bldfiles</userinput> </p> <p><userinput>abld build</userinput> </p> <p><xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How to use abld</xref> describe
+how to use the SBSv1 build tools. </p> </li>
+<li id="GUID-01951689-451E-5B11-8A71-08B263B4CA8A"><p>For the emulator, the
+example builds an executable called <filepath>euserhlexample.exe</filepath> in
+the <filepath>epoc32\release\winscw\&lt;udeb or                 urel&gt;\</filepath> folder. </p> </li>
+</ul> </section>
+<section id="GUID-B4B61C60-2DAF-5279-A934-DF5B5FCA29E7"><title>Running the
+example</title> <p>This is a console application. The user presses any key
+to step through it and the emulator closes down on exit. </p> </section>
+<section><title>See also:</title><p><xref href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita">EUser
+High Level Library</xref></p></section>
+</refbody></reference>
\ No newline at end of file