kdecore Library API Documentation

KAccel Class Reference

Handle shortcuts. Configurable shortcut support for widgets. More...

#include <kaccel.h>

Inheritance diagram for KAccel:

QAccel List of all members.

Signals

void keycodeChanged ()

Public Methods

 KAccel (QWidget *pParent, const char *psName=0)
 KAccel (QWidget *watch, QObject *parent, const char *psName=0)
virtual ~KAccel ()
KAccelActions & actions ()
const KAccelActions & actions () const
bool isEnabled ()
void setEnabled (bool bEnabled)
bool setAutoUpdate (bool bAuto)
KAccelAction * insert (const QString &sAction, const QString &sLabel, const QString &sWhatsThis, const KShortcut &cutDef, const QObject *pObjSlot, const char *psMethodSlot, bool bConfigurable=true, bool bEnabled=true)
KAccelAction * insert (const QString &sAction, const QString &sLabel, const QString &sWhatsThis, const KShortcut &cutDef3, const KShortcut &cutDef4, const QObject *pObjSlot, const char *psMethodSlot, bool bConfigurable=true, bool bEnabled=true)
KAccelAction * insert (const char *psAction, const KShortcut &cutDef, const QObject *pObjSlot, const char *psMethodSlot, bool bConfigurable=true, bool bEnabled=true)
KAccelAction * insert (KStdAccel::StdAccel id, const QObject *pObjSlot, const char *psMethodSlot, bool bConfigurable=true, bool bEnabled=true)
bool remove (const QString &sAction)
bool updateConnections ()
const KShortcutshortcut (const QString &sAction) const
bool setShortcut (const QString &sAction, const KShortcut &shortcut)
bool setSlot (const QString &sAction, const QObject *pObjSlot, const char *psMethodSlot)
bool setEnabled (const QString &sAction, bool bEnabled)
const QStringconfigGroup () const
void setConfigGroup (const QString &name)
bool readSettings (KConfigBase *pConfig=0)
bool writeSettings (KConfigBase *pConfig=0) const
void emitKeycodeChanged ()
bool insertItem (const QString &sLabel, const QString &sAction, const char *psKey, int nIDMenu=0, QPopupMenu *pMenu=0, bool bConfigurable=true) KDE_DEPRECATED
bool insertItem (const QString &sLabel, const QString &sAction, int key, int nIDMenu=0, QPopupMenu *pMenu=0, bool bConfigurable=true) KDE_DEPRECATED
bool insertStdItem (KStdAccel::StdAccel id, const QString &descr=QString::null) KDE_DEPRECATED
bool connectItem (const QString &sAction, const QObject *pObjSlot, const char *psMethodSlot, bool bActivate=true) KDE_DEPRECATED
KDE_DEPRECATED bool connectItem (KStdAccel::StdAccel accel, const QObject *pObjSlot, const char *psMethodSlot)
bool removeItem (const QString &sAction) KDE_DEPRECATED
bool setItemEnabled (const QString &sAction, bool bEnable) KDE_DEPRECATED
void changeMenuAccel (QPopupMenu *menu, int id, const QString &action) KDE_DEPRECATED
void changeMenuAccel (QPopupMenu *menu, int id, KStdAccel::StdAccel accel) KDE_DEPRECATED
int currentKey (const QString &action) const KDE_DEPRECATED
QString findKey (int key) const KDE_DEPRECATED

Static Public Methods

int stringToKey (const QString &) KDE_DEPRECATED

Protected Methods

virtual void virtual_hook (int id, void *data)

Friends

class KAccelPrivate

Detailed Description

Handle shortcuts. Configurable shortcut support for widgets.

Allow a user to configure shortcuts through application configuration files or through the KKeyChooser GUI.

A KAccel contains a list of accelerator actions.

For example, CTRL+Key_P could be a shortcut for printing a document. The key codes are listed in qnamespace.h. "Print" could be the action name for printing. The action name identifies the shortcut in configuration files and the KKeyChooser GUI.

