Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

System Customization

Introduction

This document is intended for system integrators and anyone attempting to install and configure Qtopia for a hardware platform. The document is a collection of the most common areas of customization designed to fast-track the process.

Compilation and Installation

Before attempting to compile Qtopia, ensure that you have read the following documentation:

The following sections provide additional information to help you progress from simply starting Qtopia, to compiling and installing Qtopia on the target hardware platform.

Configuring Qt/Embedded for a Device

To configure Qt/embeded for a device add the following as parameters to the Qt/Embedded configuration:

 -xplatform linux-myarm-g++ 

This instructs the configuration process to use an alternative platform specification that controls how the build proceeds. More information about platform specs can be found in Creating Custom Configuration Files.

Note:

Configuring Qtopia for a Device

To configure Qtopia for a device, add the following as parameters to the Qtopia configuration:

 -xplatform linux-myarm-g++

More information about platform specifications can be found in Creating Custom Configuration Files.

Note:

Create and Install the Qtopia Image for the Target Device

When configuring Qtopia for the target device $QPEDIR/image is the default prefix for the image created by Qtopia. After building Qtopia and running make install, the image needs to be transferred to the device. An example of the process is shown below:

Note: make install is an additive process. If the configuration changes, it is necessary to either:

Install Time Conversion files

Qtopia requires that /usr/share/zoneinfo contains the same Time Conversion data as $QPEDIR/image/etc/zoneinfo. To install the Time Conversion data files either

  1. Create a symbolic link to the Time Conversion data files provided by Qtopia, eg on the device run :
            if [ ! -d /usr/share/zoneinfo ]; then ln -s /opt/Qtopia/etc/zoneinfo /usr/share/zoneinfo; fi
        
  2. Create a symbolic link to the Time Conversion data files provided by the device's environment, eg on the device run :
            if [ -d /usr/share/zoneinfo ]; then rm -rf /opt/Qtopia/etc/zoneinfo; ln -s /usr/share/zoneinfo /opt/Qtopia/etc/zoneinfo ; fi
        

Qtopia Time on an Embedded Device

For a device to keep correct time with Qtopia requires the following:

  1. The kernel must support a Real-Time-Clock (RTC) interface and be built with correct driver for the device RTC.

  2. Linux distribution must contain /sbin/hwclock to update hardware time from system time /sbin/hwclock -systohcr, as required by Qtopia.

  3. Boot scripts set system time to hardware time on startup i{/sbin/hwclock -s}.

Note: These processes should be tested on the device prior to Qtopia controlling them.

Configuring environment variables on the device to suit Qtopia

If Qtopia is installed to /opt/Qtopia, then the environment variables are the same as for building from an SDK . If Qtopia is installed to a different location, use that location instead of /opt/Qtopia.

See also: Running Qtopia

Initial tests on Qtopia on the device

Run the following command :

 textedit -qws 

and confirm that:

See also: Running Qtopia.

Removing Components

Choosing not to build a component, eg Todo, can easily be done via editing $QPEDIR/src/custom.pri and re-configuring Qtopia. For example add the following to the custom.pri APP_PROJECTS-=applications/todo

See $QPEDIR/src/custom.pri for extra hints, see also Qtopia Build System

Developer-Only Components

There are a number of applications/features supplied with Qtopia that are not intended to be shipped with production devices:

Application/Feature Description
Rotation Setting Provided to test and demonstrate Qtopia's ability to display in different orientations. It may be helpful during development if the device uses the transformation display driver.
Shutdown Setting Provided as a development tool and 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 screen sizes quickly during development. This is a development tool only which is not intended for end-users.
Terminal Provided as a development tool. It may be reasonable to provide this as a separate installable package for advanced users who are familiar with Linux. However, the majority of users may find this tool confusing rather than useful. Therefore it is recommended this program not be included.
File Manager Provided as a development tool. Qtopia is functional without it by utilizing the Qtopia document 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:

File-system Access Permissions and Read-only file-systems

Qtopia can run as any user, provided that user has read and write permissions to certain file areas for certain functionality:

Files and directories requiring write permissions

