Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

Integration guide

• Introduction
• Linux
• Kernel requirements
• Minimal configuration
• Additional options and the Qt Extended dependencies on them
• Useful Debugging Options
• The Qt Extended root file system
• File system partitions
• Busybox configuration
• Minimal Linux Configuration
• Optional Linux Configuration
• Other tools
• Root file system/kernel sources
• Qt Extended Build system
• How to build Qt Extended
• Configure options
• Adjusting projects
• Device-specific Configuration
• Advanced build system documentation
• Qt for Embedded Linux
• Qt Feature system
• Porting
• Qt for Embedded Linux to a New Architecture
• To another Operating System
• Qt Application to Qt for Embedded Linux
• Qtopia 2.x to 4.x
• Linux Framebuffer and Display Management
• Fonts
• Keyboard/Input plug-ins
• Pointer plugins
• Accelerated Graphics Driver
• Environment Variables
• Qt Extended
• Application services
• Multiple screen support
• QWS connection timeout
• Server Tasks
• Server task plug-ins
• Task startup
• Communication
• Bluetooth
• Bluetooth Software Requirements
• Networking
• USB
• USB Host
• USB Peripheral
• USB On-the-Go
• Dynamic Display Rotation
• Document/Content system
• Document Storage
• DRM integration
• Memory management
• General information
• Out of memory management
• Hardware integration
• Device indicators
• Hardware Abstraction
• Boot Source
• Keypad Light
• Power Source
• Signal Source
• Vibration
• Key mappings
• Power Management
• Input methods
• Internationalization
• Media integration
• Audio States
• Messaging
• Multimedia Messaging
• Multimedia Messaging Viewer (SMIL)
• WAP Stack Integration
• AMR Encoder
• SXE integration
• Telephony
• Modem Integration
• VoIP integration
• Web Browser integration
• Other miscellaneous steps
• Qt Extended Environment variables
• Qt Extended customizations
• First Use
• UI customization
• Styles
• Theming
• Server widgets
• Running Qt Extended
• Building and running outside of Qt Extended build tree
• Debugging Qt Extended (local and remote)

Introduction

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

1. Integration
2. Customization

The majority of this step-by-step guide refers to the Qt Extended integration process. The target audience is system integrators and ODMs intending to integrate Qt Extended 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 Qt for Embedded Linux and Qt Extended requirements. Particular attention is paid to dependencies existing between Qt Extended features and Linux kernel/file system options.

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

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

Linux

Kernel requirements

Many of the features in Qt Extended 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 Qt Extended. 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

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

Additional options and the Qt Extended dependencies on them

Qt Extended 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 Qt Extended 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

Qt Extended has it's own file system hierarchy, which is usually mounted at /opt/Qtopia. For more details see the Qt Extended File System Standards.

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

Qt Extended 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.

Qt Extended 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.

Qt Extended 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 Qt Extended 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.

The compiler requirements are mentioned in the build prerequisites.

Root file system/kernel sources

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

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

To build a cross toolchain yourself:

• Crosstool

Qt Extended Build system

The Qt Extended 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 Qt Extended

Before Qt Extended 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 Qt Extended 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.

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

Note that the various options provided in the above table can be combined. A detailed overview of the possible options are provided by the Qt Extended configure script.

Configure options

The configure options allow the enabling/disabling of Qt Extended modules. Some modules are not required for every conceivable target device and may be disabled to reduce filesystem and memory use. Module selction can be done via configure's -modules flag.

    ./configure -devices xyz -modules ipcomms

The above example assumes that the target build for device xyz requires support for a VoIP features only. Therefore the required modules are the Base and IpComms module. The Base module is required for all Qt Extended builds and is implicitly selected by all build configurations. The next example demonstrates how to select multiple module at the same time:

    ./configure -devices xyz -modules ipcomms,cell,location

More information about the module concept can be found in the Qt Extended Modules documentation.

