<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-A6116E8B-9C4A-5B9E-AA8A-BE031408AA2F" xml:lang="en"><title>Defining

application icons, captions and properties</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Introduction</title> <p>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 <filepath>AppInfo.rh</filepath> are

used to hold the definitions. </p> </section>

<section id="GUID-33B76C7B-0A73-5890-9786-F18839309A4A"><title>Application

icons</title> <p>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. </p> <p>The

source icon files may be <filepath>.bmp</filepath> bitmaps, or a vector graphics

format. If bitmaps are used, they are built into a single <filepath>.mbm</filepath> file

(Symbian platform multiple bitmap file) as part of the build process, see <xref href="GUID-B707887A-E0FA-5DF6-A906-A91E31E17321.dita">start bitmap</xref> 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. </p> <p>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. </p> <p>In addition to <filepath>.mbm</filepath> icon

files, registration files also support vector graphics formats for instance <filepath>.svg</filepath>.

If the icon file is a vector graphics format, the <codeph>number_of_icons</codeph> value

in the <codeph>CAPTION_AND_ICON_INFO</codeph> struct is irrelevant. </p> <p>In

either case, the name of the icon file is specified in the <codeph>LOCALISABLE_APP_INFO</codeph> resource. </p> <p><b>Localising

icons </b> </p> <p>Some applications may need to localise their icons and

captions. </p> <p>Icon filenames can be localised by defining them in <filepath>.rls</filepath> files.

There should be one <filepath>.rls</filepath> file per language supported.

In the <codeph>LOCALISABLE_APP_INFO</codeph> 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 <filepath>.rls</filepath> file. See <xref href="GUID-188F9462-F805-522A-84FF-770EAB045504.dita">an

example registration file and icon/caption file</xref>. Captions are localised

using the same technique. </p> </section>

<section id="GUID-E8B8F865-D363-535C-A51B-EC66B8C76296"><title>Application

captions</title> <p>An application's caption is the text displayed beside

its icon. Typically it is the application's name. </p> <p>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. </p> </section>

<section><title>Filename</title> <p>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 <filepath>\sys\bin\</filepath> on

the same drive as the registration file. </p> </section>

<section><title>Attributes</title> <p>Registration files have an <codeph>attributes</codeph> field

which is used to identify non-standard types of application. For instance, <codeph>KAppIsControlPanelItem</codeph> identifies

control panel-type applications. Refer to the documentation for

the targetted UI platform for other supported values. </p> </section>

<section id="GUID-A28ABF97-3EF0-5554-8A66-C9EB1FF954B6"><title>Application

properties</title> <p>The following properties can be defined in registration

files. In C++ they can be retrieved using the <xref href="GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA.dita"><apiname>RApaLsSession</apiname></xref> class.

Note that not all of these are supported by every UI. </p> <p><i>embeddability</i></p> <p>An

application can have one of the following attributes: <codeph>KAppEmbeddable</codeph>, <codeph>KAppNotEmbeddable</codeph>,

or <codeph>KAppEmbeddableOnly</codeph>. The other listed values (<codeph>KAppEmbeddableUiOrStandAlone</codeph> and <codeph>KAppEmbeddableUiNotStandAlone</codeph>) are not used. The default value is <codeph>KAppNotEmbeddable</codeph>.

Embeddable applications appear in lists of embeddable applications, see for

example <xref href="GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA.dita#GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA/GUID-E0F9B1FA-976A-3A07-8A69-1713F81CE146"><apiname>RApaLsSession::GetEmbeddableApps()</apiname></xref>. A file with

the property <codeph>KAppEmbeddableOnly</codeph> appears in the embeddable

list, but not in the shell or application launcher. </p> <p><note><ul>

<li id="GUID-13D03388-1689-5B82-8343-AF85AB597138"><p>document embedding may

not be not supported by all UIs, </p> </li>

<li id="GUID-54F48257-3849-5635-9430-C7968BAF42C9"><p>the embeddable and embeddable-only

properties should only be set for file-based applications, in other words,

applications that create embeddable documents. </p> </li>

</ul></note> </p> <p><i>hidden</i></p> <p>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. </p> <p>The default value is <codeph>KAppNotHidden</codeph>. </p> <p><i>newfile</i> </p> <p>This

property indicates whether the application is document-based and supports

the creation of new files. </p> <p>The default value is <codeph>KAppDoesNotSupportNewFile</codeph>. </p> <p><i>launch</i> </p> <p>Indicates

whether the application will be launched in the foreground so that it takes

focus, or in the background. </p> </section>

<section><title>Default screen number</title> <p>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, <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini</xref>. </p> </section>

<section id="GUID-500CEB11-DA89-5A6D-B0E5-E5C881030FCD"><title>UIDs</title> <p>Two

