Qt API | Qtopia API

Qtopia Documentation

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:

• VNC Viewer

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).