In addition to the modules flag Qt Extended maintains two sets of configure options. The first set is related to the Qt Extended configure script and the second set is related to Qt's configure script.

• Qt Extended configure options
• Qt for Embedded Linux configure options

Note that Qt config options are actually passed to Qt Extended via the -extra-qtopiacore-config option provided by the Qt Extended configure script.

Adjusting projects

In addition to the removal of Qt Extended features, applications can be removed and added to a Qt Extended build. The Qt Extended project files list each individual project that is part of the build and hence enables the developer to choose among provided libraries, plug-ins and applications. This level of customization is also available via device profiles. This enables an even better level of customization but has the disadvantage that project dependencies may have to be resolved manually.

As an example the greenphone profile adds and removes the following projects to/from the build process:

    PROJECTS*=\
        3rdparty/tools/atd\
        3rdparty/applications/target_sqlite\
        settings/startupflags\
        tools/phonebounce

    PROJECTS-=\
        settings/beaming

    THEMES-=finxi

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 Qt Extended source tree. Device Profiles may be provided by hardware manufactures and/or with Qt Extended as separate packages that can easily be integrated into a Qt Extended source package. Device profiles can be found in $QTOPIA_DEPOT_PATH/devices, are entirely independent of the main Qt Extended 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
    bin/qbuild
    bin/qbuild image

The build system will use the configure options stored in QTOPIA_DEPOT_PATH/devices/greenphone/configure to build Qt Extended 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 Qt Extended 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 Qt Extended development process.

Qt for Embedded Linux

Qt Feature system

Qt for Embedded Linux 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 description of particular features, can enable/disable them and resolves dependencies among these features. This allows the adjustment of Qt for Embedded Linux library sizes as needed. Qt Extended 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 Qt for Embedded Linux libraries and not Qt Extended libraries.

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

Porting

The term porting is used to describe two similar processes. The first use of the term is in the context of modifying Qt for Embedded Linux to support a new hardware platform or operating system. In this case the statements "Porting Qt for Embedded Linux to a new Architecture" and "Porting Qt for Embedded Linux to another Operating System" refer to the process of adding the necessary platform dependent code to Qt for Embedded Linux 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 Qt Extended API.

Qt for Embedded Linux to a New Architecture

Porting Qt for Embedded Linux 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 Qt for Embedded Linux to a New Architecture document.

To another Operating System

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

Qt Application to Qt for Embedded Linux

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 Qt for Embedded Linux 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 / Qt Extended 4.x primarily involves making changes related to changes in the Qt API. Qt Extended does not support the Qt 3 Support module, so the task of porting from Qtopia 2 to Qtopia / Qt Extended 4 takes more work than porting from Qt 2 to Qt 4. An overview on the planned incompatibilities between Qtopia / Qt Extended versions and instructions on how to update your code to the new API is described in the Porting Between Qtopia/Qt Extended Versions document.

For Qtopia Qt Extended 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 Applications.

Linux Framebuffer and Display Management

Qt Extended for Embedded Linux provides screen drivers for the Linux Framebuffer, virtual framebuffer, transformed screens, VNC servers and multiple screens. Qt for Embedded Linux's default behavior is for each client application to render its contents into an off-screen buffer. The Qt Extended 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 Qt is deployed on a device the Linux framebuffer, transformed screens or multi-screen drivers are typically used. The screen driver that Qt Extended uses is specified in the QWS_DISPLAY environment variable. Refer to Qt for Embedded Linux Display Management for documentation on building screen drivers and how to specify which screen driver Qt Extended should use.

Most devices will use the Linux Framebuffer driver. The Qt for Embedded Linux 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.

Qt Extended 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

Qt for Embedded Linux uses the FreeType 2 font engine to render fonts. In addition Qt for Embedded Linux also supports native prerendered fonts (QPF2) and legacy prerendered fonts (QPF). For full details on the font formats supported by Qt for Embedded Linux see Qt for Embedded Linux Fonts.

