The QAccel class handles keyboard accelerator and shortcut keys. More...
#include <qaccel.h>
Inherits QObject.
A keyboard accelerator triggers an action when a certain key combination is pressed. The accelerator handles all keyboard activity for all children of one top level widget, so it is not affected by the keyboard focus.
In most cases, you will not need to use this class directly. Use QMenuData::insertItem() or QMenuData::setAccel() to make accelerators for operations that are also available on menus. Many widgets automatically generate accelerators, such as QButton, QGroupBox, QLabel(with QLabel::setBuddy()), QMenuBar and QTabBar. Example:
QPushButton p( "&Exit", parent ); //automatic shortcut ALT+Key_E QPopupMenu *fileMenu = new fileMenu( parent ); fileMenu->insertItem( "Undo", parent, SLOT(undo()), CTRL+Key_Z );
A QAccel contains a list of accelerator items. The following functions manipulate the list: insertItem(), removeItem(), clear(), key(), findKey().
Each accelerator item consists of an identifier and a keyboard code
combined with modifiers (SHIFT, CTRL, ALT
or UNICODE_ACCEL).
For example, CTRL + Key_P
could be a
shortcut for printing a document. The key codes are listed in
qnamespace.h. As an alternative, use UNICODE_ACCEL
with the
unicode value of the character. For example, UNICODE_ACCEL +
'A'
gies the same accelerator as Key_A.
When an accelerator key is pressed, the accelerator sends out the signal activated() with a number that identifies this particular accelerator item. Accelerator items can also be individually connected, so that two different keys will activate two different slots (see connectItem() and disconnectItem()).
Use setEnabled() to enable/disable all items in the accelerator, or setItemEnabled() to enable/disable individual items.
The function setWhatsThis() specifies the What's This text for an accelerator item.
A QAccel object handles key events to the QWidget::topLevelWidget() containing parent, and hence to any child widgets of that window. The accelerator will be deleted when parent is deleted, and will consume relevant key events until then.
Example:
QAccel *a = new QAccel( myWindow ); // create accels for myWindow a->connectItem( a->insertItem(Key_P+CTRL), // adds Ctrl+P accelerator myWindow, // connected to myWindow's SLOT(printDoc()) ); // printDoc() slot
See also: QKeyEvent, QWidget::keyPressEvent(), QMenuData::setAccel(), QButton::setAccel(), QLabel::setBuddy() and GUI Design Handbook: Keyboard Shortcuts
Constructs a QAccel object with parent parent and name name. The accelerator operates on parent.
Constructs a QAccel object that operates on watch, but is a child of parent.
This constructor is not needed for normal application programming.
Destructs the accelerator object.
[signal]
This signal is emitted when an accelerator key is pressed. id is a number that identifies this particular accelerator item.
Removes all accelerator items.
Connects an accelerator item to a slot/signal in another object.
id is the accelerator item id. receiver is the object to receive a signal. member is a slot or signal function in the receiver.
a->connectItem( 201, mainView, SLOT(quit()) );
See also: disconnectItem().
Returns the number of accelerator items in this accelerator.
Disconnects an accelerator item from a function in another object.
See also: connectItem().
[virtual protected]
Processes accelerator events intended for the top level widget.
Reimplemented from QObject.
Returns the identifier of the accelerator item with the key code key, or -1 if the item cannot be found.
Inserts an accelerator item and returns the item's identifier.
key is a key code plus a combination of SHIFT, CTRL and ALT. id is the accelerator item id.
If id is negative, then the item will be assigned a unique negative identifier.
QAccel *a = new QAccel( myWindow ); // create accels for myWindow a->insertItem( Key_P + CTRL, 200 ); // Ctrl+P to print document a->insertItem( Key_X + ALT , 201 ); // Alt+X to quit a->insertItem( UNICODE_ACCEL + 'q', 202 ); // Unicode 'q' to quit a->insertItem( Key_D ); // gets a unique negative id a->insertItem( Key_P + CTRL + SHIFT ); // gets a unique negative id
Returns TRUE if the accelerator is enabled, or FALSE if it is disabled.
See also: setEnabled() and isItemEnabled().
Returns TRUE if the accelerator item with the identifier id is enabled. Returns FALSE if the item is disabled or cannot be found.
See also: setItemEnabled() and isEnabled().
Returns the key code of the accelerator item with the identifier id, or zero if the id cannot be found.
[static]
Creates an accelerator string for the key k. For instance CTRL+Key_O gives "Ctrl+O". The "Ctrl" etc. are translated (using QObject::tr()) in the "QAccel" scope.
See also: stringToKey().
Removes the accelerator item with the identifier id.
Make sure that the accelerator is watching the correct event filter. This function is called automatically, you should not need to call it in application code.
Enables the accelerator if enable is TRUE, or disables it if enable is FALSE.
Individual keys can also be enabled or disabled.
See also: isEnabled() and setItemEnabled().
Enables or disables an accelerator item. id is the item identifier. enable specifies whether the item should be enabled or disabled.
See also: isItemEnabled() and isEnabled().
Sets a Whats This help for the accelerator item id to text.
The text will be shown when the application is in What's This mode and the user hits the accelerator key.
To set Whats This help on a menu item (with or without an accelerator key) use QMenuData::setWhatsThis().
See also: whatsThis(), QWhatsThis::inWhatsThisMode() and QMenuData::setWhatsThis().
[static]
Returns the shortcut key for string, or 0 if string has no shortcut sequence.
For example, shortcutKey("E&xit") returns ALT+Key_X, shortcutKey("&Exit") returns ALT+Key_E and shortcutKey("Exit") returns 0. (In code that does not inherit the Qt namespace class, you need to write e.g. Qt::ALT+Qt::Key_X.)
We provide a list of common accelerators in English. (At the time of writing the Microsoft and The Open Group appear to not have issued such recommendations for other languages.).
[static]
Returns an accelerator code for the string s. For example "Ctrl+O" gives CTRL+UNICODE_ACCEL+'O'. The strings "Ctrl", "Shift", "Alt" are recognized, as well as their translated equivalents in the "QAccel" scope (using QObject::tr()). Returns 0 if s is not recognized.
A common usage of this function is to provide translatable accelerator values for menus:
QPopupMenu* file = new QPopupMenu(this); file->insertItem( p1, tr("&Open..."), this, SLOT(open()), QAccel::stringToKey(tr("Ctrl+O")) );
Note that this function currently only supports character accelerators (unlike keyToString() which can produce Ctrl+Backspace, etc. from the appropriate key codes).
Returns the Whats This help text for the specified item id or QString::null if no text has been defined yet.
See also: setWhatsThis().
For internal use only.
For internal use only.
Search the documentation, FAQ, qt-interest archive and more (uses
www.trolltech.com):
This file is part of the Qt toolkit, copyright © 1995-2000 Troll Tech, all rights reserved.
Copyright İ 2000 Troll Tech | Trademarks | Qt version 2.1.0
|