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

# Qtopia - Customizing Qtopia for a Device: Keys and Buttons

- Introduction
- Default scan-codes for Qtopia keys
  - Overriding scancode mapping for Qtopia
  - Overriding the keyboard handler Qtopia Keys
  - Key behavior in Qtopia
    - Keys that are always intercepted
    - Keys that are sometimes intercepted
- Configuration of Hardware Buttons
  - User Defineable Button Mappings
  - Phone Launcher Menu
  - Phone Buttons
  - Phone SoftKey Definition
- Non-installed Components

## 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:

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:

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

Qtopia also acts upon:

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

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 Qt Key for the scan code
- The unicode character for the scan code
- The unicode character for the scan code if shift is active
- The unicode character for the scan code if control is active

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.

- Key_F30
- Key_F31
- Key_F32
- Key_F33
- Key_F34
- Key_F35
- Key_NumLock
- Key_CapsLock
- Key_Menu
- Key_Call
- Key_Hangup
- Key_Flip

#### Keys that are sometimes intercepted

- Key_Escape Rejects active dialog
- Key_F33 Accepts active dialog
- Key_Back Accepts active dialog
- Key_Context1 When behaving as Key_Menu

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:

- TapX - the action to do when key X is pressed and released. This is either:
  - 'text - insert character from text.
  - "text - insert character from text, while showing all options.
  - space - insert a space.
  - symbol - popup symbol selector.
  - modify - choose between alternatives.
  - mode - change mode or language.
  - shift - toggle upper/lowercase.
- HoldX - the action to do when key X is held down. This is the same as for Tap, except "text is not supported.

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:

- Rotation Setting - This is provided to test and demonstrate Qtopia's ability to display in different orientations. This may be helpful during development if the device uses the transformation display driver.
- Shutdown Setting - This is provided as a development tool. It 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 screensizes quickly during development. This is a development tool only which is also not intended for end users.
- Terminal - This is provided as a development tool. It may be reasonable to provide this as a seperate installable package for advanced users who are familiar with Linux however it is not expected that the majority of users will find this tool at all useful, only confusing. Therefore it is recommended this program is not included.
- File Manager - Provided as a development tool. Qtopia is functional without it using just Qtopia's 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.