Contents

• Public Functions
• Signals
• Static Public Members
• Detailed Description

Detailed Description

TheQ3Accel 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 theQAction 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 asQAbstractButton,QGroupBox,QLabel (withQLabel::setBuddy()),QMenuBar, andQTabBar. Example:

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

AQ3Accel contains a list of accelerator items that can be manipulated usinginsertItem(),removeItem(),clear(),key() andfindKey().

Each accelerator item consists of an identifier and aQKeySequence. A single key sequence consists of a keyboard code combined with modifiers (Qt::SHIFT,Qt::CTRL,Qt::ALT, orQt::UNICODE_ACCEL). For example,Qt::CTRL +Qt::Key_P could be a shortcut for printing a document. As an alternative, useQt::UNICODE_ACCEL with the unicode code point of the character. For example,Qt::UNICODE_ACCEL + 'A' gives the same accelerator asQt::Key_A.

When an accelerator key is pressed, the accelerator sends out the signalactivated() 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 (seeconnectItem() anddisconnectItem()).

Theactivated() signal isnot emitted when two or more accelerators match the same key. Instead, the first matching accelerator sends out theactivatedAmbiguously() signal. By pressing the key multiple times, users can navigate between all matching accelerators. Some standard controls likeQPushButton andQCheckBox connect theactivatedAmbiguously() signal to the harmless setFocus() slot, whereasactivated() is connected to a slot invoking the button's action. Most controls, likeQLabel andQTabBar, treatactivated() andactivatedAmbiguously() as equivalent.

UsesetEnabled() to enable or disable all the items in an accelerator, orsetItemEnabled() to enable or disable individual items. An item is active only when both theQ3Accel and the item itself are enabled.

The functionsetWhatsThis() specifies a help text that appears when the user presses an accelerator key in What's This mode.

The accelerator will be deleted whenparent 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=newQ3Accel(myWindow);a->connectItem(a->insertItem(Qt::CTRL+Qt::Key_P),               myWindow, SLOT(printDoc()));

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

Member Function Documentation

Q3Accel::Q3Accel(QWidget * parent, constchar * name = 0)

Constructs aQ3Accel object calledname, with parentparent. The accelerator operates onparent.

Q3Accel::Q3Accel(QWidget * watch,QObject * parent, constchar * name = 0)

Constructs aQ3Accel object calledname, that operates onwatch, and is a child ofparent.

This constructor is not needed for normal application programming.

Q3Accel::~Q3Accel()

Destroys the accelerator object and frees all allocated resources.

[signal]void Q3Accel::activated(int id)

This signal is emitted when the user types the shortcut's key sequence.id is a number that identifies this particular accelerator item.

See alsoactivatedAmbiguously().

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

This signal is emitted when the user types a shortcut key sequence that is ambiguous. For example, if one key sequence is a "prefix" for another and the user types these keys it isn't clear if they want the shorter key sequence, or if they're about to type more to complete the longer key sequence.id is a number that identifies this particular accelerator item.

See alsoactivated().

void Q3Accel::clear()

Removes all accelerator items.

bool Q3Accel::connectItem(int id, constQObject * receiver, constchar * member)

Connects the accelerator itemid to the slotmember ofreceiver. Returns true if the connection is successful.

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

Of course, you can also send a signal asmember.

Normally accelerators are connected to slots which then receive theactivated(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, theactivated() signal is emitted if the associated key sequence is pressed but noactivated(int id) signal is emitted.

See alsodisconnectItem() andQObject::connect().

uint Q3Accel::count() const

Returns the number of accelerator items in this accelerator.

bool Q3Accel::disconnectItem(int id, constQObject * receiver, constchar * member)

Disconnects the accelerator item identified byid from the function calledmember in thereceiver object. Returns true if the connection existed and the disconnect was successful.

See alsoconnectItem() andQObject::disconnect().

int Q3Accel::findKey(constQKeySequence & key) const

Returns the identifier of the accelerator item with the key codekey, or -1 if the item cannot be found.

int Q3Accel::insertItem(constQKeySequence & 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.

Ifid is negative, then the item will be assigned a unique negative identifier less than -1.

Q3Accel*a=newQ3Accel(myWindow);// create accels for myWindowa->insertItem(CTRL+ Key_P,200);// Ctrl+P, e.g. to print documenta->insertItem(ALT+ Key_X,201);// Alt+X, e.g. to quita->insertItem(UNICODE_ACCEL+'q',202);// Unicode 'q', e.g. to quita->insertItem(Key_D);// gets a unique negative id < -1a->insertItem(CTRL+ SHIFT+ Key_P);// gets a unique negative id < -1

bool Q3Accel::isEnabled() const

Returns true if the accelerator is enabled; otherwise returns false.

See alsosetEnabled() andisItemEnabled().

bool Q3Accel::isItemEnabled(int id) const

Returns true if the accelerator item with the identifierid is enabled. Returns false if the item is disabled or cannot be found.

See alsosetItemEnabled() andisEnabled().

QKeySequence Q3Accel::key(int id)

Returns the key sequence of the accelerator item with identifierid, or an invalid key sequence (0) if the id cannot be found.

void Q3Accel::removeItem(int id)

Removes the accelerator item with the identifierid.

void Q3Accel::setEnabled(bool enable)

Enables the accelerator ifenable is true, or disables it ifenable is false.

Individual keys can also be enabled or disabled usingsetItemEnabled(). To work, a key must be an enabled item in an enabledQ3Accel.

See alsoisEnabled() andsetItemEnabled().

void Q3Accel::setItemEnabled(int id,bool enable)

Enables the accelerator item with the identifierid ifenable is true, and disables itemid ifenable is false.

To work, an item must be enabled and be in an enabledQ3Accel.

See alsoisItemEnabled() andisEnabled().

void Q3Accel::setWhatsThis(int id, constQString & text)

Sets a What's This help text for the accelerator itemid totext.

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 Q3MenuData::setWhatsThis().

See alsowhatsThis(),QWhatsThis::inWhatsThisMode(), andQAction::setWhatsThis().

[static]QKeySequence Q3Accel::shortcutKey(constQString & str)

Returns the shortcut key sequence forstr, or an invalid key sequence (0) ifstr has no shortcut sequence.

For example, shortcutKey("E&xit") returnsQKeySequence(Qt::ALT +Qt::Key_X), shortcutKey("&Quit") returnsQKeySequence(Qt::ALT +Qt::Key_Q), and shortcutKey("Quit") returns QKeySequence().

QString Q3Accel::whatsThis(int id) const

Returns the What's This help text for the specified itemid or an empty string if no text has been specified.

See alsosetWhatsThis().