Home · All Classes · Grouped Classes · Annotated · Functions

Integration guide

• Introduction
• Linux
• Kernel requirements
• Minimal configuration
• Additional options and Qtopia's dependencies on them
• Useful Debugging Options
• The Qtopia root file system
• File system partitions
• Busybox configuration
• Minimal Linux Configuration
• Optional Linux Configuration
• Other tools
• Qtopia Build system
• How to build Qtopia
• Configure options
• Removing applications
• Device-specific Configuration
• Advanced build system documentation
• Qtopia Core
• Qt Feature system
• Porting
• Qtopia Core to a New Architecture
• To another Operating System
• Qt Application to Qtopia Core
• Qtopia 2.x to 4.x
• Linux Framebuffer and Display Management
• Fonts
• Keyboard/Input plug-ins
• Pointer plugins
• Accelerated Graphics Driver
• Settings environment variables
• Qtopia Platform
• Multiple screen support
• Server Tasks
• Bluetooth
• Bluetooth Software Requirements
• Document/Content system
• Document Storage
• DRM integration
• Memory management
• Qtopia Hardware
• Accessories
• Battery
• Boot Source
• Headset
• Keypad Light
• Signal Source
• Speaker Phone
• Vibration
• Device indicators
• Networking
• Input methods
• Internationalization
• Application services
• Environment variables
• Miscellaneous steps
• Qtopia Phone Edition
• Telephony
• Modem Integration
• Running Qtopia
• Building and running outside of Qtopia build tree
• Debugging Qtopia (local and remote)
• Qtopia customizations
• UI customization
• Styles
• Theming
• Server widgets

Introduction

In general, developing a Qtopia device requires the following two processes:

1. Integration
2. Customization

The majority of this step-by-step guide refers to the Qtopia integration process. The target audience is system integrators and ODMs intending to integrate Qtopia with their hardware. The items in this document are ordered according to their dependencies, starting with the Linux kernel and followed by the root file system requirements, then Qtopia Core, Qtopia Platform and Qtopia Phone Edition requirements. Particular attention is paid to dependencies existing between Qtopia features and Linux kernel/file system options.

Subsequent to the integration process, the Running Qtopia section describes how to start Qtopia on different targets/platforms.

The last section of this document focuses on Qtopia's customization options. This guide refers to customization as the steps that are required to modify or extend the features and user interfaces provided by Qtopia. Therefore this part of the development process is optional but usually highly desired.

Linux

Kernel requirements

Many of the features in Qtopia are dependent on support from the underlying operating system. This section outlines the dependencies between these features and the configuration options for the Linux kernel. This list has been limited to only those configuration options explicitly required by Qtopia. It is highly likely that additional configuration options will need to be enabled in order to bring the system up.

Many kernel features can be configured to be either built into the kernel binary or built as loadable modules. If you choose to configure kernel features as modules you must ensure that the modules are loaded during system startup. This can be achieved by either manually loading the modules or by using an automatic module loading mechanism such as hotplug or udev.

Minimal configuration

Qtopia requires that the Linux kernel be configured with the following minimum configuration.

Additional options and Qtopia's dependencies on them

Qtopia includes many optional features and components that may not be needed for all devices. The following table lists these optional features and components together with the Linux kernel configuration options that they depend on.

Useful Debugging Options

There are a number of Linux kernel features which are generally not desirable on a production device, but may be useful during development. This section lists these options and gives examples on how to use them during development.

    exportfs -o rw,no_root_squash,async $DEVICE_ADDRESS:$PATH_TO_IMAGE

    mount -t nfs -o nolock,tcp $SERVER_ADDRESS:$PATH_TO_IMAGE /opt/Qtopia

The Qtopia root file system

A typical Linux device's root file system hierarchy would be arranged as follows:

More information is available on the Linux filesystem at Filesystem Hierarchy Standard

Qtopia has it's own file system hierarchy, which is usually mounted at /opt/Qtopia

File system partitions

There are a number of ways a device may be partitioned, depending on the hardware configuration.

Generally, the bootloader, the kernel and at the root filesystem get their own partitions. The root fileystem can also be partitioned into /, /tmp and /home.

