# class KAccel | Configurable key binding support. More...
Definition | `#include <kaccel.h>`
Inherits | QAccel (qt) [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Methods

- KAccel ( QWidget * parent, const char *name = 0 )
- void clear ()
- void connectItem ( const QString& action, const QObject* receiver, const char *member, bool activate = true )
- void connectItem ( KStdAccel::StdAccel accel, const QObject* receiver, const char *member, bool activate = true )
- uint count () const
- int currentKey ( const QString& action ) const
- QString description ( const QString& action ) const
- void setDescription (const QString &action, const QString &description)
- int defaultKey ( const QString& action) const
- void disconnectItem ( const QString& action, const QObject* receiver, const char *member )
- QString findKey ( int key ) const
- bool insertItem ( const QString& descr, const QString& action, int defaultKeyCode, bool configurable = true )
- bool insertItem ( const QString& descr, const QString& action, int defaultKeyCode, int id, QPopupMenu *qmenu, bool configurable = true )
- bool insertItem ( const QString& descr, const QString& action, const QString& defaultKeyCode, bool configurable = true )
- bool insertItem ( const QString& descr, const QString& action, const QString& defaultKeyCode, int id, QPopupMenu *qmenu, bool configurable = true )
- bool insertStdItem ( KStdAccel::StdAccel id, const QString& descr = QString::null )
- bool insertItem ( const QString& action, int defaultKeyCode, bool configurable = true )
- bool insertItem ( const QString& action, int defaultKeyCode, int id, QPopupMenu *qmenu, bool configurable = true )
- void removeItem ( const QString& action )
- void changeMenuAccel ( QPopupMenu *menu, int id, const QString& action )
- void changeMenuAccel ( QPopupMenu *menu, int id, KStdAccel::StdAccel accel )
- bool setKeyDict ( const KKeyEntryMap& nKeyDict )
- KKeyEntryMap keyDict () const
- void readSettings (KConfig* config = 0)
- void writeSettings (KConfig* config = 0) const
- void setConfigGroup ( const QString& group )
- QString configGroup () const
- void setConfigGlobal ( bool global )
- bool configGlobal () const
- void setEnabled ( bool activate )
- bool isEnabled () const
- void setItemEnabled ( const QString& action, bool activate )
- bool isItemEnabled ( const QString& action ) const
- bool configurable ( const QString &action ) const
- bool updateItem ( const QString &action, int keyCode)
- void clearItem (const QString &action)
- void removeDeletedMenu (QPopupMenu *menu)

#### Signals

- void keycodeChanged ()

#### Public Static Methods

- static int stringToKey ( const QString& sKey )
- static QString keyToString ( int keyCode, bool i18_n = FALSE)

#### Protected Members

- int aAvailableId
- KKeyEntryMap aKeyMap
- bool bEnabled
- bool bGlobal
- QString aGroup

## Detailed Description

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 identifies 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 such as 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 used only 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.

KAccel ( QWidget * parent, const char *name = 0 ) | ### KAccel

Create a KAccel object with a parent widget and a name.

void clear () | ### clear

Remove all accelerator items.

Reimplemented from QAccel.

void connectItem ( const QString& action, const QObject* receiver, const char *member, bool activate = true ) | ### connectItem

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 connectItem ( KStdAccel::StdAccel accel, const QObject* receiver, const char *member, bool activate = true ) | ### connectItem

Same as the preceding connectItem(), but used for standard accelerators.

If the standard accelerator was not inserted so far, it will be inserted automatically.

Reimplemented from QAccel.

uint count () | ### count

[const]

Retrieve the number of accelerator items.

Reimplemented from QAccel.

int currentKey ( const QString& action ) | ### currentKey

[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 description ( const QString& action ) | ### description

[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.

void setDescription (const QString &action, const QString &description) | ### setDescription

int defaultKey ( const QString& action) | ### defaultKey

[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 disconnectItem ( const QString& action, const QObject* receiver, const char *member ) | ### disconnectItem

Disconnect an accelerator item from a function in another object.

Reimplemented from QAccel.

QString findKey ( int key ) | ### findKey

[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 insertItem ( const QString& descr, const QString& action, int defaultKeyCode, bool configurable = true ) | ### insertItem

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 insertItem ( const QString& descr, const QString& action, int defaultKeyCode, int id, QPopupMenu *qmenu, bool configurable = true ) | ### insertItem

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 items associated with this action.
qmenu | Menu containing items 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 insertItem ( const QString& descr, const QString& action, const QString& defaultKeyCode, bool configurable = true ) | ### insertItem

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 items associated with this action.
qmenu | Menu containing items 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 insertItem ( const QString& descr, const QString& action, const QString& defaultKeyCode, int id, QPopupMenu *qmenu, bool configurable = true ) | ### insertItem

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 insertStdItem ( KStdAccel::StdAccel id, const QString& descr = QString::null ) | ### insertStdItem

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 @pHelp. param descr You can optionally also assign a description to the standard item which may be used a in a popup menu.

bool insertItem ( const QString& action, int defaultKeyCode, bool configurable = true ) | ### insertItem

Convenience function form of insertItem() without the need to specify a localized function name for the user.

This is useful if the accelerator is used internally only, without appearing in a menu or a keybinding editor.

Reimplemented from QAccel.

bool insertItem ( const QString& action, int defaultKeyCode, int id, QPopupMenu *qmenu, bool configurable = true ) | ### insertItem

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 removeItem ( const QString& action ) | ### removeItem

Remove the accelerator item with the action name action.

Reimplemented from QAccel.

void changeMenuAccel ( QPopupMenu *menu, int id, const QString& action ) | ### changeMenuAccel

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 changeMenuAccel ( QPopupMenu *menu, int id, KStdAccel::StdAccel accel ) | ### changeMenuAccel

Same as changeMenuAccel() but for standard accelerators.

bool setKeyDict ( const KKeyEntryMap& nKeyDict ) | ### setKeyDict

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.

KKeyEntryMap keyDict () | ### keyDict

[const]

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 readSettings (KConfig* config = 0) | ### readSettings

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 writeSettings (KConfig* config = 0) | ### writeSettings

[const]

Write the current configurable associations to `config`, or (if `config` is zero) to the application's configuration file.

void setConfigGroup ( const QString& group ) | ### setConfigGroup

Set the group in the configuration file in which the accelerator settings are stored.

By default, this is "Keys".

QString configGroup () | ### configGroup

[const]

Retrieve the name of the group in which accelerator settings are stored.

void setConfigGlobal ( bool global ) | ### setConfigGlobal

If `global` is true, KAccel writes to the global configuration file, instead of the application configuration file.

bool configGlobal () | ### configGlobal

[const]

Will KAccel write to the global configuration file (instead of the application configuration file)?

void setEnabled ( bool activate ) | ### setEnabled

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 isEnabled () | ### isEnabled

[const]

Are accelerators enabled?

Reimplemented from QAccel.

void setItemEnabled ( const QString& action, bool activate ) | ### setItemEnabled

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 isItemEnabled ( const QString& action ) | ### isItemEnabled

[const]

Check whether a specific accelerator, `action`, is enabled.

Reimplemented from QAccel.

bool configurable ( const QString &action ) | ### configurable

[const]

Returns `true` if keyentry can be modified.

bool updateItem ( const QString &action, int keyCode) | ### updateItem

Change the keycode for an accelerator.

void clearItem (const QString &action) | ### clearItem

Remove the keycode for an accelerator.

void removeDeletedMenu (QPopupMenu *menu) | ### removeDeletedMenu

Clear any pointers to a menu.

int stringToKey ( const QString& sKey ) | ### stringToKey

[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 not be i18n()'d!

Reimplemented from QAccel.

QString keyToString ( int keyCode, bool i18_n = FALSE) | ### keyToString

[static]

Retrieve a string corresponding to the key code `keyCode`, which is empty if `keyCode` is not recognized or zero.

Reimplemented from QAccel.

void keycodeChanged () | ### keycodeChanged

[signal]

int aAvailableId | ### aAvailableId

[protected]

KKeyEntryMap aKeyMap | ### aKeyMap

[protected]

bool bEnabled | ### bEnabled

[protected]

bool bGlobal | ### bGlobal

[protected]

QString aGroup | ### aGroup

[protected]

- Version: $Id: kaccel.h,v 1.43 2000/09/24 08:19:21 coolo Exp $
- Generated: root@sparc.ports.openbsd.org on Wed May 2 09:34:58 2001, using kdoc 2.0a53.