Detailed Description
The QDeviceButtonManager class manages device button mappings.
The function buttons on a device may generate key presses and also activate services. QDeviceButtonManager allows the role of the function buttons to be accessed or modified.
The device key mapping configuration can be stored in one of two configuration files, each with the same syntax. The first is the device's defaultbuttons.conf file, located under the $QPEDIR/etc path and the second is the standard Trolltech/ButtonSettings configuration file. Conflicting entries in the Trolltech/ButtonSettings will override the defaultbuttons.conf versions.
The general configuration format is:
[Button]
Count=<mapped button count>
[Button<X>]
Name[]=<User Visible Name>
Key=<Key name>
Context=<Applicable Context>
PressedActionMappable=[0|1]
PressedActionService=<Service name>
PressedActionMessage=<Message type>
PressedActionArgs=<Argument list>
HeldActionMappable=[0|1]
HeldActionService=<Service name>
HeldActionMessage=<Message type>
HeldActionArgs=<Argument list>
The first group, Button contains the number of mappings present in the file. Subsequent Button<X> groups are then named from X = 0 ... Count - 1 to represent each mapped key.
Each key mapping contains the key to which it maps, a name, a context and the actions to take when the key is pressed and when it is held. The key is mandatory and can be any one of the keys named in the Qt::Key enum. For example, Context1 and F34 are both valid. The user visible name and context are accessible through QDeviceButton::userText() and QDeviceButton::context() respectively.
The PressedActionMappable and HeldActionMappable allow the mapping for either the pressed or held action to be disabled. If ommitted, each action is enabled (assuming the service and message information required to define a complete action is present).
The PressedActionMessage and PressedActionService define the message and the service to which the message will be sent. The PressedActionArgs defines the arguments to send with the message and is deserialized using the QtopiaServiceRequest::deserializeArguments() method. The held action grouping takes the same form as the pressed action.
Whenever the device buttons are updated through the QDeviceButtonManager API, a deviceButtonMappingChanged() message is sent on the QPE/System channel.
The Buttons settings application in Qt Extended allows the user to configure mappable device buttons.
Member Function Documentation
const QDeviceButton * QDeviceButtonManager::buttonForKeycode ( int keyCode ) const
Returns the QDeviceButton for the keyCode in the global context. If keyCode is not found, it returns 0.
const QDeviceButton * QDeviceButtonManager::buttonForKeycode ( int keyCode, const QString & context ) const
This is an overloaded member function, provided for convenience.
Returns the QDeviceButton for the keyCode in a certain context. If keyCode is not found, it returns 0.
const QList<QDeviceButton *> & QDeviceButtonManager::buttons () const
Returns the available buttons on this device. The number and location of buttons will vary depending on the device. Button numbers will be assigned by the device manufacturer and will be from most preferred button to least preffered button. Note that this list only contains user-programmable buttons.
void QDeviceButtonManager::factoryResetButtons ()
Reset the buttons back to the factory default settings.
QDeviceButtonManager & QDeviceButtonManager::instance () [static]
Returns an instance of the QDeviceButtonManager. QDeviceButtonManager cannot be constructed explicitly.
void QDeviceButtonManager::remapHeldAction ( int button_index, const QtopiaServiceRequest & action )
Reassigns the held action for button_index to action.
void QDeviceButtonManager::remapPressedAction ( int button_index, const QtopiaServiceRequest & action )
Reassigns the pressed action for button_index to action.
void QDeviceButtonManager::remapReleasedAction ( int button_index, const QtopiaServiceRequest & action )
Reassigns the released action for button_index to action.