Note: If allowing the user to download and install software packages, you will need the /tmp directory or partiton to be large enough to temporarily store any downloaded application package files.

Device Partition Layout

Qtopia can run on and use a number of file systems. Some are more appropriate for NAND flash devices while others are better for more traditional hard drive devices.

Qtopia may be installed to a read-only filesystem, provided a writable /tmp, /etc and $HOME is provided.

Busybox configuration

Busybox is a compact and powerful replacement for many common Linux(tm) utilities in a single executable, and is extremely configurable.

Qtopia uses a few system commands that are required to be on the filesystem.

Minimal Linux Configuration

A very minimal Linux System configuration might consist of these packages:

Optional Linux Configuration

In addition to the Minimal Linux System Configuration, these optional packages may be provided, or required based upon the Qtopia Components used.

These packages may be installed on the target device.

Other tools

Other tools you may want to provide for development or general use.

There are a number of commercial companies and GPL projects that can provide an Embedded Linux distribution.

• Freescale
• Wind River
• TimeSys
• OpenEmbedded
• PTXdist
• Linux From Scratch
• uClibc Buildroot

To build a cross toolchain yourself:

• Crosstool

Qtopia Build system

The Qtopia build system has its own reference documentation which provides function and variable descriptions for the various parts of the build system. This section of the integration guide will reference various parts of it as well as additional example documentation.

How to build Qtopia

Before Qtopia can be built various prerequisites and dependencies have to be satisfied. Most of these dependencies are related to the Linux system and root filesystem that Qtopia is running on. The first part of this guide explicitly states those mandatory and optional requirements. Additional information, such as supported compilers, can be found in the Dependencies and Prerequisites documentation.

Qtopia can be built in multiple ways. In general, the build system distinguishes several ways of building a Qtopia application. They are directly related to launch methods and footprint optimizations provided by Qtopia.

Note that the various options provided in the above table can be combined. A detailed overview of the possible options are provided by Qtopia's configure script. Further documentation on how to enable these optimizations in applications can be found in the following documentation:

• Optimization Using main()
• Writing Applications that Startup Quickly
• Qtopia Single Execution

Configure options

The configure options allow the enabling/disabling of Qtopia features. Some features are not required for every conceivable target device and may be disabled to reduce Qtopia's filesystem and memory use. An example is the "Minimum VoIP" device profile which is part of the Qtopia source package (see $QPEDIR/devices/min_voip). The profile shows how to reduce the size of the Qtopia build as far as possible, while still providing VoIP telephony. A large part of this optimization is simply achieved by passing the right options to Qtopia's configure script:

    -xplatform min_voip -arch arm -no-qvfb
    -displaysize 320x240
    -edition phone
    -no-modem
    -voip
    -no-helix
    -no-drm
    -no-sxe
    -prefix /opt/Qtopia
    -no-bluetooth
    -no-infrared
    -iconsize 22
    -font "dejavu:160:50"
    -languages "en_US"
    -extra-qtopiacore-config "-no-freetype"
    -extra-qtopiacore-config "-qt-libjpeg"
    -extra-qtopiacore-config "-qt-libmng"
    -extra-qtopiacore-config "-qt-libpng"
    -extra-qtopiacore-config "-qt-zlib"
    -extra-qtopiacore-config "-no-accessibility"
    -release
    -silent
    -no-samples

Qtopia maintains two sets of configure options. The first set is related to Qtopia's configure script and the second set is related to Qt's configure script.

• Qtopia configure options
• Qtopia Core configure options

Note that Qtopia Core config options are actually passed to Qtopia via the -extra-qtopiacore-config option provided by Qtopia's configure script.

Removing applications

In addition to the removal of Qtopia features, applications can be removed and added to a Qtopia build. Qtopia's project files list each individual application that is part of the build and hence enables the developer to choose among provided applications. This level of customization is also available via device profiles.

The minimal VoIP profile example excludes various applications to reduce the Qtopia footprint:

        ...
    PROJECTS-=settings/appearance
    PROJECTS-=settings/beaming
    PROJECTS-=settings/calibrate
    PROJECTS-=settings/handwriting
    PROJECTS-=settings/phonenetworks
    PROJECTS-=settings/phonesettings
    PROJECTS-=settings/callforwarding
    PROJECTS-=settings/words
    PROJECTS-=settings/packagemanager
    PROJECTS-=settings/security
    PROJECTS-=settings/serverwidgets
    PROJECTS-=settings/worldtime
        ...

