--- a/Symbian3/SDK/Source/GUID-A6116E8B-9C4A-5B9E-AA8A-BE031408AA2F.dita	Fri Jul 16 17:23:46 2010 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,160 +0,0 @@
-<?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>
-</conbody></concept>
\ No newline at end of file