|
Home · All Classes · Grouped Classes · Annotated · Functions | |
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.
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()
[Button2]
Name=Multitasking Button
Key=Home
PressedActionMappable=0
PressedActionService=TaskManager
PressedActionMessage=multitask()
HeldActionMappable=0
HeldActionService=TaskManager
HeldActionMessage=showRunningTasks()
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.
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
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.
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.
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
| Copyright © 2007 Trolltech | Trademarks | Qtopia 4.2.5 |