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

Integration guide


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.


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.

Kernel FeatureQt Extended Dependency
System V IPC (Shared Memory and Semaphores)Qt Extended uses System V IPC (shared memory and semaphores) to share window regions between client applications and the server. For full details on integrating this feature see Linux Framebuffer and Display Management.

The Linux kernel must be configured with the following option to enable System V IPC.

Unix-domain SocketsQt Extended uses Unix-domain Sockets for Inter-process Communication (IPC) between client applications and the server. For details on the IPC mechanism used in Qt Extended See Client/Server Communication and Qt Extended IPC Layer.

The Linux kernel must be configured with the following options to enable Unix-domain Sockets

Linux FramebufferQt Extended uses the Linux Framebuffer to draw onto the screen of the device. For full details on integrating this feature see Linux Framebuffer and Display Management.

The Linux kernel must be configured with the following options to enable access to the Framebuffer device

  • Device specific Framebuffer driver
proc FilesystemThe proc virtual filesystem provides an interface for querying the status of and controlling certain aspect of the running system. Qt Extended uses this filesystem for managing processes, authenticating IPC communication when SXE is enabled, monitoring memory use, querying mounted filesystems, managing network interfaces, power management and querying general system information.

The proc filesystem must be mounted on /proc during start-up.

The Linux kernel must be configured with the following option to enable access to the proc filesystem.


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.

Optional Qt Extended ComponentDescription
AT ModemThe telephony stack includes support for AT modems. These devices are typically connected via a serial interface. If the modem is connected via a different interface, you will need to enable support for that interface. For full details on modem integration see Modem Integration.

The Linux kernel must be configured with the following options to enable access to an AT modem connected via a serial interface

  • Device specific serial driver
  • Device specific modem driver
BluetoothQt Extended supports Bluetooth communication devices via the BlueZ API. For full details on Bluetooth integration see Bluetooth.

The Linux kernel must be configured with the following options to enable Bluetooth support

  • Device specific Bluetooth driver

Depending on how the Bluetooth device is connected other configuration options may be required. For example, to support a Bluetooth device connected via a serial interface the following addition configuration options will need to be enabled

  • Device specific serial driver
Internet, VoIPQt Extended can use a variety of network interfaces to provide Internet connectivity. For full details on integrating Internet connectivity see Networking. As VoIP routes calls over the Internet, it has the same kernel configuration requirements as Internet connectivity.

The Linux kernel must be configured with the following options to enable support for Internet connectivity

  • Device specific network interface drivers

For WiFi support the following additional configuration options will also need to be enabled

  • Device specific WiFi driver

Qt Extended supports Internet connectivity over GPRS. This feature requires the following additional configuration options to be enabled


Qt Extended can connect to OpenVPN based Virtual Private Networks (VPNs). This feature requires the following kernel configuration option


Qt Extended can share it's Internet connection with other devices. This feature requires the following kernel configuration option

SXEQt Extended provides a Safe Execution Environment (SXE) for running third party applications. The SXE environment currently uses the LIDS patch set to provide kernel level Mandatory Access Controls (MACs). For full details on SXE integration see SXE integration.

The Linux kernel must be patched and configured with the following options to fully enable SXE functionality

CameraThe Camera application uses the video4linux API to access the device's camera.

The Linux kernel must be configured with the following options to enable camera support

  • Device specific camera driver

The camera device used by the Camera application is configured in the custom.h file as V4L_VIDEO_DEVICE.

InfraredQt Extended supports Infrared devices.

The Linux kernel must be configured with the following options to enable Infrared support

  • Device specific infrared driver
Multimedia CardsQt Extended supports multimedia cards. The most common filesystems used on these devices are FAT or FAT32, although these are not the only possibility.

For maximum compatibility it is recommended that the Linux kernel be configured with the following options to enable support for multimedia cards

  • Device specific multimedia card driver