whereas the greenphone profile actually adds applications to the build process:

    PROJECTS-=\
        settings/beaming
    PROJECTS*=\
        3rdparty/tools/atd\
        3rdparty/applications/target_sqlite
    !free_package|free_plus_binaries:PROJECTS*=\
        tools/phonebounce

Device-specific Configuration

As already mentioned earlier in this guide device profiles provide a convenient way of bundling device-specific code and configurations. This removes the need for code customizations within in the main Qtopia source tree. Device Profiles may be provided by hardware manufactures and/or by Trolltech as separate packages that can easily be integrated into a Qtopia source package. Device profiles can be found in $QTOPIA_DEPOT_PATH/devices, are entirely independent of the main Qtopia source tree and are easily enabled via the build system.

The following example configures, compiles and installs the Greephone device profile which is located in $QTOPIA_DEPOT_PATH/devices/greenphone:

    cd $QPEDIR
    $QTOPIA_DEPOT_PATH/configure -device greenphone
    make
    make install

The build system will use the configure options stored in QTOPIA_DEPOT_PATH/devices/greenphone/configure to build Qtopia for the Greenphone. Note that even cross-compiling is handled by device profiles.

The device plugin tutorial may be of interest as well because it demonstrates how a new profile is created using the requirement for a device plugin, such as a keyboard plugin, as an example.

Advanced build system documentation

The Qtopia build system has a separate documentation index. Its main aim is to explain the various project file functions, variables and how they interact with the configure script. Supplemental overviews and tutorials introduce common tasks which may occur during the Qtopia development process.

Qtopia Core

Qt Feature system

Qtopia Core allows the fine-tuning of library content via the qconfig tool. QConfig provides a visual user interface that enables a convenient way of customizing library content. It presents a short dscription of particular features, can enable/disable them and resolves dependencies among these features. This allows the adjustment of Qtopia Core library sizes as needed. Qtopia uses a default configuration provided by QPEDIR/qtopiacore/qconfig-qpe.h which may be used as a starting point for further customization. Please note that the qconfig system can only be used to customize Qtopia Core libraries and not Qtopia libraries.

qconfig-qpe.h excludes the following Qt components from a standard Qtopia build:

Porting

The term porting is used to describe two similar processes. The first use of the term is in the context of modifying Qtopia Core to support a new hardware platform or operating system. In this case the statements "Porting Qtopia Core to a new Architecture" and "Porting Qtopia Core to another Operating System" refer to the process of adding the necessary platform dependent code to Qtopia Core to support the target hardware platform and operating system. The second use refers to the process of changing application code, for an existing application, to work with a newer version of the Qtopia API.

Qtopia Core to a New Architecture

Porting Qtopia Core to a new Architecture involves implementing device drivers for keypad input pointer input, and screen output. You must also ensure that platform dependent atomic operations are provided. These topics are covered in the Porting Qtopia Core to a New Architecture document.

To another Operating System

Porting Qtopia Core to another Operating System involves replacing all Linux specific system calls used in Qtopia Core with equivalents available on the new Operating System. Porting Qtopia Core to Another Operating System documents the Linux specific system calls that are currently used and what they are used for.

Qt Application to Qtopia Core

Existing Qt 4 applications should require no porting provided there is no platform dependent code. If platform dependent code is used, Porting Qt Applications to Qtopia Core provides information on how to manage platform dependent code within your application.

Qtopia 2.x to 4.x

Porting applications from Qtopia 2.x to Qtopia 4.x primarily involves making changes related to changes in the Qt API. Qtopia does not support the Qt 3 Support module, so the task of porting from Qtopia 2 to Qtopia 4 takes more work than porting from Qt 2 to Qt 4. An overview on the planned incompatibilities between Qtopia versions and instructions on how to update your code to the new API is described in the Porting Between Qtopia Versions document.

