Q3Accel Class Reference
[Qt3Support module]

Detailed Description

The Q3Accel 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 Q3MenuData::insertItem() or Q3MenuData::setAccel() to make accelerators for operations that are also available on menus. Many widgets automatically generate accelerators, such as QAbstractButton, QGroupBox, QLabel (with QLabel::setBuddy()), QMenuBar, and QTabBar. Example:

 QPushButton p("&Exit", parent); // automatic shortcut Alt+E
 Q3PopupMenu *fileMenu = new fileMenu(parent);
 fileMenu->insertItem("Undo", parent, SLOT(undo()),
                      Qt::CTRL + Qt::Key_Z);

A Q3Accel 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 (Qt::SHIFT, Qt::CTRL, Qt::ALT, or Qt::UNICODE_ACCEL). For example, Qt::CTRL + Qt::Key_P could be a shortcut for printing a document. As an alternative, use Qt::UNICODE_ACCEL with the unicode code point of the character. For example, Qt::UNICODE_ACCEL + 'A' gives the same accelerator as Qt::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 Q3Accel 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"));

can be triggered with both the 'M' key, and with Shift+M, unless a second accelerator is defined for the Shift+M combination.

Example:

 Q3Accel *a = new Q3Accel(myWindow);
 a->connectItem(a->insertItem(Qt::CTRL + Qt::Key_P),
                myWindow, SLOT(printDoc()));

QAbstractButton::setAccel() QLabel::setBuddy() QKeySequence

See also QKeyEvent and QWidget::keyPressEvent().

Member Function Documentation

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

 Q3Accel *a = new Q3Accel(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