Application information files

Contents

• Changes to aiftool in EPOC Release 5
• Overview
• Application icons
• Application captions
• Application capabilities
• UIDs, extension and location
• MIME support

Changes to aiftool in EPOC Release 5

The changes to aiftool in EPOC Release 5 are:

• MIME type support. As detailed in the topic MIME support, .aif files now define MIME type priorities. This allows applications to be associated with, and automatically launched by, non EPOC-native documents, e.g. HTML.
• _UNICODE switch. As detailed in the topic UIDs, extension and location, the resource file now supports a _UNICODE switch for selection between the narrow build and Unicode UID values.

Overview

Application Information Files, extension .aif, store data concerning an application. The information includes the application’s:

• icon in various sizes
• caption in supported languages
• capabilities, such as embedding, new-file and hidden
• MIME-type support priorities

The aiftool tool can be used to create .aif files, as described in the topic Creating application information files. There are also C++ reader and writer classes for manipulating the data stored in .aif files (the writer class is rarely needed).

An EPOC program can run without an .aif file. In this case; a default icon, typically a question mark, is used for the application and its documents; MIME types are not supported; embedding is not supported; and the application does not support new-file, e.g. the ability to create files from the system shell rather than from within an application. The default caption is the name of its executable, without the extension.

The following topics describe each of the application properties defined in the application information file.

Application icons

Icons are used to represent applications, and their associated files/documents, when they are embedded, or when they are shown on the extras bar or system shell.

Up to 5 icons, in a number of different sizes, can be stored  — the most appropriate size for the current container zoom state is displayed. Supplying a variety of sizes helps to ensure that an icon will not have to be dynamically scaled when it is drawn at a particular size — scaling small bitmaps generally results in a marked loss of quality. Typically icons of sizes 24x24, 32x32, and 48x48 might be supplied for an EPOC program running on a ½ VGA screen. Smaller icons might also be supplied for use as iconic doors in applications, such as Word, which may be in relatively small zoom states e.g. 9x9 and 12x12.

Each icon size needs a picture bitmap, and a mask bitmap. The mask should be black for the regions which are to be selected from the picture, and white for the transparent areas where the background should show through.

Application captions

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

Captions for multiple languages can be stored in one .aif, and the one corresponding to the current system language is used. If there is no caption matching the current system language, the .aif filename is used. This means that one .aif can be used for multiple language versions of an application, as long as the icon does not need to change across these versions.

The set of supported languages is as given in the list below. Note that a test language is also supported.

Application capabilities

Application capabilities are encapsulated by the TApaAppCapability class. The three file properties/capabilities defined in an .aif file are detailed below:

embeddability

An EPOC application can be defined as embeddable, not embeddable, or EmbeddableOnly. An embeddable file appears in the embeddable list (Ctrl+Shift+O in any editor, e.g. Word). A file with the property EmbeddableOnly appears in the embeddable list, but will not appear on the extras bar.

By default, files are not embeddable.

hidden

An application can be defined as Hidden or Not Hidden. The Hidden property is intended for applications which are to run in the background. Such files do not appear in the extras bar or in the embeddable applications list, however they are visible in the system task list.

By default, files are not hidden.

new-file

An application can be defined with capabilities Does Not Support New File or Supports New File. The property allows new files to be created from the system screen as well as in the program. Files supporting the property appear in the list accessed when Ctrl+N is pressed on the system screen.

By default, files do not support the New File property.

UIDs, extension and location

Application information files are located in the same directory as the application DLL with which they are associated. They are normally given the same name as the application file, extension .app, but with an extension .aif.

Like other EPOC files, application information files have a set of 3 identifying UIDs:

• The first UID identifies the file as a stream store, see KDirectFileStoreLayoutUid, defined in s32file.h
• The second UID identifies the DLL as an application information store , see KUidAppInfoFile, defined in apadef.h
• The third UID associates the AIF with its parent application, e.g. KUidAppNameApp

When an .aif file is created using aiftool, users need only specify the third UID. Aiftool automatically inserts the others.

Narrow and Unicode application build variants cannot use each other documents, and can hence be looked upon as different applications. Consequently they must have different third UIDs. The _UNICODE flag is used to select the appropriate third UID for the current build variant, when the source .aif resource text file is compiled . Note: Unicode is not supported in this release.

MIME support

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

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 hence 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. Hence either application can be launched to handle a text document, however if both applications are present, the text editor is launched by preference.

EDataTypePriorityHigh should only be assigned under exceptional conditions  — e.g. if no other application could ever handle a particular MIME type as brilliantly.

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.

Notes:

• Given two applications with the same MIME type priority, EPOC arbitrarily launches one of the applications.
• Developers can give users the ability to set their application as the default MIME type launcher — through the user defined mapping API (datastore.h, class CTypeStoreManager). This is usually accessed via an application menu option Make me the default.