An +example registration file and icon/caption file

Registration file with an icon/caption definition file

The +registration file

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:

START RESOURCE HelloWorld_reg.rss +TARGETPATH \private\10003a3f\apps +END

This will cause HelloWorld_reg.rss to +be compiled, creating HelloWorld_reg.rsc. On the Symbian +emulator, all registration files should be located in \private\10003a3f\apps. +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 \private\10003a3f\import\apps. +In all cases, the registration file must be located on the same drive as the +application.

A minimal registration file looks like this:

#include <appinfo.rh> + +UID2 KUidAppRegistrationResourceFile +UID3 0x10004299 // application UID +RESOURCE APP_REGISTRATION_INFO + { + app_file = "HelloWorld"; + localisable_resource_file = "\\resource\\apps\\HelloWorld_loc"; + }

All registration files must define UID2, +which is always KUidAppRegistrationResourceFile, and UID3, +which is the application's UID, and an APP_REGISTRATION_INFO resource +that minimally needs to provide the name of the application binary (using +the app_file statement). All registration files need to #include appinfo.rh.

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.

The localisable icon/caption definition +file

This file defines the application's captions and the name +of the icon file. It is built to the \resource\apps\ 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 _loc suffix.

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:

start resource HelloWorld_loc.rss +targetpath \resource\apps +lang 01 02 +end

These lines cause two versions of the file to be compiled, +called HelloWorld_loc.r01 and HelloWorld_loc.r02. HelloWorld_loc.rss looks +like this:

#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; + } + }; + }

Unlike most resource files, because there is only one +resource defined in the file, it does not need to include a four character NAME or +an RSS_SIGNATURE resource, and the LOCALISABLE_APP_INFO resource +does not need an ID.

The captions and the icon filename are referred +to by symbolic identifiers rather than by the strings themselves. The strings +are defined in .rls files (resource localisable string +files), as shown below and conditional compilation statements are used to +include the appropriate .rls file. For more information, +on localising strings in resource files, see How +to localise resources.

HelloWorld01.rls contains:

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"

HelloWorld02.rls contains:

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"

The +mbm icon files are built by adding start +bitmap statements to the mmp file, for instance:

START BITMAP Hello.mbm +TARGETPATH \Resource\Apps +SOURCE c8,1 icon24.bmp icon24m.bmp icon32.bmp icon32m.bmp icon48.bmp icon48m.bmp +END

Registration file without an icon/caption definition file

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 LOCALISABLE_APP_INFO 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 LOCALISABLE_APP_INFO resource as well as the +name and location of the UI resource file. In other words, the line:

localisable_resource_file = "\\resource\\apps\\HelloWorld_loc";

needs +to be changed to:

localisable_resource_file = "\\resource\\apps\\HelloWorld"; +localisable_resource_id = R_LAI;

where R_LAI is +the ID of the LOCALISABLE_APP_INFO resource. Because the +registration file needs to give the resource ID, it must #include the +application's generated resource header file, HelloWorld.rsg. +Also, the UI resource file needs to #include AppInfo.rh for +the LOCALISABLE_APP_INFO definition.