Detailed Description
The QAccel class handles keyboard accelerator and shortcut keys.
A keyboard accelerator triggers an action when a certain key
combination is pressed. The accelerator handles all keyboard
activity for all the 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
the QAction class to create actions with accelerators that can be
used in both menus and toolbars. If you're only interested in
menus 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 that can be
manipulated using insertItem(), removeItem(), clear(), key() and
findKey().
Each accelerator item consists of an identifier and a QKeySequence. A single key sequence consists of 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 code point of the character. For example, UNICODE_ACCEL + 'A' gives 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 or disable all the items in an
accelerator, or setItemEnabled() to enable or disable individual
items. An item is active only when both the QAccel and the item
itself are enabled.
The function setWhatsThis() specifies a help text that appears
when the user presses an accelerator key in What's This mode.
A QAccel object passes 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::accel, QLabel::setBuddy(), QKeySequence, GUI Design Handbook: Keyboard Shortcuts and Miscellaneous Classes.
Member Function Documentation
QAccel::QAccel ( QWidget * parent, const char * name = 0 )
Constructs a QAccel object called name, with parent parent.
The accelerator operates on parent.
QAccel::QAccel ( QWidget * watch, QObject * parent, const char * name = 0 )
Constructs a QAccel object called name, that operates on watch, and is a child of parent.
This constructor is not needed for normal application programming.
QAccel::~QAccel ()
Destroys the accelerator object and frees all allocated resources.
void QAccel::activated ( int id ) [signal]
This signal is emitted when an accelerator key is pressed. id
is a number that identifies this particular accelerator item.
void QAccel::clear ()
Removes all accelerator items.
bool QAccel::connectItem ( int id, const QObject * receiver, const char * member )
Connects the accelerator item id to the slot member of receiver.
a->connectItem( 201, mainView, SLOT(quit()) );
Of course, you can also send a signal as member.
See also disconnectItem().
Example: t14/gamebrd.cpp.
uint QAccel::count () const
Returns the number of accelerator items in this accelerator.
bool QAccel::disconnectItem ( int id, const QObject * receiver, const char * member )
Disconnects an accelerator item with id id from the function
called member in the receiver object.
See also connectItem().
bool QAccel::eventFilter ( QObject * o, QEvent * e ) [virtual protected]
Processes accelerator events intended for the top level widget. e is the event that occurred on object o.
Reimplemented from QObject.
int QAccel::findKey ( const QKeySequence & key ) const
Returns the identifier of the accelerator item with the key code
key, or -1 if the item cannot be found.
int QAccel::insertItem ( const QKeySequence & key, int id = -1 )
Inserts an accelerator item and returns the item's identifier.
key is a key code and an optional 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 less than -1.
QAccel *a = new QAccel( myWindow ); // create accels for myWindow
a->insertItem( CTRL + Key_P, 200 ); // Ctrl+P, e.g. to print document
a->insertItem( ALT + Key_X, 201 ); // Alt+X, e.g. to quit
a->insertItem( UNICODE_ACCEL + 'q', 202 ); // Unicode 'q', e.g. to quit
a->insertItem( Key_D ); // gets a unique negative id < -1
a->insertItem( CTRL + SHIFT + Key_P ); // gets a unique negative id < -1
Example: t14/gamebrd.cpp.
bool QAccel::isEnabled () const
Returns TRUE if the accelerator is enabled; otherwise returns
FALSE.
See also setEnabled() and isItemEnabled().
bool QAccel::isItemEnabled ( int id ) const
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 sequence of the accelerator item with identifier
id, or an invalid key sequence (0) if the id cannot be found.
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
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" context.
The function is superfluous. Cast the QKeySequence k to a
QString for the same effect.
void QAccel::removeItem ( int id )
Removes the accelerator item with the identifier id.
void QAccel::repairEventFilter ()
Makes 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.
void QAccel::setEnabled ( bool enable )
Enables the accelerator if enable is TRUE, or disables it if enable is FALSE.
Individual keys can also be enabled or disabled using
setItemEnabled(). To work, a key must be an enabled item in an
enabled QAccel.
See also isEnabled() and setItemEnabled().
void QAccel::setItemEnabled ( int id, bool enable )
Enables the accelerator item with the identifier id if enable is TRUE, and disables item id if enable is FALSE.
To work, an item must be enabled and be in an enabled QAccel.
See also isItemEnabled() and isEnabled().
void QAccel::setWhatsThis ( int id, const QString & text )
Sets a What's This help text 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 What's This help on a menu item (with or without an
accelerator key), use QMenuData::setWhatsThis().
See also whatsThis(), QWhatsThis::inWhatsThisMode(), QMenuData::setWhatsThis() and QAction::whatsThis.
QKeySequence QAccel::shortcutKey ( const QString & str ) [static]
Returns the shortcut key sequence for str, or an invalid key
sequence (0) if str has no shortcut sequence.
For example, shortcutKey("E&xit") returns ALT+Key_X,
shortcutKey("&Quit") returns ALT+Key_Q and shortcutKey("Quit")
returns 0. (In code that does not inherit the Qt namespace class,
you must write e.g. Qt::ALT+Qt::Key_Q.)
We provide a list of common accelerators in English. At the time of writing, Microsoft and Open
Group do not appear to have issued equivalent recommendations for
other languages.
QKeySequence QAccel::stringToKey ( const QString & s ) [static]
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
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" context (using QObject::tr()). Returns 0
if s is not recognized.
This function is typically used with tr(), so that accelerator keys can be replaced in
translations:
QPopupMenu *file = new QPopupMenu( this );
file->insertItem( p1, tr("&Open..."), this, SLOT(open()),
QAccel::stringToKey(tr("Ctrl+O", "File|Open")) );
Notice the "File|Open" translator comment. It is by no means
necessary, but it provides some context for the human translator.
The function is superfluous. Construct a QKeySequence from the
string s for the same effect.
See also QObject::tr() and Internationalization with Qt.
Example: i18n/mywidget.cpp.
QString QAccel::whatsThis ( int id ) const
Returns the What's This help text for the specified item id or
QString::null if no text has been specified.
See also setWhatsThis().
This file is part of the Qt toolkit.
Copyright © 1995-2002
Trolltech. All Rights Reserved.
