--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-188F9462-F805-522A-84FF-770EAB045504.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,111 @@
+<?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-188F9462-F805-522A-84FF-770EAB045504" xml:lang="en"><title>An
+example registration file and icon/caption file</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section><title>Introduction</title> <p>This document describes two methods
+of defining application registration information. In both cases, a minimal
+example registration file called <filepath>HelloWorld_reg.rss</filepath> is
+used. In the first method, the icon/caption information is defined in its
+own file. In the second, it is defined in the application's UI resource file.
+The registration file is largely the same in both cases. </p> </section>
+<section><title>Registration file with an icon/caption definition file</title> <p><b>The
+registration file </b> </p> <p>A registration file is a resource file that
+is compiled by the resource compiler in the standard way, by including lines
+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
+TARGETPATH \private\10003a3f\apps
+END</codeblock> <p>This will cause <filepath>HelloWorld_reg.rss</filepath> to
+be compiled, creating <filepath>HelloWorld_reg.rsc</filepath>. On the Symbian
+emulator, all registration files should be located in <filepath>\private\10003a3f\apps</filepath>.
+This is also true on real hardware for registration files built into the ROM.
+For applications installed onto a phone using the standard software installation
+method, their registration files should be installed into <filepath>\private\10003a3f\import\apps</filepath>.
+In all cases, the registration file must be located on the same drive as the
+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>
+
+UID2 KUidAppRegistrationResourceFile
+UID3 0x10004299 // application UID
+RESOURCE APP_REGISTRATION_INFO
+ {
+ app_file = "HelloWorld";
+ localisable_resource_file = "\\resource\\apps\\HelloWorld_loc";
+ }</codeblock> <p>All registration files must define <codeph>UID2</codeph>,
+which is always <codeph>KUidAppRegistrationResourceFile</codeph>, and <codeph>UID3</codeph>,
+which is the application's UID, and an <codeph>APP_REGISTRATION_INFO</codeph> resource
+that minimally needs to provide the name of the application binary (using
+the <codeph>app_file</codeph> statement). All registration files need to <codeph>#include</codeph> <filepath>appinfo.rh</filepath>. </p> <p>If
+a localisable icon/caption definition file is provided, as in this example,
+its full path and filename must be specified, excluding the drive letter and
+file extension. </p> <p><b>The localisable icon/caption definition
+file </b> </p> <p>This file defines the application's captions and the name
+of the icon file. It is built to the <filepath>\resource\apps\</filepath> directory
+on the same drive as the registration file; this applies both on the Symbian
+emulator and target phone. By convention it has the same filename as the application,
+but with a <filepath>_loc</filepath> suffix. </p> <p>It is a standard localisable
+Symbian resource file, so it is compiled by the resource compiler by including
+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
+targetpath \resource\apps
+lang 01 02
+end</codeblock> <p>These lines cause two versions of the file to be compiled,
+called <filepath>HelloWorld_loc.r01</filepath> and <filepath>HelloWorld_loc.r02</filepath>. <filepath>HelloWorld_loc.rss</filepath> looks
+like this: </p> <codeblock id="GUID-BFADC6C8-6D06-50A6-BB0E-CCE40C7D12D0" xml:space="preserve">#include <appinfo.rh>
+#ifdef LANGUAGE_01
+#include "HelloWorld01.rls"
+#elif defined LANGUAGE_02
+#include "HelloWorld02.rls"
+#endif
+RESOURCE LOCALISABLE_APP_INFO
+ {
+ short_caption = STRING_r_short_caption;
+ caption_and_icon =
+ {
+ CAPTION_AND_ICON_INFO
+ {
+ caption = STRING_r_caption;
+ number_of_icons = 3; // each icon must be a bitmap/mask pair
+ icon_file = STRING_r_icon_file;
+ }
+ };
+ }</codeblock> <p>Unlike most resource files, because there is only one
+resource defined in the file, it does not need to include a four character <codeph>NAME</codeph> or
+an <codeph>RSS_SIGNATURE</codeph> resource, and the <codeph>LOCALISABLE_APP_INFO</codeph> resource
+does not need an ID. </p> <p>The captions and the icon filename are referred
+to by symbolic identifiers rather than by the strings themselves. The strings
+are defined in <filepath>.rls</filepath> files (resource localisable string
+files), as shown below and conditional compilation statements are used to
+include the appropriate <filepath>.rls</filepath> file. For more information,
+on localising strings in resource files, see <xref href="GUID-F35C5336-907C-5B2A-92C6-F8883D49996E.dita">How
+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"
+rls_string STRING_r_caption "Hello World"
+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"
+rls_string STRING_r_caption "Bonjour tout le monde"
+rls_string STRING_r_icon_file "z:\\resource\\apps\\Bonjour.mbm"</codeblock> <p>The
+mbm icon files are built by adding <xref href="GUID-B707887A-E0FA-5DF6-A906-A91E31E17321.dita">start
+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
+TARGETPATH \Resource\Apps
+SOURCE c8,1 icon24.bmp icon24m.bmp icon32.bmp icon32m.bmp icon48.bmp icon48m.bmp
+END</codeblock> </section>
+<section><title>Registration file without an icon/caption definition file</title> <p>As
+an alternative to defining the icon/caption information in an icon/caption
+definition file, it can be defined in the application's existing UI resource
+definition file. In this case, the <codeph>LOCALISABLE_APP_INFO</codeph> resource
+must be given an ID, because it is no longer the only resource defined in
+the file. The registration file is as before, except that it must now specify
+the ID of the <codeph>LOCALISABLE_APP_INFO</codeph> resource as well as the
+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
+to be changed to: </p> <codeblock id="GUID-3EE8477E-4FB1-51F9-AF42-42107FFA6933" xml:space="preserve">localisable_resource_file = "\\resource\\apps\\HelloWorld";
+localisable_resource_id = R_LAI;</codeblock> <p>where <codeph>R_LAI</codeph> is
+the ID of the <codeph>LOCALISABLE_APP_INFO</codeph> resource. Because the
+registration file needs to give the resource ID, it must <codeph>#include</codeph> the
+application's generated resource header file, <filepath>HelloWorld.rsg</filepath>.
+Also, the UI resource file needs to <codeph>#include</codeph> <filepath>AppInfo.rh</filepath> for
+the <codeph>LOCALISABLE_APP_INFO</codeph> definition. </p> </section>
+</conbody></concept>
\ No newline at end of file