![]() Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |
![]() |
This document sets out the implementation requirements for specific devices and makes recommendations for the optimal installation of Qtopia on a handheld device. How you install Qtopia on a given device will be determined by the functionality of that device.
See Also Qtopia - Customizing Qtopia for a Device: Keys and Buttons.
In some cases it is desirable to have a customized launcher interface that better suits the intended application of the target device. Qtopia supports custom laucher user interfaces via the ServerInterface. This interface provides all of the infrastructure necessary to implement a launcher while maintaining compatibility with the Qtopia application and document models.
The launcher user interface is part of the Qtopia server ($QPEDIR/src/server) which provides services such as syncing and filesystem management.
The first step when writing a user interface is to implement a class derived from ServerInterface. This interface provides the functionality necessary to show the available applications and documents available on a Qtopia device.
The createGUI() and destroyGUI() functions must be implemented to create and show the launcher and any other user interface components.
Most of the functions provided by the ServerInterface are to manage adding and removing applications and documents as necessary. The ServerInterface documentation describes each one in detail.
The default Qtopia launcher is implemented by the Launcher class.
In addition to the launcher itself, it is usually necessary to provide some system components, such as input methods and status display.
There are several classes in the default Qtopia user interface that may be reused in a custom interface. Most user interfaces will make use of some of these classes to ensure a useable system:
An interface providing these components will support most of the default Qtopia launcher functionality.
The Qtopia libraries also assume that QPE/Taskbar QCOP channel is available and supports the following functions:
The default Qtopia launcher uses the TaskBar class to encapsulate the above functionality.
When planning to customize and install Qtopia on a specific device, there are a number of factors that must be taken into consideration. The following is a list of typical factors:
All of the changes required to add these device specific customizations are centralized in Qtopia and involve a small number of files (described below). This document should make it easy for OEMs and system integrators to understand how to make Qtopia aware of any special hardware that a device might have.
During configure, the -platform option is used to select which custom-<platform-spec>.h file will be used when compiling Qtopia. The following macros can be defined or undefined in a custom.h file to customize Qtopia for the specific hardware. The associated custom-<platform-spec>.cpp file will be compiled and linked to provide any custom functions that are required.
In addition to the above macros and defines, the following three functions must be implemented in the custom-<platform-spec>.cpp file.
For reference implementations of the device specific code, the existing custom-*.* files found in src/libraries/qtopia/ may be of guidance.
There are a number of applications/features supplied with Qtopia that are not intended to be shipped with production devices:
The following applications are unsupported 3rd party applications/ports intended purely to demonstrate the flexibility of Qtopia:
If Qtopia crashes twice in quick succession "Safe Mode" will be entered and no plugins will be loaded in case the crash was caused by a misbehaving plugin. In some cases there are plugins that are required for correct operation of the device. These plugins can be specified in the .directory file in $QPEDIR/plugins/<type>/.directory. For example, if the simple8 text codec is always required:
[Desktop Entry] Name=Text Codecs Comment=Provides support for various international languages. Required=simple8 Apply=QPE/System restart()
A number of points should be considered when integrating Qtopia with a device that has power management.
Qtopia's power management is handled by Qt embedded. The QWSServer uses the QWSScreenSaver interface in order to decide what to do. Qtopia provides the screensaver behaviour by extending from QWSScreenSaver. This screensaver (QPEScreenSaver) is implemented in qpeapplication.cpp and provides the following three screensaver levels:
Qtopia will call the platform-specific function qpe_setBrightness(int) in order to adjust the light for the display.
The last level depends on the specific version of Qtopia. The PDA version will use the APM daemon and suspends the execution of Qtopia whereas the phone editon closes open applications and returns to the home screen. For further information please refer to: For PDA Edition and For Phone Edition.
The QWSServer provides the following interface which allows the registration and customization of arbitrary screensavers:
\list \i - void setScreenSaver ( QWSScreenSaver * ) \i - void setScreenSaverIntervals ( int * ms ) \i - void screenSaverActivate ( bool ) \endlist
Qtopia's screensaver can be adjusted by the user via the power management (Light & Power) application.
Qtopia runs the 'apm' command to suspend. The system's AT daemon is used to unsuspend upon RTC alarms. The system's AT daemon is used to write the RTC clock (because on some systems only one process can manipulate the RTC).
The system's "Power" key or the third screensaver level just sends a key (Qt::KeyF34) to Qtopia, which then does the actual suspend. It triggers the execution of ServerApplication::togglePower(). All CPU functions are suspended once
system("apm --suspend");
is executed. Normal operation will resume once a "Wake up" event comes from apmd.
Suspension is not enabled in the phone edition.
"apm --suspend"would suspend the CPU and shutdown the device. This behaviour is acceptable for PDA's because they don't need to listen for incoming calls. However, the qpe server must be running in order to receive calls. If Qtopia shuts down the power, everything would stop working. We will assume that Qtopia Phone does not do that (or that if it does, Linux ensures resume on modem activity).
Rather than suspending the device the number of CPU cycles has been minimized while the qpe server is showing the home screen. In addition to the first and second screensaver level (already known from the PDA edition) Qtopia Phone automatically closes applications and returns to the home screen. Background activities (like time/date updates and the execution of the battery monitor) are reduced to ensure that the CPU consumption is at the lowest possible level.
Files from external devices such as SD and CF cards are scanned on insertion and supported documents are mapped in to Qtopia's document view.
The scanning is triggered when the Qtopia library receives one of the following messages via the QPE/Card QCOP channel:
If QPE_SYSTEM_SYSFILEMONITOR (see above) is defined, Qtopia assumes that the surrounding system generates these messages (eg. by using the qcop command in the system HotPlug scripts). Otherwise, Qtopia polls every few seconds (wasting CPU).
When Qtopia scans for external devices such as SD and CF cards, it uses an heuristic to work out what is an external card. If this automatic detection is inadequate due to the specifics of your device, you may alternatively provide the file /opt/Qtopia/etc/default/Storage.conf, with a group for each relevant device in /etc/mtab, with settings of this form:
[/dev/hda1] Name = Internal Storage Removable = 0 [/dev/sda1] Name = Card Removable = 1
With the above, /dev/hda1 will be internal storage, and when /dev/sda1 is mounted (eg. by Linux Hotplug system), a storage location named "Card" will be available to the user: any documents there will appear on the Documents page. This file can be translated as with any Qtopia Config file.
Qtopia uses UTF8 for all file formats. System functions are also expected to use UTF8 encoding. For example, with $LANG set to "ja", strftime() must return a string in UTF8 encoding. Depending on the underlying operating system, this may require "ja" to be an alias for the "ja_JP.utf8" locale.
Note that Qtopia expects all file systems to use utf8 encoding. This usually requires attention in /etc/mtab and /usr/share/locale. Particular attention should be paid to removable media.
Qtopia can run as any user, provided that user has read and write permissions to certain file areas for certain functionality:
If a read-only filesystem is used, such as cramfs, then a symlink shadow should be created such that the above directories are writeable, but those files that are to be storeda in the cramfs filesystem are symbolic links to the actual files. For example, /opt/Qtopia/apps/Applications/calculator.desktop would be a symbolic link to /opt/Qtopia-ROM/apps/Applications/calculator.desktop.
As an alternative to the single directory specified by $QPEDIR, most Qtopia components support $QTOPIA_PATH, with is a colon-separated list of directories. By setting this variable (to, for example, "/opt/Qtopia:/opt/Qtopia-ROM"), and setting $PATH and $LD_LIBRARY_PATH appropriately, the following component directories can be searched in multiple places:
This greatly reduces the overhead of using symbolic links.
The Qtopia Phone Edition includes MMS functionality in the messages client.
Qtopia 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 see : $QPEDIR/src/applications/qtmail/mmscomms_http.{cpp,h}
To choose an alternate WAP stack connection method
The AMR encoder included with Qtopia is a reference implementation only. It is recommended that an encoder optimized for the target platform be installed. The media recorder plugin interface provides a convenient method of integrating the codec. See MediaRecorderEncoder class.
We have found that the implementation of the GSM specification varies from GSM module to GSM module. It is therefore highly likely that there will be a need to modify at least $QPEDIR/src/libraries/qtopiaphone/{muxdevice.*, atchat.*} to ensure that the GSM subset that the module supports is being used.
To support a GSM module the follow guide may be used:
Copyright © 2001-2005 Trolltech | Trademarks | Qtopia version 2.1.1
|