|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-3AF1F492-3D7D-5F8C-B1AE-16FBD8224775" xml:lang="en"><title>Resource |
|
13 Files </title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Resource files contain data separated from executable code. The purpose |
|
15 of using resource files are to define user interface components and store |
|
16 localisable data. </p> |
|
17 <p>The application framework defined by the Uikon Core expects features of |
|
18 the application UI, such as menus, to be supplied in a resource file. The |
|
19 framework reads these resources itself. Other user interface components, such |
|
20 as dialogs, can also be easily created from resources, without the application |
|
21 needing to use this API itself. </p> |
|
22 <p>The API has two key concepts - resource file reader and resource component |
|
23 reader. </p> |
|
24 <section><title>Resource file reader</title> <p>Resource files contain data |
|
25 in numbered resources. The resource file reader allows such files to be opened |
|
26 and closed, and individual resources within them, as identified by symbolic |
|
27 identifiers, to be read into binary descriptors. Data items are then extracted |
|
28 from these descriptors using the resource component reader. </p> <p>The resource |
|
29 file can be read using <xref href="GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA.dita"><apiname>RResourceFile</apiname></xref>. </p> </section> |
|
30 <section><title>Resource component reader</title> <p>A resource is defined |
|
31 as a struct. Struct members can be simple, such as integers and strings, or |
|
32 complex, such as other structs, or arrays of structs. The resource component |
|
33 reader is used to read these struct members from a binary descriptor holding |
|
34 the resource into C++ variables. The application must ensure that it places |
|
35 the struct members into variables of appropriate types. </p> <p>The resource |
|
36 component header information can be accessed using <xref href="GUID-B375D32E-1F91-30FA-8605-A2E163111F9A.dita"><apiname>TResourceReader</apiname></xref>. </p> </section> |
|
37 <section id="GUID-EA9C30E1-AB21-5042-9417-CFDE320C519D"><title>Basic resource |
|
38 file use</title> <p>The basic concepts involved with using resource files |
|
39 are as follows: </p> <ul> |
|
40 <li id="GUID-67FFC98D-2829-5146-B4B6-5DEB3A4966BA"><p>In a resource file, |
|
41 define structs or use appropriate pre-defined structs and then define resources |
|
42 that use those structs. </p> </li> |
|
43 <li id="GUID-C57BD780-2B6F-547F-B008-FAD1F51B565F"><p>Run the resource compiler |
|
44 to produce both a generated header file and a resource file. The generated |
|
45 header file defines the symbols which a program uses to refer to the resources. </p> </li> |
|
46 </ul> <p>A program which requires a resource file then performs the following: </p> <ul> |
|
47 <li id="GUID-6E6F8010-F264-5F28-A540-D122530C98ED"><p>Includes the generated |
|
48 header file in the appropriate source file to get symbolic access to the IDs |
|
49 of the resources contained within the file. </p> </li> |
|
50 <li id="GUID-8E1FFF9C-6D4A-5926-AE9E-703E2B224F23"><p>Opens a <codeph>RResourceFile</codeph> object, |
|
51 specifying the generated resource file name. </p> </li> |
|
52 <li id="GUID-AB22B5E3-1C8E-5994-B4E4-28CCD62297BD"><p>Reads any resource that |
|
53 is required. The resource is identified by a symbolic ID which has been <codeph>#define</codeph> d |
|
54 as a number; the content of the resource is read into a binary descriptor, |
|
55 derived from <codeph>TDesC8</codeph>. </p> </li> |
|
56 <li id="GUID-E743799B-77A2-51F6-AC73-1D8A9325FD5E"><p>Converts the binary |
|
57 descriptor into whatever target format is appropriate for the data in the |
|
58 resource file. </p> </li> |
|
59 <li id="GUID-83832E00-F8A1-5F42-80A7-AA29C11D1CFD"><p>Discards the descriptor, |
|
60 if appropriate, when the binary descriptor has been fully converted into its |
|
61 target format. </p> </li> |
|
62 <li id="GUID-8E5F9573-7180-5E44-ABAD-53D4F9608E33"><p>Closes the <codeph>RResourceFile</codeph> when |
|
63 all operations on the resource file are complete. </p> </li> |
|
64 </ul> <p>The resource text can be changed and the resources recompiled without |
|
65 altering or recompiling the C++ program. For example, to alter the language |
|
66 used by text strings. </p> </section> |
|
67 <section><title>Resource File Interface</title><p>Resource files contain data |
|
68 in numbered resources. A resource file has the following format:</p><fig id="GUID-9CFB3B14-9C09-42E2-A87E-ED07BD2E7E36"> |
|
69 <image href="GUID-FB479891-8788-5548-B875-A5C637EC2DE6_d0e183692_href.png" placement="inline"/> |
|
70 </fig><p>A resource file is generated from text input using the resource compiler. |
|
71 The index can be used to efficiently find a resource given its numeric ID. |
|
72 There can be 1 to 4095 resources in a resource file. Each resource contains |
|
73 binary data whose length is determined by subtracting the start position of |
|
74 the resource from the start of the next resource (or from the start of the |
|
75 index, for the last resource in the file). </p><p> Functions for handling |
|
76 resources in a resource file are encapsulated in the <codeph>RResourceFile</codeph> class. |
|
77 This class provides functions for: </p><p><ul> |
|
78 <li><p>opening and closing the file</p></li> |
|
79 <li><p>reading resources</p></li> |
|
80 <li><p>support for using multiple resource files</p></li> |
|
81 </ul></p><p>Generally, the process for reading a resource is to read it into |
|
82 a buffer of sufficient length, analyse it and place its data into C++ classes. |
|
83 Then, if appropriate, release the buffer. </p><p>The <codeph>TResourceReader</codeph> class |
|
84 must be used to simplify the process of resource data analysis. </p> </section> |
|
85 <section id="GUID-3E43B598-5857-5660-B9F0-432FD9AC56AA"><title>File types |
|
86 in resource file usage</title> <p>The file types involved in resource file |
|
87 usage are defined in the following diagram: </p> <fig id="GUID-4C93BFC7-89BD-5E88-BA68-D6273F13BB8D"> |
|
88 <title> File types </title> |
|
89 <image href="GUID-4A5A50EB-261E-5739-904E-1D14D1A6BAD9_d0e183738_href.png" placement="inline"/> |
|
90 </fig> <p>These files work together as follows: </p> <ul> |
|
91 <li id="GUID-CA9BB1F1-0535-5F18-9CD2-AC2C02DACE8D"><p>the C++ compiler and |
|
92 linker, together, take <filepath>.cpp</filepath> source files and produce <filepath>.exe</filepath> output |
|
93 (or <filepath>.dll</filepath>, or <filepath>.app</filepath>, or another such |
|
94 extension). </p> </li> |
|
95 <li id="GUID-D1E44783-4179-5E25-9C2A-715E167E8177"><p>the resource compiler |
|
96 takes a <filepath>.rss</filepath> source file containing <codeph>RESOURCE</codeph> statements |
|
97 and converts it into a <filepath>.rsc</filepath> resource file which contains |
|
98 the resources the executable program will use. It also produces a <filepath>.rsg</filepath> generated |
|
99 header file, which contains the symbolic IDs of these resources. </p> </li> |
|
100 <li id="GUID-5E468821-D48B-5633-9801-F3ACFA96024C"><p>the <filepath>.rsg</filepath> file |
|
101 is <codeph>#include</codeph> d by the <filepath>.cpp</filepath> file, so that |
|
102 the C++ compiler has access to the symbolic IDs of the resources that will |
|
103 be used. </p> </li> |
|
104 <li id="GUID-99F5E649-D5E6-59F0-A6F0-C51A52756FA7"><p>C++ class definitions |
|
105 are specified in a <filepath>.h</filepath> file; a typical application will |
|
106 include several system header files and usually one or more of its own. </p> </li> |
|
107 <li id="GUID-84ED8144-AEBD-51CD-A9CE-240D143A773A"><p>resource structs are |
|
108 specified in a <filepath>.rh</filepath> file. A typical application will use |
|
109 system-provided resource headers, which define standard controls etc. Only |
|
110 if the application requires its own structs, will it include its own <filepath>.rh</filepath> file. </p> </li> |
|
111 <li id="GUID-BDDFAD1C-48FD-52F0-85A0-553CB2BAC5AA"><p>flag values are <codeph>#define</codeph> d |
|
112 in a file which must be available to both the C++ compiler and the resource |
|
113 compiler: the <filepath>.hrh</filepath> extension is used for this and <filepath>.hrh</filepath> files |
|
114 are typically <codeph>#include</codeph> d into the <filepath>.h</filepath> file |
|
115 that defines the classes (for C++) and the <filepath>.rh</filepath> file that |
|
116 defines the structs (for the resource compiler). </p> </li> |
|
117 </ul> </section> |
|
118 <section id="GUID-41C5ABE7-C081-5259-9814-0436844C85AD"><title>Type safety |
|
119 issues</title> <p>Software systems implemented in C++ are designed to be type-safe. |
|
120 Proper use of header files, make utilities, type declarations, classes and |
|
121 templates makes it difficult to pass data of the wrong type to functions, |
|
122 to assign data of the wrong type to variables, or to construct a program whose |
|
123 modules are inconsistent with one another. Thus a major source of programming |
|
124 errors is detected while the program is being built, before running it. </p> <p>A |
|
125 program which uses resources must have a resource file which matches that |
|
126 program's requirements. However, the resource file and the executable program |
|
127 are only loosely bound together. A variety of errors are possible while dealing |
|
128 with resources, which cannot be detected during the build process. Programmers |
|
129 should be aware of these and take appropriate measures to avoid them. </p> <p>Additional |
|
130 sources of error include: </p> <ul> |
|
131 <li id="GUID-C08B03AF-E50C-577A-90F7-1462B223E9D0"><p>Having a program and |
|
132 resource file which do not correspond. </p> <p>This can arise because the |
|
133 resource file formats were updated, or the program was updated, but the resource |
|
134 file was not updated. When the program is run, the resources it loads are |
|
135 in the wrong format. </p> </li> |
|
136 <li id="GUID-81AB0840-8122-5C34-9DE9-A10DCB02E39D"><p>The structures in the |
|
137 resource file may be of a different format from that expected by the C++ program. </p> <p>If |
|
138 the C++ program expects a <codeph>LONG</codeph> while a <codeph>WORD</codeph> is |
|
139 present in the resource file, then the C++ program will read two extra bytes |
|
140 from the data item in the resource file. Any subsequent data read from that |
|
141 resource will be an error. </p> <p>This kind of error can only be avoided |
|
142 by C++ programs knowing which structs they are dealing with, knowing the data |
|
143 layouts of those structs in a resource file and writing code which works in |
|
144 that context. </p> </li> |
|
145 <li id="GUID-E61214E6-9FC8-5A6E-8EEC-452FF135A89C"><p>Having resources of |
|
146 unexpected type. </p> <p>The most likely reason for this to arise is because |
|
147 there is no type safety in the resource compiler. Thus, it is possible for |
|
148 a programmer to wrongly guess what kind of struct a particular resource must |
|
149 use. Appropriate comments in the <filepath>.rh</filepath> files and the documentation |
|
150 of the resource file, will help to reduce this kind of error. </p> </li> |
|
151 </ul> <p>The resource compiler does provide some elementary safety features: </p> <ul> |
|
152 <li id="GUID-736C2471-93C2-5AD6-8E73-CBA30DF5C6C0"><p>All resources are represented |
|
153 by a symbolic ID. This ensures that the resource IDs used by the C++ program |
|
154 and those expected by the compiler match, if the recommended build procedures |
|
155 are followed. </p> </li> |
|
156 <li id="GUID-8DE5ABAE-2504-5DC9-BDCC-70C8ABF806AA"><p>Flag values, maximum |
|
157 length constants and some other values, may be defined in a <filepath>.hrh</filepath> file. |
|
158 This ensures that C++ programs uses correct resource. </p> </li> |
|
159 </ul> </section> |
|
160 </conbody><related-links> |
|
161 <link href="GUID-EA107811-240C-5F95-922B-7C042FA00A87.dita"><linktext>Reading a |
|
162 string resource</linktext></link> |
|
163 </related-links></concept> |