Home · All Classes · Grouped Classes · Annotated · Functions

Keypad Button Behavior

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. 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 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 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 "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 Qtopia Expression evaluates to true. By using an expression that references the Qtopia 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:

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

KeyUsual meaning
Key_Context1Left soft key on the soft menu bar.
Key_SelectCenter soft key on the soft menu bar.
Key_BackRight soft key on the soft menu bar.
Key_Context2, Key_Context3, Key_Context4Other soft keys on the soft menu bar.
Key_CallKey to place a phone call (green key on mobile phones).
Key_HangupKey to hang up a phone call (red key on mobile phones). This key is usually also the power on/off key when held down.
Key_Up, Key_Down, Key_Left, Key_RightDirectional movement keys.
Key_VolumeUp, Key_VolumeDownAdjust the volume of the currently playing media or the current phone call.
Key_FlipKey that is sent whenever a flip phone is opened or closed. A key release event should be sent when the flip is opened, and a key press event sent when the flip is closed.
Key_F27Handset cradle on desk phones. A key release event should be sent when the handset is picked up, and a key press event should be sent when the handset is replaced in the cradle.
Key_F28Key on the headphones, which indicates whether to accept the incoming call or hang up the current call.
Key_F29Lock key, for locking/unlocking the keypad.

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:

KeyUsual meaning
Key_F4Camera key, for launching the camera program, or taking a picture if the camera program is currently active.
Key_F5Headset key, for transfering audio to the headset.
Key_F6Speakerphone key, for transfering audio to the speakerphone.
Key_F7Multitask, showing running tasks in the task manager.
Key_F8Multitask, switching between the running applications.
Key_F9Launch the Datebook application.
Key_F10Launch the Contacts application.
Key_F11Launch the Todo application.
Key_F12Return to the home screen.
Key_F13Launch the Messages application.
Key_F14Voice mail key.
Key_F15Transfer key.
Key_F16Options key.
Key_F17Conference key.
Key_F18Intercom key.
Key_F19Redial key.
Key_F20Hold key.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3