1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-A6116E8B-9C4A-5B9E-AA8A-BE031408AA2F" xml:lang="en"><title>Defining |
|
13 application icons, captions and properties</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section><title>Introduction</title> <p>This document describes the properties |
|
15 of an application that are defined in application registration files and in |
|
16 other related files. Various resource structs declared in <filepath>AppInfo.rh</filepath> are |
|
17 used to hold the definitions. </p> </section> |
|
18 <section id="GUID-33B76C7B-0A73-5890-9786-F18839309A4A"><title>Application |
|
19 icons</title> <p>Icons are used to represent applications and their associated |
|
20 document files in the system shell or application launcher. If the phone's |
|
21 UI supports embedding, icons may also be used to represent embedded documents. </p> <p>The |
|
22 source icon files may be <filepath>.bmp</filepath> bitmaps, or a vector graphics |
|
23 format. If bitmaps are used, they are built into a single <filepath>.mbm</filepath> file |
|
24 (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. |
|
25 Different sizes of source bitmap should be supplied. The OS selects the most |
|
26 appropriate icon size for the UI's current zoom state. This avoids the need |
|
27 for the icon to be dynamically scaled when it is drawn at a different size. |
|
28 Scaling small bitmaps generally results in a loss of quality. The required |
|
29 icon sizes are specific to the UI. </p> <p>For each icon size, an image bitmap |
|
30 and a mask bitmap are needed. The mask should be black for the parts of the |
|
31 image that should be visible, and white for the transparent areas, where the |
|
32 background should appear instead. </p> <p>In addition to <filepath>.mbm</filepath> icon |
|
33 files, registration files also support vector graphics formats for instance <filepath>.svg</filepath>. |
|
34 If the icon file is a vector graphics format, the <codeph>number_of_icons</codeph> value |
|
35 in the <codeph>CAPTION_AND_ICON_INFO</codeph> struct is irrelevant. </p> <p>In |
|
36 either case, the name of the icon file is specified in the <codeph>LOCALISABLE_APP_INFO</codeph> resource. </p> <p><b>Localising |
|
37 icons </b> </p> <p>Some applications may need to localise their icons and |
|
38 captions. </p> <p>Icon filenames can be localised by defining them in <filepath>.rls</filepath> files. |
|
39 There should be one <filepath>.rls</filepath> file per language supported. |
|
40 In the <codeph>LOCALISABLE_APP_INFO</codeph> definition, the icon filenames |
|
41 should be referred to by their symbolic identifiers, rather than as the strings |
|
42 themselves. Conditional compilation statements are used in the resource file |
|
43 to include the appropriate <filepath>.rls</filepath> file. See <xref href="GUID-188F9462-F805-522A-84FF-770EAB045504.dita">an |
|
44 example registration file and icon/caption file</xref>. Captions are localised |
|
45 using the same technique. </p> </section> |
|
46 <section id="GUID-E8B8F865-D363-535C-A51B-EC66B8C76296"><title>Application |
|
47 captions</title> <p>An application's caption is the text displayed beside |
|
48 its icon. Typically it is the application's name. </p> <p>Captions are defined |
|
49 in the localisable icon/caption definition, which provides for short and long |
|
50 captions. The short caption may be used in situations where screen space is |
|
51 limited. Captions are localised in the same way as icon filenames, see above. </p> </section> |
|
52 <section><title>Filename</title> <p>Registration files must provide the filename, |
|
53 excluding path and extension of the application's executable. This is needed |
|
54 in order for the application architecture to be able to find and launch the |
|
55 application. The application architecture expects it to be located in <filepath>\sys\bin\</filepath> on |
|
56 the same drive as the registration file. </p> </section> |
|
57 <section><title>Attributes</title> <p>Registration files have an <codeph>attributes</codeph> field |
|
58 which is used to identify non-standard types of application. For instance, <codeph>KAppIsControlPanelItem</codeph> identifies |
|
59 control panel-type applications. Refer to the documentation for |
|
60 the targetted UI platform for other supported values. </p> </section> |
|
61 <section id="GUID-A28ABF97-3EF0-5554-8A66-C9EB1FF954B6"><title>Application |
|
62 properties</title> <p>The following properties can be defined in registration |
|
63 files. In C++ they can be retrieved using the <xref href="GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA.dita"><apiname>RApaLsSession</apiname></xref> class. |
|
64 Note that not all of these are supported by every UI. </p> <p><i>embeddability</i></p> <p>An |
|
65 application can have one of the following attributes: <codeph>KAppEmbeddable</codeph>, <codeph>KAppNotEmbeddable</codeph>, |
|
66 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>. |
|
67 Embeddable applications appear in lists of embeddable applications, see for |
|
68 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 |
|
69 the property <codeph>KAppEmbeddableOnly</codeph> appears in the embeddable |
|
70 list, but not in the shell or application launcher. </p> <p><note><ul> |
|
71 <li id="GUID-13D03388-1689-5B82-8343-AF85AB597138"><p>document embedding may |
|
72 not be not supported by all UIs, </p> </li> |
|
73 <li id="GUID-54F48257-3849-5635-9430-C7968BAF42C9"><p>the embeddable and embeddable-only |
|
74 properties should only be set for file-based applications, in other words, |
|
75 applications that create embeddable documents. </p> </li> |
|
76 </ul></note> </p> <p><i>hidden</i></p> <p>Hidden applications run in the background. |
|
77 They are not shown to the user and do not appear in the application launcher |
|
78 or in the embeddable applications list. </p> <p>The default value is <codeph>KAppNotHidden</codeph>. </p> <p><i>newfile</i> </p> <p>This |
|
79 property indicates whether the application is document-based and supports |
|
80 the creation of new files. </p> <p>The default value is <codeph>KAppDoesNotSupportNewFile</codeph>. </p> <p><i>launch</i> </p> <p>Indicates |
|
81 whether the application will be launched in the foreground so that it takes |
|
82 focus, or in the background. </p> </section> |
|
83 <section><title>Default screen number</title> <p>This number identifies the |
|
84 screen on which the application is displayed. It can be omitted if the phone |
|
85 has a single screen. In v8.1b, the application can only ever appear on this |
|
86 screen; this may change in later releases. For the Symbian emulator, screen |
|
87 numbers are initialised in the window server initialisation file, <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini</xref>. </p> </section> |
|
88 <section id="GUID-500CEB11-DA89-5A6D-B0E5-E5C881030FCD"><title>UIDs</title> <p>Two |
|
89 UIDs must be specified in the source registration file: <codeph>UID2</codeph> and <codeph>UID3</codeph>. <codeph>UID2</codeph> always |
|
90 has the value <codeph>KUidAppRegistrationResourceFile</codeph>; <codeph>UID3</codeph> is |
|
91 the third UID of the application. </p> </section> |
|
92 <section id="GUID-2E24E9DA-4EBF-5CB5-96CB-112E7610227A"><title>MIME support</title> <p>Multipurpose |
|
93 Internet Mail Extensions, MIMEs, define a file format for transferring non-ASCII |
|
94 data, such as graphics, audio and fax, over the Internet. The <codeph>datatype_list</codeph> section |
|
95 lists the MIME types that the application supports, and the priority of support |
|
96 that each type is given. When a file is opened, Symbian platform launches |
|
97 the application which has the highest priority of support for the type of |
|
98 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 |
|
99 files, and would be given a priority of <codeph>EDataTypePriorityNormal</codeph> for |
|
100 that file type. A web browser is less good at handling text files, and would |
|
101 be assigned the lower priority <codeph>EDataTypePriorityLow</codeph>. So, |
|
102 either application can be launched to handle a text file, however if both |
|
103 applications are present, the text editor is launched in preference. </p> <p> <codeph>EDataTypePriorityHigh</codeph> should |
|
104 only be assigned under exceptional conditions, for instance if no other application |
|
105 could ever handle a particular MIME type as well. </p> <p> <codeph>EDataTypePriorityLastResort</codeph> should |
|
106 also be used sparingly. Text editors are terrible at displaying HTML, and |
|
107 would either have the priority <codeph>EDataTypePriorityLastResort</codeph>, |
|
108 or would not support the type at all. </p> <p>Given two applications with |
|
109 the same MIME type priority, Symbian platform arbitrarily launches one of |
|
110 them. </p> </section> |
|
111 <section><title>View-specific information</title> <p>For view-based applications, |
|
112 as an alternative to using an application-wide caption and icons, each view |
|
113 in the application can define its own icon and captions. This is so that specific |
|
114 application views can be launched directly from the phone's application launcher/shell. |
|
115 This feature may not be supported by all phone UIs. </p> <p>The following |
|
116 view-specific properties can be specified, using a <codeph>VIEW_DATA</codeph> resource |
|
117 struct, declared in <filepath>appinfo.rh</filepath>: </p> <ul> |
|
118 <li id="GUID-27E58734-77D5-5420-A0E5-E5635530913A"><p>The view's UID. </p> <p>This |
|
119 uniquely identifies the view within the application (in C++ this corresponds |
|
120 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> |
|
121 <li id="GUID-BA449839-7205-5997-99BF-CA0E23C6A796"><p>The screen mode that |
|
122 the view uses. </p> <p>A screen mode is a combination of screen rotation and |
|
123 screen size. Screen modes are identified by an index; the first one is zero. |
|
124 For the Symbian emulator, screen modes are initialised in the window server |
|
125 initialisation file, <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita">wsini.ini</xref>. |
|
126 The default value is zero. </p> <p>For example, on phones that use a flip-down |
|
127 keypad, the screen mode changes when the flip is opened or closed. On such |
|
128 phones, there may be a flip open and flip closed version of each view. </p> </li> |
|
129 <li id="GUID-79366634-C36E-5FEC-B77A-01D594A9BDD2"><p>The number of icons |
|
130 for the view. </p> <p>The icons are contained in the icon file. If the icon |
|
131 file is a vector graphics format, the <codeph>number_of_icons</codeph> value |
|
132 is irrelevant. </p> </li> |
|
133 <li id="GUID-E79B5B73-7527-5EBA-922E-8787AA6D43AF"><p>The view's caption. </p> </li> |
|
134 </ul> <p>The view-specific information is defined in the <codeph>view_list</codeph> which |
|
135 is an array of <codeph>VIEW_DATA</codeph> structs, one for each view in the |
|
136 application. It can be accessed in C++ through the <xref href="GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA.dita"><apiname>RApaLsSession</apiname></xref> class, |
|
137 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> |
|
138 <section><title>Service list</title> <p>Server applications implement services |
|
139 on behalf of client applications, using a server. They are new in v9.0 and |
|
140 the motivation behind them is platform security. Because the client and the |
|
141 server applications run in separate processes, their memory areas and private |
|
142 data files are protected from each other. </p> <p>The service list is a list |
|
143 of services offered by a server application. Each entry in the list consists |
|
144 of a <codeph>uid</codeph>, which identifies the service, and the ID of another |
|
145 resource (<codeph>opaque_data</codeph>) that describes how the service is |
|
146 implemented. The latter is called opaque data because how it is used is up |
|
147 to the server application, not the UI framework. For example, it might contain |
|
148 the ID of a localised text resource for display in the UI, or the ID of a |
|
149 resource struct that allows client code to distinguish between different implementations |
|
150 of the service. </p> <p>The information defined in the service list can be |
|
151 retrieved using the <xref href="GUID-5EEE8745-F483-33C0-A5B1-AEB5544DE2BA.dita"><apiname>RApaLsSession</apiname></xref> class. For example, clients |
|
152 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 |
|
153 in the registration file, or localisable and therefore defined as a resource |
|
154 in the localisable icon/caption definition file, if one exists, or in the |
|
155 UI resource file. If the localisable icon/caption definition file is used, |
|
156 it must include a four character <codeph>NAME</codeph> and an <codeph>RSS_SIGNATURE</codeph> resource, |
|
157 like most other resource files, and as it would no longer be the only resource |
|
158 defined in the file, the <codeph>LOCALISABLE_APP_INFO</codeph> resource must |
|
159 be given an ID, which must be specified in the registration file's <codeph>localisable_resource_id</codeph> field. </p> </section> |
|
160 </conbody></concept> |
|