![]() Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |
![]() |
This document sets out the key and button related implementation requirements for specific devices and makes recommendations for the optimal installation of Qtopia on a handheld device. How you install Qtopia on a given device will be determined by the functionality of that device.
This document should be read in conjunction with Qtopia - Customizing Qtopia for a Device.
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 | Forth 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 select | Not Applicable | Optional |
Key_F33 | maps to enter on widgets that need ok | Not Applicable | Optional |
Qtopia is designed to be flexible in terms of the keys required. The default mapping for Qtopia has the following keys:
Qtopia also acts upon:
Qtopia can operate without Key_Call and Key_Hangup.
Qtopia can operate without Key_Left and Key_Right.
Qtopia can operate with Key_Menu rather than Key_Context1.
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.
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
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. You can also provide Translations for the button's name by include a field with:
Name[ja]=...
This line describes the name of the button if the language is set to 'ja' or Japanese.
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.
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.
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
There are a number of applications/features supplied with Qtopia that are not intended to be shipped with production devices:
Copyright © 2001-2005 Trolltech | Trademarks | Qtopia version 2.1.1
|