![]() Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference |
![]() |
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.
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.
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:
$QTDIR/configure --help
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:
$QPEDIR/configure --help
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:
cd $QPEDIR/image tar -cf $HOME/qtopiaimage.tar .
mount -t nfs myhost:/home/myuser /mnt/tmp
cd / tar xf /mnt/tmp/qtopiaimage.tar
Note: make install
is an additive process. If the configuration changes, it is necessary to either:
make install
to create a new image
make cleaninstall
from $QPEDIR.
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
if [ ! -d /usr/share/zoneinfo ]; then ln -s /opt/Qtopia/etc/zoneinfo /usr/share/zoneinfo; fi
if [ -d /usr/share/zoneinfo ]; then rm -rf /opt/Qtopia/etc/zoneinfo; ln -s /usr/share/zoneinfo /opt/Qtopia/etc/zoneinfo ; fi
For a device to keep correct time with Qtopia requires the following:
Note: These processes should be tested on the device prior to Qtopia controlling them.
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
Run the following command :
textedit -qws
and confirm that:
See also: Running Qtopia.
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
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. |
The following applications are unsupported 3rd party applications/ports intended purely to demonstrate the flexibility of Qtopia:
Qtopia can run as any user, provided that user has read and write permissions to certain file areas for certain functionality:
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 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.
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.
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.
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.
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()
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.
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.
A number of points should be considered when integrating Qtopia with a device that has power management.
Qtopia's power management is handled by Qt embedded. The QWSServer uses the QWSScreenSaver interface in order to decide what to do. Qtopia provides the screensaver 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.
Qtopia runs the 'apm' command to suspend. The system's AT daemon is used to unsuspend upon RTC alarms. The system's AT daemon is used to write the RTC clock (because on some systems only one process can manipulate the RTC).
The system's "Power" key or the third screensaver level just sends a key (Qt::KeyF34) to Qtopia, which then does the actual suspend. It triggers the execution of ServerApplication::togglePower(). All CPU functions are suspended once
system("apm --suspend");
is executed. Normal operation will resume once a "Wake up" event comes from apmd.
Suspension is not enabled in the phone edition.
"apm --suspend"would suspend the CPU and shutdown the device. This 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.
Qtopia's memory management is divided into two segments. These parts can be controlled via :
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. |
Qtopia includes two classes to support dual screen phones:
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
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.
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.
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.
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.
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.
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.
For information about adding a new mouse driver see : Qt/Embedded Pointer Handling.
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:
To manually start the calibration on a Qtopia phone device, run
qcop "QPE/System" "execute(QString)" "calibrate"
We have found that the implementation of the GSM specification varies
between
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
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.
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
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
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
Qtopia's appearance can be modified on several ways
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.
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.
To make extra fonts available to Qtopia it is likely that the makeqpf ultility will need to be run. For more details see : makeqpf
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.
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
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
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.
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
Qtopia has 3 ways that it identifies storage locations.
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.
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.
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.
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).
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.
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.
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:
Qtopia does not include a WAP stack with the MMS client. Instead, an interface is provided which allows any WAP stack to be integrated. The MmsComms class must be subclassed and the virtual functions implemented and signals emitted as appropriate. The MmsCommsHttp class provides a sample implementation using HTTP over TCP/IP see : $QPEDIR/src/applications/qtmail/mmscomms_http.{cpp,h}
To choose an alternate WAP stack connection method
The AMR encoder included with Qtopia is a reference implementation only. It is recommended that an encoder optimized for the target platform be installed. The media recorder plug-in interface provides a convenient method of integrating the codec. See MediaRecorderEncoder class.
Copyright © 2005 Trolltech | Trademarks | Qtopia version 2.2.0
|