Qt for Embedded Linux ships with several fonts. The licensing terms for these fonts are described in Licenses for Fonts Used in Qt for Embedded Linux.

Qt Extended 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

Qt Extended keyboard handling is controlled by Qt for Embedded Linux. There are a few default keyboard drivers available: tty usb sl5000 yopy vr41xx qvfb

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

More information about Keyboard Plugins:

• Keypad Architecture
• Qt for Embedded Linux Character Input
• Keypad Button Behavior

Pointer plugins

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

More information about Mouse Pointer plug-ins:

• Mouse Pointer Handling
• Qt for Embedded Linux Pointer Handling
• Mouse Pointer Calibration

Accelerated Graphics Driver

The display performance can be enhanced by the use of a hardware graphics accelerator.

More information about Accelerated Graphics Drivers in Qt for Embedded Linux:

• Qt for Embedded Linux Display Management
• Accelerated Graphics Driver Example
• OpenGL for Embedded Systems Example

Environment Variables

Qt Extended makes use of a few environment variables. These are usually set by the startup script.

    #!/bin/sh
    export QWS_DISPLAY=LinuxFb:mmWidth34:mmHeight44:0
    /opt/Qtopia/bin/qpe

They can also be set from the defaultbuttons.conf file.

    [Environment]
    QWS_DISPLAY=LinuxFb:mmWidth34:mmHeight44:0

Note that variables set in defaultbuttons.conf do not override variables set in the environment before running Qt Extended.

More Information on most Qt for Embedded Linux Environmental Variables:

• Qt for Embedded Linux Environment Variables

In addition to the Qt for Embedded Linux specific environment variables mentioned above the following standard variables may be required:

                <language>_<country>.<codeset>

Qt Extended

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 Qt Extended IPC.

Qt Extended services are documented in the service documentation. It explains what services are provided by Qt Extended, 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 Qt Extended class (see the ClockService as an example).

Multiple screen support

Qt Extended 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.

Qt Extended 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.

QWS connection timeout

The Qt Extended Server needs to launch processes during startup but it also needs to do it's own initializing which can cause the processes to die. This happens because of a 5 second timeout, QWS clients wait only 5 seconds for the server to respond after connecting to it's socket.

To avoid this problem the server sets the QWS_CONNECTION_TIMEOUT variable to 30, extending the timeout to 30 seconds. This value was chosen after testing on the Greenphone. It can be overriden by setting the variable (see Qt Extended Environment Variables for how to do this).

Server Tasks

The Qt Extended 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 Qt Extended by extending, replacing and removing tasks from the Qt Extended Server application with little or no changes required to the Qt Extended 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 Qt Extended 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 Qt Extended Build System automatically includes source files in this directory into the Qt Extended 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.

Server task plug-ins

This mechanism enables the Qt Extended Server to add new task to the system without having to recompile the server. This is particularly useful for patching of already deployed systems. More information about server task plug-ins can be found in the Server task plug-in tutorial.

Task startup

The startup process of the Qt Extended 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 Qt Extended Server Tasks.

Qt Extended 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, startup and idle groups are preemptively started by Qt Extended.

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 Qt Extended 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 Qt Extended 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
        ...

Some tasks cannot be set as on-demand tasks, but can have their construction delayed until after the user interface is shown. This is accomplished by putting the task in the idle group. Tasks in this group will be started shortly after the UI is displayed, but their construction will be delayed if the user starts interacting with the device (for example, making calls).

Good candidates for this task group are tasks which provide services in the background with no user-visible component. For example, a task providing a Bluetooth dialup service can be placed in the idle group by adding the following to Tasks.cfg:

        ...
        [idle]
        BtDialupServiceTask
        ...

In some cases, launch time of the Qt Extended Server can be improved by placing the All task in the idle group and manually specifying any tasks in startup which must be launched before the user interface is shown.

Communication

