The HelloWorld GUI Application

Using exactly the same example application as used in Chapter 1, we look at the two generic project files for the HelloWorld example in detail and examine the contents of each line by line. You must have a component definition ( bld.inf ) and a project definition ( .mmp ) file for each development project. The bld.inf file for a project may refer to one or more .mmp files, one for each component to be built. In simple projects there will be a single component ”for example, a single reference to the .mmp file for the application itself. In more complex projects, it may involve other components in addition to the application, such as dynamic link libraries ( DLLs ), and there may be multiple .mmp files. The component definition and project definition files are used by the tool chain to construct a build command file ( abld.bat ). You can use this file for various purposes, such as creating other project and workspace files for your chosen platform or development environment, or building the project for the emulator or target device in debug or release formats.

HelloWorld bld.inf

The HelloWorld component description file ( bld.inf ) refers to a single project definition file ( HelloWorld.mmp ).

 // HelloWorld bld.inf PRJ_MMPFILES // List the .mmp file(s) required for the project HelloWorld.mmp 

For a simple application (or single component), such as the HelloWorld example, this is typically all there is in a bld.inf file. A list of the .mmp file(s) in the project is placed after the PRJ_MMPFILES statement. In this example this is simply the name of the .mmp file for the application. In a more complex project there might be a list of several other .mmp files ”one for each component part of the application.

The bldmake tool processes the component definition file ( bld.inf ) in the current directory and generates the batch file abld.bat and several build batch makefiles ( .make ). The makefiles are used by abld to carry out the various stages of building the component. To see a general list of the syntax of the bldmake command, type:

 bldmake 

Then, by typing the following, you will see a general list of the syntax of the other statements valid in a bld.inf file:

 bldmake inf 

HelloWorld.mmp

A project definition (. mmp ) file specifies the properties of a project component in a platform- and compiler-independent way. It may then be used, along with the bld.inf file, by the SDK build tools ( abld.bat ) or an IDE to produce platform-specific makefiles. The HelloWorld.mmp project definition file is shown here, followed by an explanation of each statement in Table 2-1.

[View full width]

 
 [View full width] 
 // HelloWorld.mmp file TARGET  HelloWorld.app TARGETTYPE  app UID  0x100039CE 0x101F6148 TARGETPATH \system\apps\HelloWorld LANG 01 SOURCEPATH ..\src SOURCE  HelloWorldApplication.cpp SOURCE  HelloWorldAppUi.cpp SOURCE  HelloWorldDocument.cpp SOURCE  HelloWorldContainer.cpp RESOURCE ..\data\HelloWorld.rss RESOURCE ..\data\HelloWorld_caption.rss USERINCLUDE . ..\inc SYSTEMINCLUDE \epoc32\include LIBRARY euser.lib apparc.lib cone.lib eikcore.lib LIBRARY eikcoctl.lib avkon.lib commonengine.lib AIF HelloWorld.aif ..\aif HelloWorldaif.rss c12 context_pane_icon.bmp  context_pane_icon_mask.bmp list_icon.bmp list_icon_mask.bmp 

To see a complete list of the valid statements in an .mmp file, open up a command prompt, navigate to your SDK, and type makmake “mmp .

UIDs

A UID is a globally unique identifier consisting of a 32-bit number. In Symbian OS, objects are identified by their UID type , which has three component UIDs: UID1 , UID2 and UID3 . UID1 determines whether a file is a document or executable code. It should be seen as a system-level identifier, distinguishing between executables, DLLs and such like. UID1 is determined by the TARGETTYPE statement in the .mmp file.

Table 2-1. Statements from the HelloWorld.mmp File