A KAccel object handles key events sent to its parent widget and to all children of this parent widget. The most recently created KAccel object has precedence over any KAccel objects created before it. When a shortcut pressed, KAccel calls the slot to which it has been connected. If you want to set global accelerators, independent of the window which has the focus, use KGlobalAccel.

Reconfiguration of a given shortcut 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. A convenience method is 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* pAccel = new KAccel( this );

 // Insert an action "Scroll Up" which is associated with the "Up" key:
 pAccel->insert( "Scroll Up", i18n("Scroll up"),
                       i18n("Scroll up the current document by one line."),
                       Qt::Key_Up, this, SLOT(slotScrollUp()) );
 // Insert an standard acclerator action.
 pAccel->insert( KStdAccel::Print, this, SLOT(slotPrint()) );

 // Update the shortcuts by read any user-defined settings from the
 //  application's config file.
 pAccel->readSettings();
 *

See also:
KGlobalAccel , KAccelShortcutList , KKeyChooser , KKeyDialog
Version:
Id:
kaccel.h,v 1.99 2003/11/02 13:50:14 lukas Exp

Definition at line 94 of file kaccel.h.


Constructor & Destructor Documentation

KAccel::KAccel QWidget   pParent,
const char *    psName = 0
 

Creates a new KAccel that watches pParent, which is also the QObject's parent.

Parameters:
pParent  the parent and widget to watch for key strokes
psName  the name of the QObject

Definition at line 342 of file kaccel.cpp.

KAccel::KAccel QWidget   watch,
QObject   parent,
const char *    psName = 0
 

Creates a new KAccel that watches watch.

Parameters:
watch  the widget to watch for key strokes
parent  the parent of the QObject
psName  the name of the QObject

Definition at line 349 of file kaccel.cpp.


Member Function Documentation

bool KAccel::isEnabled  
 

Checks whether the KAccel is active.

Returns:
true if the QAccel enabled

Definition at line 366 of file kaccel.cpp.

void KAccel::setEnabled bool    bEnabled
 

Enables or disables the KAccel.

Parameters:
bEnabled  true to enable, false to disable

Reimplemented from QAccel.

Definition at line 367 of file kaccel.cpp.

Referenced by setItemEnabled().

bool KAccel::setAutoUpdate bool    bAuto
 

Enable auto-update of connections.

This means that the signals are automatically disconnected when you disable an action, and re-enabled when you enable it. By default auto update is turned on. If you disable auto-update, you need to call updateConnections() after changing actions.

Parameters:
bAuto  true to enable, false to disable
Returns:
the value of the flag before this call

Definition at line 368 of file kaccel.cpp.

KAccelAction * KAccel::insert const QString   sAction,
const QString   sLabel,
const QString   sWhatsThis,
const KShortcut   cutDef,
const QObject   pObjSlot,
const char *    psMethodSlot,
bool    bConfigurable = true,
bool    bEnabled = true
 

Create an accelerator action.

Usage:

 insert( "Do Something", i18n("Do Something"),
   i18n("This action allows you to do something really great with this program to "
        "the currently open document."),
   ALT+Key_D, this, SLOT(slotDoSomething()) );
     *
Parameters:
sAction  The internal name of the action.
sLabel  An i18n'ized short description of the action displayed when using KKeyChooser to reconfigure the shortcuts.
sWhatsThis  An extended description of the action.
cutDef  The default shortcut.
pObjSlot  Pointer to the slot object.
psMethodSlot  Pointer to the slot method.
bConfigurable  Allow the user to change this shortcut if set to 'true'.
bEnabled  The action will be activated by the shortcut if set to 'true'.

Definition at line 370 of file kaccel.cpp.

Referenced by connectItem().