Bluetooth

Qt Extended 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 Qt Extended.

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

Qt Extended supports the following Bluetooth connection sockets

• L2CAP
• RFCOMM
• SCO

Qt Extended 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 Software Requirements

Qt Extended 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.

Networking

Qt Extended 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 Qt Extended. 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 Qt Extended, 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.

USB

USB Host

Qt Extended does not provide any specific USB host functionality. Outlined below is information that may be helpful in supporting hotplugged USB devices.

• Ensure drivers are loaded, e.g. via hotplug or udev.
• If necessary notify Qt Extended of the new devices. This can be done via custom udev rules and qcop.

Depending on the connected peripheral device you will may need to provide addition configuration. For example

• Mass storage devices must have a corresponding entry in the Storage.conf configuration file.
• Keyboard and mouse handlers need to be instantiated for new input devices. This can be handled by a Server Task that monitors for new input devices.

USB Peripheral

Qt Extended includes support for selecting the class of USB peripheral device your device appears as when connected to a PC. If your device will only ever operate as a single USB device class you will not need to enable USB Peripheral support in Qt Extended. This support is based on the standard USB Gadget subsystem in Linux 2.6. You may override this functionality to support a 3rd party USB Gadget stack by creating custom USB gadget provider classes. See QUsbGadget, QUsbEthernetGadget, QUsbSerialGadget, QUsbStorageGadget, QUsbManager. If support for additional device classes is added, UsbGadgetTask server task should be extended as well.

For an example implementation of a 3rd party USB Gadget stack see Supporting alternative USB Gadget Stacks.

There is no standard way of querying the connection status of the USB cable. The system integrator should ensure that the Value Space key /Hardware/UsbGadget/cableConnected is set to true when the USB cable is connected to the device and false otherwise. See QValueSpaceObject for details on how to add entries to the Value Space.

Configuration settings for the USB gadget framework is in the Usb.conf configuration file. The default configuration file is set up to use the dummy_hcd virtual USB peripheral controller. The dummy_hcd peripheral controller can be used for testing USB peripheral functionality when real peripheral hardware is not available. To configure Qt Extended to work with your device you will need to

1. Copy the Usb.conf configuration file to the etc/default/Trolltech directory in your device profile.
2. Modify the PeripheralController/Path configuration setting to point to the sysfs path of your USB peripheral controller.
3. Modify the PeripheralController/SupportedGadgets configuration setting to include only those USB device classes that you would like to support on your device. Available options are Ethernet, Storage and Serial.

USB On-the-Go

Qt Extended does not provide any specific USB On-the-Go (OTG) functionality. Outlined below is information that may be helpful in integrating USB OTG support with Qt Extended.

OTG functionality is handled within the Linux kernel. During Host Negotiation Protocol (HNP) the Linux kernel will check the connected device against a whitelist specified in linux/drivers/usb/core/otg_whitelist.h. The whitelist in this file should be modified to include only the devices that have been tested with your device.

If your device assumes A-role (host) you may need to implement some of the suggestions outlined in the USB Host section above.

If your device assumes B-role (peripheral) the USB Peripheral configuration is used.

Dynamic Display Rotation

Qt Extended has support for dynamically changing the display orientation, and can be rotated in 90, 180, 270 degrees.

To use dynamic rotation, an integrator must:

• Enable the Transformed driver in Qt for Embedded Linux: * as build-in driver, update the devices/<device>/configure file:

                            -extra-qtopiacore-config -qt-gfx-transformed

  * as plugin driver, update the devices/<device>/configure file:

                            -extra-qtopiacore-config -plugin-gfx-transformed

• Add

       -dynamic-rotation

  argument to the devices/<device>/configure file to enable rotation and build the RotationManager and rotation settings application.

• Export the appropriate QWS_DISPLAY value before running Qt Extended eg : export QWS_DISPLAY=Transformed:Rot270

Further documentation can be found in Rotation