Audio Playback and RecordingQt Extended Extended can be configured to process sound either with or without the Media Server integration. For details on Media Server integration is see Media integration.

The Linux kernel provides two sets of sound drivers, the Open Sound System (OSS) and the Advanced Linux Sound Architecture (ALSA). Qt Extended supports both sets of drivers when built without Media Server integration. Generally only one set of drivers will be used at a time. Check the documentation on the Media Server for it's requirements if Media Server integration is being used.

The Linux kernel must be configured with the following options to enable OSS based audio playback and recording

  • Device specific OSS audio drivers

Alternatively the Linux kernel must be configured with the following options to enable ALSA based audio playback and recording

  • Device specific ALSA audio drivers
USB GadgetsQt Extended can manage what class of USB device your device appears as when connected to a PC. For details on USB integration see USB.

The Linux kernel must be configured with the following options to enable USB Gadget support

  • Device specific USB peripheral controller drivers

and one or more of the following gadget drivers


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.

Useful Development OptionsDescription
NFS Filesystem SupportEnabling NFS support allows you to mount remote NFS shares onto your device. NFS shares can be used as an alternative method of accessing the Qt Extended image on your device, instead of reflashing the device.

Note: The runtime performance of Qt Extended may be degraded when running over NFS. This is caused by delays in transferring data over the network interface.

To enable NFS support configure the Linux kernel with the following options enabled


To run Qt Extended over NFS you will first need to export the Qt Extended image directory to your device. Please consult the documentation for your development system on how to achieve this. On a Linux system, the following command can be used to export the Qt Extended image directory to your device. You should replace $DEVICE_ADDRESS and $PATH_TO_IMAGE with the IP address of your device and the absolute path to the Qt Extended image directory you want to export.

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

To mount the exported Qt Extended image on your device run the following command on your device, replacing $SERVER_ADDRESS with the IP address of the development system that is exporting the Qt Extended image and $PATH_TO_IMAGE with the same absolute path you used above. If you have configured Qt Extended with a different runtime prefix you will need to replace /opt/Qt Extended with that prefix.

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

Finally you can run Qt Extended over NFS by setting up the environment variables as you normally would and running /opt/Qtopia/bin/qpe. For more details on running Qt Extended via NFS see Running Qt Extended using NFS

The Qt Extended root file system

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

/bincommand binaries
/bootbootloader files
/devdevice files
/etcsystem configuration files
/libsystem libraries and kernel modules
/mediamount point for removable media
/mntmount point for mounting temporary file systems
/optadd-on software packages
/procstub directory for kernel processes.
/sbinsystem binary commands
/tmptemporary files
/usrsecondary hierarchy
/varvariable data

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.

/binQt Extended binaries.
/etcQt Extended system configuration files.
/helpQt Extended html help documentation.
/i18nQt Extended translation files.
/libQt Extended library files.
/picsQt Extended images and icons.
/pluginsQt Extended plugins
/qt_pluginsQt for Embedded Linux plugins.
/servicesQt Extended service task directory
/soundsQt Extended sound files.

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.

File System TypeComments
ext2general read/write. no journaling. not recommended for NAND devices.
ext3general read/write. journalled ext2. not recommended for NAND devices.
cramfsread only compressed
squashfsread only compressed. requires kernel patches. See squashfs web site
jffs2read/write, compressed, journalled, NAND device only.
yaffsread/write, compressed, journalled, NAND device only. kernel patches required. See yaffs web site
ramfs or tmpfsread/write, dynamic size allocation (in RAM), for temporary files.

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.