.mmp Statement	Function
TARGET	The name of the application, which must have the correct filename extension: . exe , .app , .dll and so on.
TARGETTYPE	Defined as app (this option determines the value of UID1 ), meaning this is a GUI application. There are many other types, including dll , exe, tsy , csy and ldd .
UID	Specifies a unique system identifier ( UID2 ) for a GUI application: 0x100039CE and 0x101F6148 that is absolutely unique to the application itself ( UID3 ). UID2 and UID3 are not required for .exe applications. UID s are explained in the next section of this chapter.
TARGETPATH	The location of the final built application and its components ”this is always under \system\apps\ relative to the root of a device drive or an emulated drive such as c: or the emulated ROM ( z: ) drive.
LANG	This statement is used if an application is to support different languages. Each language supported has a two-digit code. This is described later in this chapter in the Localization of Applications and Resources subsection. It is also covered in more detail in Chapter 4.
SOURCEPATH	The location path of the source files for the project.
SOURCE	This statement refers to the name(s) of the source file(s) for the project. This statement can occur multiple times and can have multiple filenames on each statement line.
RESOURCE	Refers to a source file that defines the majority of the user interface elements, such as menus , dialogs, text strings and so on. Also the source file for the application captions.
USERINCLUDE , SYSTEMINCLUDE	These statements refer to the location of the application-specific header files for the project with path information for system header files. All Symbian OS projects should specify \epoc32\include\ for their SYSTEMINCLUDE path ”relative to the root of the SDK.
LIBRARY	Lists the application framework and graphics libraries required for linking to ”these are the .lib files corresponding to the shared library DLLs whose functions you will be calling at runtime.
AIF	The statement refers to an Application Information File ( .aif ) that contains icons and other application properties defined in the application resource file. .aif files are explained later in this chapter. The application details and characteristics are specified in the text-based resource file HelloWorldaif.rss , and the source bitmaps and masks for the icons are listed as a series of Windows .bmp files. The c12 parameter refers to the color depth (12-bit) to be used when the files are converted from .bmp to Symbian OS .mbm format as part of the icon creation.

For a document file, UID2 determines the type of document it is (application data file, or .aif file). For an executable code file, the value of UID2 determines the type of executable it is (for example, . app , .dll or .tsy ). For executable code files, UID2 and UID3 are specified in the .mmp file on the UID line.

UID3 is an application-level identifier; the value for your application must be absolutely unique across all other applications. These values are issued only by Symbian. Unique UIDs for applications and other purposes can only be obtained from Symbian by emailing [e-mail]. A range of UIDs: 0x01000000 to 0x0FFFFFFF , is available for use during development, but be very careful never to release an application with an experimental UID.

Symbian OS uses UIDs to associate documents (data files) and .aif files with their respective application; UID3 is included in the header of each data file, executable file or .aif file. However, it is still necessary for executables and their components to have the correct filename extensions, otherwise they will not run correctly, appear in the Application Launcher or be associated correctly with their document.

When an application creates a document file, all three UIDs, plus a 32-bit checksum, are automatically incorporated into the first 16 bytes of the file header by the application framework.

Sometimes you will get a link error when you build your project because a required library is missing from the .mmp file. To find out which library you need to list in the .mmp file, you can check out the SDK documentation or use the clindex utility that produces an up-to-date ordered listing ”for details see More Tools and Utilities later in this chapter.

Stack and Heap Sizes

Automatic (locally scoped) variables , function arguments and so on are stored in an area of memory called the stack. Memory allocated dynamically, through operators such as new (or new (ELeave) in Symbian OS code), is taken from a pool called the heap. Both a stack and a heap are created by the system for each application or thread of execution. Stack memory allocation and deallocation is controlled by the runtime environment. Memory allocated and deallocated on the heap is under the direct control of the developer. In most cases such allocations are under your control; in some cases they are under the control of the operating system designers. Careful control of allocation, and in particular the deallocation of heap memory, is a vital requirement placed on all Symbian OS developers.

By default the stack size for an application is 8KB, but you may need a larger stack for certain types of application. However, you must be careful not to use this facility to misuse the stack. In Symbian OS code only small objects should be put on the stack; all large objects are normally allocated on the heap. If you do need more than 8KB of stack ”for example, in a highly recursive application ”you can use the EPOCSTACKSIZE statement in your application's .mmp file to override the default 8KB. The size of the stack (in bytes) can be specified in decimal or hexadecimal format. On target hardware if a stack overflow occurs on ARM, it will cause a page fault; the application will be panicked and will terminate, and an error ( KERN- EXEC 3 ) will be reported . See the SDK documentation for comprehensive error-code information ”search for "Panic categories and numbers " or "System panic reference".

