An -example registration file and icon/caption file

Introduction

This document describes two methods -of defining application registration information. In both cases, a minimal -example registration file called HelloWorld_reg.rss 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.

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.

+ + + + + +An +example registration file and icon/caption file +

Introduction

This document describes two methods +of defining application registration information. In both cases, a minimal +example registration file called HelloWorld_reg.rss 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.

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.

\ No newline at end of file