commandQt Extended ComponentsBusybox configNotes
ashStartup/scriptShells CONFIG_ASH, need bash symlink
hwclockqalarmserverLinux System Utilities CONFIG_HWCLOCK
logreadLogging viewerSystem Logging Utilities CONFIG_LOGREAD
syslogdLogging viewerSystem Logging Utilities CONFIG_SYSLOGD
echooommanagerShells CONFIG_ASH_BUILTIN_ECHOQt Extended version 4.3
cpsystemtimeCoreutils CONFIG_CP
rmpackagemanager, obexservicemanagerCoreutils CONFIG_RM
mkdirobexservicemanagerCoreutils CONFIG_MKDIR
modprobeUSB peripheral supportLinux Module Utilities CONFIG_MODPROBEQt Extended version 4.4
rmmodUSB peripheral supportLinux Modules Utilities CONFIG_RMMODQt Extended version 4.4

Minimal Linux Configuration

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

PackageMinimum VersionDescriptionNotes
binutilsBase system binary utilities
glibcEssential C library
glibc-linuxthreadsMulti-threading capability
linux kernel2.4.19 (recommend 2.6.20)Linux kernel
busybox1.2.1system commands. See Busybox
e2fsprogsfile system tools
libasoundAlsa sound support
patchpatching toolcompile time requirement only
perlcompile time requirement only
libsvgparser for SVG content
libxsltXSLT C library

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.

Qt Extended ComponentPackage
  • D-Bus
  • Bluez-libs
  • Bluez-utils
  • Bluez-firmware
  • Bluez-hcidump
  • OpenObex
  • expat
  • v4l (Video 4 Linux)
  • D-Bus
Image Viewer
  • ungif
  • libpng
  • libjpeg
Media Player
  • Helix
  • GStreamer (libgstreamer)
  • ALSA (libasound)
  • LIDS
  • App Armor
  • syslog-ng
Telephony (Googletalk)
  • Telepathy
  • Telepathy-gabble
  • tslib
Wireless Networking
  • wireless-tools
  • ppp
  • wpa_supplicant

These packages may be installed on the target device.

PackageMinimum VersionDescriptionQt Extended ComponentNotes
ALSAAdvanced Linux Sound ArchitectureMedia Player
D-Bus1.0.2Message Bus system / Inter process communication D-Busdbus
DHCPDHCP serverNetworking
HelixHelix Multimedia EngineMedia PlayerHelix Integration
OpenObexObject Exchange protocolbluetooth, Irda
PPPPoint to Point ProtocolNetworking
TSLib1.0Touchscreen LibraryTSLib pluginMouse Pointer Handling
WAPIntegrator-provided componentMMS
bluez-firmware1.2bluez firmware utilitiesBluetooth
bluez-libs3.9bluez libraryBluetooth
bluez-utils3.9bluez utilitiesBluetooth
dosfstoolsutilities for DOS file systems
dropbearssh service and client
expatXML ParserBluetooth
e2fsprogsUtilities for ext2 file systems
LIDS1.2.2Linux Intrusion Detection SystemSafe Execution Environment - SXE
libungifGIF library
pcmciaPCMCIA utilities
sqliteSQLite databasePIM, MessagingProvided by Qt for Embedded Linux
sysvinitsysvinit project System initializationbusybox also provides a simple init without runlevels
udevKernel device managerUdev web site
v4lVideo For Linuxcamera
wireless_tools0.28wireless utilitieswireless networking Wireless Tools
wpa_supplicant0.4.9WPA\WPA2 Authenticationwireless networking
zoneinfoTime Zone DataWorldTime, Date/TimeTime on an Embedded Device

Other tools

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

PackageProvidesQt Extended ComponentNotes
libelfLinux file system tools
dosfstoolsDOS file system tools
libungifgif library
zlibFile Compression UtilityPackage ManagerProvided by Qt for Embedded Linux
libjpegJPEG image libraryProvided by Qt for Embedded Linux
OpenSSHOpenSSHdeveloper tool
telnetTelnet Terminal Servicesdeveloper tool
ftpFile Transfer Protocoldeveloper tool
tarArchive Utilitydeveloper tool
freetypeFont LibraryProvided by Qt for Embedded Linux Fonts
libmngPNG animation libraryProvided by Qt for Embedded Linux
libpngProvided by Qt for Embedded Linux
md5Provided by Qt for Embedded Linux
gdb serverRemote debugging utilityRemote Debugging
prelinkBinary optimizationPrelink Tutorial

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.

