Application information files

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

aif files can be specified in a number of ways:

• through the GUI tool AIF Builder: see Introduction to AIF Builder

• through manually writing an Aiftool resource file: see Aiftool resource file format — .rss

If you manually write an Aiftool resource file,

• If you are using C++, you can specify that Aiftool should be invoked as part of the abld process, by using the aif keyword in your .mmp file.

• You can invoke the command-line Aiftool tool to create the aif file, as described in the topic Application information file compiler aiftool.exe.

There are also C++ reader and writer classes for manipulating the data stored in aif files (the writer class is rarely needed).

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

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

Aif files allow multiple icons of different sizes to 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. The icon sizes to use vary between device families:

• Crystal: two icons, with sizes 64x50 and 25x20.

• Quartz: most applications have only a 20x16 icon, which the Launcher combines with a round background icon. A 32x32 icon can also be supplied, and if it is, is used unchanged.

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.

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 three file properties/capabilities defined in an .aif file are detailed below. Note the following language-specific behaviour:

• C++: all properties apply

• OPL: the embeddability property does not apply

• Java: no properties apply

An application can be defined as embeddable, not embeddable, or EmbeddableOnly. An embeddable file appears in the embeddable list. A file with the property EmbeddableOnly appears in the embeddable list, but not on the shell.

It is possible to set the Embeddable or EmbeddableOnly capability for an application which does not create embeddable documents, e.g. for a Java application. Attempting to embed such an application will cause the system to return Not Supported.

By default, the capability is not embeddable.

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 on the shell or in the embeddable applications list, however they are visible in the system task list.

The Hidden capability can be applied to any application. However Java applications should not be hidden, because this will remove their icon from the shell — which is the whole point of giving them an aif file.

By default, files are not hidden.

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.

It is possible to set the Supports New File capability for an application which does not have the ability to create new document files, e.g. for a Java application. Attempting to create a new file for such an application will cause the system to launch the application.

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

In C++, these capabilities are encapsulated in the TApaAppCapability class.

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

Like other 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.

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.

• 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 (datastor.h, class CTypeStoreManager).

• Java applications do not support MIME types.