Document/Content system

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

Document Storage

Documents in Qt Extended 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

Qt Extended is able to handle Digital Rights Management. See Document System: DRM for general details on how the document system handles DRM protected files and refer to DRM Agent Integration if more information on integrating a particular drm agent is required.

Memory management

General information

Qt Extended 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 Qt Extended documentation provides a quick introduction (using valgrind as an example) to how memory related performance issues might be detected.

Out of memory management

Qtopia 4.3 introduces the concept of an Out-Of-Memory (OOM) management. The Qt Extended management system consists of four parts:

1. OOM Data Manager
2. Application Launcher integration
3. Memory Monitor
4. Low Memory Handler

Together these four components are responsible for the avoidance of OOM situation and if it should become necessary for the detection of immanent problems and the subsequent handling of these situations. The Memory Monitor and the Low Memory Handler can be customized by subclassing/replacing certain Qt Extended Server interface/tasks. The various management classes are part of the Qt Extended Server.

Hardware integration

Device indicators

Devices such as Mobile Phones often have indication lights, for things such as charging status, or new email indicators. The QDeviceIndicators class may be used to control an arbitrary number of LED's on the device.

Hardware Abstraction

The Qt Extended Hardware Abstraction is used to access hardware devices from Qt Extended applications. A hardware abstraction provides a standard method of querying available devices and a standard interface for accessing those devices. Currently the Qt Extended Hardware Abstraction defines hardware interfaces for the following devices

• Boot Source
• Keypad Light
• Power Source
• Signal Source
• Vibration

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

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

Boot Source

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

Keypad Light

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

Power Source

Power sources are used to query information about the available power sources. Power sources describe both batteries and wall power sources. For documentation on how to implement a power source see QPowerSourceProvider. Qt Extended provides two methods of accessing power source information. The first method uses the standard Qt Extended Hardware Abstraction API, for details refer to QPowerSource. The second method is a simplified interface provided by QPowerStatus.

Qt Extended supports multiple power sources on a single device. See QPowerSource for details on how to specify a default power sources.

Signal Source

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

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

Vibration

Vibration abstractions are used to alert the user. Typically a device has only a single vibration abstraction. For documentation on how to implement a vibration abstraction see QVibrateAccessoryProvider. For documentation on how to use a vibration abstraction from a Qt Extended application see QVibrateAccessory.

Qt Extended uses the vibrate abstraction to alert the user to a variety of conditions.

Key mappings

The defaultbuttons.conf file provides integrators a way to map the devices keypad to certain actions, map out characters to be generated and specify details for the UI. The relevant sections:

Power Management

Qt Extended includes support for managing a device's power states. This feature can be used to decrease the power consumption of a device, and extend battery life, when the user is not interacting with it. The system supports multiple levels of power saving, transitioning between each power saving level after a period of user inactivity.

Within the Qt Extended Server QtopiaPowerManager defines the generic power management interface. This interface must be implemented if power management functionality is required. Qt Extended includes a default implementation that supports three power saving levels:

• dim backlight
• backlight off
• suspend device

See PhonePowerManager for details.

Additional power saving levels can be defined by subclassing either PhonePowerManager or QtopiaPowerManager.

Applications can influence the minimum power saving level that the system will enter with the QtopiaApplication::setPowerConstraint() function. For example a video player would use this function to temporarily disable all power management settings. An audio player would use this function to temporarily disable suspending the device, but still allowing the display to be turned off.

Finer control of the Qt Extended power manager is provided by the QtopiaPowerManager service.

The suspend state is typically the lowest power state that a device can enter while still being on. Transitioning into and out of the suspended state generally requires additional set up and restore tasks. These are implemented as server tasks that implement the SystemSuspendHandler interface. The SystemSuspend server task coordinates suspending and resuming the system to and from its lowest power saving state.

Input methods

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