The default heap size for an application is 1MB. Again, you can increase (or decrease) this if required. The EPOCHEAPSIZE statement will allow you to specify minimum and maximum heap values ”this is not problematic under the emulator, since the maximum heap limit is not enforced.

Depending on the IDE you are using, the EPOCSTACKSIZE and EPOCHEAPSIZE statements may have no effect under the emulator environment. It may be necessary to change project settings directly within your IDE to allocate more (or less) stack or heap space to the application.

Trying to use too much stack when building for the emulator under Microsoft Visual C++ may result in the following error:

 Engtest.obj : error LNK2001: unresolved external symbol __chkstk \EPOC32\RELEASE\WINS\DEB/ENGTEST.exe : fatal error LNK1120: 1 unresolved externals Error executing link.exe. 

To fix this for WINS builds in the Visual C++ IDE, select ProjectSetting from the menu and select the C++ tab in the dialog. Insert a new line such as:

 /Gs9999 /FD /c 

where 9999 is the new stack size (decimal) in bytes.

Additional Project Components

As a matter of good object-oriented design and to aid maintainability and flexibility, Symbian OS applications are typically split into two main parts : the UI, and an application engine ”also known as the model. The UI is typically subdivided into on-screen representation(s) of the data and a handler or controller that determines the overall behavior of the application. Application engines typically encompass the data structures needed to represent the application's data, the algorithms and any data persistence.

Often, engines are created as a separate component ”typically as a DLL. If this is the case, the engine DLL is created as an additional component project with its own .mmp file. This file will be listed as a component in the bld.inf file for the main application. The name of the engine DLL must then be included in the LIBRARY statement in the .mmp file for the application.

Application architectures and the key classes in a Symbian OS UI application are discussed in more detail in Chapter 4; where an example project is provided that shows how to create a DLL to encapsulate the engine functionality.

Building and Running

Open a Windows command prompt and navigate to the folder containing the project definition ( .mmp ) and component definition ( bld.inf ) files ”for example, \EMCCSoft\HelloWorld\ group in the root of your SDK.

To create the abld.bat file, type:

 bldmake bldfiles 

To compile and link the project from the command line, type:

abld build wins udeb	”for Visual C++
abld build winsb udeb	”for CodeWarrior
abld build winscw udeb	”for Borland C++

This will build the project for the Series 60 debug emulator. Normally projects such as the HelloWorld example application are built and run from within an IDE.

The build process in some IDEs may not build all the resources required by a complete application ”for example, bitmap ( .mbm ) and icon ( .aif ) files. Command-line builds, using abld , will do a complete build, including creating all the resource and components specified in the project. Type abld to see the general syntax of the command file, or type abld help commands to list all of the command options.

To run the application you need to first start up the Series 60 emulator. At the command prompt type:

 epoc 

Generally this is all that is required to start the emulator from a command prompt. If you have more than one SDK installed, you may need to ensure the correct version is selected ”for example, by using the devices command. Normally you could create the IDE project files and build and run the emulator from within your chosen IDE, as described in Chapter 1. For application debugging, running your application from within an IDE in debug mode is a requirement, not an option.

Once you have started up the Series 60 debug emulator, navigate to and select the HelloWorld application, then click on the Selection button (in the center of the navigation control) to invoke the application. The application will run and should appear as shown in Figure 2-1.

Figure 2-1. The GUI application build process summary.

HelloWorld GUI Executable and Runtime Files

This subsection looks at the files produced by the build process, showing the type and purpose of each file, and its location on an emulator and a target device. The whole build process in terms of the input source plus header files and the output runtime files is summarized in Figure 2-2.

Figure 2-2. The HelloWorld application.

At least two files make up a minimum GUI application, the .app and .rsc files (for example, HelloWorld.app and HelloWorld.rsc ). The HelloWorld.app file is the application executable ”in other words, the output from the compilation and linking process. The HelloWorld.rsc file is the binary resource file produced by the resource compiler.

