Developing Series 60 Applications: A Guide for Symbian OS C++ Developers: A Guide for Symbian OS C++ Developers

2017-07-07 02:10:07

Symbian OS SDKs include a number of tools and utilities; Series 60 SDKs provide even more tools. EMCC Software Ltd has also placed additional tools and utilities into the public domain. These extra tools are listed here because they are used frequently, are particularly helpful, are important or are not very well documented elsewhere. References on how to obtain the additional tools are also provided.

Multi-Bitmaps and Bmconv the Bitmap Converter

Bitmaps provide the pixel patterns used by pictures, icons and masks, sprites and brush styles for filling areas of the display. To optimize bitmap performance, Symbian OS uses files containing multiple bitmaps in its own highly compressed format. A tool is provided ( bmconv.exe ) with the Series 60 SDK that takes one or more Windows bitmap ( .bmp ) files as input and generates a single Symbian OS multi-bitmap file (. mbm ), optimized for efficient runtime loading.

To see the bmconv syntax and options simply type bmconv at a command prompt.

The bmconv tool also generates a header file ( .mbg ) with symbolic definitions (identifiers) for each bitmap in the file. This generated header file is placed in the \epoc32\include folder of the SDK. It is intended for inclusion ( #include ) in your C++ code to allow you to reference any of the individual bitmaps as required.

Two types of .mbm files are possible, file store bitmap files that are loaded into RAM and ROM image bitmap files that do not use any RAM when being accessed ”only system developers normally create ROM-based .mbm files.

During the conversion process it is possible to specify the number of bits per pixel for the converted bitmaps and whether they should be color or grayscale. The program can also split Symbian OS multi-bitmap ( .mbm ) files back into component bitmap files in Windows bitmap ( .bmp ) format.

You do not always have to use the bmconv tool directly to produce bitmap files that are dedicated to a particular application. Building the required bitmaps can be performed as part of the standard abld project building process. A list of .bmp files can be specified in the project definition ( .mmp ) file. The next section shows an example of the START BITMAP statement in the project definition ( .mmp ) file syntax. See the Series 60 SDK documentation for further details of the START BITMAP syntax.

Multi-Bitmap Files, Colors and Palette Support

The hardware color capabilities of Series 60 devices may differ from product to product. Typically, the display is capable of producing a minimum of 4096 colors (12-bit) for Series 60 1.x, and up to 64K colors (16-bit) for Series 60 2.x. All of these color bits may be used to provide the best possible reproduction, for example, when displaying a full-color JPEG photograph.

It is common to specify the generation of a Symbian OS multi-bitmap ( .mbm ) file and set the target color modes in the application's .mmp file as illustrated below:

START BITMAP myapp.mbm HEADER TARGETPATH \system\apps\MyApp SOURCEPATH ..\Data SOURCE c8 MyPict.bmp // Color256 SOURCE c8 MyOtherPict.bmp // Color256 SOURCE 1 MyOtherPict_Mask.bmp // Black&White mask END

When the project is rebuilt completely, typically from the command prompt, bmconv will generate the .mbm file. It can be invoked directly from the command line if preferred.

It is possible to specify 12-bit color (4096 or Color4k ) or 16-bit color ( Color64k ), however, there is a palette with 256 color (8-bit) entries that is used for drawing user interface graphics, such as icons and window borders. Using this palette saves memory space while also ensuring a consistent look for the graphics from product to product.

For Series 60 SDKs the bmconv utility has been changed so that the caller can optionally specify a target palette file as parameter for use in the conversion. Bitmaps with a target color mode other than Color256 are not affected. Bitmaps with a target color mode of Color256 are converted using the Series 60 palette ”in other words, the 216 colors in the color cube, and 10 gray shades. The palette file used as a bmconv parameter can be found under the root level of your SDK at: \epoc32\include\ThirdPartyBitmap.pal .

The color indices in the palette are divided into the following sections:

Static colors ” This section contains 216 colors commonly known as web-safe colors, and an additional 10 grays, for a total of 226 indices. These colors are constant, so they stay the same regardless of the color scheme in use.

Scheme colors ” Twenty-three indices are reserved for use in color schemes. The RGB values in this part of the palette can be switched so that the user can change the overall UI color scheme, for example, from blue to green. These indices are used in those parts of the UI graphics that should follow the color scheme.

Notification colors ” These four colors are to be used in the respective notes (confirmation, information, warning and error notes).

Series 60-specific coding identification colors ” It is useful to recognize a bitmap that is intended for use with the Series 60 color palette and that supports the color-schemes feature. This can be achieved by checking the RGB values of certain palette indices. If the values match the predefined values, the image is identified as Series 60 specific, and the palette index values in the product will be used to render the image instead of the image's own palette values. If the palette entries of the identification color indices do not match (or if a different bitmap format than indexed noncompressed Windows bitmap is used), the RGB values of the image will be used.

Masking color ” One index (255) is reserved for masking color. The pixels of this index value are rendered as transparent in the mask.

Series 60 Application Wizards

A number of example projects have been provided throughout the book, and these can be used as the basis of any of your own new projects and applications.

Alternatively, you can use the wizard facilities provided by the various IDEs to create a project for a basic Series 60 application.

Microsoft Visual C++ 6.0

If you are using Microsoft Visual C++ as your IDE, you can create new projects via the Series 60 Application Wizard provided as part of the SDK. It offers you a simple and convenient way to generate a basic application framework from within the Visual C++ IDE. The wizard will generate a project based on one of three alternative UI display designs: the dialog-based, Avkon view-switching or traditional Symbian OS control-based application architectures. It will create:

Skeleton code and declarations for the four basic classes (App, AppUI, Document and View) associated with most Symbian OS applications.

All the build and project files necessary to build the project.

Simple resource files and bitmaps that are used as default application icons.

The files needed to install the application onto a device.

Using the wizard is very easy and is well documented in the Series 60 SDK, so its use is not covered here in great detail. However, it does present you with options to create projects conforming to one of three basic application designs. Each of these is covered in Chapter 4, so it is recommended that you read that chapter before using the wizard.

Borland C++BuilderX

As described in Chapter 1, you can open an existing Series 60 project file by importing its bld.inf file into the IDE. This is done through the Object Gallery , invoked by selecting FileNew from the menu and then choosing the Import Symbian C++ Project option. Other alternatives available at the time of writing are:

New Symbian GUI Application

New Symbian Empty Project

New Symbian DLL

New Symbian C++ File

New Symbian .H File

New Symbian Resource File

New Symbian AIF wizard

Selecting New Symbian GUI Application will create the basic framework for a Symbian project. This, however, is currently based on the Uikon CEik - base classes, not the CAkn - base classes required by a Series 60 GUI application.

Metrowerks CodeWarrior

CodeWarrior can create new projects based on supplied template projects (called stationery). To use this, choose FileNew ... and select Symbian Stationery Wizard from the Project tab. Give the project a name and set the location ”use the Set option to browse. Choose a vendor and the specific SDK version you are working with ”press Next and select the specific type of project you want from a drop-down tree under the C++ check box. A wizard then will create a basic Series 60 project for you with source and header files.

It is possible to create your own stationery. It is also expected that some Licensees may provide device-specific stationery as part of Licensee Development Kits and SDKs.

Miscellaneous SDK Tools

Series 60 SDKs provide a number of additional tools and utilities as a convenience to developers. Look in the \Series60Tools folder under the root of your SDK for up-to-the-minute availability, details of installation and correct usage.

EPOCSwitch

EpocSwitch sits in your PC system tray and allows you to select the SDK you want to use (by right-clicking the icon). You can also double-click the icon or select a command prompt from the menu to give you a command prompt with the environment set up correctly. Unfortunately it is not compatible with the new approach to SDK configuration management adopted by Symbian OS 7.0s ”see EnvironmentSwitch .

EnvironmentSwitch

EnvironmentSwitch is available from Series 60 2.0. It replaces EpocSwitch , offering the same functionality but being fully compatible with both the latest SDKs and earlier versions. As with EpocSwitch , it sits in the system tray and is activated by right-clicking.

EPOCToolbar

This makes available a Symbian OS-specific toolbar ”but only in the Microsoft Visual C++ IDE. The six icons give access to six convenient utilities.

MBMViewer

This allows you conveniently to browse the bitmaps/icons embedded in Symbian OS .mbm files on your PC.

MMPClick

Allows you to right-click on an .mmp file and choose from a context menu the target platform you want to build for ( armi urel , wins udeb , wins urel ), or else create the Microsoft Visual C++ workspace and project files.

SMS Inbox

This is an emulator application that you can leave running in the background while you are testing the process of sending/receiving SMS messages from within your application. When an SMS is sent, it is copied to a \smsout folder. Received SMS messages are copied into a \smsin folder. The usual SMS viewer and editor can be used for editing the SMS messages.

More Tools and Utilities

Customizing Microsoft Visual C++ - Syntax Highlighting

Syntax highlighting for Symbian OS and other user-defined keywords can be enabled using file called usertype.dat . User-defined keywords can be set to a color different from that of C++ keywords, making Symbian OS keywords easier to spot. It works for Visual C++ 6.0 ”see clindex below for how to keep the keywords file right up to date. Usertype.dat and instructions on its use are available from http://www.emccsoft.com.

Customizing Microsoft Visual C++ - Symbian OS Variable Expansion

During a debugging session it is useful to be able to view the contents of a variable in a Watch window. However, Visual C++ is not always able to usefully display user-defined types. Fortunately, you can customize Visual C++, using a file called autoexp.dat , so that complex new data types are properly expanded in Watch windows and datatips. Autoexp.dat and instructions on its use are available from http://www.emccsoft.com.

Clindex

To find out which objects are supplied by which library (and hence list in your .mmp file) you can check out the SDK documentation or use the clindex utility from EMCC Software Ltd. Run over your Microsoft Visual C++ SDK installation, it produces an up-to-date ordered listing of all objects and their corresponding libraries. In addition clindex has an option to merge all found class names into your usertype.dat file. clindex and instructions on its use are available from http://www.emccsoft.com.