The front-end implementation for IM support is provided via plug-ins (see Input Methods: Class Overview for more details). By default Qt Extended provides a few reference implementations which demonstrate certain IM capabilities:

As stated earlier, the Qt Extended input methods are reference implementations. Their purpose is to demonstrate and test certain capabilities of the Qt Extended 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

Qt Extended can be translated into several languages. By default, Qt Extended 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 Qt Extended can handle the various layout and space issues caused by most languages.

The Qt Extended Internationalization guide explains the fundamental details of the Qt Extended 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. For more details please contact qt-sales@nokia.com.

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

Media integration

The Qt Extended media system is an engines/plug-in based client server architecture which allows the implementation of user frontend's without particular knownledge of the backend. The Qt Extended Multimedia overview provide an introduction into the frameworks architecture and demonstrates common integration tasks by means of tutorials.

Audio States

Audio functionality can change depending on the context. For example when a headset is plugged in. QAudioStatePlugin provides the ability to override the defaults for a particular device.

Messaging

Qt Extended provides Messaging functionality that enables Qt Extended devices to support SMS, MMS and electronic mail messaging. The Messaging Documention provides the main entry page into the messaging parts of Qt Extended.

Multimedia Messaging

Qt Extended includes MMS functionality in the Messages client but does not include a WAP stack implementation that would be needed to send or receive such messages.

Multimedia Messaging Viewer (SMIL)

Qt Extended includes a SMIL 2.0 parser/viewer in directory: $QPEDIR/src/libraries/qtopiasmil/.

This SMIL viewer is intended for use with an MMS viewer and is currently only used by the Messages application.

The SMIL viewer:

• covers a subset of SMIL 2.0 basic
• can be modified to implement SMIL 2.0 basic language specification
• implements functionality as required by: MMS Conformance Document 1.2 Candidate Version 29-September-2003 (OMA-MMS-CONF-v1_2-20030929-C).

WAP Stack Integration

Qt Extended does not include a WAP stack with the MMS client. Instead, an interface is provided which allows any WAP stack to be integrated. The MmsComms class must be subclassed and the virtual functions implemented and signals emitted as appropriate.

The MmsCommsHttp class provides a sample implementation using HTTP over TCP/IP.

Refer to: $QPEDIR/src/applications/qtmail/mmscomms_http.cpp and $QPEDIR/src/applications/qtmail/mmscomms_http.h.

To choose an alternate WAP stack connection method:

1. to choose the MmsComms implementation:
   • modify the MmsClient::setAccount function in $QPEDIR/src/applications/qtmail/mmsclient.cpp
2. to list the source/header files for the Mmscomms implementation:
   • modify MMSCOMMS_HEADERS and MSCOMMS_SOURCES in $QPEDIR/src/applications/qtmail/qtmail.pri

AMR Encoder

The AMR encoder included with Qt Extended is a reference implementation only. It is recommended that an encoder optimized for the target platform be installed. The media recorder plug-in interface provides a convenient method of integrating the codec.

SXE integration

Qt Extended sandbox based security mechanism called the Safe Execution Environment (SXE) Safe Execution Environment, which supports the download and secure execution of 3rd party native applications.

The SXE consists of several major components working together in tandem.

• Package Manager
• Application level policy
• OS level policy using LIDS
• Security Monitor(aka SxeMonitor)

Telephony

Qt Extended provides Telephony support that enables Qt Extended devices to use GSM and Voice over IP (VoIP) functionality. The Telephony Documentation provides the main entry page into the telephony components of Qt Extended.

Modem Integration

Qt Extendedsupports vendor-specific modem commands through the use of plug-ins to the Qt Extended 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"

VoIP integration

The main Qt Extended telephony components are based on GSM/UMTS networks. However many other communication bearers require similar if not even identicial infrastructure support. Therefore new bearers can easily be integrated into the Qt Extended telephony API. In fact the higher API layers are almost agnostic in regards to the actual communication protocol.