Path Use Notes
/dev/fb0 Painting Frame Buffer Requires write permissions.
$HOME User settings and documents Requires write permissions.
/opt/Qtopia/... Qtopia files Requires write permissions for installing additional software.
/etc/ppp/... PPP configuration options Requires write permissions for Network Settings.
/etc/pcmcia/... LAN/wireless network options Requires write permissions for Network Settings.

Using Read-only file-systems

Using read-only file-systems can have a number of benefits. Compressed read-only file-systems such as cramfs and squashfs often have better compression than read-write file-systems such as jffs2. Also read-only file-systems provide a measure of protection for important system files.

Single Executable

If the device does not require that users can install additional applications or plug-ins it is possible to compile Qtopia as a single, statically built executable. This uses less space than the dynamic build but does not allow other applications to link to Qtopia libraries.

If Qtopia is build as a single, statically built executable /opt/Qtopia does not require write permissions and can be mounted on a read-only file-system.

See Qtopia Single Exec.

Using Symbolic Links

Symbolic links are the easiest way of mixing read-only and read-write file-systems. Set QPEDIR to be a location on the read-write file-system and use symbolic links to link individual files to their respective locations on the read-only file-system. For example /opt/Qtopia/apps/Applications/calculator.desktop would be a symbolic link to /opt/Qtopia-ROM/apps/Applications/calculator.desktop.

This has better flash usage than using just a read-write file-system and allows installing additional applications and updating components of Qtopia.

Using Multiple Qtopia Paths.

Improved support for multiple Qtopia paths was added in Qtopia 2.1. Some components of Qtopia can reside in a number of directory locations. This reduces the need for symbolic links when mixing read-only and read-write file systems, reducing flash ram usage. The subdirectories of Qtopia that support multiple Qtopia paths include:

If the QTOPIA_PATHS environment variable is set to include an appropriate directory on the read-only file-system, then for the above subdirectories symbolic linking of files to the read-only file-system is not required. It is still necessary to use symbolic links for the apps subdirectory to allow installable applications.

The QTOPIA_PATH environment variable is set as a colon-separated list of directories. For example "/opt/Qtopia:/opt/Qtopia-ROM". It is also required that the PATH and LD_LIBRARY_PATH environment variables are set appropriately.

Plug-ins and Safe Mode

If Qtopia crashes twice in quick succession "Safe Mode" will be entered and no plug-ins will be loaded in case the crash was caused by a misbehaving plug-in. In some cases there are plug-ins that are required for correct operation of the device. These plug-ins 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()

Tailoring Qtopia's Hardware Configuration

When planning to customize and install Qtopia on a specific device a number of a number of factors that must be taken into consideration:

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.

Device-specific Code (custom[-platform].h)

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.

Macro Name description
QPE_USE_MALLOC_FOR_NEW #define this to have memory allocated 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 that requires calibration.
QPE_OWNAPM #define this if the device has existing APM settings that must be disabled first by Qtopia via ioctls to /dev/apm_bios.
QPE_HAVE_MEMALERTER #define this if the device needs Qtopia to alert the user of low memory conditions. A low memory situation will either be triggered/detected by initMemalerter() (if QPE_MEMALERTER_IMPL is defined) or Qtopia will use its own default implementation.
QPE_MEMALERTER_IMPL #define this as a macro that implements any functions required to implement the MEMALERTER functionality (including initMemalerter()).
QPE_INITIAL_NUMLOCK_STATE #define this as a macro that 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.
QPE_SYSTEM_SYSFILEMONITOR #define this if your device's HotPlug system for Removable Storage Cards is Qtopia-aware.
QPE_SYNC_CLOCK_FROM_QD Datebook on Qtopia Desktop sends the "current time" to Qtopia after it has finished synchronizing. #define this to make Qtopia set it's clock from the time received so that the clock on the PDA is kept in sync with the desktop.
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.
QTOPIA_ENABLE_EXPORTED_BACKGROUNDS #define this to have the phone homescreen background used as the background for the launcher.
QTOPIA_ENABLE_GLOBAL_BACKGROUNDS #define this to have the phone homescreen background used as the background for all applications. Requires QTOPIA_ENABLE_EXPORTED_BACKGROUNDS.
QTOPIA_USE_QSS_VOLUME #define this to set the system sound level through qss rather than modifying /dev/mixer (for PDA Edition).

