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-188F9462-F805-522A-84FF-770EAB045504" xml:lang="en"><title>An |
|
13 example registration file and icon/caption file</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section><title>Introduction</title> <p>This document describes two methods |
|
15 of defining application registration information. In both cases, a minimal |
|
16 example registration file called <filepath>HelloWorld_reg.rss</filepath> is |
|
17 used. In the first method, the icon/caption information is defined in its |
|
18 own file. In the second, it is defined in the application's UI resource file. |
|
19 The registration file is largely the same in both cases. </p> </section> |
|
20 <section><title>Registration file with an icon/caption definition file</title> <p><b>The |
|
21 registration file </b> </p> <p>A registration file is a resource file that |
|
22 is compiled by the resource compiler in the standard way, by including lines |
|
23 like the following in the application's mmp file: </p> <codeblock id="GUID-CA21DAF9-C789-54D3-B768-212F03EB8EAB" xml:space="preserve">START RESOURCE HelloWorld_reg.rss |
|
24 TARGETPATH \private\10003a3f\apps |
|
25 END</codeblock> <p>This will cause <filepath>HelloWorld_reg.rss</filepath> to |
|
26 be compiled, creating <filepath>HelloWorld_reg.rsc</filepath>. On the Symbian |
|
27 emulator, all registration files should be located in <filepath>\private\10003a3f\apps</filepath>. |
|
28 This is also true on real hardware for registration files built into the ROM. |
|
29 For applications installed onto a phone using the standard software installation |
|
30 method, their registration files should be installed into <filepath>\private\10003a3f\import\apps</filepath>. |
|
31 In all cases, the registration file must be located on the same drive as the |
|
32 application. </p> <p>A minimal registration file looks like this: </p> <codeblock id="GUID-386B4305-538A-58B7-9908-34104EE20814" xml:space="preserve">#include <appinfo.rh> |
|
33 |
|
34 UID2 KUidAppRegistrationResourceFile |
|
35 UID3 0x10004299 // application UID |
|
36 RESOURCE APP_REGISTRATION_INFO |
|
37 { |
|
38 app_file = "HelloWorld"; |
|
39 localisable_resource_file = "\\resource\\apps\\HelloWorld_loc"; |
|
40 }</codeblock> <p>All registration files must define <codeph>UID2</codeph>, |
|
41 which is always <codeph>KUidAppRegistrationResourceFile</codeph>, and <codeph>UID3</codeph>, |
|
42 which is the application's UID, and an <codeph>APP_REGISTRATION_INFO</codeph> resource |
|
43 that minimally needs to provide the name of the application binary (using |
|
44 the <codeph>app_file</codeph> statement). All registration files need to <codeph>#include</codeph> <filepath>appinfo.rh</filepath>. </p> <p>If |
|
45 a localisable icon/caption definition file is provided, as in this example, |
|
46 its full path and filename must be specified, excluding the drive letter and |
|
47 file extension. </p> <p><b>The localisable icon/caption definition |
|
48 file </b> </p> <p>This file defines the application's captions and the name |
|
49 of the icon file. It is built to the <filepath>\resource\apps\</filepath> directory |
|
50 on the same drive as the registration file; this applies both on the Symbian |
|
51 emulator and target phone. By convention it has the same filename as the application, |
|
52 but with a <filepath>_loc</filepath> suffix. </p> <p>It is a standard localisable |
|
53 Symbian resource file, so it is compiled by the resource compiler by including |
|
54 lines like the following in the application's mmp file: </p> <codeblock id="GUID-FB3180D0-086E-5B3B-BC73-51BA723512D6" xml:space="preserve">start resource HelloWorld_loc.rss |
|
55 targetpath \resource\apps |
|
56 lang 01 02 |
|
57 end</codeblock> <p>These lines cause two versions of the file to be compiled, |
|
58 called <filepath>HelloWorld_loc.r01</filepath> and <filepath>HelloWorld_loc.r02</filepath>. <filepath>HelloWorld_loc.rss</filepath> looks |
|
59 like this: </p> <codeblock id="GUID-BFADC6C8-6D06-50A6-BB0E-CCE40C7D12D0" xml:space="preserve">#include <appinfo.rh> |
|
60 #ifdef LANGUAGE_01 |
|
61 #include "HelloWorld01.rls" |
|
62 #elif defined LANGUAGE_02 |
|
63 #include "HelloWorld02.rls" |
|
64 #endif |
|
65 RESOURCE LOCALISABLE_APP_INFO |
|
66 { |
|
67 short_caption = STRING_r_short_caption; |
|
68 caption_and_icon = |
|
69 { |
|
70 CAPTION_AND_ICON_INFO |
|
71 { |
|
72 caption = STRING_r_caption; |
|
73 number_of_icons = 3; // each icon must be a bitmap/mask pair |
|
74 icon_file = STRING_r_icon_file; |
|
75 } |
|
76 }; |
|
77 }</codeblock> <p>Unlike most resource files, because there is only one |
|
78 resource defined in the file, it does not need to include a four character <codeph>NAME</codeph> or |
|
79 an <codeph>RSS_SIGNATURE</codeph> resource, and the <codeph>LOCALISABLE_APP_INFO</codeph> resource |
|
80 does not need an ID. </p> <p>The captions and the icon filename are referred |
|
81 to by symbolic identifiers rather than by the strings themselves. The strings |
|
82 are defined in <filepath>.rls</filepath> files (resource localisable string |
|
83 files), as shown below and conditional compilation statements are used to |
|
84 include the appropriate <filepath>.rls</filepath> file. For more information, |
|
85 on localising strings in resource files, see <xref href="GUID-F35C5336-907C-5B2A-92C6-F8883D49996E.dita">How |
|
86 to localise resources</xref>. </p> <p> <filepath>HelloWorld01.rls</filepath> contains: </p> <codeblock id="GUID-CC264837-CE3D-514A-A35A-032CE6F040C1" xml:space="preserve">rls_string STRING_r_short_caption "Hello" |
|
87 rls_string STRING_r_caption "Hello World" |
|
88 rls_string STRING_r_icon_file "z:\\resource\\apps\\Hello.mbm"</codeblock> <p> <filepath>HelloWorld02.rls</filepath> contains: </p> <codeblock id="GUID-941FDCF8-FAE9-5E3B-A5AA-FC85A6D6B9FA" xml:space="preserve">rls_string STRING_r_short_caption "Bonjour" |
|
89 rls_string STRING_r_caption "Bonjour tout le monde" |
|
90 rls_string STRING_r_icon_file "z:\\resource\\apps\\Bonjour.mbm"</codeblock> <p>The |
|
91 mbm icon files are built by adding <xref href="GUID-B707887A-E0FA-5DF6-A906-A91E31E17321.dita">start |
|
92 bitmap</xref> statements to the mmp file, for instance: </p> <codeblock id="GUID-B73430EF-510C-583E-B721-E82BB4BE1784" xml:space="preserve">START BITMAP Hello.mbm |
|
93 TARGETPATH \Resource\Apps |
|
94 SOURCE c8,1 icon24.bmp icon24m.bmp icon32.bmp icon32m.bmp icon48.bmp icon48m.bmp |
|
95 END</codeblock> </section> |
|
96 <section><title>Registration file without an icon/caption definition file</title> <p>As |
|
97 an alternative to defining the icon/caption information in an icon/caption |
|
98 definition file, it can be defined in the application's existing UI resource |
|
99 definition file. In this case, the <codeph>LOCALISABLE_APP_INFO</codeph> resource |
|
100 must be given an ID, because it is no longer the only resource defined in |
|
101 the file. The registration file is as before, except that it must now specify |
|
102 the ID of the <codeph>LOCALISABLE_APP_INFO</codeph> resource as well as the |
|
103 name and location of the UI resource file. In other words, the line: </p> <codeblock id="GUID-08AEB128-25E5-52DA-AD3E-C8733BA660A1" xml:space="preserve">localisable_resource_file = "\\resource\\apps\\HelloWorld_loc";</codeblock> <p>needs |
|
104 to be changed to: </p> <codeblock id="GUID-3EE8477E-4FB1-51F9-AF42-42107FFA6933" xml:space="preserve">localisable_resource_file = "\\resource\\apps\\HelloWorld"; |
|
105 localisable_resource_id = R_LAI;</codeblock> <p>where <codeph>R_LAI</codeph> is |
|
106 the ID of the <codeph>LOCALISABLE_APP_INFO</codeph> resource. Because the |
|
107 registration file needs to give the resource ID, it must <codeph>#include</codeph> the |
|
108 application's generated resource header file, <filepath>HelloWorld.rsg</filepath>. |
|
109 Also, the UI resource file needs to <codeph>#include</codeph> <filepath>AppInfo.rh</filepath> for |
|
110 the <codeph>LOCALISABLE_APP_INFO</codeph> definition. </p> </section> |
|
111 </conbody></concept> |
|