To build a cross toolchain yourself:

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.

Build typedescription
NormalEvery application is compiled into a binary that is executed by the Qt Extended Server.
QuicklauncherThis is the default mode for Qt Extended. It improves the application startup time by using a stub application to preload libraries and construct classes that are common to all Qt Extended applications in the background before an application is started. A quicklaunch enabled application is built as a plugin that is loaded by the stub application.
Singleexec ModeThe Qt Extended Server and all applications are linked together in a single large binary. A single binary is smaller in size than many separate application binaries and launch times are decreased because libraries are statically linked together with applications. The disadvantages are reduced flexibility when updating libraries and applications on already deployed devices, and the inability of user-installed applications to dynamically link against the Qt Extended libraries.

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.

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:




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 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:

QT_NO_STLstandard template library compatibility
QT_NO_COLORDIALOGremoves QColorDialog
QT_NO_ERRORMESSAGEremoves QErrorMessage
QT_NO_FILEDIALOGremoves QFileDialog
QT_NO_INPUTDIALOGremoves QInputDialog
QT_NO_PROGRESSDIALOGremoves QProgressDialog
QT_NO_TABDIALOGremoves Q3TabDialog
QT_NO_IMAGEFORMAT_PPMremoves support for PPM images
QT_NO_IMAGE_HEURISTIC_MASKremoves support for 1-bpp heuristic mask (see QImage::createHeuristicMask() )
QT_NO_IMAGE_TEXTremoves support for image file text strings
QT_NO_BIG_CODECSno support for big codecs e.g., CJK (should be added via plug-ins when necessary)
QT_NO_CODECSno support for non-unicode text conversions
QT_NO_DIRMODELno data model support for the local filesystem (see QDirModel)
QT_NO_CURSORno mouse cursor support (see QCursor)
QT_NO_DRAGANDDROPremoves drag and drop mechanisms
QT_NO_EFFECTSremoves special widget effects (e.g., fading and scrolling)
QT_NO_SESSIONMANAGERremoves support for session management
QT_NO_NETWORKPROXYremoves network layer proxy support (see QNetworkProxy)
QT_NO_SOCKS5removes SOCKS v5 network proxy support (depends on QT_NO_NETWORKPROXY)
QT_NO_COLORNAMESremoves colar names such as "red", which are used by QColor
QT_NO_QWS_ALPHA_CURSORremoves support for alpha-blended cursors
QT_NO_QWS_CURSORremoves support for visible cursors (depends on QT_NO_CURSOR)
QT_NO_QWS_DECORATION_WINDOWSno support for "Windows" style decorations of top level windows
QT_NO_QWS_MOUSEremoves mouse driver support
QT_NO_QWS_MOUSE_AUTOremoves support for auto-detected mouse drivers
QT_NO_QWS_MOUSE_MANUALremoves support for non-autodetected mouse drivers
QT_NO_STYLE_MOTIFremoves support for Motif look and feel (see QMotifStyle)
QT_NO_STYLE_CDEremoves support for CDE look and feel (depends in QT_NO_STYLE_MOTIF)
QT_NO_STYLE_PLASTIQUEremoves support for widget style similar to the Plastik style available in KDE (see QPlastiqueStyle)
QT_NO_STYLE_WINDOWSXPremoves support for Microsoft WindowsXP look and feel (see QWindowsXPStyle)
QT_NO_CONTEXTMENUremoves support for pop-up menus on right mouse click
QT_NO_DOCKWIDGETremoves support for docking widgets inside a QMainWindow or floated as a top-level window (see QDockWidget)
QT_NO_WORKSPACEremoves QWorkSpace
QT_NO_SPLITTERremoves QSplitter
QT_NO_SIZEGRIPremoves QSizeGrip
QT_NO_DIALremoves QDial
QT_NO_SYNTAXHIGHLIGHTERremoves QSyntaxHighlighter
QT_NO_STATUSBARremoves QStatusBar
QT_NO_STATUSTIPremoves support for status tip functionality and events
QT_NO_TOOLBOXremoves QToolBox
QT_NO_TOOLTIPremoves QToolTip


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.


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.