In addition to the above macros and defines, the following three functions must be implemented in the custom-<platform-spec>.cpp file.

Function Name Description
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 specific 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 assistance.

Power Management

A number of points should be considered when integrating Qtopia with a device that has power management.

Technical Details

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

Qtopia's screensaver can be adjusted by the user via the power management (Light & Power) application.

For PDA Edition

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.

For Phone Edition

Suspension is not enabled in the phone edition.

 "apm --suspend" 
would suspend the CPU and shutdown the device. This behavior 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.

Memory Management

Qtopia's memory management is divided into two segments. These parts can be controlled via :

QPE_HAVE_MEMALERTER enables Qtopia to alert the user if the device is running under low memory conditions. It relies on the macro QPE_MEMALERTER_IMPL which should be defined if a customized memory alerter implementation is available. Otherwise Qtopia will use its own default implementation which is based on page faults. It is recommended to use initMemalerter() if the device has some kind of hardware support to detect the memory situation.

The memory alerter should return five different memory states. The following list describes these states and their consequences for the server.

Memory State Description
MemUnknown This is the initial state and has no consequences for the server. This state can also be used to indicate that the system has no information available about the status of the memory usage.
MemNormal The memory consumption is within its normal parameters and does not require any attention from the server.
MemLow This state will initiate the shutdown of one lazy application (idle in the background). If QPE_LAZY_APPLICATION_SHUTDOWN is not defined this state will do nothing.
MemVeryLow This state initiates the shutdown of all lazy applications and will inform the user about the situation at hand.
MemCritical This state means that the system is overloaded. An indication for this state is page thrashing. The server will shutdown all lazy applications. If the lazy application shutdown is not enabled or did not shutdown any application gracefully the application that was started at last will be terminated in order to prevent that the kernel terminates the qpe server itself.

Dual Screen Displays

Qtopia includes two classes to support dual screen phones:

Example Dual Screen Application

There is an example of a simple status display for a dual screen phone in src/tools/dualdisplaybasic. It provides a small display, similar to a monochrome LCD display that displays the state of the phone. It illustrates use of the phone status library and qcopbridge library. There are two possibilities for displaying the display.

1. Using one Qt/E display

In this case, the status display will appear as a floating display in the Qtopia display. This is the common case for a LCD display which does not need the complete Qt/E graphics engine to drive it. To view in this mode, simply run the application.

2. Using a separate display

In this case, the status display appears in a separate framebuffer. This case is desirable on a larger, full color secondary display. The QCop Bridge is employed to transfer status messages between the two different Qt/E displays. To view the example in this mode create a separate framebuffer and start the application in this framebuffer. For example:

qvfb -width 83 -height 36 -qwsdisplay :2
./dualdisplaybasic -qws -display :2

Keypad Architecture

For an overview on character input in Qt/Embedded see : Character Input-QWS

To add a new driver it is necessary to modify : $QTDIR/src/kernel/qkeyboard_qws.cpp see : QWS Keyboard Handler.

Default scan-codes for Qtopia keys

Nearly all PDA's and Phones have keys that are not found on a regular keyboard. In order for Qtopia to function correctly when installed on a device, it needs these keys to be defined. The easiest way to do this is to have the keyboard driver for the device emit the scancodes for the existing mapping for Qtopia.

In addition to the normal mapping for a US-101 keyboard, the following table sets out the codes that are required / available / optional:

Scancode Qt Key Code Description Keypad Mode no keypad mode
"65" Key_Menu Application menu key Optional Not Available
"67" Key_Back Accept/Close dialog key Required Not Available
"68" Key_Yes Yes Optional Not Available
"69" Key_No No Optional Not Available
"87" Key_Call Start call, accept incoming call Optional Not Available
"88" Key_Hangup End call, reject incoming call Optional Not Available
"116" Key_Select Select menu option, checkbox, pressbutton Required Not Available
"120" F31 Toggle input method Optional Optional
"121" F32 Sync device Optional Optional
"122" F34 Power/Sleep Optional Required
"123" F35 Toggle backlight Optional Optional
"124" Context1 First Context button Optional Not Available
"125" Context2 Second Context button Optional Not Available
"126" Context3 Third Context button Optional Not Available
"127" Context4 Fourth Context button Optional Not Available

