[kdecore Index] [kdecore Hierarchy] [Headers]
Configurable key binding support. More...
#include <kaccel.h>
The KAccel class handles keyboard accelerators, allowing a user to configure key bindings through application configuration files or through the KKeyChooser GUI.
A KAccel contains a list of accelerator items. Each accelerator item consists of an action name and a keyboard code combined with modifiers (SHIFT, CTRL and ALT.)
For example, "CTRL+P" could be a shortcut for printing a document. The key codes are listed in ckey.h. "Print" could be the action name for printing. The action name indentifies the key binding in configuration files and the KKeyChooser GUI.
When pressed, an accelerator key calls the slot to which it has been connected. Accelerator items can be connected so that a key will activate two different slots.
A KAccel object handles key events to its parent widget and all children of this parent widget.
Key binding configuration during run time can be prevented by specifying that an accelerator item is not configurable when it is inserted. A special group of non-configurable key bindings are known as the standard accelerators.
The standard accelerators appear repeatedly in applications for standard document actions like printing and saving. Convenience methods are available to insert and connect these accelerators which are configurable on a desktop-wide basis.
It is possible for a user to choose to have no key associated with an action.
The translated first argument for insertItem is only used in the configuration dialog.
KAccel *a = new KAccel( myWindow ); a->insertItem( i18n("Scroll up"), "Scroll Up", "Up" ); a->connectItem( "Scroll up", myWindow, SLOT( scrollUp() ) ); // a->insertStdItem( KAccel::Print ); //not necessary, since it // is done automatially with the// connect below!
a->connectItem(KAccel::Print, myWindow, SLOT( printDoc() ) );
a->readSettings();
If a shortcut has a menu entry as well, you could insert them like this. The example is again the KAccel::Print from above.
int id; id = popup->insertItem("&Print",this, SLOT(printDoc())); a->changeMenuAccel(popup, id, KAccel::Print );
If you want a somewhat "exotic" name for your standard print action, like id = popup->insertItem(i18n("Print &Document"),this, SLOT(printDoc())); it might be a good idea to insert the standard action before as a->insertStdItem( KAccel::Print, i18n("Print Document") ) as well, so that the user can easily find the corresponding function.
This technique works for other actions as well, your scroll up function in a menu could be done with
id = popup->insertItem(i18n"Scroll &up",this, SLOT(scrollUp())); a->changeMenuAccel(popup, id, "Scroll Up" );
Please keep the order right: first insert all functions in the acceleratior, then call a->readSettings() and _then_ build your menu structure.
[public]
Creates a KAccel object with a parent widget and a name.
[public]
Destroys the accelerator object.
[public]
Removes all accelerator items.
[public]
Connect an accelerator item to a slot/signal in another object.
Arguments:
member | a slot or signal in the receiver |
activate | indicates whether the accelerator item should be enabled immediately |
receiver | the object to receive a signal |
action | the accelerator item action name. |
[public]
Same as connectItem from above, but for standard accelerators. If the standard accelerator was not inserted so far, it will be inserted automatically.
[public]
Returns the number of accelerator items.
[public]
Returns the key code of the accelerator item with the action name action, or zero if either the action name cannot be found or the current key is set to no key.
[public]
Returns the description of the accelerator item with the action name action, or zero if the action name cannot be found. Useful for menus.
[public]
Returns the default key code of the accelerator item with the action name action, or zero if the action name cannot be found.
[public]
Disconnects an accelerator item from a function in another object.
[public]
Returns that identifier of the accelerator item with the keycode key, or zero if the item cannot be found.
[public]
Inserts an accelerator item and returns -1 if the key code defaultKeyCode is not valid.
Arguments:
configurable | indicates whether a user can configure the key binding using the KKeyChooser GUI and whether the key will be written back to configuration files on calling writeSettings. If an action already exists the old association and connections will be removed.. |
defaultKeyCode | is a key code to be used as the default for the action. |
descr | is the localized name of the action, useful in menus or the keybinding editor. |
action | is the internal accelerator item action name. It is supposed to be the same for all language. |
[public]
Inserts an accelerator item and returns -1 if the key code defaultKeyCode is not valid.
Arguments:
configurable | indicates whether a user can configure the key binding using the KKeyChooser GUI and whether the key will be written back to configuration files on calling writeSettings. If an action already exists the old association and connections will be removed.. |
defaultKeyCode | is a key plus a combination of SHIFT, CTRL and ALT to be used as the default for the action. |
descr | is the localized name of the action, useful in menus or the keybinding editor. |
action | is the internal accelerator item action name. It is supposed to be the same for all language. |
[public]
Inserts a standard accelerator item if id equal to Open, New, Close, Save, Print, Quit, Cut, Copy, Paste, Undo, Find, Replace, Insert, Home, End, Prior, Next, or Help.
If an action already exists the old association and connections will be removed..
You can (optional) also assign a description to the standard item which may be used a in a popup menu.
[public]
Convenience function without the need to specify a localized function name for the user. This is useful if the accelerator is only used internally, without appearing in a menu or a keybinding editor.
[public]
Often (usually?) shortcuts should be visible in the menu structure of an application. Use this function for that purpose. Note that the action must have been inserted before!
[public]
Same as changeMenuAccel but for standard accelerators
[public]
Returns the dictionary of accelerator action names and KKeyEntry objects. Note that only a shallow copy is returned so that items will be lost when the KKeyEntry objects are deleted.
[public]
Reads all key associations from the application's configuration files.
[public]
Removes the accelerator item with the action name action.
[public]
Enables the accelerator if activate is TRUE, or disables it if activate is FALSE..
Individual keys can also be enabled or disabled.
[public]
Enables or disables an accelerator item.
Arguments:
activate | specifies whether the item should be enabled or disabled. |
action | is the accelerator item action name. |
[public]
Sets the dictionary of accelerator action names and KKeyEntry objects to nKeyDict.. Note that only a shallow copy is made so that items will be lost when the KKeyEntry objects are deleted.
[public static]
Returns a standard action name if id equal to Open, New, Close, Save, Print, Quit, Cut, Copy, Paste, Undo, Find, Replace, Insert, Home, End, Prior, Next, or Help and zero otherwise.
[public]
Writes the current configurable associations to the application's configuration files
| Kdoc |