<?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 concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-3AF1F492-3D7D-5F8C-B1AE-16FBD8224775" xml:lang="en"><title>Resource
Files </title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Resource files contain data separated from executable code. The purpose
of using resource files are to define user interface components and store
localisable data. </p>
<p>The application framework defined by the Uikon Core expects features of
the application UI, such as menus, to be supplied in a resource file. The
framework reads these resources itself. Other user interface components, such
as dialogs, can also be easily created from resources, without the application
needing to use this API itself. </p>
<p>The API has two key concepts - resource file reader and resource component
reader. </p>
<section><title>Resource file reader</title> <p>Resource files contain data
in numbered resources. The resource file reader allows such files to be opened
and closed, and individual resources within them, as identified by symbolic
identifiers, to be read into binary descriptors. Data items are then extracted
from these descriptors using the resource component reader. </p> <p>The resource
file can be read using <xref href="GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA.dita"><apiname>RResourceFile</apiname></xref>. </p> </section>
<section><title>Resource component reader</title> <p>A resource is defined
as a struct. Struct members can be simple, such as integers and strings, or
complex, such as other structs, or arrays of structs. The resource component
reader is used to read these struct members from a binary descriptor holding
the resource into C++ variables. The application must ensure that it places
the struct members into variables of appropriate types. </p> <p>The resource
component header information can be accessed using <xref href="GUID-B375D32E-1F91-30FA-8605-A2E163111F9A.dita"><apiname>TResourceReader</apiname></xref>. </p> </section>
<section id="GUID-EA9C30E1-AB21-5042-9417-CFDE320C519D"><title>Basic resource
file use</title> <p>The basic concepts involved with using resource files
are as follows: </p> <ul>
<li id="GUID-67FFC98D-2829-5146-B4B6-5DEB3A4966BA"><p>In a resource file,
define structs or use appropriate pre-defined structs and then define resources
that use those structs. </p> </li>
<li id="GUID-C57BD780-2B6F-547F-B008-FAD1F51B565F"><p>Run the resource compiler
to produce both a generated header file and a resource file. The generated
header file defines the symbols which a program uses to refer to the resources. </p> </li>
</ul> <p>A program which requires a resource file then performs the following: </p> <ul>
<li id="GUID-6E6F8010-F264-5F28-A540-D122530C98ED"><p>Includes the generated
header file in the appropriate source file to get symbolic access to the IDs
of the resources contained within the file. </p> </li>
<li id="GUID-8E1FFF9C-6D4A-5926-AE9E-703E2B224F23"><p>Opens a <codeph>RResourceFile</codeph> object,
specifying the generated resource file name. </p> </li>
<li id="GUID-AB22B5E3-1C8E-5994-B4E4-28CCD62297BD"><p>Reads any resource that
is required. The resource is identified by a symbolic ID which has been <codeph>#define</codeph> d
as a number; the content of the resource is read into a binary descriptor,
derived from <codeph>TDesC8</codeph>. </p> </li>
<li id="GUID-E743799B-77A2-51F6-AC73-1D8A9325FD5E"><p>Converts the binary
descriptor into whatever target format is appropriate for the data in the
resource file. </p> </li>
<li id="GUID-83832E00-F8A1-5F42-80A7-AA29C11D1CFD"><p>Discards the descriptor,
if appropriate, when the binary descriptor has been fully converted into its
target format. </p> </li>
<li id="GUID-8E5F9573-7180-5E44-ABAD-53D4F9608E33"><p>Closes the <codeph>RResourceFile</codeph> when
all operations on the resource file are complete. </p> </li>
</ul> <p>The resource text can be changed and the resources recompiled without
altering or recompiling the C++ program. For example, to alter the language
used by text strings. </p> </section>
<section><title>Resource File Interface</title><p>Resource files contain data
in numbered resources. A resource file has the following format:</p><fig id="GUID-9CFB3B14-9C09-42E2-A87E-ED07BD2E7E36">
<image href="GUID-FB479891-8788-5548-B875-A5C637EC2DE6_d0e154935_href.png" placement="inline"/>
</fig><p>A resource file is generated from text input using the resource compiler.
The index can be used to efficiently find a resource given its numeric ID.
There can be 1 to 4095 resources in a resource file. Each resource contains
binary data whose length is determined by subtracting the start position of
the resource from the start of the next resource (or from the start of the
index, for the last resource in the file). </p><p> Functions for handling
resources in a resource file are encapsulated in the <codeph>RResourceFile</codeph> class.
This class provides functions for: </p><p><ul>
<li><p>opening and closing the file</p></li>
<li><p>reading resources</p></li>
<li><p>support for using multiple resource files</p></li>
</ul></p><p>Generally, the process for reading a resource is to read it into
a buffer of sufficient length, analyse it and place its data into C++ classes.
Then, if appropriate, release the buffer.   </p><p>The <codeph>TResourceReader</codeph> class
must be used to simplify the process of resource data analysis.  </p> </section>
<section id="GUID-3E43B598-5857-5660-B9F0-432FD9AC56AA"><title>File types
in resource file usage</title> <p>The file types involved in resource file
usage are defined in the following diagram: </p> <fig id="GUID-4C93BFC7-89BD-5E88-BA68-D6273F13BB8D">
<title>              File types            </title>
<image href="GUID-4A5A50EB-261E-5739-904E-1D14D1A6BAD9_d0e154981_href.png" placement="inline"/>
</fig> <p>These files work together as follows: </p> <ul>
<li id="GUID-CA9BB1F1-0535-5F18-9CD2-AC2C02DACE8D"><p>the C++ compiler and
linker, together, take <filepath>.cpp</filepath> source files and produce <filepath>.exe</filepath> output
(or <filepath>.dll</filepath>, or <filepath>.app</filepath>, or another such
extension). </p> </li>
<li id="GUID-D1E44783-4179-5E25-9C2A-715E167E8177"><p>the resource compiler
takes a <filepath>.rss</filepath> source file containing <codeph>RESOURCE</codeph> statements
and converts it into a <filepath>.rsc</filepath> resource file which contains
the resources the executable program will use. It also produces a <filepath>.rsg</filepath> generated
header file, which contains the symbolic IDs of these resources. </p> </li>
<li id="GUID-5E468821-D48B-5633-9801-F3ACFA96024C"><p>the <filepath>.rsg</filepath> file
is <codeph>#include</codeph> d by the <filepath>.cpp</filepath> file, so that
the C++ compiler has access to the symbolic IDs of the resources that will
be used. </p> </li>
<li id="GUID-99F5E649-D5E6-59F0-A6F0-C51A52756FA7"><p>C++ class definitions
are specified in a <filepath>.h</filepath> file; a typical application will
include several system header files and usually one or more of its own. </p> </li>
<li id="GUID-84ED8144-AEBD-51CD-A9CE-240D143A773A"><p>resource structs are
specified in a <filepath>.rh</filepath> file. A typical application will use
system-provided resource headers, which define standard controls etc. Only
if the application requires its own structs, will it include its own <filepath>.rh</filepath> file. </p> </li>
<li id="GUID-BDDFAD1C-48FD-52F0-85A0-553CB2BAC5AA"><p>flag values are <codeph>#define</codeph> d
in a file which must be available to both the C++ compiler and the resource
compiler: the <filepath>.hrh</filepath> extension is used for this and <filepath>.hrh</filepath> files
are typically <codeph>#include</codeph> d into the <filepath>.h</filepath> file
that defines the classes (for C++) and the <filepath>.rh</filepath> file that
defines the structs (for the resource compiler). </p> </li>
</ul> </section>
<section id="GUID-41C5ABE7-C081-5259-9814-0436844C85AD"><title>Type safety
issues</title> <p>Software systems implemented in C++ are designed to be type-safe.
Proper use of header files, make utilities, type declarations, classes and
templates makes it difficult to pass data of the wrong type to functions,
to assign data of the wrong type to variables, or to construct a program whose
modules are inconsistent with one another. Thus a major source of programming
errors is detected while the program is being built, before running it. </p> <p>A
program which uses resources must have a resource file which matches that
program's requirements. However, the resource file and the executable program
are only loosely bound together. A variety of errors are possible while dealing
with resources, which cannot be detected during the build process. Programmers
should be aware of these and take appropriate measures to avoid them. </p> <p>Additional
sources of error include: </p> <ul>
<li id="GUID-C08B03AF-E50C-577A-90F7-1462B223E9D0"><p>Having a program and
resource file which do not correspond. </p> <p>This can arise because the
resource file formats were updated, or the program was updated, but the resource
file was not updated. When the program is run, the resources it loads are
in the wrong format. </p> </li>
<li id="GUID-81AB0840-8122-5C34-9DE9-A10DCB02E39D"><p>The structures in the
resource file may be of a different format from that expected by the C++ program. </p> <p>If
the C++ program expects a <codeph>LONG</codeph> while a <codeph>WORD</codeph> is
present in the resource file, then the C++ program will read two extra bytes
from the data item in the resource file. Any subsequent data read from that
resource will be an error. </p> <p>This kind of error can only be avoided
by C++ programs knowing which structs they are dealing with, knowing the data
layouts of those structs in a resource file and writing code which works in
that context. </p> </li>
<li id="GUID-E61214E6-9FC8-5A6E-8EEC-452FF135A89C"><p>Having resources of
unexpected type. </p> <p>The most likely reason for this to arise is because
there is no type safety in the resource compiler. Thus, it is possible for
a programmer to wrongly guess what kind of struct a particular resource must
use. Appropriate comments in the <filepath>.rh</filepath> files and the documentation
of the resource file, will help to reduce this kind of error. </p> </li>
</ul> <p>The resource compiler does provide some elementary safety features: </p> <ul>
<li id="GUID-736C2471-93C2-5AD6-8E73-CBA30DF5C6C0"><p>All resources are represented
by a symbolic ID. This ensures that the resource IDs used by the C++ program
and those expected by the compiler match, if the recommended build procedures
are followed. </p> </li>
<li id="GUID-8DE5ABAE-2504-5DC9-BDCC-70C8ABF806AA"><p>Flag values, maximum
length constants and some other values, may be defined in a <filepath>.hrh</filepath> file.
This ensures that C++ programs uses correct resource. </p> </li>
</ul> </section>
</conbody><related-links>
<link href="GUID-EA107811-240C-5F95-922B-7C042FA00A87.dita"><linktext>Reading a
string resource</linktext></link>
</related-links></concept>