|
|
Handle keyboard accelerators.
Allow an 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 sent to its parent widget and to all children of this parent widget.
Key binding reconfiguration 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 ); // Insert an action "Scroll Up" which is associated with the "Up" key: a->insertItem( i18n("Scroll up"), "Scroll Up", "Up" ); // Insert an action "Scroll Down" which is not associated with any key: a->insertItem( i18n("Scroll down"), "Scroll Down", 0); a->connectItem( "Scroll up", myWindow, SLOT( scrollUp() ) ); // a->insertStdItem( KStdAccel::Print ); //not necessary, since it // is done automatially with the // connect below! a->connectItem(KStdAccel::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 KStdAccel::Print from above.
int id; id = popup->insertItem("&Print",this, SLOT(printDoc())); a->changeMenuAccel(popup, id, KStdAccel::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( KStdAccel::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.
|
Create a KAccel object with a parent widget and a name.
void |
Remove all accelerator items.
Reimplemented from QAccel
void |
Connect an accelerator item to a slot/signal in another object.
Arguments:
Parameters:
action | The accelerator item action name. |
receiver | The object to receive a signal. |
member | A slot or signal in the receiver. |
activate | Indicates whether the accelerator item should be enabled immediately. |
Reimplemented from QAccel
void |
Same as connectItem() from above, but for standard accelerators.
If the standard accelerator was not inserted so far, it will be inserted automatically.
Reimplemented from QAccel
uint |
[const]
Retrieve the number of accelerator items.
Reimplemented from QAccel
uint |
[const]
Retrieve 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.
QString |
[const]
Retrieve the description of the accelerator item with the
action name action
, or QString::null if the action name cannot
be found. Useful for menus.
uint |
[const]
Retrieve the default key code of the accelerator item with
the action name
action
, or zero if the action name cannot be found.
void |
Disconnect an accelerator item from a function in another object.
Reimplemented from QAccel
QString |
[const]
Rerieve the identifier of the accelerator item with the keycode key
,
or QString::null if the item cannot be found.
Reimplemented from QAccel
bool |
Insert an accelerator item.
If an action already exists the old association and connections will be removed.
Parameters:
descr | The localized name of the action, useful in menus or the keybinding editor. |
action | The internal accelerator item action name. It is supposed to be the same for all languages. |
defaultKeyCode | A key code to be used as the default for the action. Set it to 0 for no default key (It still may be configured later.) |
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 when writeSettings() is called. |
Returns: true
if successful.
Reimplemented from QAccel
bool |
Insert an accelerator item.
If an action already exists the old association and connections will be removed.
Parameters:
descr | The localized name of the action, useful in menus or the keybinding editor. |
action | The internal accelerator item action name. It is supposed to be the same for all languages. |
defaultKeyCode | A key code to be used as the default for the action. Set it to 0 for no default key (It still may be configured later.) |
id | Menu index of menu item associated with this action. |
qmenu | Menu containing item associated with this action. |
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 when writeSettings() is called. |
Returns: true
if successful.
Reimplemented from QAccel
bool |
Insert an accelerator item.
If an action already exists the old association and connections will be removed.
Parameters:
descr | The localized name of the action, useful in menus or the keybinding editor. |
action | The internal accelerator item action name. It is supposed to be the same for all languages. |
defaultKeyCode | A key plus a combination of Shift, Ctrl and Alt to be used as the default for the action. |
id | Menu index of menu item associated with this action. |
qmenu | Menu containing item associated with this action. |
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 when writeSettings() is called. |
Returns: true
if successful.
Reimplemented from QAccel
bool |
Insert an accelerator item.
If an action already exists the old association and connections will be removed..
Parameters:
descr | The localized name of the action, useful in menus or the keybinding editor. |
action | The internal accelerator item action name. It is supposed to be the same for all languages. |
defaultKeyCode | A key plus a combination of Shift, Ctrl and Alt to be used as the default for the action. |
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 when writeSettings() is called. |
Returns: true
if successful.
Reimplemented from QAccel
bool |
Insert a standard accelerator item.
If an action already exists the old association and connections will be removed. param id One of the following: Open, New, Close, Save, Print, Quit, Cut, Copy, Paste, Undo, Redo, Find, Replace, Insert, Home, End, Prior, Next, or Help. param descr You can optionally also assign a description to the standard item which may be used a in a popup menu.
bool |
Convenience function form of insertItem() 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.
Reimplemented from QAccel
bool |
Convenience function for of insertItem() 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.
Reimplemented from QAccel
void |
Remove the accelerator item with the action name action.
Reimplemented from QAccel
void |
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!
void |
Same as changeMenuAccel() but for standard accelerators.
bool |
Set 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.
QDict<KKeyEntry> |
Retrieve 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.
void |
Read all key associations from config
, or (if config
is zero) from the application's configuration file
KGlobal::config().
The group in which the configuration is stored can be set with setConfigGroup().
void |
Write the current configurable associations to config
,
or (if config
is zero) to the application's
configuration file.
void |
Set the group in the configuration file in which the accelerator settings are stored.
By default, this is "Keys".
QString |
[const]
Retrieve the name of the group in which accelerator settings are stored.
void |
If @global is @true, KAccel writes to the global configurtion file, instead of the application configuration file.
bool |
[const]
Will KAccel write to the global configuration file (instead of the appliation configuration file)?
void |
Enable all accelerators if activate is true
, or disable it if
activate is false
.
Individual keys can also be enabled or disabled.
Reimplemented from QAccel
bool |
[const]
Are accelerators enabled?
Reimplemented from QAccel
void |
Enable or disable an accelerator item.
Parameters:
action | The accelerator item action name. |
activate | Specifies whether the item should be enabled or disabled. |
Reimplemented from QAccel
bool |
[const]
Check whether a specific accelerator, action
, is enabled.
Reimplemented from QAccel
bool |
[const]
Returns true
if keyentry can be modified.
bool |
Change the keycode for an accelerator.
void |
Remove the keycode for an accelerator.
void |
Clear any pointers to a menu.
uint |
[static]
Retrieve the key code corresponding to the string sKey
or
zero if the string
is not recognized.
The string must be something like "Shift+A", "F1+Ctrl+Alt" or "Backspace" for example. That is, the string must consist of a key name plus a combination of the modifiers Shift, Ctrl and Alt.
N.B.: sKey
must @bf not be i18n()'d!
Reimplemented from QAccel
QString |
[static]
Retrieve a string corresponding to the key code keyCode
,
which is empty if
keyCode
is not recognized or zero.
Reimplemented from QAccel