Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

Keypad Button Behavior

• Keypad Button Behavior
• User Definable Button Mappings
• Phone Launcher Menu
• Phone Buttons
• Input Methods
• Phone SoftKey Definition
• Usual Key Meanings

Keypad Button Behavior

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 Definable Button Mappings

Button Mappings map the hard buttons on a device to application actions. 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=3
    [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()
    [Button2]
    Name=Multitasking Button
    Key=Home
    PressedActionMappable=0
    PressedActionService=TaskManager
    PressedActionMessage=multitask()
    HeldActionMappable=0
    HeldActionService=TaskManager
    HeldActionMessage=showRunningTasks()
    [Button3]
    Name=Power Button
    Key=Hangup
    HeldActionService=Launcher
    HeldActionMessage=execute(QString)
    HeldActionArgs=@ByteArray(\0\0\0\x1\0\0\0\n\0\0\0\0\x10\0s\0h\0u\0t\0\x64\0o\0w\0n)

This example describes a device with three hardware buttons. One that opens the calendar application, one that opens the contacts application or beams the owners business card, and a third that is used for multitasking.

    [Button]
    Count=3

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

If your driver does not already map to the right keycode a custom driver may be required. Driver's can be added by deriving from the QWSMouseHandler and QMouseDriverPlugin classes, or the QWSKeyboardHandler and QKbdDriverPlugin classes, and using Qt's plugin mechanism. See the How to Create Qt Plugins documentation and the Plug & Paint example for details.

    PressedActionService=Calendar
    PressedActionMessage=raiseToday()
    HeldActionService=Calendar
    HeldActionMessage=raise()

These describe what occurs when a button is pressed or held. The Service is a Qt Extended Service, described in Qt Extended 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 Qt Extended calendar application. Only actions that take no parameters can be used.

The "Multitasking Button" in the example uses:

    HeldActionMappable=0

To disable the user from changing the button's functionality. This could be important for certain usability or branding considerations.

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=Applications/simapp.desktop{@/Telephony/Status/SimToolkitAvailable},Applications/calculator.desktop
    8=Applications
    9=Documents

Note the example for button 7 is a list of alternatives separated by commas. The first alternative (simapp.desktop) is only used if the bracketed Qt Extended Expression evaluates to true. By using an expression that references the Value Space, this mechanism allows the function associated with a button to be determined dynamically.

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. By default each key is associated only with it's moniker so the '2' key enters a 2, the '#' enters '#' etc.

The LocaleTextButtons modifies or extends the TextButtons section, but only defines the text associated with the current language. The texts in these sections are translated in the standard way for Config files. Any buttons not specified are drawn from TextButtons.

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

TextButtons and PhoneTextButtons can also be used as a base for widgets using custom input method hints.

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.
  • "\\"textc{"} - 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 "\\"textc{"} is not supported.

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.

Input Methods

The format of the input method section is as follows:

    [InputMethods]
    DefaultIM=Phone Keys

If the named input method is available, it will be activated by default on startup. If this entry is not present, the default input method depends on the PrimaryInput entry of the Device section.

Additionally, configuration options for the symbol picker are available. For backwards compatibility, these are in a different section as follows:

    [IMethod]
    picker_width=13
    picker_font_point_size=6

picker_width determines the number of characters per row on the symbol picker, and picker_font_point_size determines the size of the font used on the symbol picker. If this results in too many characters per row to fit onscreen, the rightmost characters will not be visible.

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

Usual Key Meanings

This section describes the usual key meanings that Qt Extended uses, across many different device categories. If your device has a similar key, it is recommended that you choose the mapping in this list.

The following keys are handled specially in the source code, and should be mapped exactly as listed here:

The following table indicates special functions that are usually handled in the defaultbuttons.conf file rather than in the source code. Keys that only appear in defaultbuttons.conf can be mapped to any function key, but the following mappings are recommended for consistency across device types: