Qt API | Qtopia API Qtopia Documentation

Qtopia - Customizing Qtopia for a Device

This document provides some recommendations for installing Qtopia on a device.

There are a number of aspects to customizing Qtopia for a specific device which must be considered.

Fortunately all of the changes required to add those device specific customizations are centralized in Qtopia to just a few files which are described below. This document should make it easy for OEMs and system integrators to understand how to make Qtopia aware of any special hardware that a device might have.

Device-Specific Code

During configure, the -platform option is used to select which custom-<platform-spec>.h file will be used when compiling Qtopia. The following macros can be defined or undefined in a custom.h file to customize Qtopia for the specific hardware. The associated custom-<platform-spec>.cpp file will be compiled and linked to provide any custom functions that are also required.

In addition to the above macros and defines, the following three functions must be implemented in the custom-<platform-spec>.cpp file.

For reference implementations of the device specific code, the existing custom-*.* files found in src/libraries/qtopia/ may be of guidance.

Device-Specific Files

The default hardware button mappings for a device are defined by the etc/defaultbuttons-<platform-spec>.conf files.

The format of the file is as follows:

[Button]
Count=<number of button records below>
[Button<button number counting from 0>]
Name=<name of the button (in english)>
Name[ja]=<japanese translations of the button name>
Name[<lang>]=<other lang translations of the button name etc>
Key=<associated key code emitted by the button eg. F9>
PressedActionService=<name of default service associated with press>
PressedActionMessage=<message to send to service (refer to services for details)>
HeldActionService=<name of default service associated with press>
HeldActionMessage=<message to send to service (refer to services for details)>

An example of what this may look like in a real example is:

[Button]
Count=2
[Button0]
Name=Calendar Button
Name[ja]=???
Key=F9
PressedActionService=Calendar
PressedActionMessage=raiseToday()
HeldActionService=Calendar
HeldActionMessage=raise()
[Button1]
Name=Contacts Button
Name[ja]=???
Key=F10
PressedActionService=Contacts
PressedActionMessage=raise()
HeldActionService=Contacts
HeldActionMessage=beamBusinessCard()

Images of the buttons, which should correspond to the appearance of the device hardware, are in pics/Button/n.png, with n corresponding to the button number in the configuration file.

See the existing files, especially the generic file, for guidance.

Non-installed Components

There are a number of applications/features supplied with Qtopia that are not intended to be shipped with production devices:

Unsupported Components

The following applications are unsupported 3rd party applications/ports intended purely to demonstrate the flexibility of Qtopia:

Required Plugins

If Qtopia crashes twice in quick succession "Safe Mode" will be entered and no plugins will be loaded in case the crash was caused by a misbehaving plugin. In some cases there are plugins that are required for correct operation of the device. These plugins can be specified in the .directory file in $QPEDIR/plugins/<type>/.directory. For example, if the simple8 text codec is always required:

[Desktop Entry]
Name=Text Codecs
Comment=Provides support for various international languages.
Required=simple8
Apply=QPE/System restart()

Power Management

A number of points should be considered when integrating Qtopia with a device that has power management.

Custom Qtopia Launcher User Interface

In some cases it is desireable to have a cusomized launcher interface that better suits the intended application of the target device. Qtopia supports custom laucher user interfaces via the ServerInterface. This interface provides all of the infrastructure necessary to implement a launcher, while maintaining compatiblity with the Qtopia application and document models.

The launcher user interface is part of the Qtopia server ($QPEDIR/src/server) which provides services such as syncing and filesystem management.

Launcher

The first step when writing a user interface is to implement a class derived from ServerInterface. This interface provides the functionality necessary to show the available applications and documents available on a Qtopia device.

The createGUI() and destroyGUI() functions must be implemented to create and show the laucnher and any other user interface components.

Most of the functions provided by the ServerInterface are to manage adding and removing applications and documents as necessary. The ServerInterface documentation describes each one in detail.

The default Qtopia launcher is implemented by the Launcher class.

Other User Interface Components

In addition to the launcher itself, it is ususally necessary to provide some system components, such as input methods and status display.

There are several classes in the default Qtopia user interface that may be reused in a custom interface. Most user interfaces will make use of some of these classes to ensure a useable system:

An interface providing these components will support most of the default Qtopia launcher functionality.

The Qtopia libraries aslo assume that QPE/Taskbar QCOP channel is available and supports the following functions:

The default Qtopia launcher uses the TaskBar class to encapsulate the above functionality.


Copyright © 2001-2002 TrolltechTrademarks
Qtopia version 1.7.0