For Qtopia 4 applications it is no longer recommended that the main() function be written explicitly by the programmer. Instead macros are used to declare the application entry point. These macros are designed so that your application can be built for different configurations (such as singleexec, quicklaunch and standard builds) without requiring any code changes. For details on declaring the entry point for your application see Optimization Using main() and the Application macro guide.

Linux Framebuffer and Display Management

Qtopia Core provides screen drivers for the Linux Framebuffer, virtual framebuffer, transformed screens, VNC servers and multiple screens. Qtopia Core's default behavior is for each client application to render its contents into an off-screen buffer. The Qtopia server process copies the memory contents onto the screen. For an overview of this process see Graphics Rendering and Drawing on Screen.

The virtual framebuffer and VNC server drivers are used predominantly during development. When Qtopia is deployed on a device the Linux framebuffer, transformed screens or multi-screen drivers are typically used. The screen driver that Qtopia uses is specified in the QWS_DISPLAY environment variable. Refer to Qtopia Core Display Management for documentation on building screen drivers and how to specify which screen driver Qtopia should use.

Most devices will use the Linux Framebuffer driver. The Qtopia Core document Testing the Linux Framebuffer includes a small test program that can be used to verify that the Linux Framebuffer is configured and works correctly.

Qtopia includes support for multiple screens and accelerated graphics drivers. For documentation on integrating these features refer to Multiple Screen Support and Accelerated Graphics Driver.

Fonts

Qtopia Core uses the FreeType 2 font engine to render fonts. In addition Qtopia Core also supports native prerendered fonts (QPF). For full details on the font formats supported by Qtopia Core see Qtopia Core Fonts.

Qtopia Core ships with several fonts. The licensing terms for these fonts are described in Licenses for Fonts Used in Qtopia Core.

Qtopia selects the font size based on the size and resolution of the target display. Please refer to Setting the Display Size which demonstrates how the actual font size is calculated.

Keyboard/Input plug-ins

Qtopia's keyboard handling is controlled by Qtopia Core. There are a few default keyboard drivers available: tty usb sl5000 yopy vr41xx qvfb

A custom keyboard driver may be implemented through Qtopia's Device Configuration Profiles, and documentation can be found for the class QWSKeyboardHandler.

More information about Keyboard Plugins:

• Keypad Architecture
• Qtopia Core Character Input
• Keypad Button Behavior

Pointer plugins

In Qtopia Core, there are built-in Mouse Pointer (touchscreen) Plugins. If none of these work, a Device Configuration may include a custom mouse pointer plugin-in.

More information about Mouse Pointer plug-ins:

• Mouse Pointer Handling
• Qtopia Core Pointer Handling
• Mouse Pointer Calibration

Accelerated Graphics Driver

Qtopia's display performance can be enhanced by the use of a hardware graphics accelerator.

More information about Accelerated Graphics Drivers in Qtopia Core:

• Qtopia Core Display Management
• Accelerated Screen Driver Example

Settings environment variables

Qtopia makes use of a few environment variables. These are usually set by the Qtopia startup script. The QWS_DISPLAY environment variable can also be set from the defaultbuttons.conf file. More Information on most Qtopia Core Environmental Variables:

• Qtopia Core Environment Variables

In addition to the Qtopia Core specific environment variables mentioned above the following standard variables may be required:

            <language>_<country>.<codeset>

Qtopia Platform

Multiple screen support

Qtopia supports multiple screens. A possible use case for such a situation might be a clamshell phone which has a small status display on the outside and a larger display on the inside. The Dual Screen guide describes the necessary setup steps for dual display development and how any application can display a widget on the secondary display. Support for more than two displays can be achieved with similar steps.

Qtopia Phone Editon provides an integrated and themeable secondary display via the server widget classes QAbstractSecondaryDisplay and ThemedSecondaryDisplay. More details can be found in the Server widgets part of this guide.

Server Tasks

The Qtopia server application is structured as a collection of server tasks. Ideally each task would perform a small, well-defined portion of work or functionality. Server tasks allow ODMs to easily customize Qtopia by extending, replacing and removing tasks from the Qtopia server application with little or no changes required to the Qtopia server source code. This is achieved by using device profiles and the $QPEDIR/etc/Tasks.cfg configuration file. For information about particular server tasks refer to the server task class documentation.

