Mercurial Mercurial > oss > FCL > sftools > depl > docscontent / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Symbian3/SDK/Source/GUID-3AF1F492-3D7D-5F8C-B1AE-16FBD8224775.dita
changeset 0 89d6a7a84779 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-3AF1F492-3D7D-5F8C-B1AE-16FBD8224775.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,163 @@
+<?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>
\ No newline at end of file
FCL/sftools/depl/docscontent