Qtopia - Customizing Qtopia for a Device
This document provides some recommendations for installing Qtopia on a device.
There are a number of aspects to customizing Qtopia for a specific
device which must be considered.
- If the device has a touch screen, Qtopia will need to enable calibration.
- If the device runs off batteries, Qtopia may be required to call APM functions for power saving.
See the Power Management section below for more details.
- If the device has special hardware buttons, they may need to be mapped to
applications and have associated images displayed in the user interface.
- If the device has a buzzer for alarms and other beeps, Qtopia will need to know how to use this hardware
and enable it for the associated events.
- If the device has a LCD screen with a back light or front light, Qtopia will need to know how to adjust
the brightness for it.
- If the device has any special LEDs to indicate status to the user, Qtopia will need to know how to
set the LEDs.
Fortunately all of the changes required to add those device specific customizations are centralized in Qtopia
to just a few files which are described below. This document should make it easy for OEMs and system integrators
to understand how to make Qtopia aware of any special hardware that a device might have.
Device-Specific Code
During configure, the -platform option is used to
select which custom-<platform-spec>.h file will be used when compiling Qtopia.
The following macros can be defined or undefined in a custom.h file to
customize Qtopia for the specific hardware. The associated custom-<platform-spec>.cpp
file will be compiled and linked to provide any custom functions that are also required.
- QPE_USE_MALLOC_FOR_NEW - #define this to have memory alloced using malloc() instead of the default C++ new implementation (this is faster in some cases).
- QPE_NEED_CALIBRATION - #define this if there is a touch screen which requires calibration.
- QPE_OWNAPM - #define this if the device has existing APM settings which must be disabled first by qtopia via ioctls to /dev/apm_bios.
- QPE_HAVE_TOGGLELIGHT - #define this if the device has a hardware button for turning on and off an LCD backlight if applicable.
- QPE_HAVE_MEMALERTER - #define this if the device needs Qtopia to alert the user of low memory conditions, a function called initMemalerter() must be implemented.
- QPE_MEMALERTER_IMPL - #define this as a macro which implements any functions required to implement the MEMALERTER functionality (including initMemalerter()).
- QPE_INITIAL_NUMLOCK_STATE - #define this as a macro which implements any device specific methods used to initialize the numlock state.
- QPE_ARCHITECTURE - #define this with a string that contains the manufacturer and model that uniquely identifies the device, for example "SHARP/SL5500".
- QPE_DEFAULT_TODAY_MODE - #define this as "Daily" or "Never" (including the quotes) to tell Qtopia if by default it should run the today program daily or never.
- QPE_FONT_HEIGHT_TO_ICONSIZE(x) - #define this as a macro to provide a mapping from a font height to an icon size in pixels.
- CUSTOM_SOUND_INIT - #define this to call a function to initialize any custom sound devices like buzzers.
- CUSTOM_SOUND_IMPL - #define this as a macro to define any custom functions required to be used by the other CUSTOM_SOUND macros.
- CUSTOM_SOUND_ALARM - #define this as a macro which implements the device specific code to sound an alarm (perhaps using a buzzer).
- CUSTOM_LEDS( led, status ) - #define this as a macro which can set an LED to a given status if applicable. The first argument specifies which LED, and the status is an integer with device specific meaning.
- CUSTOM_SOUND_TOUCH( press ) - #define this as a macro which implements a given sound to be associated with taps to the screen if applicable.
- CUSTOM_SOUND_KEYCLICK( k, p, r ) - #define this as a macro which implements a given sound to be associated with keyboard key presses if applicable.
In addition to the above macros and defines, the following three functions must be implemented in the custom-<platform-spec>.cpp file.
- int qpe_sysBrightnessSteps(); - This function is called by qtopia to query the number of graduations the device's LCD backlight/frontlight has.
- void qpe_setBrightness(int); - This function must be implemented with any device specifc code used to set the backlight/frontlight brightness to the specified level.
- void PowerStatusManager::getStatus(); - This function must be implemented to query the power status. The PowerStatus class in qtopia/power.h defines the power status abstraction. See the custom-linux-generic-g++.cpp file for details of a default implementation.
For reference implementations of the device specific code, the existing custom-*.* files found in src/libraries/qtopia/ may be of guidance.
Device-Specific Files
The default hardware button mappings for a device are defined
by the etc/defaultbuttons-<platform-spec>.conf files.
The format of the file is as follows:
[Button]
Count=<number of button records below>
[Button<button number counting from 0>]
Name=<name of the button (in english)>
Name[ja]=<japanese translations of the button name>
Name[<lang>]=<other lang translations of the button name etc>
Key=<associated key code emitted by the button eg. F9>
PressedActionService=<name of default service associated with press>
PressedActionMessage=<message to send to service (refer to services for details)>
HeldActionService=<name of default service associated with press>
HeldActionMessage=<message to send to service (refer to services for details)>
An example of what this may look like in a real example is:
[Button]
Count=2
[Button0]
Name=Calendar Button
Name[ja]=???
Key=F9
PressedActionService=Calendar
PressedActionMessage=raiseToday()
HeldActionService=Calendar
HeldActionMessage=raise()
[Button1]
Name=Contacts Button
Name[ja]=???
Key=F10
PressedActionService=Contacts
PressedActionMessage=raise()
HeldActionService=Contacts
HeldActionMessage=beamBusinessCard()
Images of the buttons, which should correspond
to the appearance of the device hardware, are in pics/Button/n.png, with
n corresponding to the button number in the configuration file.
See the existing files, especially the generic file, for guidance.
Non-installed Components
There are a number of applications/features supplied with Qtopia that are
not intended to be shipped with production devices:
- Rotation Setting - This is provided to test and demonstrate Qtopia's ability
to display in different orientations. This may be helpful during development
if the device uses the transformation display driver.
- Shutdown Setting - This is provided as a development tool. It should
not be necessary on a production device. It can be removed by deleting
apps/Settings/quit.desktop, on most devices it is expected that there is
a physical power button, therefore the user is not expected to ever manually
run or shutdown Qtopia.
- screensize applet - allows changing the maximum window size for testing
different screensizes quickly during development. This is a
development tool only which is also not intended for end users.
- Terminal - This is provided as a development tool. It may be reasonable to
provide this as a seperate installable package for advanced users who are
familiar with Linux however it is not expected that the majority of users will
find this tool at all useful, only confusing. Therefore it is recommended this
program is not included.
- File Manager - Provided as a development tool. Qtopia is functional without
it using just Qtopia's document model. Files from external devices such as SD and CF cards
are automatically scanned on insertion and supported documents are mapped in to Qtopia's
document view. Files can also be transfered back and forth from a PC via Qtopia
Desktop which also maps the documents to Qtopia's document view and model. Adding
the File Browser can make it possible for users to add and remove files from the
device in a way which does not correspond to Qtopia's document model which can break the
interface. We therefore do not recommend this program should be included on a device
to ensure a consistent document model in addition to protecting critical user and system
files and settings.
Unsupported Components
The following applications are unsupported 3rd party applications/ports
intended purely to demonstrate the flexibility of Qtopia:
Required Plugins
If Qtopia crashes twice in quick succession "Safe Mode" will be entered and
no plugins will be loaded in case the crash was caused by a misbehaving
plugin. In some cases there are plugins that are required for correct
operation of the device. These plugins can be specified in the .directory
file in $QPEDIR/plugins/<type>/.directory. For example, if the simple8
text codec is always required:
[Desktop Entry]
Name=Text Codecs
Comment=Provides support for various international languages.
Required=simple8
Apply=QPE/System restart()
Power Management
A number of points should be considered when integrating Qtopia with a
device that has power management.
- Qtopia controls the power state (using pen and key
input to restart timeouts), not the kernel.
- The system's "Power" key just sends a key to Qtopia, which
then does the actual suspend.
- Qtopia supports multiple shutdown levels. By default these
are On, Light Dim, LightOff, and Suspend. Additional levels
can be added with a small amount of coding.
- Qtopia calls platform-specific functions to set lighting level
for 'dimming' and turning off the light.
- 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).
Custom Qtopia Launcher User Interface
In some cases it is desireable to have a cusomized launcher interface
that better suits the intended application of the target device. Qtopia
supports custom laucher user interfaces via the ServerInterface. This
interface provides all of the infrastructure necessary to implement a
launcher, while maintaining compatiblity with the Qtopia application and
document models.
The launcher user interface is part of the Qtopia server
($QPEDIR/src/server) which provides services such as syncing
and filesystem management.
Launcher
The first step when writing a user interface is to implement a class
derived from ServerInterface. This interface provides the functionality
necessary to show the available applications and documents available
on a Qtopia device.
The createGUI() and destroyGUI() functions must be implemented to create
and show the laucnher and any other user interface components.
Most of the functions provided by the ServerInterface are to manage adding
and removing applications and documents as necessary. The ServerInterface
documentation describes each one in detail.
The default Qtopia launcher is implemented by the Launcher class.
Other User Interface Components
In addition to the launcher itself, it is ususally necessary to provide
some system components, such as input methods and status display.
There are several classes in the
default Qtopia user interface that may be reused in a custom interface.
Most user interfaces will make use of some of these classes to ensure a
useable system:
- InputMethods - loads and displays input methods.
- RunningAppBar - displays running application icons.
- SysTray - loads and displays applets.
- StartMenu - provides menus for launcher tabs and accessory plugins.
An interface providing these components will support most of the default
Qtopia launcher functionality.
The Qtopia libraries aslo assume that QPE/Taskbar QCOP channel is available
and supports the following functions:
- message(QString) - display a status message.
- hideInputMethod() - hide any visible input method.
- showInputMethod() - show the currently selected input method.
- showInputMethod(QString) - show the specified input method.
- reloadInputMethods() - release and reload the input method plugins.
- reloadApplets() - release and reload the applets.
The default Qtopia launcher uses the TaskBar class to encapsulate the
above functionality.
Copyright © 2001-2002 Trolltech | Trademarks
| Qtopia version 1.7.1
|