In most cases Qtopia server tasks are implemented as QObject derived classes. An exception to this are functional tasks, which are implemented as static functions. The developer uses QTOPIA_TASK() and QTOPIA_STATIC_TASK() macros to declare server tasks. For full details see the QtopiaServerApplication documentation. The following example demonstrates how to implement a server task. First the class is declared in the header file

    // exampleservertask.h
    #include <QObject>

    class ExampleServerTask : public QObject
    {
        public:
            ExampleServerTask();
    };

Then the class is implemented and registered with the task system in the implementation file

    #include "exampleservertask.h"

    ExampleServerTask::ExampleServerTask()
    {
        ...
    }

    QTOPIA_TASK(ExampleServerTask, ExampleServerTask);

New server tasks are added by placing the source code for the server tasks into the server/ directory of the configured device profile. The Qtopia Build System automatically includes source files in this directory into the Qtopia server application.

Existing server tasks can be extended to provide additional functionality or to implement device specific code by creating subclasses of the existing server tasks. Source code for these classes should be stored in the server/ directory of the configured device profile.

Removing server tasks can be achieved by adding task names to the exclude group of the $QPEDIR/etc/Tasks.cfg configuration file.

The startup process of the Qtopia Server Application is defined by the order that tasks are listed in the Tasks.cfg configuration file. Tasks.cfg supports the definition of task groups which can be used to collect related tasks together. Except for a few reserved task group names, group names can be any alphanumeric string. For details on the format of the Tasks.cfg configuration file refer to Qtopia Server Tasks.

Qtopia supports two types of tasks: preemptive tasks and on-demand tasks. Preemptive tasks are started during the startup process as defined in the Tasks.cfg configuration file. On-demand tasks are configured as such by marking tasks to be started on demand in the Tasks.cfg configuration file. Only tasks in the reserved prestartup and startup groups are preemptively started by Qtopia.

Some server tasks provide essential functionality and their startup order must be well defined. Two such tasks are the QtopiaApplication server task (implemented in the QtopiaServerApplication class) and the QtopiaServerApplicationLauncher tasks. The startup order of the QtopiaApplication server task must be configured correctly as many other server tasks have an implicit dependency on it. This requirement is documented as part of the Tasks Startup Order. Typically Qtopia is configured to start the QtopiaApplication task from the prestartup group. To achieve this Tasks.cfg should contain a prestartup group with contents similar to

    [prestartup]
    EnvironmentSetup
    DBMigrate
    QtopiaApplication
    IpcRouter

QtopiaServerApplicationLauncher is part of the application launcher framework. It functions as a proxy for the Qtopia Server within the application launcher framework. To ensure correct behavior it is essential that the QtopiaServerApplicationLauncher task is the first task with the ApplicationTypeLauncher interface that is started. The startup sequence of the application framework is typically configured by including something similar to the following in the Tasks.cfg configuration file:

    ...
    [ApplicationLauncher]
    ApplicationMonitor
    ApplicationLauncher
    QtopiaServerApplicationLauncher
    BuiltinApplicationLauncher
    ConsoleApplicationLauncher
    QuickExeApplicationLauncher
    QuickForkedApplicationLauncher
    SandboxedExeApplicationLauncher
    SimpleExeApplicationLauncher

    [startup]
    +ApplicationLauncher
    ...

Bluetooth

Qtopia uses the official Linux Bluetooth stack, BlueZ, for Bluetooth support. The Bluetooth Support document covers the third party requirements and describes the Bluetooth functionality supported by Qtopia.

The Bluetooth Service Management Framework enables Bluetooth services to be handled consistently within Qtopia.

Qtopia supports the following Bluetooth connection sockets

• L2CAP
• RFCOMM
• SCO

Qtopia includes implementations of the following Bluetooth services.

• Bluetooth handsfree service Audio Gateway
• Bluetooth headset service Audio Gateway
• Bluetooth dial-up networking service

For documentation on creating additional Bluetooth services, refer to Creating a custom Bluetooth service.