KAccelAction * KAccel::insert const QString   sAction,
const QString   sLabel,
const QString   sWhatsThis,
const KShortcut   cutDef3,
const KShortcut   cutDef4,
const QObject   pObjSlot,
const char *    psMethodSlot,
bool    bConfigurable = true,
bool    bEnabled = true
 

Same as first insert(), but with separate shortcuts defined for 3- and 4- modifier defaults.

Definition at line 381 of file kaccel.cpp.

KAccelAction * KAccel::insert const char *    psAction,
const KShortcut   cutDef,
const QObject   pObjSlot,
const char *    psMethodSlot,
bool    bConfigurable = true,
bool    bEnabled = true
 

This is an overloaded function provided for convenience.

The advantage of this is when you want to use the same text for the name of the action as for the user-visible label.

Usage:

 insert( i18n("Do Something"), ALT+Key_D, this, SLOT(slotDoSomething()) );
Parameters:
psAction  The name AND label of the action.
cutDef  The default shortcut for this action.
pObjSlot  Pointer to the slot object.
psMethodSlot  Pointer to the slot method.
bConfigurable  Allow the user to change this shortcut if set to 'true'.
bEnabled  The action will be activated by the shortcut if set to 'true'.

Definition at line 392 of file kaccel.cpp.

KAccelAction * KAccel::insert KStdAccel::StdAccel    id,
const QObject   pObjSlot,
const char *    psMethodSlot,
bool    bConfigurable = true,
bool    bEnabled = true
 

Similar to the first insert() method, but with the action name, short description, help text, and default shortcuts all set according to one of the standard accelerators.

See also:
KStdAccel.

Definition at line 402 of file kaccel.cpp.

References QString::isEmpty(), and KStdAccel::name().

bool KAccel::remove const QString   sAction
 

Removes the accelerator action identified by the name.

Remember to also call updateConnections().

Parameters:
sAction  the name of the action to remove
Returns:
true if successful, false otherwise

Definition at line 420 of file kaccel.cpp.

bool KAccel::updateConnections  
 

Updates the connections of the accelerations after changing them.

This is only necessary if you have disabled auto updates which are on by default.

Returns:
true if successful, false otherwise
See also:
setAutoUpdate() , getAutoUpdate()

Definition at line 422 of file kaccel.cpp.

const KShortcut & KAccel::shortcut const QString   sAction const
 

Return the shortcut associated with the action named by sAction.

Parameters:
sAction  the name of the action
Returns:
the action's shortcut, or a null shortcut if not found

Definition at line 425 of file kaccel.cpp.

References KShortcut::null().

bool KAccel::setShortcut const QString   sAction,
const KShortcut   shortcut
 

Set the shortcut to be associated with the action named by sAction.

Parameters:
sAction  the name of the action
shortcut  the shortcut to set
Returns:
true if successful, false otherwise

Definition at line 437 of file kaccel.cpp.

References KShortcut::toStringInternal().

bool KAccel::setSlot const QString   sAction,
const QObject   pObjSlot,
const char *    psMethodSlot
 

Set the slot to be called when the shortcut of the action named by sAction is pressed.

Parameters:
sAction  the name of the action
pObjSlot  the owner of the slot
psMethodSlot  the name of the slot
Returns:
true if successful, false otherwise

Definition at line 431 of file kaccel.cpp.

Referenced by connectItem().

bool KAccel::setEnabled const QString   sAction,
bool    bEnabled
 

Enable or disable the action named by sAction.

Parameters:
sAction  the action to en-/disable
bEnabled  true to enable, false to disable
Returns:
true if successful, false otherwise

Definition at line 434 of file kaccel.cpp.

const QString & KAccel::configGroup   const
 

Returns the configuration group of the settings.

Returns:
the configuration group
See also:
KConfig

Definition at line 449 of file kaccel.cpp.

void KAccel::setConfigGroup const QString   name
 

Returns the configuration group of the settings.

Parameters:
name  the new configuration group
See also:
KConfig