In an application intended for release, an application information ( .aif ) file must also be supplied ”it is not essential during development. An .aif file contains icons, optionally captions in the supported languages, and specifies certain application properties such as whether embedding is supported. An application will still function if the .aif file is not present. However, it will have a default icon provided by the system, and other application characteristics will be set by the system to defaults. If a caption resource file (for example, HelloWorld_caption.rss ) was specified, an additional file for installation HelloWorld_caption.rsc will be generated. See "Captions" in the AIF Files subsection later.

In Symbian OS, a GUI application is a special form of DLL that always has an .app filename extension. A specific framework is provided by the system to load and correctly initialize GUI applications. As a developer, you must conform to the requirements of this framework and will have to provide implementations of a number of pure virtual functions in order that your application will start up correctly. Optionally, you may also provide implementations of a number of other virtual framework functions in order to achieve additional specific behavior that you may require. The application framework and the associated virtual and pure virtual functions are discussed in detail in Chapter 4.

In order to be automatically recognized by the system, all GUI applications must follow a location convention ”they must be under a folder such as: \system\apps\ appname \ . So in the case of the HelloWorld example, the files described earlier ( HelloWorld.app , HelloWorld.rsc , HelloWorld_caption.rsc , and HelloWorld.aif ) should be located in a folder called \system\apps\HelloWorld\ . This folder has to be at the root level of a target device drive or an emulated drive such as c: or z: (the emulated ROM drive).

Keep the name of your application to 16 characters or less (case is not significant), otherwise your application may not appear under the Series 60 emulator, even though the build process did not report any errors!

A number of other files may be essential for the correct functioning of a particular application. For example, there may be need for a compressed multibitmap ( .mbm ) file, application-specific data files and so on. It is usual to put such essential files in the same location as the key application files ”in other words: \system\apps\appname\ .

Sometimes you will get an infuriating " Not found " error message when you try to run your application on target or under the emulator ”something is missing or incorrect, but the system does not give you any further clues! Check that your application UID is correct ”you may have forgotten to update all the UIDs in your code (including your .mmp and .pkg files). Also a DLL may be missing ”this is more common when you install to a target device and forget to move all DLLs across. One further common problem is that another file is missing, such as the .mbm , resource file or another required application data file.

HelloWorld Project Files and Locations

You will find a number of related folders located under \EMCCSoft\HelloWorld\ , and they are set out in Table 2-2.

Table 2-2. The Source Folders in the HelloWorld Project

Folder	Contents
\aif	HelloWorld.aif and the source bitmaps ( .bmp ) for the .aif file.
\data	HelloWorld.rss and HelloWorld_caption.rss ”the application resource files to generate HelloWorld.rsc and HelloWorld_caption.rsc .
\group	HelloWorld.mmp and bld.inf platform-neutral project files.
\inc	HelloWorld header ( .h ) files and other #include d files such as Helloworld.loc and Helloworld.l01 .
\install	HelloWorld.pkg package file for creating the installation ( .sis ) file via makesis.exe . HelloworldFR.pkg is the "run application on install" version. The HelloWorld.sis files are placed here when built.
\src	HelloWorld source ( .cpp ) files.

This subfolder and file organization for the project ”under the project name folder ”will reflect the structure defined in the .mmp file. In some cases the data and install folders may not exist, and the associated files may be located in the group folder instead. Virtually all files generated during a build and the intermediate build files are placed outside of this folder structure, except for:

• The abld.bat file ” This is not portable between SDKs and must be regenerated when the bld.inf or .mpp file changes.

• On building, the HelloWorld.sis file is placed in the folder containing the .pkg file.

HelloWorld GUI Source Files

This subsection outlines the contents and the function of each of the source files that form the example project, but the detailed discussion of Series 60 application design principles is left until Chapter 4.

Source and Header Files

The files listed in Table 2-3 make up the body of the C++ application source, header files and class modules.

Table 2-3. Source Files in the HelloWorld Project