There are two additional keys that do not have default mappings, and should not be used. They are listed below only for reasons of compatibility.

Qt key code Description Keypad Mode No Keypad Mode
Key_F30 maps to space on widgets that need a select key Not Applicable Optional
Key_F33 maps to enter on widgets that need a ok key Not Applicable Optional

Qtopia is designed to be flexible in terms of the keys required. The default mapping for Qtopia has the following keys:

Key Name Description
Key_Select selects/activates/toggles/edits the currently highlighted item.
Key_Context1 soft key 1; mapped to Key_Menu in default mapping.
Key_Back leave dialog, or Key_Backspace while editing text and no real Key_Backspace.
Key_Call answer or make a call.
Key_Hangup hang up a call or return to home screen.
Key_Up navigate to previous item, or up one line.
Key_Down navigate to next item, or down one line.
Key_Left navigate to previous page in Tab Widget, or left one character.
Key_Right navigate to next page in Tab Widget, or left one character.
Key_Flip pressed and held while the display is "closed" (eg. Clamshell phone), released when open. Answers or hangs up calls.
Key_Backspace deletes character/item.

Note: Qtopia can operate without:

and Qtopia can operate with Key_Menu rather than Key_Context.

If a device has an alternate button mapping, Trolltech will endeavour to provide assistance in getting Qtopia to work with alternate button mapping.

Overriding scancode mapping for Qtopia

If it is not possible to map the device buttons' emit to the default scan codes for the Qtopia keys, then the mapping can be overridden in custom-linux-<device>-g++.*. In custom-linux-<device>-g++.h add:

#define QPE_OVERRIDE_KEYMAP
struct KeyOverride;
extern const KeyOverride* qtopia_override_keys();

and in custom-linux-<device>-g++.cpp add:

typedef struct KeyOverride {
    ushort scan_code;
    QWSServer::KeyMap map;
};

static const KeyOverride deviceKeys[] = {
   { 0x79,   {   Qt::Key_F34,    0xffff, 0xffff, 0xffff  } }, // power
#if defined(QT_KEYPAD_MODE)
   { 0x7a,   {   Qt::Key_Call,      0xffff, 0xffff, 0xffff  } },
   { 0x7b,   {   Qt::Key_Context1,  0xffff, 0xffff, 0xffff  } },
   { 0x7c,   {   Qt::Key_Back,      0xffff, 0xffff, 0xffff  } },
   { 0x7d,   {   Qt::Key_Hangup,    0xffff, 0xffff, 0xffff  } },
   { 0x7e,   {   Qt::Key_Flip,      0xffff, 0xffff, 0xffff  } },
#else
   { 0x7a,   {   Qt::Key_F9,        0xffff, 0xffff, 0xffff  } },
   { 0x7b,   {   Qt::Key_F10,       0xffff, 0xffff, 0xffff  } },
   { 0x7c,   {   Qt::Key_F11,       0xffff, 0xffff, 0xffff  } },
   { 0x7d,   {   Qt::Key_F12,       0xffff, 0xffff, 0xffff  } },
   { 0x7e,   {   Qt::Key_F13,       0xffff, 0xffff, 0xffff  } },
#endif
   { 0,      {   0,                 0xffff, 0xffff, 0xffff  } }
};

const KeyOverride* qtopia_override_keys()
{
    return deviceKeys;
}

Where deviceKeys is the mapping of scan code to the structure composing of:

The example above is for the iPAQ h3xxx models.

Overriding the keyboard handler Qtopia Keys

If your device does not have a keyboard driver, then it is possible to implement a special keyboard handler for the device. However this is not recommended. If it is not possible to use the mapping described above to fix your keyboard, please contact Trolltech support with the details and we will provide instructions on the best solution.

Key behavior in Qtopia

Keys that are always intercepted

