S60 Platform: Descriptor Example v2.1
-------------------------------------

This updated C++ code example demonstrates how to use descriptors (Symbian OS strings) 
and related APIs. The example is an S60 application that is used to run one example 
method or all of them. The methods write a log on the screen or in a file that 
demonstrates the results of different statements.

The UI has a menu with the following submenus: Declarations, Manipulations, and Other 
buffers. Under these submenus there are menus that execute a specific example method. 
When the method is run, the results are displayed on the screen.
    
Example methods can also be run as a batch by selecting the command Run All from the 
menu. In this case, all methods are executed and the results are forwarded into the 
c:\DescriptorEx.log.txt file.

It is much easier to read the results with a good editor on a PC than on the device 
screen, because some of the lines in the example outputs are quite long. When running the 
example in the emulator, the file can be easily read from 
\Epoc32\winscw\c\data\DescriptorEx.log.txt (or \Epoc32\winscw\c\nokia\DescriptorEx.log.txt 
prior to S60 3rd Edition).

The example has been updated to support S60 5th Edition and touch UI.

------------------------------------------------------------------------------------------

PREREQUISITES

Symbian C++ basics.

------------------------------------------------------------------------------------------

IMPORTANT FILES/CLASSES

The descriptor classes (TBuf, HBufC, RBuf, and so on) are the most important classes in 
this example. These classes are well documented in the SDK documentation and their usage 
is demonstrated in the example.

Headers:
--------
The following headers define the UI layer of the application:

DescriptorExApp.h
DescriptorExAppUi.h
DescriptorExContainer.h
DescriptorExDocument.h

StringRenderer.h declares the helper functions that are used to render strings. 
DescriptorExamples.h declares the example methods that describe the usage of descriptors 
and related APIs:

void ToStack();                 // Demonstrates
void ToHeap();                  // how to declare
void Literals();                // descriptors.

void NonModifyingMethods();     // Demonstrates how methods 
void ModifyingMethods();        // are used to access data,
void CharacterConversions();    // alter data, parse strings, and 
void LexicalAnalysis();         // convert data between encodings.

void CircularBuffers();         // Demonstrates
void FlatDynamicBuffers();      // the usage of
void SegmentedDynamicBuffers(); // descriptor
void PackageBuffers();          // related APIs.

Implementations:
----------------
 
DescriptorExApp.cpp         // Implement
DescriptorExAppUi.cpp       // the UI
DescriptorExContainer.cpp   // of the
DescriptorExDocument.cpp    // application.

DeclaringDescriptors.cpp    // Implement the
ManipulatingDescriptors.cpp // example methods
OtherBuffers.cpp            // described above.
   
FileForwarder.cpp   // Implement the helper functions and
StringRenderer.cpp  // classes used by the examples and the UI.


Important classes: TBuf, HBufC, RBuf.

------------------------------------------------------------------------------------------

KNOWN ISSUES

No known issues.
    
------------------------------------------------------------------------------------------

RUNNING THE EXAMPLE

Once the example is running, select the tests to run from the Options menu. The results 
are written into a file, declared as follows:
_LIT( KFileName, "c:\\Data\\DescriptorEx.log.txt" );

You can use the file manager application to see the log file for the results.

The RBuf demonstration (CDescriptorExamples::RBufDemonstrations) contains code examples 
where RBuf objects are manipulated. It does not write any results into the file.

------------------------------------------------------------------------------------------

BUILD & INSTALLATION INSTRUCTIONS

The steps for building and installing the application on a device depend on the S60 
platform version:

--Mobile device
    cd to /DescriptorEx/group
    bldmake bldfiles
    abld build gcce urel
    cd to /DescriptorEx/sis
    Edit the paths in DescriptorEx_S60.pkg to match those in your development environment.
    makesis DescriptorEx_S60.pkg
    
    Sign the SIS package 
      - See the SDK Help for information about self-signed .sis packages, or
        http://www.symbiansigned.com/ for information about Developer Certificates.

    Install the signed .sis file on an S60 3rd Edition device.
    If you get a "Certificate error" during the installation of a self-signed package, 
    check that App.Manager -> Settings -> Software Installation is set to "All". 
    
--Emulator (WINSCW)
    cd to /DescriptorEx/group
    bldmake bldfiles
    abld build winscw udeb
    Start the emulator.
    
------------------------------------------------------------------------------------------

COMPATIBILITY

S60 5th Edition
S60 3rd Edition, Feature Pack 2
S60 3rd Edition, Feature Pack 1
S60 3rd Edition

Tested with: Nokia 5800 XpressMusic, Nokia E90 Communicator, Nokia N95.
    
------------------------------------------------------------------------------------------

VERSION HISTORY     

2.1 Modified to support S60 5th Edition: scalability fixed, editor scrollbars visibility 
    fixed and other minor bugs fixed. Skin support added.
2.0 Ported from S60 2nd Edition to S60 3rd Edition.
1.0 First release.

------------------------------------------------------------------------------------------

RELATED DOCUMENTATION

Descriptors in Symbian Developer Library:
http://www.symbian.com/developer/techlib/v9.1docs/doc_source/guide/Base-subsystem-guide/N10086/BuffersAndStrings/Descriptors/index.html

Introducing the RBuf Descriptor (Mark Shackman):
http://developer.symbian.com/main/downloads/papers/RBuf/Introduction_to_RBuf_v1.0.pdf