File Name	Contents	Class Module	Comments
HelloWorldApp.h	Class and function declarations	The application	Application creation/initialization
HelloWorldApp.cpp	Class and function definitions
HelloWorldAppUi.h	Class and function declarations	The application UI	Command handler/controller
HelloWorldAppUi.cpp	Class and function definitions
HelloWorldDocument.h	Class and function declarations	The document	Owns the data or application model
HelloWorldDocument.cpp	Class and function definitions
HelloWorldContainer.h	Class and function declarations	The application's data view	Displays the application's data
HelloWorldContainer.cpp	Class and function definitions

Once you have the HelloWorld project open in your IDE, you will probably discover another source file called HelloWorld.uid.cpp . This is the UID source file; the build tools automatically generate it under a folder such as: \epoc32\Build\Symbian\6.1\Series60\HelloWorld\group\HelloWorld\wins in the root of your SDK. There should be no need for you to edit this file. It simply defines the application's UIDs as a data segment and is required by some types of DLL running under the emulator (WINS) environment.

Application Resource Files

Resource Source Script ( .rss ) files (for example, HelloWorld.rss ) are used by applications in Symbian OS to define the way a GUI application will look on screen. Much of the information that defines the appearance, behavior and functionality of an application is stored in a resource file. Created external to the main body of the executable, everything from the status pane, menus, general user interface controls, through to individual dialog boxes can be defined in the resource file. Individual resources are loaded very efficiently as required at runtime, and hence the memory requirements are minimized.

Application resources are compiled (and may be compressed) at build time into binary files that are used at runtime (by default with .rsc extensions). During the build steps the resource compiler processes this file. It is typically compiled automatically before the compilation of the source files (but only if the resource file has been updated since the last running of the resource compiler). The output of the resource compiler is a binary file that is used at runtime to supply the resource information as required. The default output name has the same name as the application, but with an .rsc filename extension.

