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.