Definition at line 452 of file kaccel.cpp.

bool KAccel::readSettings KConfigBase   pConfig = 0
 

Read all shortcuts from pConfig, or (if pConfig is zero) from the application's configuration file KGlobal::config().

The group in which the configuration is stored can be set with setConfigGroup().

Parameters:
pConfig  the configuration file, or 0 for the application configuration file
Returns:
true if successful, false otherwise

Definition at line 455 of file kaccel.cpp.

bool KAccel::writeSettings KConfigBase   pConfig = 0 const
 

Write the current shortcuts to pConfig, or (if pConfig is zero) to the application's configuration file.

Parameters:
pConfig  the configuration file, or 0 for the application configuration file
Returns:
true if successful, false otherwise

Definition at line 461 of file kaccel.cpp.

void KAccel::emitKeycodeChanged  
 

Emits the keycodeChanged() signal.

Definition at line 464 of file kaccel.cpp.

References keycodeChanged().

void KAccel::keycodeChanged   [signal]
 

Emitted when one of the key codes has changed.

Referenced by emitKeycodeChanged().

bool KAccel::insertItem const QString   sLabel,
const QString   sAction,
const char *    psKey,
int    nIDMenu = 0,
QPopupMenu   pMenu = 0,
bool    bConfigurable = true
 

Deprecated:
use insert

Definition at line 475 of file kaccel.cpp.

bool KAccel::insertItem const QString   sLabel,
const QString   sAction,
int    key,
int    nIDMenu = 0,
QPopupMenu   pMenu = 0,
bool    bConfigurable = true
 

Deprecated:
use insert

Definition at line 487 of file kaccel.cpp.

References KShortcut::init().

bool KAccel::insertStdItem KStdAccel::StdAccel    id,
const QString   descr = QString::null
 

Deprecated:
use insert

Definition at line 501 of file kaccel.cpp.

bool KAccel::connectItem const QString   sAction,
const QObject   pObjSlot,
const char *    psMethodSlot,
bool    bActivate = true
 

Deprecated:
use insert

Definition at line 512 of file kaccel.cpp.

References setSlot().

KDE_DEPRECATED bool KAccel::connectItem KStdAccel::StdAccel    accel,
const QObject   pObjSlot,
const char *    psMethodSlot
[inline]
 

Deprecated:
use insert( accel, pObjSlot, psMethodSlot );

Definition at line 342 of file kaccel.h.

References insert().

bool KAccel::removeItem const QString   sAction
 

Deprecated:
use remove

Definition at line 523 of file kaccel.cpp.

bool KAccel::setItemEnabled const QString   sAction,
bool    bEnable
 

Deprecated:

Definition at line 526 of file kaccel.cpp.

References setEnabled().

void KAccel::changeMenuAccel QPopupMenu   menu,
int    id,
const QString   action
 

Deprecated:

Definition at line 529 of file kaccel.cpp.

References QPopupMenu::changeItem(), QString::find(), QString::isEmpty(), QPixmap::isNull(), QString::length(), QPopupMenu::pixmap(), QString::replace(), and QPopupMenu::text().

Referenced by changeMenuAccel().

void KAccel::changeMenuAccel QPopupMenu   menu,
int    id,
KStdAccel::StdAccel    accel
 

Deprecated:

Definition at line 556 of file kaccel.cpp.

References changeMenuAccel().

int KAccel::stringToKey const QString   [static]
 

Deprecated:

Definition at line 561 of file kaccel.cpp.

int KAccel::currentKey const QString   action const
 

Deprecated:
Use shortcut().
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.

Definition at line 566 of file kaccel.cpp.

QString KAccel::findKey int    key const
 

Deprecated:
Use actions().actionPtr().
Return the name of the accelerator item with the keycode key, or QString::null if the item cannot be found.

Definition at line 574 of file kaccel.cpp.


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdecore Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sun May 16 22:01:24 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003