7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE task |
10 <!DOCTYPE task |
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
12 <task id="GUID-EA107811-240C-5F95-922B-7C042FA00A87" xml:lang="en"><title>Reading |
12 <task id="GUID-EA107811-240C-5F95-922B-7C042FA00A87" xml:lang="en"><title>Reading a String Resource </title><abstract><p>The simplest use of a resource file involves reading |
13 a String Resource </title><abstract><p>The simplest use of a resource file involves reading string resources |
13 string resources and interpreting the source data. </p></abstract><prolog><metadata><keywords/></metadata></prolog><taskbody> |
14 and interpreting the source data. </p></abstract><prolog><metadata><keywords/></metadata></prolog><taskbody> |
14 <context id="GUID-FD651A99-73F0-4CDD-9B4F-7C3A1DE8C4BE"><p>Resources are defined in terms of structs which are accessed |
15 <context><p>Resources are defined in terms of structs which are accessed and |
15 and read by the <xref href="GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA.dita"><apiname>RResourceFile</apiname></xref> class, and interpreted |
16 read by the <xref href="GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA.dita"><apiname>RResourceFile</apiname></xref> class, and interpreted by the <xref href="GUID-B375D32E-1F91-30FA-8605-A2E163111F9A.dita"><apiname>TResourceReader</apiname></xref>. |
16 by the <xref href="GUID-B375D32E-1F91-30FA-8605-A2E163111F9A.dita"><apiname>TResourceReader</apiname></xref>. An application may also |
17 An application may also use resources from multiple files simultaneously. |
17 use resources from multiple files simultaneously. See <xref href="GUID-98903A01-CD04-5345-84AE-2E440CE06E11.dita">Resource File examples</xref> for more information. </p><p>Consider a sample resource file where |
18 See <xref href="GUID-98903A01-CD04-5345-84AE-2E440CE06E11.dita">Resource File examples</xref> for |
18 a struct of STRING is defined having a single member of type <codeph>LTEXT</codeph>: </p><codeblock xml:space="preserve">// define structures |
19 more information. </p><p>Consider a sample resource file where a struct of |
|
20 STRING is defined having a single member of type <codeph>LTEXT</codeph>: </p><codeblock xml:space="preserve">// define structures |
|
21 STRUCT STRING |
19 STRUCT STRING |
22 { |
20 { |
23 LTEXT text; |
21 LTEXT text; |
24 } |
22 } |
25 // define resources |
23 // define resources |
28 text=Bonjour tout le monde!; |
26 text=Bonjour tout le monde!; |
29 } |
27 } |
30 </codeblock> </context> |
28 </codeblock> </context> |
31 <steps id="GUID-F147E8CF-65D1-5025-BA85-E0D171DBEFFD"> |
29 <steps id="GUID-F147E8CF-65D1-5025-BA85-E0D171DBEFFD"> |
32 <step id="GUID-0BAEB54B-5A6E-59F6-B14E-FAF0A3D15F27"><cmd/> |
30 <step id="GUID-0BAEB54B-5A6E-59F6-B14E-FAF0A3D15F27"><cmd/> |
33 <info>Compile the resource file using <xref href="GUID-9C57F0C6-E2E3-58A2-907D-924A7E22EA97-GENID-1-13-1-1-5-1-4-1.dita">the |
31 <info>Compile the resource file using the resource compiler (rcomp) |
34 resource compiler</xref> (rcomp) to generate an <filepath>.rsc</filepath> file |
32 to generate an <filepath>.rsc</filepath> file and an <filepath>.rsg</filepath> file. </info> |
35 and an <filepath>.rsg</filepath> file. </info> |
33 <info><p>For information on resource compiler, see <b>Symbian^3 Tools |
|
34 Guide > Building</b>. </p></info> |
36 <substeps id="GUID-0B421705-A5CD-5FF7-BB95-C17559811267"> |
35 <substeps id="GUID-0B421705-A5CD-5FF7-BB95-C17559811267"> |
37 <substep id="GUID-673E32C9-665C-5388-AE17-780A149F8837"><cmd/> |
36 <substep id="GUID-673E32C9-665C-5388-AE17-780A149F8837"><cmd/> |
38 <info> <filepath>.rsc</filepath> file contains the resource data; this is |
37 <info> <filepath>.rsc</filepath> file contains the resource data; |
39 the resource file that must be referred to at run-time by the <codeph>RResourceFile</codeph> class |
38 this is the resource file that must be referred to at run-time by |
40 in the C++ code. </info> |
39 the <codeph>RResourceFile</codeph> class in the C++ code. </info> |
41 </substep> |
40 </substep> |
42 <substep id="GUID-AEE254EB-0716-5478-B1DF-F8ED8E4FF8E1"><cmd/> |
41 <substep id="GUID-AEE254EB-0716-5478-B1DF-F8ED8E4FF8E1"><cmd/> |
43 <info> <filepath>.rsg</filepath> file is a <keyword>generated |
42 <info> <filepath>.rsg</filepath> file is a <keyword>generated |
44 header</keyword> file that contains <codeph>#define</codeph> statements |
43 header</keyword> file that contains <codeph>#define</codeph> statements for each resource defined in the source file. In the |
45 for each resource defined in the source file. In the resource file generated |
44 resource file generated here, the only resource is called <codeph>hello</codeph> and the generated header file contains: </info> |
46 here, the only resource is called <codeph>hello</codeph> and the generated |
|
47 header file contains: </info> |
|
48 <stepxmp><codeblock id="GUID-385BB8E3-FF77-5A95-8F65-043E72412959" xml:space="preserve">#define HELLO 1</codeblock> </stepxmp> |
45 <stepxmp><codeblock id="GUID-385BB8E3-FF77-5A95-8F65-043E72412959" xml:space="preserve">#define HELLO 1</codeblock> </stepxmp> |
49 <info>Note that the name in the generated header file is converted to upper |
46 <info>Note that the name in the generated header file is converted |
50 case. </info> |
47 to upper case. </info> |
51 </substep> |
48 </substep> |
52 </substeps> |
49 </substeps> |
53 </step> |
50 </step> |
54 <step id="GUID-3367B1DD-C2E9-5780-A77A-7F574D2EC541"><cmd/> |
51 <step id="GUID-3367B1DD-C2E9-5780-A77A-7F574D2EC541"><cmd/> |
55 <info> <codeph>#include</codeph> the <filepath>.rsg</filepath> file in the |
52 <info> <codeph>#include</codeph> the <filepath>.rsg</filepath> file |
56 file containing the C++ code, to access the resource IDs generated by the |
53 in the file containing the C++ code, to access the resource IDs generated |
57 resource compiler. For example, for a project refered as <codeph>ReadText</codeph>, |
54 by the resource compiler. For example, for a project refered as <codeph>ReadText</codeph>, this might be: </info> |
58 this might be: </info> |
|
59 <stepxmp><codeblock id="GUID-AC615F67-6331-500C-B91E-ADD6A94464FB" xml:space="preserve">#include ReadText.rsg</codeblock> </stepxmp> |
55 <stepxmp><codeblock id="GUID-AC615F67-6331-500C-B91E-ADD6A94464FB" xml:space="preserve">#include ReadText.rsg</codeblock> </stepxmp> |
60 </step> |
56 </step> |
61 <step id="GUID-ACC66DA2-4AC8-536B-9912-7CE632C0A8DF"><cmd/> |
57 <step id="GUID-ACC66DA2-4AC8-536B-9912-7CE632C0A8DF"><cmd/> |
62 <info>Initialize the <codeph>RResourceFile</codeph> object in the C++ program, |
58 <info>Initialize the <codeph>RResourceFile</codeph> object in the |
63 specifying the name of the resource file: </info> |
59 C++ program, specifying the name of the resource file: </info> |
64 <stepxmp><codeblock id="GUID-5CF79231-E42C-51DF-9002-FD1ED8AB21C1" xml:space="preserve"> |
60 <stepxmp><codeblock id="GUID-5CF79231-E42C-51DF-9002-FD1ED8AB21C1" xml:space="preserve"> |
65 RResourceFile resourceFile; |
61 RResourceFile resourceFile; |
66 resourceFile.OpenL( fsSession,_L( Z:\\system\\data\\ReadText.rsc ) );</codeblock> </stepxmp> |
62 resourceFile.OpenL( fsSession,_L( Z:\\system\\data\\ReadText.rsc ) );</codeblock> </stepxmp> |
67 <info>Note: To access the resource file contents, a session with the file |
63 <info>Note: To access the resource file contents, a session with the |
68 server must be started using an instance of <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref> class. </info> |
64 file server must be started using an instance of <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref> class. </info> |
69 </step> |
65 </step> |
70 <step id="GUID-CA53A8D1-E13E-50A8-96A7-B6B397B82DB3"><cmd/> |
66 <step id="GUID-CA53A8D1-E13E-50A8-96A7-B6B397B82DB3"><cmd/> |
71 <info>Use one of the three functions (<xref href="GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA.dita#GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA/GUID-9B16E6B8-84A4-37DF-BBB4-EC8B04FDB14C"><apiname>RResourceFile::AllocReadLC()</apiname></xref>, <xref href="GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA.dita#GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA/GUID-8CEE29E0-78F3-3DD6-B068-85C8E0403884"><apiname>RResourceFile::AllocReadL()</apiname></xref> or <xref href="GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA.dita#GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA/GUID-DF6DFFD5-E923-3C4E-87F0-BC4EE7C8B586"><apiname>RResourceFile::ReadL()</apiname></xref> to read a resource as shown in the following |
67 <info>Use one of the three functions (<xref href="GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA.dita#GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA/GUID-9B16E6B8-84A4-37DF-BBB4-EC8B04FDB14C"><apiname>RResourceFile::AllocReadLC()</apiname></xref>, <xref href="GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA.dita#GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA/GUID-8CEE29E0-78F3-3DD6-B068-85C8E0403884"><apiname>RResourceFile::AllocReadL()</apiname></xref> or <xref href="GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA.dita#GUID-AA6DEF11-6F23-3523-A9F7-F15DF918E1BA/GUID-DF6DFFD5-E923-3C4E-87F0-BC4EE7C8B586"><apiname>RResourceFile::ReadL()</apiname></xref> to read a resource as shown in the following code fragment: </info> |
72 code fragment: </info> |
|
73 <stepxmp><codeblock id="GUID-92AC4270-4A4D-52F1-B5C4-CFF6FBD19700" xml:space="preserve">HBufC8* dataBuffer = resourceFile.AllocReadLC( HELLO );</codeblock> </stepxmp> |
68 <stepxmp><codeblock id="GUID-92AC4270-4A4D-52F1-B5C4-CFF6FBD19700" xml:space="preserve">HBufC8* dataBuffer = resourceFile.AllocReadLC( HELLO );</codeblock> </stepxmp> |
74 </step> |
69 </step> |
75 <step id="GUID-77F9A976-6E09-5158-B515-256F4B878CDB"><cmd/> |
70 <step id="GUID-77F9A976-6E09-5158-B515-256F4B878CDB"><cmd/> |
76 <info>Interpret the resource data using a <codeph>TResourceReader</codeph> object. |
71 <info>Interpret the resource data using a <codeph>TResourceReader</codeph> object. This provides access to the text string through a pointer |
77 This provides access to the text string through a pointer descriptor as shown |
72 descriptor as shown in the following code fragment: </info> |
78 in the following code fragment: </info> |
|
79 <stepxmp><codeblock id="GUID-CB3BE44D-72F5-5E15-8D1D-52F513D9D980" xml:space="preserve"> |
73 <stepxmp><codeblock id="GUID-CB3BE44D-72F5-5E15-8D1D-52F513D9D980" xml:space="preserve"> |
80 TResourceReader theReader; |
74 TResourceReader theReader; |
81 ... |
75 ... |
82 theReader.SetBuffer( datafBuffer ); |
76 theReader.SetBuffer( datafBuffer ); |
83 TPtrC textdata = reader.ReadTPtrC();</codeblock> </stepxmp> |
77 TPtrC textdata = reader.ReadTPtrC();</codeblock> </stepxmp> |
84 </step> |
78 </step> |
85 </steps> |
79 </steps> |
86 <result><p>In this example, once the resource data is no longer needed, the |
80 <result id="GUID-565451D8-6C9E-4F1C-BC15-BFA4F3DD6D1D"><p>In this example, once the resource data is no longer needed, |
87 heap descriptor, dataBuffer, can be removed from the cleanup stack and destroyed |
81 the heap descriptor, dataBuffer, can be removed from the cleanup stack |
88 as shown in the code fragment: </p><codeblock xml:space="preserve">CleanupStack::PopAndDestroy();</codeblock><p>When |
82 and destroyed as shown in the code fragment: </p><codeblock xml:space="preserve">CleanupStack::PopAndDestroy();</codeblock><p>When all operations on the resource file are complete, the resource |
89 all operations on the resource file are complete, the resource file can be |
83 file can be closed using the RResourceFile::close() function as: </p><codeblock xml:space="preserve">resourceFile.Close();</codeblock></result> |
90 closed using the RResourceFile::close() function as: </p><codeblock xml:space="preserve">resourceFile.Close();</codeblock></result> |
|
91 <example><title>Example</title> <p>Consider a resource constructed |
84 <example><title>Example</title> <p>Consider a resource constructed |
92 from the following definition. </p> <codeblock id="GUID-538D959C-A85A-5675-9B14-ED81AB860F47" xml:space="preserve">RESOURCE ARRAY anarray |
85 from the following definition. </p> <codeblock id="GUID-538D959C-A85A-5675-9B14-ED81AB860F47" xml:space="preserve">RESOURCE ARRAY anarray |
93 { |
86 { |
94 items= |
87 items= |
95 { |
88 { |
97 LBUF { txt="Enter"; }, |
90 LBUF { txt="Enter"; }, |
98 LBUF { txt="Tab"; }, |
91 LBUF { txt="Tab"; }, |
99 LBUF { txt="Del"; }, |
92 LBUF { txt="Del"; }, |
100 LBUF { txt="Space"; } |
93 LBUF { txt="Space"; } |
101 }; |
94 }; |
102 }</codeblock> <p>A <codeph>TPtrC</codeph> representing the second item can |
95 }</codeblock> <p>A <codeph>TPtrC</codeph> representing the second |
103 be constructed using the <codeph>ReadTPtrC()</codeph> function. The example |
96 item can be constructed using the <codeph>ReadTPtrC()</codeph> function. |
104 simply takes the length of the text <codeph>Enter</codeph>: </p> <codeblock id="GUID-9817910D-0661-513D-BB3A-9557D70688AD" xml:space="preserve">// open the resource file |
97 The example simply takes the length of the text <codeph>Enter</codeph>: </p> <codeblock id="GUID-9817910D-0661-513D-BB3A-9557D70688AD" xml:space="preserve">// open the resource file |
105 ... |
98 ... |
106 HBufC8* res = resourceFile.AllocReadLC( ANARRAY ); |
99 HBufC8* res = resourceFile.AllocReadLC( ANARRAY ); |
107 TResourceReader theReader; |
100 TResourceReader theReader; |
108 ... |
101 ... |
109 TInt len; |
102 TInt len; |
110 len = ( theReader.ReadTPtrC( 1,res ) ).Length(); // len == 5 |
103 len = ( theReader.ReadTPtrC( 1,res ) ).Length(); // len == 5 |
111 ...</codeblock> </example> |
104 ...</codeblock> </example> |
112 </taskbody><related-links> |
105 </taskbody><related-links> |
113 <link href="GUID-3AF1F492-3D7D-5F8C-B1AE-16FBD8224775.dita"><linktext>Resource |
106 <link href="GUID-3AF1F492-3D7D-5F8C-B1AE-16FBD8224775.dita"><linktext>Resource |
114 files</linktext></link> |
107 files</linktext></link> |
115 <link href="GUID-07C031C2-7FFC-5B0E-9691-E6E678E65C4B.dita"><linktext>Resource |
|
116 file format</linktext></link> |
|
117 <link href="GUID-3527AAEE-210F-524B-A655-A65F1CE86C80.dita"><linktext>Resource |
|
118 compilation</linktext></link> |
|
119 </related-links></task> |
108 </related-links></task> |