Keyboard driverSourceDescription
tty$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdtty_qws.cppStandard tty keyboard
usb$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdusb_qws.cppStandard USB keyboard
sl5000$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdsl5000_qws.cppKeyboard specific to the Sharp Zaurus 5500
yopy$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdyopy_qws.cppKeyboard specific to the Yopy
vr41xx$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdvr41xx_qws.cppKeyboard specific for the NEC Vr41XX device.
qvfb$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdvfb_qws.cppKeyboard specific for Qvfb

More information about Keyboard Plugins:

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.

pc$QPEDIR/qtopiacore/qt/src/gui/embedded/qmousepc_qws.cppStandard pc mouse
bus$QPEDIR/qtopiacore/qt/src/gui/embedded/qmousebus_qws.cppStandard bus mouse
linuxtp$QPEDIR/qtopiacore/qt/src/gui/embedded/qmouselinuxtp_qws.cppStandard Linux Touchscreen
yopy$QPEDIR/qtopiacore/qt/src/gui/embedded/qmouseyopy_qws.cppYopy device
vr41xx$QPEDIR/qtopiacore/qt/src/gui/embedded/qmousevr41xx_qws.cppvr41 device
tslib$QPEDIR/qtopiacore/qt/src/gui/embedded/qmousetslib_qws.cppUse libts for touchscreen events.
qvfb$QPEDIR/qtopiacore/qt/src/gui/embedded/qmousevfb_qws.cppMouse pointer for QVFb

More information about Mouse Pointer plug-ins:

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:

Environment Variables

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

    export QWS_DISPLAY=LinuxFb:mmWidth34:mmHeight44:0

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


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:

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

LANGSpecifies the language and codeset to be used by Qt for Embedded Linux. If problems with missing or wrong text codecs are occuring this variable should be checked. The format for this variable is:

A valid example would be en_GB.utf8 (British English w/ UTF8 codeset). The codeset must always be set to utf8 for Qt Extended. Refer to the Internationalization section for more details on language and translation specifc information.

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

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

        #include "exampleservertask.h"


        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


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:



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:


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.



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

Qt Extended includes implementations of the following Bluetooth services.

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.


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

network typerelated plug-in
Local Area Network (LAN)QPEDIR/src/plugins/network/lan
Wireless Local Area Network (WLAN)QPEDIR/src/plugins/network/lan
Dial-up via analog modem, GPRS or UMTSQPEDIR/src/plugins/network/dialing
Bluetooth Dial-up Networking (DUN)QPEDIR/src/plugins/network/bluetooth
Bluetooth Personal Area Networking (PAN)planned for future relases of Qt Extended

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 Host

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

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

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:

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.

  • MountPoints
  • DocumentsDefault
  • ApplicationsDefault
  • Names all the mount points available.
  • Names which MountPoint Qt Extended should keep user Documents by default.
  • Names which MountPoint Qt Extended should install Application packages to by default.
  • MountPoint
  • Path
  • Names which MountPoint Qt Extended should install user Packages to.
  • path to installed directory from Applications mount point.
  • Name[]
  • Documents
  • Applications
  • String name for home.
  • Whether Qt Extended should scan HOME for Documents.
  • Whether Qt Extended should scan HOME for applications.
  • Name[]
  • Path
  • Removable
  • Applications
  • Documents
  • ContentDatabase
  • User string
  • Path to device node of storage device.
  • Whether MountPoint is removable media.
  • Whether Qt Extended should scan this MountPoint for documents.
  • Whether Qt Extended should scan this MountPoint for applications.
  • Whether Qt Extended should store content in a database on the MountPoint or in the system database.

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

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 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:

