Integration guide

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

        [prestartup]
        EnvironmentSetup
        DBMigrate
        QtopiaApplication
        IpcRouter

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:

        ...
        [ApplicationLauncher]
        ApplicationMonitor
        ApplicationLauncher
        QtopiaServerApplicationLauncher
        BuiltinApplicationLauncher
        ConsoleApplicationLauncher
        QuickExeApplicationLauncher
        QuickForkedApplicationLauncher
        SandboxedExeApplicationLauncher
        SimpleExeApplicationLauncher

        [startup]
        +ApplicationLauncher
        ...

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:

        ...
        [idle]
        BtDialupServiceTask
        ...

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.

Communication

Bluetooth

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

• L2CAP
• RFCOMM
• SCO

Qt Extended includes implementations of the following Bluetooth services.

• Bluetooth handsfree service Audio Gateway
• Bluetooth headset service Audio Gateway
• Bluetooth dial-up networking service

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.

Networking

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

network type	related 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 UMTS	QPEDIR/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

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.

• Ensure drivers are loaded, e.g. via hotplug or udev.
• If necessary notify Qt Extended of the new devices. This can be done via custom udev rules and qcop.

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

• Mass storage devices must have a corresponding entry in the Storage.conf configuration file.
• Keyboard and mouse handlers need to be instantiated for new input devices. This can be handled by a Server Task that monitors for new input devices.

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:

• Enable the Transformed driver in Qt for Embedded Linux: * as build-in driver, update the devices/<device>/configure file:

                            -extra-qtopiacore-config -qt-gfx-transformed

  * as plugin driver, update the devices/<device>/configure file:

                            -extra-qtopiacore-config -plugin-gfx-transformed

• Add

       -dynamic-rotation

  argument to the devices/<device>/configure file to enable rotation and build the RotationManager and rotation settings application.

• Export the appropriate QWS_DISPLAY value before running Qt Extended eg : export QWS_DISPLAY=Transformed:Rot270

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.

Section	Key	Description
MountTable	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.
Packages	MountPoint Path	Names which MountPoint Qt Extended should install user Packages to. path to installed directory from Applications mount point.
HOME	Name[] Documents Applications	String name for home. Whether Qt Extended should scan HOME for Documents. Whether Qt Extended should scan HOME for applications.
MountPoint0	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

• Boot Source
• Keypad Light
• Power Source
• Signal Source
• Vibration

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

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:

Section	Details	Possible settings.
[Translation]		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"
[LocaleTextButtons]		TapX[]=<'string> - Specifies tap action, where X is button specifier and string is characters
[PhoneTextButtons]		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 used	DefaultIM=<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:

• dim backlight
• backlight off
• suspend device

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 method	source	Description
Phone keys	$QPEDIR/src/3rdparty/plugins/inputmethods/pkim	The 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/handwriting	This 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/keyboard	The Keyboard input method demonstrates widget based pop up text input.
Docked Keyboard	$QPEDIR/src/plugins/inputmethods/dockedkeyboard	The 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.

Internationalization

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:

• Translating Categories
• Translating Themes
• Other build system related internationalization tasks

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.

Messaging

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:

• covers a subset of SMIL 2.0 basic
• can be modified to implement SMIL 2.0 basic language specification
• implements functionality as required by: MMS Conformance Document 1.2 Candidate Version 29-September-2003 (OMA-MMS-CONF-v1_2-20030929-C).

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:
   • modify the MmsClient::setAccount function in $QPEDIR/src/applications/qtmail/mmsclient.cpp
2. to list the source/header files for the Mmscomms implementation:
   • modify MMSCOMMS_HEADERS and MSCOMMS_SOURCES in $QPEDIR/src/applications/qtmail/qtmail.pri

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.

• Package Manager
• Application level policy
• OS level policy using LIDS
• Security Monitor(aka SxeMonitor)

Telephony

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

Step	Description
Device-specific code	Qt 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 device	Qt Extended requires /sbin/hwclock to update the system time and zone information for time conversion purposes.
Removable Media and Devices	Qt 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:

• Qt for Embedded Linux Environment Variables
• Environment Settings to Run Qt Extended

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

Variable	Description
QTOPIA_PHONE_DEVICE	Specifies 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_PHONE_DUMMY	If this Variable is set to 1 Qt Extended uses a telephony dummy implementation which does not require a real serial device. However its capabilities are limited as well.
QTOPIA_PHONE_MUX	If this variable is set to no disables multiplexing in Qt Extended. See also GSM Modem Integration
QTOPIA_PHONE_VENDOR	Specifies 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:

• Calibration of the touchscreen
• Language Selection
• TimeZone Selection
• Time and Date Format Selection

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:

• FirstUse: if true, the First Use tool will be displayed after the startup.
• NeedTimeZone: if true, the time zone selection dialog will be enabled. This dialog is not required if the device automatically detects the current time and time zone.
• NeedCalibrate: if true, the touchscreen calibration tool will be enabled. The calibration will be enforced if /etc/pointercal is empty or wrong.

UI customization

Styles

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.

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

Theming

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.

• Theming
• Theming Files
• Title Bar Theming
• Context Bar Theming
• Home and Call Screen Themes
• Window Decoration Themes

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.

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

Abstract widget	Description
QAbstractMessageBox	This 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.
QAbstractServerInterface	This 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.
QAbstractBrowserScreen	This 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.
QAbstractCallHistory	This 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.
QAbstractCallScreen	This 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.
QAbstractContextLabel	This 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.
QAbstractDialerScreen	This 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) .
QAbstractHeader	This 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.
QAbstractHomeScreen	This 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.
QAbstractSecondaryDisplay	This 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.
QAbstractTaskManager	This 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:

• Compile and Run the Example Application
• Tutorial: Creating a New Application

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.