UIDs must be specified in the source registration file: <codeph>UID2</codeph> and <codeph>UID3</codeph>. <codeph>UID2</codeph> always

has the value <codeph>KUidAppRegistrationResourceFile</codeph>; <codeph>UID3</codeph> is

the third UID of the application. </p> </section>

<section id="GUID-2E24E9DA-4EBF-5CB5-96CB-112E7610227A"><title>MIME support</title> <p>Multipurpose

Internet Mail Extensions, MIMEs, define a file format for transferring non-ASCII

data, such as graphics, audio and fax, over the Internet. The <codeph>datatype_list</codeph> 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. </p> <p>There are four priority levels, of which only <codeph>EDataTypePriorityNormal</codeph> or <codeph>EDataTypePriorityLow</codeph> should normally be used. For example, a text editor is good at editing text/plain

files, and would be given a priority of <codeph>EDataTypePriorityNormal</codeph> for

that file type. A web browser is less good at handling text files, and would

be assigned the lower priority <codeph>EDataTypePriorityLow</codeph>. So,

either application can be launched to handle a text file, however if both

applications are present, the text editor is launched in preference. </p> <p> <codeph>EDataTypePriorityHigh</codeph> should

only be assigned under exceptional conditions, for instance if no other application

could ever handle a particular MIME type as well. </p> <p> <codeph>EDataTypePriorityLastResort</codeph> should

also be used sparingly. Text editors are terrible at displaying HTML, and

would either have the priority <codeph>EDataTypePriorityLastResort</codeph>,

or would not support the type at all. </p> <p>Given two applications with

the same MIME type priority, Symbian platform arbitrarily launches one of

them. </p> </section>

<section><title>View-specific information</title> <p>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. </p> <p>The following

view-specific properties can be specified, using a <codeph>VIEW_DATA</codeph> resource

struct, declared in <filepath>appinfo.rh</filepath>: </p> <ul>

<li id="GUID-27E58734-77D5-5420-A0E5-E5635530913A"><p>The view's UID. </p> <p>This

uniquely identifies the view within the application (in C++ this corresponds

to <xref href="GUID-3DEA9A17-CB50-3DCD-87AC-0E91B377FB0E.dita#GUID-3DEA9A17-CB50-3DCD-87AC-0E91B377FB0E/GUID-2A49E3A5-815F-339C-AFB3-CB21D9AC53EB"><apiname>TVwsViewId::iViewUid</apiname></xref>). This must be specified. </p> </li>

<li id="GUID-BA449839-7205-5997-99BF-CA0E23C6A796"><p>The screen mode that

the view uses. </p> <p>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, <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini</xref>.

The default value is zero. </p> <p>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. </p> </li>

<li id="GUID-79366634-C36E-5FEC-B77A-01D594A9BDD2"><p>The number of icons

for the view. </p> <p>The icons are contained in the icon file. If the icon

file is a vector graphics format, the <codeph>number_of_icons</codeph> value

is irrelevant. </p> </li>

<li id="GUID-E79B5B73-7527-5EBA-922E-8787AA6D43AF"><p>The view's caption. </p> </li>

</ul> <p>The view-specific information is defined in the <codeph>view_list</codeph> which

is an array of <codeph>VIEW_DATA</codeph> structs, one for each view in the

application. It can be accessed in C++ through the <xref href="GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA.dita"><apiname>RApaLsSession</apiname></xref> class,

see for example <xref href="GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA.dita#GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA/GUID-3687ED39-4D19-3C96-AAB4-FF6C977411BB"><apiname>RApaLsSession::GetAppViews()</apiname></xref>, and <xref href="GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA.dita#GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA/GUID-FFB678A1-A717-3D0D-9996-858E77E0AB80"><apiname>RApaLsSession::GetAppViewIcon()</apiname></xref>. </p> </section>

<section><title>Service list</title> <p>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. </p> <p>The service list is a list

of services offered by a server application. Each entry in the list consists

of a <codeph>uid</codeph>, which identifies the service, and the ID of another

resource (<codeph>opaque_data</codeph>) 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. </p> <p>The information defined in the service list can be

retrieved using the <xref href="GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA.dita"><apiname>RApaLsSession</apiname></xref> class. For example, clients

can find out which server applications implement a particular service by calling <xref href="GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA.dita#GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA/GUID-F5482751-DC3B-3C31-9BE4-6CFDF076E76A"><apiname>RApaLsSession::GetServiceImplementationsLC()</apiname></xref>. </p> <p>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 <codeph>NAME</codeph> and an <codeph>RSS_SIGNATURE</codeph> resource,

like most other resource files, and as it would no longer be the only resource

defined in the file, the <codeph>LOCALISABLE_APP_INFO</codeph> resource must

be given an ID, which must be specified in the registration file's <codeph>localisable_resource_id</codeph> field. </p> </section>