Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded

Qtopia - Customizing Qtopia for a Device: Keys and Buttons

Introduction

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.

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:

scancodeQt key codedescription keypad modeno keypad mode
65 Key_Menu Application menu key OptionalNot Available
67 Key_Back Accept/Close dialog key RequiredNot Available
68 Key_Yes Yes OptionalNot Available
69 Key_No No OptionalNot Available
87 Key_Call Start call, accept incoming callOptionalNot Available
88 Key_Hangup End call, reject incoming call OptionalNot Available
116 Key_Select Select menu option, checkbox, pressbuttonRequiredNot Available
120 F31 Toggle input method OptionalOptional
121 F32 Sync device OptionalOptional
122 F34 Power/Sleep Optional?Required
123 F35 Toggle backlight OptionalOptional
124 Context1 First Context button OptionalNot Available
125 Context2 Second Context button OptionalNot Available
126 Context3 Third Context button OptionalNot Available
127 Context4 Forth Context button OptionalNot 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 codedescription keypad modeno keypad mode
Key_F30 maps to space on widgets that need selectNot ApplicableOptional
Key_F33 maps to enter on widgets that need okNot ApplicableOptional

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.

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.

Configuration of Hardware Buttons

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

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.

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.

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

Non-installed Components

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