Defining -application icons, captions and properties

Introduction

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.

Application -icons

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 platform 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.

Application -captions

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.

Filename

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.

Attributes

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.

Application -properties

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.

embeddability

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.

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

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.

newfile

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

The default value is KAppDoesNotSupportNewFile.

launch

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

Default screen number

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 Symbian emulator, screen -numbers are initialised in the window server initialisation file, wsini.ini.

UIDs

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.

MIME support

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 platform 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 platform arbitrarily launches one of -them.

View-specific information

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 Symbian 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().

Service list

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.