Some keys are always intercepted before they reach an application. If a pointer device is available an application can do a keyboard grab to get these keys.

Keys that are sometimes intercepted

While the screen lock is active (sim card pin required for example) the applications will only be allowed keys such as Key_Back and Key_No. This is to reduce the chance of anyone accessing the phone's data while the sim-card pin is still required.

Pointer Architecture

For information about adding a new mouse driver see : Qt/Embedded Pointer Handling.

Calibration

Some touchscreen devices require pointer calibration. Qtopia already contains built in support for calibration but it is disabled by default on almost all platforms. To enable calibration support:

  1. Use a touchscreen pointer driver that supports calibration, such as the TPanel driver.
  2. Add the QPE_NEED_CALIBRATION definition to the Device-specific header for the build. This definition will add the Calibrate application to the devices settings list and enable calibration in the First Use application in the PDA edition. It can be omitted if neither is desirable.
  3. To support a calibrated touch screen, PrimaryInput=Touchscreen must included in the [Device] group of the $QPEDIR/etc/default-buttons.conf

To manually start the calibration on a Qtopia phone device, run

 qcop "QPE/System" "execute(QString)" "calibrate" 

GSM Modem Integration

We have found that the implementation of the GSM specification varies between GSM modules. It is therefore likely that modifications will be needed to $QPEDIR/src/libraries/qtopiaphone.

To simplify matters, most of the module-specific code can be placed in a vendor-specific plug-in, located under $QPEDIR/src/plugins/phonevendors. The plug-in should inherit the PhoneVendorAt class and override its methods to implement the vendor specifics.

Qtopia Phone will load every vendor plug-in that is installed and queries each one to see which is capable of handling the GSM modem. A vendor plug-in will typically issue vendor-specific AT commands to determine if the modem is supported.

The QTOPIA_PRELOAD_PHONE_PLUGIN macro in custom.h can be used to force Qtopia Phone to load only that plug-in, ignoring any others that may be present in the system.

GSM 07.10 multiplexing, implemented in muxdevice.*, is a common cause of problems. During initial testing, you can disable it by setting the QTOPIA_PHONE_MUX environment variable to "no". Qtopia Phone will still function, but you will be unable to make GPRS calls without multiplexing support.

The MAX_GSM0710_FRAME_SIZE, QTOPIA_EXTRA_CMUX_PARAMS, and QTOPIA_ADVANCED_CMUX macros in custom.h can be used to customize the behavior of the GSM 07.10 implementation, the alternative is to modify muxdevice.cpp.

The Qtopia source code supports Wavecom-style multiplexing, as an example of how to implement a non-CMUX multiplexing system. This mode is enabled with the use of the QTOPIA_WAVECOM_MUX macro in custom.h.

To support a GSM module the follow guide may be used:

  1. Check the AT commands that Qtopia requires in Phone Library and determine which ones your GSM module supports.
  2. Determine the appropriate alternative AT commands suited to your GSM module and write the vendor-specific plug-in to issue these commands.
  3. Run Qtopia.
  4. Check the error/message log for commands that are reported as error.
  5. Using the error log modify the plug-in and/or the phone library so that the modem-supported AT command parameters are used. For example, AT+CMUX=1,0,5 vs AT+CMUX=0,0,5 .
  6. Repeat from step 3 until GSM calls are possible, SIM details are being read etc ...

Serial Proxy

Most modern phones have an external serial interface, which is used to connect to a computer for the purposes of data calls, FAX transmissions, or synchronization with desktop applications.

The SerialProxy class assists with this process.

The Phone.conf file needs to be placed under the etc/defaultx" directory on the vendor system.

Warning

Using a serial proxy is not possible when connecting Qtopia to In such a case ensure that Phone.conf file does not contain an entry for "ExternalAccessDevice".

Customizing Qtopia's Appearance

Qtopia's appearance can be modified on several ways

Replacing the Qtopia Launcher

In some cases it is desirable to have a customized launcher interface better suited to the application on the target device. Qtopia supports custom launcher user-interfaces via the ServerInterface. This interface provides 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 file-system management.