Bluetooth can be used as a transport layer for the OBEX protocol. Qtopia includes an implementation of the OBEX Push Service. To create additional OBEX services, subclass QObexServer.

Bluetooth Software Requirements

Qtopia requires Linux kernel and additional third party software to support Bluetooth. Bluetooth Kernel Configuration describes the necessary Linux kernel configuration. Optional Linux Configuration lists the required third party packages.

Document/Content system

Qtopia has a robust Document and Content system to enable the user to easily find documents and content.

Document Storage

Documents in Qtopia are usually stored in the user's $HOME directory under the Documents directory, in a tree as such: /<file type>/<mine type>/<file name>.

For example, if a user creates a voice note, the resulting file gets stored in $HOME/Documents/audio/x-wav/June_5_2007_333_AM.wav

The content system categorizes the file and stores its location in the database. The user can then access their files from the Documents menu in the launcher.

A Storage.conf file can be supplied detailing alternate locations for documents.

DRM integration

Qtopia is able to handle Digital Rights Management. See DRM Integration for details.

Memory management

Qtopia performs adequately with 64 MB of RAM. However the best value may depend on the actual device and most importantly the size of the display. A significant proportion of memory is used for the shared pixmap cache. More details on how to influence the size of the pixmap cache can be found in the Managing Memory Usage documentation.

If it is necessary to debug various memory related problems, profiling tools like valgrind and gprof should be used to determine potential bottlenecks. The Qtopia documentation provides a quick introduction (using valgrind as an example) to how memory related performance issues might be detected.

Qtopia Hardware

Accessories

The Qtopia Accessory System is used to access hardware devices from Qtopia applications. The accessory system provides a standard method of querying for available accessories and a standard interface for accessing those accessories. Currently the Qtopia Accessory System defines hardware interfaces for the following devices

• Battery
• Boot Source
• Headset
• Keypad Light
• Signal Source
• Speaker Phone
• Vibration

The system integrator adds device-specific code for their device by creating a new accessory class that inherits from one of the base accessory provider classes and overrides the member functions with device-specific implementations. Alternatively the base accessory provider classes can be instantiated directly, connecting the appropriate signals and slots to provide the necessary device-specific functionality.

Accessories are made available to the system when an accessory provider object is instantiated. Typically this is done during system startup from a server task.

Battery

Battery accessories are used to query information about the available batteries. For documentation on how to implement a battery accessory see QBatteryAccessoryProvider. For documentation on how to use battery accessories from a Qtopia application see QBatteryAccessory.

Qtopia supports multiple battery accessories on a single device. See QBatteryAccessory for details on how to specify a default battery accessory.

Boot Source

Boot source accessories are used to query the event that triggered the last boot sequence. Typically a device has only a single boot source accessory. For documentation on how to implement a boot source accessory see QBootSourceAccessoryProvider. For documentation on how to use boot source accessories from a Qtopia application see QBootSourceAccessory.

Headset

Headset accessories are used to access headsets. For documentation on how to implement a headset accessory see QHeadsetAccessoryProvider. For documentation on how to use a headset accessory from a Qtopia application see QHeadsetAccessory.

Keypad Light

Keypad light accessories are used to control the state of the keypad light on the device. Typically a device has only a single keypad light accessory. For documentation on how to implement a keypad light accessory see QKeypadLightAccessoryProvider. For documentation on how to use the keypad light accessory from a Qtopia application see QKeypadLightAccessory.

Signal Source

Signal source accessories are used to query information about the available signal sources. For documentation on how to implement a signal source accessory see QSignalSourceProvider. For documentation on how to use signal source accessories from a Qtopia application see QSignalSource.

Qtopia supports multiple signal sources on a single device. See QSignalSource for details on how to specify a default signal source.

Speaker Phone

Speaker phone accessories are used to access a speaker phone. For documentation on how to implement a speaker phone accessory see QSpeakerPhoneAccessoryProvider. For documentation on how to use speaker phone accessories from a Qtopia application see QSpeakerPhoneAccessory.

Qtopia Phone uses the speaker phone accessory to switch to and from speaker phone mode during a call.

Vibration

Vibration accessories are used to alert the user. Typically a device has only a single vibration accessory. For documentation on how to implement a vibration accessory see QVibrateAccessoryProvider. For documentation on how to use a vibration accessory from a Qtopia application see QVibrateAccessory.