One additional communication bearer that is directly supported by Qt Extended is Voice over IP (VoIP). The VoIP Integration describes the main VoIP components used by the Qt Extended reference implementation and demonstrates how they interact with the Qt Extended phone user interface. The reference implementation uses the open source library libdissipate2 which provides simple SIP functionality.

Note: Currently due to licensing inconsistencies libdissipate2 cannot be shipped with Qt Extended.

If the hardware platform already features its own SIP implementation the Qt Extended VoIP implementation can easily be replaced as described by the Qt Extended general VoIP Integration guide. It describes the necessary steps to integrate new SIP clients as well as new telephony services in general.

Web Browser integration

Any web browser integrated with Qt Extended should respond to the WebAccess service. The web browser should invoke Qt Extended services to fullfil external application needs, including:

1. Messages::composeMessage(QMailMessage) - for "mailto:" URLs.
2. Dialer::dial(QString,QString) - for "tel:" URLs.
3. PlayMedia::openURL(QString) - for media URLs not handled the browser.

The QSettings value "Trolltech/WebAccess/Locations/Home" is the user's globally set Home page.

Other miscellaneous steps

Qt Extended Environment variables

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

• Qt for Embedded Linux Environment Variables
• Environment Settings to Run Qt Extended

In addition to Qt for Embedded Linux's environment variables Qt Extended uses the following variables to further specify its behavior:

Qt Extended customizations

First Use

After the first startup, the "First Use" tool is launched. It presents a user interface allowing the user to set initial settings for Qt Extended. The following settings can be set:

• Calibration of the touchscreen
• Language Selection
• TimeZone Selection
• Time and Date Format Selection

Depending on the devices capabilities some of the above settings may not be necessary. In order to accommodate for such cases the tool can be customized by modifying the [Startup] group in the file $QPEDIR/etc/default/Trolltech/qpe.conf The following fields can be edited:

• FirstUse: if true, the First Use tool will be displayed after the startup.
• NeedTimeZone: if true, the time zone selection dialog will be enabled. This dialog is not required if the device automatically detects the current time and time zone.
• NeedCalibrate: if true, the touchscreen calibration tool will be enabled. The calibration will be enforced if /etc/pointercal is empty or wrong.

UI customization

Styles

Qt Extended uses the Qt Style framework to define the look and feel of the common widgets used by Qt Extended applications. Qt Extended provides a default style, Qt Extended, which is implemented in QPhoneStyle and QtopiaStyle. The look and feel of Qt Extended 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 Qt Extended, styles are linked to themes, which the user can select in the Appearance Settings application. The following segment of $QPEDIR/etc/themes/qtopia.conf demonstrates how a widget style is associated with a given theme. In this example the Qt Extended style is used when the user selects the Qt Extended theme.

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

In addition the Qt Extended applications follow a style guide which describes the guide lines for user interfaces. The focus is on consistency.

Theming

Integrators can extend the Qt Extended look and feel by customizing the theme. Several themes are shipped with Qt Extended (see QPEDIR/etc/themes for details) and may serve as examples.

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

Server widgets

The 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 UML diagram shows a selection of server widgets and how they are connected to 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 Qt Extended server must be restarted in order to update the user interface. Besides the default implementations Qt Extended 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.

Running Qt Extended

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

In order to test Qt Extended functionality Qt Extended 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 Qt for Embedded Linux documentation also contains a Running Qt for Embedded Linux Applications help which shows the qws command line supported by Qt for Embedded Linux.

Building and running outside of Qt Extended build tree

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

• Compile and Run the Example Application
• Tutorial: Creating a New Application

Debugging Qt Extended (local and remote)

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

In some situation it may be necessary to debug Qt Extended 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 Qt Extended. This situation can be solved by using gdb's remote debugging facilities. The Qt Extended Remote Debugging guide provides a quick demonstration how Qt Extended may be remotely debugged.

See also QDeviceIndicators and QValueSpaceItem.