The default Qtopia launcher is implemented by the Launcher class. The first step when writing a user-interface is to implement a class derived from ServerInterface. This interface provides the functionality to display the 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.

The functions provided by the ServerInterface manage the addition and removal of applications and documents as necessary. The ServerInterface documentation describes the functions in detail.

Reusable User-Interface Components

In addition to the launcher it is 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 re-used in a custom interface. Most user-interfaces make use of some of these classes to ensure a usable system:

An interface providing these components will support the Qtopia launcher default functionality.

The Qtopia libraries also assume that QPE/Taskbar QCOP channel is available and supports the following functions:

Function Description
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 plug-ins.
reloadApplets() release and reload the applets.

The default Qtopia launcher uses the TaskBar class to encapsulate the above functionality.

Fonts

To make extra fonts available to Qtopia it is likely that the makeqpf ultility will need to be run. For more details see : makeqpf

Keypad Button Behavior

The configuration of hardware buttons for a device is defined by the etc/defaultbuttons-<platform-spec>.conf files.

The file is divided into sections.

See the existing files, especially the generic file, for guidance.

User Defineable Button Mappings

Button Mappings are what maps the hard buttons on a device to application shortcuts in Qtopia. For example a calendar button that brings up todays schedule, or a button to beam your business card.

The description of the buttons should be included in defaultbuttons.conf on the device, or defaultbuttons-<platform>.conf if in the build tree.

An example of what this may look like:

[Button]
Count=2
[Button0]
Name=Calendar Button
Key=F9
PressedActionService=Calendar
PressedActionMessage=raiseToday()
HeldActionService=Calendar
HeldActionMessage=raise()
[Button1]
Name=Contacts Button
Key=F10
PressedActionService=Contacts
PressedActionMessage=raise()
HeldActionService=Contacts
HeldActionMessage=beamBusinessCard()

This example describes a device with two hardware buttons. One that opens the calendar application, and another that opens the contacts application or beams the owners business card.

[Button]
Count=2

This indicates that also in defaultbuttons.conf there are two groups, named Button0 and Button1. Each group describes the button and its actions. For example starting from the line [Button0] to another group definition or the end of the file defines the first button mapping.

Name[]=Calendar Button
...
[Translation]
File=QtopiaDefaults
Context=Buttons

This describes the name of the button. Qtopia provides a Buttons application where the user can change the button mapping for shortcut buttons on their device. The Name of a button is how the button is described to them. The translation for the button's name can be found in $QPEDIR/i18n/<your-lang>/QtopiaDefaults.ts.

Images can be provided for the buttons by placing them in pics/Button/. The name of the image should be the number of the button as described in defaultbuttons.conf. For this example, the image for the calendar button would be ../pics/Button/0.png.

Key=F9

This describes the Qt keycode the button maps to. These are the codes listed in qnamespace.h found in the Qt include directory. To map a key to a Qt keycode, see Overriding scancode mapping for Qtopia.

PressedActionService=Calendar
PressedActionMessage=raiseToday()
HeldActionService=Calendar
HeldActionMessage=raise()

These describe what occurs when a button is pressed or held. The Service is a Qtopia Service, described in Qtopia Application Services. In this case the name of the services is calendar, and the action is raise(), or raiseToday(). Both the service and actions are already provided for the Qtopia calendar application. Only actions that take no parameters can be used.

Phone Launcher Menu

The launcher menu on a phone is often a 3 by 4 grid, corresponding to the positioning of the keys 1 to 9, *, 0, and #.

The format of the launcher menu section of the file is as follows:

[Menu]
Rows=<rows of icons>
Columns=<columns of icons>
Map=<one character for each icon, left to right, top to bottom>
Default=<character of initially focussed icon>
<character>=<desktop file or directory>
... for each character in Map.

An example of what this may look like in a real example is:

[Menu]
Rows=3
Columns=3
Map=123456789
Default=5
1=
2=Applications/datebook.desktop
3=Games
4=
5=Applications/addressbook.desktop
6=Settings
7=
8=Applications
9=Documents

Phone Buttons

The dialing and other buttons of a phone are configured by the "SystemButtons", "TextButtons", "PhoneTextButtons", and "LocaleTextButtons" sections of the defaultbuttons.conf file.

