<?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_d0e195180_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_d0e195226_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>