SectionDetailsPossible settings.
  • File=
  • Context=
[Menu]Specifies details for the main 'grid'
  • Rows=<number>
  • Columns=<number>
  • Map=<characters(123456789*0#)> - Maps grid to keypad shortcuts.
  • Default=<number> - Which in map should Qt Extended default to.
  • <number (from Map)>=<apps.desktop> - Specifies an application desktop file to handle.
  • Animator=Bounce
[SoftKeys]Provides assignments for Qt Extended softkeys at the botton of the screen
  • Count=<number> - number of buttons to display
  • KeyX=<Qt Key> - assign Qt Keycode to this button. Where X is a number starting with 0. Possible codes: Context1, Select, Back.
[SystemButtons]Provides Qt keycode assignments for physical buttons.
  • Count=<number> - number of physical buttons
  • KeyX=<Qt keycode> - assign Qt Keycode to this button. Where X is a number starting with 0. Possible codes: Context1, Select, Back, Call, Hangup
[TextButtons]Maps physical buttons to hold and tab actions.
  • Buttons=<characters(123456789*0#)> - which buttons to map
  • HoldX=<'Y> - Specifies hold actions, where X is button specifier and Y is a character to send, ie. 0-9,*,# or mode|shift|symbol
  • TapX=<"string"> - Specifies tap actions, where X is button specifier, and string is characters, i.e "wxyz9"
  • TapX[]=<'string> - Specifies tap action, where X is button specifier and string is characters
  • Buttons=<button specifier>
  • TapX=<characters> - Specifies tap action, where X is button specifier
  • HoldX=<characters> - Specifies hold actions, where X is buttons specifier
[Device]Provides device information.PrimaryInput=(Keypad|Touchscreen) - Tells Qt Extended to use keypad or touchscreen.
[Button]Tells Qt Extended number of physical buttons to provide mapping for.Count=<number>
[ButtonX]Specifies a physical button and mapping its actions. X being a number starting at 0 to the number specified in [Button]/Count.
  • Name=<string>
  • Key=<Qt Key>, i.e. F7
  • HeldActionService=<Service>
  • HeldActionMessage=<QCop message>
  • PressedActionService=<Service>
  • PressedActionMessage=<QCop message>
[Environment]Specifies environmental configuration.QWS_DISPLAY=<gfx driver><:driver specific options><:display number>
[InputMethods]Specifies default InputMethod to be usedDefaultIM=<string:Identifier>

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:

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:

Input methodsourceDescription
Phone keys$QPEDIR/src/3rdparty/plugins/inputmethods/pkimThe Phone key input method is intended for use with keypad buttons with the common 0-9, # and * buttons. It uses a dictionary lookup system to guess the most likely input, as well as a multitap system.
FullScreen Handwriting$QPEDIR/src/3rdparty/plugins/inputmethods/pkim and $QPEDIR/src/libraries/handwritingThis IM can be used when using a pointing device such as a touchscreen or mouse. It composes characters out of multiple strokes. It uses the same dictionary as the Phone keys
Keyboard$QPEDIR/src/plugins/inputmethods/keyboardThe Keyboard input method demonstrates widget based pop up text input.
Docked Keyboard$QPEDIR/src/plugins/inputmethods/dockedkeyboardThe Docked Keyboard provides widget based input methods not unlike the Keyboard. However the difference is the presentation of the input widget. Using the same popup widget as the normal keyboard, this input method docks itself along side other widgets on the display (instead of on top of them), reducing the available display space for normal widgets.

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.


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:

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.


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:

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:
  2. to list the source/header files for the Mmscomms implementation:
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.


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

Device-specific codeQt Extended expects device-specific code to be implemented by the system integrator. See <custom.h> for the required and available functions/macros.
Setting time on a deviceQt Extended requires /sbin/hwclock to update the system time and zone information for time conversion purposes.
Removable Media and DevicesQt Extended must be notified when a removable media or a PCMCIA card is connected to the device. Note that the StabMonitor server task can provide such notifications for PCMCIA cards (for details refer to the class documentation).

Qt Extended Environment variables

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

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

QTOPIA_PHONE_DEVICESpecifies the phone device and speed. Qt Extended will use a default device if this variable is not set. The default value is set in custom.h.

See also Modem Integration and Using a phone device

QTOPIA_PHONEIf this Variable is set to Dummy Qt Extended uses a telephony dummy implementation which does not require a real serial device. However its capabilities are limited as well.
QTOPIA_PHONE_MUXIf this variable is set to no disables multiplexing in Qt Extended.

See also GSM Modem Integration

QTOPIA_PHONE_VENDORSpecifies the multiplexer plug-in that Qt Extended uses.

See also Multiplexer plug-in tutorial

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:

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:

UI customization


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.

        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.


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.

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.

"Server Widgets UML"

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

Abstract widgetDescription
QAbstractMessageBoxThis abstract server widget provides an interface for message boxes. This allows the easy replacement of message boxes. The PhoneMessageBox class implements the Qt Extended default message box.
QAbstractServerInterfaceThis is the main UI widget instantiated by the Qt Extended Server that is common to all Qt Extended editions. The PhoneLauncher class implements this interface for the Qt Extended. The remaining abstract server widgets are based on the PhoneLauncher as it is the PhoneLauncher class that creates and connects the remaining server widgets.
QAbstractBrowserScreenThis abstract server widget is Qt Extended specific and provides the main application browser. Users use it to navigate through and launch applications. The PhoneBrowserScreen class implements the default behaviour.
QAbstractCallHistoryThis abstract server widget is Qt Extended specific and provides the main call history view. It shows outgoing, incoming and missed calls and their details. In addition it provides shortcuts to store new contact details, send messages or call a number. The default call history is implemented by PhoneCallHistory.
QAbstractCallScreenThis abstract server widget is Qt Extended specific and provides the main call screen. The call screen is shown during calls. It displays all active active calls, enables call management features such as merging and holding of calls and informs the user about call parameter such as length or contact details.
QAbstractContextLabelThis abstract server widget provides the interface for the soft key menubar. It is docked to the bottom of the screen and shows the menu and current key shortcuts. Applications cannot access or display anything in this area. The BaseContextLabel extends the widget interface by adding button related behaviour. This may be of interest if the default context label (ThemdedContextLabel) UI is already too specific.
QAbstractDialerScreenThis abstract server widget is Qt Extendedspecific and provides the dialer screen. Qt Extended provides two implementation for this server widget (PhoneQuickDialerScreen and PhoneTouchDialerScreen). The decision which class is instanciated depends on whether Qt Extended is used on a touchscreen (PhoneTouchDialerScreen) or a keypad phone (PhoneQuickDialerScreen) .
QAbstractHeaderThis abstract server widget provides the interface for the title bar. The title bar is docked to the top of the screen. Applications cannot access or display anthing in this area. The default implementation is provided by PhoneHeader.
QAbstractHomeScreenThis abstract server widget provides the main idle screen interface. It is the first widget shown to the user. It can displays status information such as the number of missed calls or the name of the current network.
QAbstractSecondaryDisplayThis abstract server widget provides the secondary screen display. A secondary display is used by e.g., Clamshell phones which provide a small status display on the outside. The ThemedSecondaryDisplay class implements the default widget for Qt Extended.
QAbstractTaskManagerThis abstract server widget provides the interface for the task manager. The task manager shows the list of running applications, enables multitasking and allows the user to kill an application if that should be required.

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:

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.

Copyright © 2009 Trolltech Trademarks
Qt Extended 4.4.3