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.