For the HelloWorld example application, the name will be HelloWorld.rsc . In addition, a header file, with an .rsg filename extension, is generated by the resource compilation stages. This file contains a series of symbolic name/numeric constant pairs (as #define s) that identify each of the user interface elements. This file must be #include d in the .cpp files wherever the resources are referenced or used.

Resource files and their internal structure may initially appear complex, but taken step by step they are quite straightforward. Comprehensive explanations and examples of application resource files are provided throughout this book, and many other examples are available in the Series 60 SDK example projects.

Optionally another resource file, HelloWorld_caption.rss , may be created to define captions for the application ”in other words, the application name for display in the Application Launcher . Two caption sizes are quoted to accommodate the display options of the Application Launcher grid and list views. The resource compiler also processes this file during a full project build.

Other Header Files

Note that avkon.hrh (located in \epoc32\include ) contains many enumerated constants defined by the Series 60 user interface and application framework. This is a very important file for Series 60 applications. For example, one of the constants defined is EAknCmdExit ; an application's menu option Exit should always generate this command. The standard value passed by the framework when an application should close down (for example, under low memory conditions or for a system backup) is EEikCmdExit as defined in Uikon.hrh .

A special header file, called HelloWorld.hrh , is part of most projects and contains definitions of any enumerated constants that may be used in both source files ( .cpp ) and resource files ( .rss ). These constants are very specific to an application and are typically used for menu commands, key handling, view identifiers, or for command handling in dialogs.

The structure of the UI resources and controls that are used in the application's resource file are defined in files with .rh extensions. It is possible to define your own resource structures for custom user interface components that you produce yourself. Specific SDKs provide numerous resource structures, and the .rh files that define them are located in the ..\epoc32\include\ folder under your SDK folder tree. Resource files and resource header ( .rh ) files are covered in more detail in Chapter 5.

Resource Compiler

Virtually all user interface elements and controls can be defined in the application resource file. Individual resources are loaded as required at runtime from the compiled resource file (by default with .rsc extensions), and hence the memory requirements are minimized.

Resource files can be localized without recompiling the main program. For ease of localization, all user interface text is usually separated out from the main resource ( .rss ) file into separate header files that are conditionally #include d into the main resource file at build time. It is the included language text files, not the main resource file, that are later translated into the different supported languages. A version of the application resource file is produced for each language. Localization is discussed in more detail later in this section.

Application caption resources may be used to provide captions (the application's name) in two different lengths and in multiple languages. The captions are displayed with the application's icon in the Application Launcher . The resource compiler also processes the caption resource file(s) during a full build. See the AIF Files subsection later in this chapter for more details.

The resource compiler ( rcomp.exe ) is usually invoked automatically from within an IDE. Alternatively it can be run from the command prompt; typically this is performed through a command file ( epocrc.bat ) that combines the actions of passing a resource file through the C++ preprocessor, and then compiling it with rcomp.exe . Compilation of resource files generates a binary output file plus an .rsg header file that is #include d into C++ code to identify specific user interface resources such as text strings, dialogs and menu components.

Localization of Applications and Resources

If your application is to be distributed outside of your own locale, then localization needs should be considered from the outset of a project. Good support for localization is provided in Symbian OS and the SDK build system and tools.

For Latin character sets, adapting an application for a different language text should only require changing the resource file, since user visible text should never be embedded in C++ source files. However, you will have to adopt a flexible attitude toward layout, as text translated into different languages will obviously have different lengths.

Each supported language has a two-digit identifier code; for example, English is 01 , French is 02 and German is 03 . These language codes are all defined in \Epoc32\Include\e32std.h . For each language you will typically create a specific text file by having the default language file translated. Each language file can then be conditionally included in the main application resource file at build time. The process of localizing an application in this way is demonstrated by a variant of the HelloWorld example used in this chapter, called HelloWorldLoc . Each specific text file typically has the two-digit language code forming the last two characters of the filename extension. So, in the HelloWorldLoc variant of this example project you will see there are three variants of the included text file with extensions of .l01 , .l02 and .l03 for the English, French and German variants.

There are also a number of support classes for other locale-sensitive information and formatting. For instance, the TLocale and related classes are defined in e32std.h and allow dates, times, currency and many other locale-sensitive data types to be correctly formatted for the current system locale. You need to become aware of the data types that are locale sensitive, the formatting classes available and be sure to use them whenever you are presenting data on screen.

A number of approaches are possible for providing language variants and installation files that give the user options at application install time.

Resource files compiled for specific languages will typically have filename extensions such as .r01 , .r02 , .r03 and so on, and the user may be given a choice of language at install time. The default compiled resource file has the extension .rsc ; any language variant can be renamed to this extension during installation. A Series 60 project file ( .mmp ) can list the supported languages via the LANG statement.

 LANG 01 02 03 

When a full project build is performed, the system will compile the English ( 01 ), French ( 02 ) and German ( 03 ) resources for the application. More information on the installation of multilingual applications is provided later in this chapter, and localization of dates is described in Chapter 4.

With non-Latin languages, the localization of text is much more complex. Symbian OS and Series 60 do provide some support for producing devices using languages such as Chinese, Japanese, Korean, Hebrew, Arabic and Thai. However, writing applications that support these languages is a specialist subject and is beyond the scope of this book.

AIF Files

Application information ( .aif ) files are used at runtime and store data concerning an application, including:

• Icons in two sizes (defined later in this chapter), are used by the system to represent your application.

• Capabilities, such as document embedding, new-file creation, whether the application is hidden or not and MIME-type support priorities.

• Optionally, application captions ( names ) in the supported languages ”although better support for captions is provided via the caption resource file system described later in this section.

Without an .aif file an application will use a default icon, and the application name as a caption (without the filename extension). It can be created independently of the application by the aifbuilder tool provided with the Series 60 SDK. The aifbuilder tool allows you to define the properties of the .aif file and saves the details of a project's definition in a file with an .aifb filename extension. Note that aifbuilder depends on a Java99 2 Runtime, which is available from http://java.sun.com.

You can specify the composition of .aif files manually through text-based resource files with an .rss filename extension (for example, HelloWorldaif.rss ). This is the option used in all of the example GUI applications described in this chapter. This resource file is compiled by the aiftool utility ”it can be performed manually at a command prompt, or automatically during a full project build. The .aif build process also converts the bitmap files that form the icon (with bmconv , as described later in this chapter) and then creates the .aif file. The aiftool utility and the syntax of .aif files are documented in the Series 60 SDK.

Icons

Icons are used to represent applications and their associated files/documents, both when they are embedded and when they are shown on the application shell. Series 60 icons are usually provided in two sizes. The most appropriate size for the current container "zoom state" will be displayed, if an icon of the specific size is not available ”for example, the Application Launcher grid and list views use icons 42 pixels wide by 29 pixels high, whereas the application context pane of the status pane (shown at the top of the screen when an application has focus) uses icons 44 by 44 pixels in size. As illustrated in Figure 2-3, in the application view the Messages icon is 42 by 29 pixels, whereas the Messages icon at the top of the screen in the status pane is 44 by 44 pixels.

Figure 2-3. Series 60 icon sizes.

Supplying a variety of icon sizes helps to ensure that the system can use the most appropriate size. Supplying only a single icon will result in dynamic scaling when it is drawn at a particular size ”scaling small bitmaps generally results in a marked loss of quality.

Aifbuilder can launch an icon designer facility that will generate the bitmaps and masks that make up the icon. AIF icon designer helps you produce such icons in the required Symbian OS-specific bitmap file format, called the multibitmap file format ( .mbm ).

AIF File Localization

If your application design requires different icons for different languages, you can achieve this by producing multiple copies of the .aif file, each containing the appropriate bitmaps, using the aiftool utility. Each localized .aif file produced is usually saved with the extension .aXX , where XX is the two-digit language code associated with the appropriate locale. The application framework software (Apparc) has been modified to attempt to load an .aif file associated with the current system language setting.

MIME Support

Native Symbian OS files ”those created by Symbian compliant applications ”are recognized by the system through the UID system described earlier, in particular through UID3 . For nonnative files, MIME type recognition is an excellent alternative. Multipurpose Internet Mail Extensions ( MIME s) define a file format for transferring nontextual data, such as graphics, audio and fax over the Internet. See http://www.iana.org/assignments/media-types/ for more details on MIME types.

A Symbian OS application may specify in its .aif file any MIME types that it supports and the priority of support that each type is given. For example, you may wish to have your application support the display and editing of plain text files. When a file is to be opened, Symbian OS launches the application that has the highest-priority support for the selected file type.

There are four priority levels (defined by enumeration in \epoc32\include\aiftool.rh ), of which only EDataTypePriorityNormal or EDataTypePriorityLow should normally be used.

For example, your text editor is clearly going to be good at editing text/plain files, and hence should be given a priority of EDataTypePriorityNormal for that file type. A Web browser is less suited to handling text files and would be assigned the lower priority EDataTypePriorityLow . Hence either application can be launched to handle a text document. If both applications are present, however, the text editor is launched by preference. Given two applications with the same MIME type priority, Symbian OS will arbitrarily launch one of the applications.

For more information on .aif files and MIME type support, see the Series 60 SDK documentation.

Captions

Avkon, the Series 60 UI and application framework, provides alternative capability to associate captions with an application ”functionality that should be used in preference to that available through the caption normally supplied via an .aif file. By default, the system will use the caption supplied in the .aif file. However, it is possible for application authors to generate a separate caption file, containing both a normal length caption and a short caption ”these are provided for use in either the list or grid view of the Application Launcher . The short caption is used in application grid view, whereas the normal caption is used in application list view. The caption file is generated in the same way as a normal GUI resource file. For the HelloWorld project, the caption source file is HelloWorld_caption.rss , and the binary output file, used at runtime, is called HelloWorld_caption.rsc . This is placed in the \system\apps\HelloWorld\ folder with the other application files ”for example, .app , .rsc , .aif and so on.

If required, you can generate a separate caption file for each language supported by your application. The convention for naming the caption resource files is as follows :

NAME_OF_APP_caption.rss , where NAME_OF_APP is the name of the application ”in the HelloWorld example that would be HelloWorld_caption.rss . The caption resource can be built as part of the normal build process by adding the additional line to an application's .mmp file:

 RESOURCE <NAME OF APP>_caption.rss 

The compiled resource file will then appear in:

\system\apps\appname\appname_caption.rXX , where XX is the two-digit language code specified in the .mmp file.