Defining application icons, captions and properties

This document describes the properties of an application that are defined in application registration files and in other related files. Various resource structs declared in AppInfo.rh are used to hold the definitions.

Icons are used to represent applications and their associated document files in the system shell or application launcher. If the phone's UI supports embedding, icons may also be used to represent embedded documents.

The source icon files may be .bmp bitmaps, or a vector graphics format. If bitmaps are used, they are built into a single .mbm file (Symbian OS multiple bitmap file) as part of the build process, see start bitmap for details. Different sizes of source bitmap should be supplied. The OS selects the most appropriate icon size for the UI's current zoom state. This avoids the need for the icon to be dynamically scaled when it is drawn at a different size. Scaling small bitmaps generally results in a loss of quality. The required icon sizes are specific to the UI.

For each icon size, an image bitmap and a mask bitmap are needed. The mask should be black for the parts of the image that should be visible, and white for the transparent areas, where the background should appear instead.

In addition to .mbm icon files, registration files also support vector graphics formats for instance .svg. If the icon file is a vector graphics format, the number_of_icons value in the CAPTION_AND_ICON_INFO struct is irrelevant.

In either case, the name of the icon file is specified in the LOCALISABLE_APP_INFO resource.

Localising icons

Some applications may need to localise their icons and captions.

Icon filenames can be localised by defining them in .rls files. There should be one .rls file per language supported. In the LOCALISABLE_APP_INFO definition, the icon filenames should be referred to by their symbolic identifiers, rather than as the strings themselves. Conditional compilation statements are used in the resource file to include the appropriate .rls file. See an example registration file and icon/caption file. Captions are localised using the same technique.

An application's caption is the text displayed beside its icon. Typically it is the application's name.

Captions are defined in the localisable icon/caption definition, which provides for short and long captions. The short caption may be used in situations where screen space is limited. Captions are localised in the same way as icon filenames, see above.

Registration files must provide the filename, excluding path and extension of the application's executable. This is needed in order for the application architecture to be able to find and launch the application. The application architecture expects it to be located in \sys\bin\ on the same drive as the registration file.

Registration files have an attributes field which is used to identify non-standard types of application. For instance, KAppIsControlPanelItem identifies control panel-type applications. Refer to the documentation for the targetted UI platform for other supported values.

The following properties can be defined in registration files. In C++ they can be retrieved using the RApaLsSession class. Note that not all of these are supported by every UI.

An application can have one of the following attributes: KAppEmbeddable, KAppNotEmbeddable, or KAppEmbeddableOnly. The other listed values (KAppEmbeddableUiOrStandAlone and KAppEmbeddableUiNotStandAlone) are not used. The default value is KAppNotEmbeddable. Embeddable applications appear in lists of embeddable applications, see for example RApaLsSession::GetEmbeddableApps(). A file with the property KAppEmbeddableOnly appears in the embeddable list, but not in the shell or application launcher.

Notes:

• document embedding may not be not supported by all UIs,

• the embeddable and embeddable-only properties should only be set for file-based applications, in other words, applications that create embeddable documents.

Hidden applications run in the background. They are not shown to the user and do not appear in the application launcher or in the embeddable applications list.

The default value is KAppNotHidden.

This property indicates whether the application is document-based and supports the creation of new files.

The default value is KAppDoesNotSupportNewFile.

Indicates whether the application will be launched in the foreground so that it takes focus, or in the background.

This number identifies the screen on which the application is displayed. It can be omitted if the phone has a single screen. In v8.1b, the application can only ever appear on this screen; this may change in later releases. For the emulator, screen numbers are initialised in the window server initialisation file, wsini.ini.

Two UIDs must be specified in the source registration file: UID2 and UID3. UID2 always has the value KUidAppRegistrationResourceFile; UID3 is the third UID of the application.

Multipurpose Internet Mail Extensions, MIMEs, define a file format for transferring non-ASCII data, such as graphics, audio and fax, over the Internet. The datatype_list section lists the MIME types that the application supports, and the priority of support that each type is given. When a file is opened, Symbian OS launches the application which has the highest priority of support for the type of data in the file.

There are four priority levels, of which only EDataTypePriorityNormal or EDataTypePriorityLow should normally be used. For example, a text editor is good at editing text/plain files, and would be given a priority of EDataTypePriorityNormal for that file type. A web browser is less good at handling text files, and would be assigned the lower priority EDataTypePriorityLow. So, either application can be launched to handle a text file, however if both applications are present, the text editor is launched in preference.

EDataTypePriorityHigh should only be assigned under exceptional conditions, for instance if no other application could ever handle a particular MIME type as well.

EDataTypePriorityLastResort should also be used sparingly. Text editors are terrible at displaying HTML, and would either have the priority EDataTypePriorityLastResort, or would not support the type at all.

Given two applications with the same MIME type priority, Symbian OS arbitrarily launches one of them.

For view-based applications, as an alternative to using an application-wide caption and icons, each view in the application can define its own icon and captions. This is so that specific application views can be launched directly from the phone's application launcher/shell. This feature may not be supported by all phone UIs.

The following view-specific properties can be specified, using a VIEW_DATA resource struct, declared in appinfo.rh:

• The view's UID.

  This uniquely identifies the view within the application (in C++ this corresponds to TVwsViewId::iViewUid). This must be specified.

• The screen mode that the view uses.

  A screen mode is a combination of screen rotation and screen size. Screen modes are identified by an index; the first one is zero. For the emulator, screen modes are initialised in the window server initialisation file, wsini.ini. The default value is zero.

  For example, on phones that use a flip-down keypad, the screen mode changes when the flip is opened or closed. On such phones, there may be a flip open and flip closed version of each view.

• The number of icons for the view.

  The icons are contained in the icon file. If the icon file is a vector graphics format, the number_of_icons value is irrelevant.

• The view's caption.

The view-specific information is defined in the view_list which is an array of VIEW_DATA structs, one for each view in the application. It can be accessed in C++ through the RApaLsSession class, see for example RApaLsSession::GetAppViews(), and RApaLsSession::GetAppViewIcon().

Server applications implement services on behalf of client applications, using a server. They are new in v9.0 and the motivation behind them is platform security. Because the client and the server applications run in separate processes, their memory areas and private data files are protected from each other.

The service list is a list of services offered by a server application. Each entry in the list consists of a uid, which identifies the service, and the ID of another resource (opaque_data) that describes how the service is implemented. The latter is called opaque data because how it is used is up to the server application, not the UI framework. For example, it might contain the ID of a localised text resource for display in the UI, or the ID of a resource struct that allows client code to distinguish between different implementations of the service.

The information defined in the service list can be retrieved using the RApaLsSession class. For example, clients can find out which server applications implement a particular service by calling RApaLsSession::GetServiceImplementationsLC().

The opaque data may be non-localisable and therefore defined as a resource in the registration file, or localisable and therefore defined as a resource in the localisable icon/caption definition file, if one exists, or in the UI resource file. If the localisable icon/caption definition file is used, it must include a four character NAME and an RSS_SIGNATURE resource, like most other resource files, and as it would no longer be the only resource defined in the file, the LOCALISABLE_APP_INFO resource must be given an ID, which must be specified in the registration file's localisable_resource_id field.