QAccel Class Reference

Detailed Description

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()).

The activated() signal is not emitted when two or more accelerators match the same key. Instead, the first matching accelerator sends out the activatedAmbiguously() signal. By pressing the key multiple times, users can navigate between all matching accelerators. Some standard controls like QPushButton and QCheckBox connect the activatedAmbiguously() signal to the harmless setFocus() slot, whereas activated() is connected to a slot invoking the button's action. Most controls, like QLabel and QTabBar, treat activated() and activatedAmbiguously() as equivalent.

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.

The accelerator will be deleted when parent is deleted, and will consume relevant key events until then.

Please note that the accelerator

        accelerator->insertItem( QKeySequence("M") );
    

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 )

QAccel::QAccel ( QWidget * watch, QObject * parent, const char * name = 0 )

This constructor is not needed for normal application programming.

QAccel::~QAccel ()

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.

See also activatedAmbiguously().

void QAccel::activatedAmbiguously ( int id ) [signal]

This signal is emitted when an accelerator key is pressed. id is a number that identifies this particular accelerator item.

See also activated().

void QAccel::clear ()

bool QAccel::connectItem ( int id, const QObject * receiver, const char * member )

        a->connectItem( 201, mainView, SLOT(quit()) );
    

Of course, you can also send a signal as member.

Normally accelerators are connected to slots which then receive the activated(int id) signal with the id of the accelerator item that was activated. If you choose to connect a specific accelerator item using this function, the activated() signal is emitted if the associated key sequence is pressed but no activated(int id) signal is emitted.

See also disconnectItem().

Example: t14/gamebrd.cpp.

uint QAccel::count () const

bool QAccel::disconnectItem ( int id, const QObject * receiver, const char * member )

See also connectItem().

bool QAccel::eventFilter ( QObject *, QEvent * ) [virtual protected]

Reimplemented from QObject.

int QAccel::findKey ( const QKeySequence & key ) const

int QAccel::insertItem ( const QKeySequence & key, int id = -1 )

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

See also setEnabled() and isItemEnabled().

bool QAccel::isItemEnabled ( int id ) const

See also setItemEnabled() and isEnabled().

QKeySequence QAccel::key ( int id )

QString QAccel::keyToString ( QKeySequence 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" context.

The function is superfluous. Cast the QKeySequence k to a QString for the same effect.

void QAccel::removeItem ( int id )

void QAccel::repairEventFilter ()

void QAccel::setEnabled ( bool enable )

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 )

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 )

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]

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]

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

See also setWhatsThis().

This file is part of the Qt toolkit. Copyright © 1995-2003 Trolltech. All Rights Reserved.