The format of the SystemButtons section of the file is as follows:

[SystemButtons]
Count=n
Key0=Name of Qt key code, e.g. Menu, Select, Context1
... for each system button on the device 0 to n

An example of what this may look like in a real example is:

[SystemButtons]
Count=5
Key0=Menu
Key1=Select
Key2=Back
Key3=Call
Key4=Hangup

The TextButtons section defines all text and actions associated with each button. For example, the "2" key is associated with "2", as well as the letters "a", "b", "c", and all variants of those letters.

The LocaleTextButtons section is like the TextButtons section, except it only defines the text associated with the current language. The texts in these sections are translated in the standard way for Config files.

The PhoneTextButtons section defines all phone number text and actions associated with each button. For example, the "*" key might choose between any of the characters "*", "+", and "p" (for pause).

The format of the TextButtons, PhoneTextButtons, and LocaleTextButtons sections of the file are similar, as follows:

[TextButtons]
Buttons=0123456789*#
Tap0= ...
Hold0= ...
...

For each button listed in Buttons, define:

Character insertions where the first character is punctuation are treated specially. The details of the special treatment are internal.

Timing behavior for phone buttons are handled by the ButtonTimings section of the file.

[ButtonTimings]
ButtonHeldTimeout=1500
AutoAcceptTimeout=1200

The ButtonHeldTimeout is the number of milliseconds a button needs to be held for the held behavior described above to take affect. The AutoAcceptTimeout is the number of milliseconds after a key is tapped before the composed text is confirmed. This only applies to some text input modes.

The help file "help/html/help-input.html" should be modified to explain the usage of phone keys.

Phone SoftKey Definition

The format of the soft-key definition section of the file is as follows:

[SoftKeys]
Count=n
Key0=Name of Qt key code, e.g. Menu, Select, Context1

An example of what this may look like in a real example is:

[SoftKeys]
Count=3
Key0=Context1
Key1=Select
Key2=Back

Document and File Storage

Qtopia has 3 ways that it identifies storage locations.

Algorithm based on device names

This is the original method and is generally not suitable to new devices. You can modify the algorithm but it it much easier to specify the locations you want with Storage.conf.

Storage.conf

If $QPEDIR/etc/default/Storage.conf exists, it is used when deciding what parts of the file-system are available for Qtopia's use. It must define 1 non-removable and any number of removable locations.

Note: Due to the way the configuration system works, $HOME/Settings/Storage.conf will override $QPEDIR/etc/default/Storage.conf. This should not matter on released devices as the available devices will not change. On a development system you should ensure $HOME/Settings/Storage.conf is removed when $QPEDIR/etc/default/Storage.conf is changed.

Here is a simple example of a Storage.conf file.

[/dev/hda1]
Name = Internal Storage
Removable = 0
[/dev/sda1]
Name = CF card
Removable = 1

This file specifies the device /dev/hda1 as the non-removable storage. It calls this location "Internal Storage". There is also a removable storage location called "CF card" that uses the device /dev/sda1.

It is possible to add translation to the names in Storage.conf. If you require this ability, please contact support-embedded@trolltech.com as a patch needs to be applied to your Qtopia tree.

The "device" in Storage.conf must correspond to the first column of /etc/mtab. Here are some examples of devices.

All-else-fails hack

If no storage locations are found a fallback is used. When this happens $HOME is used as the "Internal Storage" location. As $HOME is generally writable this tends to work but you will not have access to removable storage if this happens. Provide a Storage.conf file so that your devices are explicitly noted.

Non-removable vs Removable storage

Application data is stored in the non-removable location. Documents can be in any location. Removable locations are re-scanned on insertion and removal.

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

Integrator Provided Components

A number of Qtopia components are just stubs, or functionless interfaces, that provide a convenient abstraction for integrators to provide an implementation of their own. Integrators must implement these stubs before the particular Qtopia component will work correctly.

Multimedia Messaging

The Qtopia Phone Edition 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)

Qtopia 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

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

AMR Encoder

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 plug-in interface provides a convenient method of integrating the codec. See MediaRecorderEncoder class.


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0