QAccel(3qt)QAccel(3qt)NAME
QAccel - Handles keyboard accelerator and shortcut keys
#include <qaccel.h>
Inherits QObject.
Public Members
QAccel ( QWidget * parent, const char * name=0 )
QAccel ( QWidget * watch, QObject * parent, const char *
name=0 )
~QAccel ()
bool isEnabled () const
void setEnabled ( bool )
uint count () const
int insertItem ( int key, int id=-1 )
void removeItem ( int id )
void clear ()
int key ( int id )
int findKey ( int key ) const
bool isItemEnabled ( int id ) const
void setItemEnabled ( int id, bool enable )
bool connectItem ( int id, const QObject * receiver, const
char * member )
bool disconnectItem ( int id, const QObject * receiver,
const char * member )
void repairEventFilter ()
void setWhatsThis ( int id, const QString & )
QString whatsThis ( int id ) const
void setIgnoreWhatsThis ( bool ) (internal)
bool ignoreWhatsThis () const (internal)
Signals
void activated ( int id )
Static Public Members
int shortcutKey ( const QString & )
QString keyToString ( int k )
int stringToKey ( const QString & )
Protected Members
virtual bool eventFilter ( QObject *, QEvent * )
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 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
Trolltech AS 13 June 2001 1
QAccel(3qt)QAccel(3qt)
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 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/disable all items in the
accelerator, or setItemEnabled() to enable/disable
individual items. An item is active only when the QAccel
is enabled and the item itself is.
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
Trolltech AS 13 June 2001 2
QAccel(3qt)QAccel(3qt)
Shortcuts
MEMBER FUNCTION DOCUMENTATIONQAccel::QAccel ( QWidget * parent, const char * name=0 )
Constructs a QAccel object with parent parent and name
name. The accelerator operates on parent.
QAccel::QAccel ( QWidget * watch, QObject * parent, const char *
name=0 )
Constructs a QAccel object that operates on watch, but is
a child of parent.
This constructor is not needed for normal application
programming.
QAccel::~QAccel ()
Destructs 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().
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 from a function in another
object.
See also connectItem().
bool QAccel::eventFilter ( QObject * o, QEvent * e ) [virtual
protected]
Processes accelerator events intended for the top level
widget.
Trolltech AS 13 June 2001 3
QAccel(3qt)QAccel(3qt)
Reimplemented from QObject.
int QAccel::findKey ( int 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 ( int key, int id=-1 )
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
bool QAccel::isEnabled () const
Returns TRUE if the accelerator is enabled, or FALSE if it
is disabled.
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().
int QAccel::key ( int id )
Returns the key code of the accelerator item with the
identifier id, or zero if the id cannot be found.
QString QAccel::keyToString ( int k ) [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().
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.
Trolltech AS 13 June 2001 4
QAccel(3qt)QAccel(3qt)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 key item if enable is TRUE, and
disables item if enable is FALSE.
To work, a key must be an enabled item in an enabled
QAccel.
See also isItemEnabled() and isEnabled().
void QAccel::setWhatsThis ( int id, const QString & text )
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().
int QAccel::shortcutKey ( const QString & str ) [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.
int QAccel::stringToKey ( const QString & s ) [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.
Trolltech AS 13 June 2001 5
QAccel(3qt)QAccel(3qt)
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")) );
QString QAccel::whatsThis ( int id ) const
Returns the Whats This help text for the specified item id
or QString::null if no text has been defined yet.
See also setWhatsThis().
bool QAccel::ignoreWhatsThis () const
For internal use only.
void QAccel::setIgnoreWhatsThis ( bool b )
For internal use only.
SEE ALSO
http://doc.trolltech.com/qaccel.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page (qaccel.3qt)
and the Qt version (2.3.1).
Trolltech AS 13 June 2001 6