Qtopia Phone uses the vibrate accessory to alert the user to a variety of conditions.

Device indicators

Devices such as Mobile Phones often have indication lights, for things such as charging status, or new email indicators.

Networking

Qtopia uses network plug-ins to enable new types of network bearer. At present the following network types are supported:

In general each plug-in provides three components. The GUI component allows the user to configure each network connection via the Settings -> Internet application or any other application that wants to do so. The second component initiates and publishes state changes such as the starting/stopping of the physical network device and the change of routes. The third part is a network script that abstracts the OS/distribution specific network interface configuration from Qtopia. This is done via shell scripts.

Due to the different types of supported network interfaces, the script interfaces are different for each plug-in. It is required to implement these scripts as part of the integration process. To ease the initial development process all plug-in's ship with sample scripts demonstrating the expected functionality. The (W)LAN plug-in for example provides a SuSE 9.3 and a busybox implementation. They may be used as a starting point for the integration process. The exact script parameters and configuration file formats are described in the Network Services documentation.

If it is necessary to support a network bearer that is not yet supported by Qtopia, new plug-ins can be added by implementing the abstract QtopiaNetworkPlugin and QtopiaNetworkInterface interfaces. An overview of network related classes and how they interact with each other can be found in the QNetworkDevice class documentation.

Input methods

Qtopia's input method handling consists of two parts. The IM backend is provided by the Qtopia server which is responsible for the loading of input method plug-ins and input/output related Qtopia classes. These classes build the framework for input method plug-ins.

The front-end implementation for Qtopia's IM support is provided via plug-ins. By default Qtopia provides a few reference implementations which demonstrate certain IM capabilities:

As stated earlier, Qtopia's input methods are reference implementations. Their purpose is to demonstrate and test certain capabilities of Qtopia's back-end implementation as well as providing sample code for new plug-in development. The input method tutorial describes the steps required for plug-in development.

Internationalization

Qtopia can be translated into several languages. By default, Qtopia only provides an English user interface. However user interfaces have been designed and tested with a variety of European and Asian languages to ensure that Qtopia can handle the various layout and space issues caused by most languages.

The Qtopia Internationalization guide explains the fundamental details of Qtopia's i18n support, such as how the build system can support the process and how to generate translations for new (not yet) supported languages. The build system documentation has some additional documentation which covers Non-code Translatable (translations required for settings and xml files) related information:

• Translating Categories
• Translating Themes
• Other build system related internationalization tasks

It is possible to purchase translations for selected languages from Trolltech. For more details please contact sales@trolltech.com.

The number of supported languages is limited by Qt. Please consult the Internationalization with Qt guide to obtain an overview.

Application services

Services are a standardized way of accessing functionality supplied by other applications. Any application can utilize these services via the QtopiaService* classes. Messages between applications are delivered via Qtopia IPC.

Qtopia services are documented in the service documentation. It explains what services are provided by Qtopia, how they can be accessed and the steps required to add new services. The various meta-information describing a service can be found in $QPEDIR/services and each service is documented like any other Qtopia class (see the ClockService as an example).

Environment variables

Qtopia uses various environmental variables to facilitate various settings, which are documented in:

• Qtopia Core Environment Variables
• Environment Settings to Run Qtopia

Miscellaneous steps

Qtopia Phone Edition

Telephony

Qtopia Phone Edition provides Telephony support that enables Qtopia devices to use GSM and Voice over IP (VoIP) functionality. The Telephony Documentation provides the main entry page into the telephony parts of Qtopia.

Modem Integration

Qtopia Phone supports vendor-specific modem commands through the use of plug-ins to the Qtopia Phone Modem Library. The process of implementing a vendor-specific phone-vendor plug-in and multiplexer plug-in is covered in GSM Modem Integration and Tutorial: Writing a Multiplexer Plug-in respectively. Before starting it may be necessary to configure the Linux kernel to support the modem device. See AT Modem for details on what is required for modems connected via a serial interface.

The QTOPIA_PHONE_DEVICE macro in custom.h is used to specify the modem device. QTOPIA_PHONE_DEVICE can also be set as an environment variable. The format of QTOPIA_PHONE_DEVICE is

    <device>:<baud rate>

For example to specify /dev/ttyS0 as the modem device with a baud rate of 115200, add the following preprocessor define to custom.h

    #define QTOPIA_PHONE_DEVICE "/dev/ttyS0:115200"

or alternatively the QTOPIA_PHONE_DEVICE environment variable could be set. For Bourne compatible shells

    export QTOPIA_PHONE_DEVICE="/dev/ttyS0:115200"

Running Qtopia

The Running Qtopia reference documentation describes how to run Qtopia on desktop machines as well as running Qtopia on a target device (directly flashed onto the device or via NFS).

In order to test Qtopia Phone functionality Qtopia provides a Phone simulator (see $QTOPIA_DEPOT_PATH/src/tools/phonesim) which simulates a significant subset of the GSM 27.007 AT command set. This may be used if a real modem is not available for testing purposes. The Qtopia Core documentation also contains a Running Qtopia Core Applications help which shows the qws command line supported by Qtopia Core.

Building and running outside of Qtopia build tree

In addition to standard Qtopia applications and libraries which are already incorporated into the build system it may be necessary to add more (including 3rdparty) applications to a Qtopia build. For this purpose the Qtopia build system provides qtopiamake which allows development from outside of the main build tree. Please refer to the following documents for further information:

• Compile and Run Example Application
• Tutorial: Creating an Application

Debugging Qtopia (local and remote)

Debugging Qtopia applications is an important part of the development process. The Debugging Qtopia Applications guide provides a basic introduction showing how to use gdb and Qtopia's internal logging mechanisms.

In some situation it may be necessary to debug Qtopia running on a remote device because a particular bug may only happen on the target device but not on a desktop machine. This imposes further restriction upon the debugging process because the target device may not have sufficient memory to hold a complete debug build of Qtopia. This situation can be solved by using gdb's remote debugging facilities. The Qtopia Remote Debugging guide provides a quick demonstration how Qtopia may be remotely debugged.

Qtopia customizations

UI customization

Styles

Qtopia uses the Qt Style framework to define the look and feel of the common widgets used by Qtopia applications. Qtopia provides a default style, Qtopia, which is implemented in QPhoneStyle and QtopiaStyle. The look and feel of Qtopia applications can be changed by implementing new styles. New styles are created by deriving new classes from QStyle. Refer to Creating a custom style and Styles Example documentation on creating custom styles. Custom styles are loaded using the plug-in system. For details on creating a style plug-in and registering the custom style with the QStyleFactory refer to Writing Qt Extensions.

If your device will be used with both left-to-right and right-to-left layouts you should consider the implications this has when designing custom styles.

When creating custom widgets it is important to make them style-aware, doing so will allow you to maintain a consistent look and feel.

In Qtopia, styles are linked to themes, which the user can select in Appearance Settings. The following segment of $QPEDIR/etc/themes/qtopia.conf demonstrates how a widget style is associated with a given theme. In this example the Qtopia style is used when the user selects the Qtopia theme.

    [Theme]
    Name[] = Qtopia
    Style = Qtopia
    ...

For full details on customizing Qtopia's UI using themes refer to Theming.

Theming

Integrators can extend Qtopia's look and feel by customizing the theme.

• Theming
• Theming Files
• Title Bar Theming
• Context Bar Theming
• Home and Call Screen Themes
• Window Decoration Themes

Server widgets

Qtopia's Server widget concept is the user interface customization with the most flexibility. It enables the replacement of widget components via abstract widget classes which define how the various main user interface components interact with each other.

The following table describes the purpose of the various abstract server widget:

The main benefits of server widgets are their flexibility and configurability. Large UI parts can be exchanged against alternative implementations by changing a confguration file. However unlike themes the Qtopia server must be restarted in order to update the user interface. Besides the default implementations Qtopia ships with a couple of sample server widgets which demonstrate the possibilities. The server widget settings application (see $QPEDIR/src/settings/serverwidgets) is a reference application that allows the user to change the server appearance using server widgets.

See also QDeviceIndicators and QValueSpaceItem.