Q3Accel Class Reference

#include <q3accel.h>

Inheritance diagram for Q3Accel:

Inheritance graph
[legend]
Collaboration diagram for Q3Accel:

Collaboration graph
[legend]
List of all members.

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

See also:
QKeyEvent QWidget::keyPressEvent() QAbstractButton::setAccel() QLabel::setBuddy() QKeySequence

Definition at line 36 of file q3accel.h.

Signals

void activated (int id)
void activatedAmbiguously (int id)

Public Member Functions

 Q3Accel (QWidget *parent, const char *name=0)
 Q3Accel (QWidget *watch, QObject *parent, const char *name=0)
 ~Q3Accel ()
bool isEnabled () const
void setEnabled (bool)
uint count () const
int insertItem (const QKeySequence &key, int id=-1)
void removeItem (int id)
void clear ()
QKeySequence key (int id)
int findKey (const QKeySequence &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)
bool ignoreWhatsThis () const

Static Public Member Functions

static QKeySequence shortcutKey (const QString &)
static QString keyToString (QKeySequence k)
static QKeySequence stringToKey (const QString &)

Private Attributes

Q3AccelPrivate * d

Friends

class Q3AccelPrivate
class Q3AccelManager

Constructor & Destructor Documentation

Q3Accel::Q3Accel ( QWidget *  parent,
const char *  name = 0 
)

Constructs a Q3Accel object called name, with parent parent. The accelerator operates on parent.

Definition at line 569 of file q3accel.cpp.

References d, Q3AccelPrivate::enabled, QObject::parent(), Q3AccelPrivate, qWarning(), and Q3AccelPrivate::watch.

00570     : QObject(parent, name)
00571 {
00572     d = new Q3AccelPrivate(this);
00573     d->enabled = true;
00574     d->watch = parent;
00575 #if defined(QT_CHECK_NULL)
00576     if (!d->watch)
00577         qWarning("Q3Accel: An accelerator must have a parent or a watch widget");
00578 #endif
00579 }

Here is the call graph for this function:

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

Constructs a Q3Accel object called name, that operates on watch, and is a child of parent.

This constructor is not needed for normal application programming.

Definition at line 587 of file q3accel.cpp.

References d, Q3AccelPrivate::enabled, Q3AccelPrivate, qWarning(), and Q3AccelPrivate::watch.

00588     : QObject(parent, name)
00589 {
00590     d = new Q3AccelPrivate(this);
00591     d->enabled = true;
00592     d->watch = watch;
00593 #if defined(QT_CHECK_NULL)
00594     if (!d->watch)
00595         qWarning("Q3Accel: An accelerator must have a parent or a watch widget");
00596 #endif
00597 }

Here is the call graph for this function:

Q3Accel::~Q3Accel (  ) 

Destroys the accelerator object and frees all allocated resources.

Definition at line 603 of file q3accel.cpp.

References d.

00604 {
00605     delete d;
00606 }

Member Function Documentation

bool Q3Accel::isEnabled (  )  const

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

See also:
setEnabled(), isItemEnabled()

Definition at line 639 of file q3accel.cpp.

References d, and Q3AccelPrivate::enabled.

00640 {
00641     return d->enabled;
00642 }

void Q3Accel::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 Q3Accel.

See also:
isEnabled(), setItemEnabled()

Definition at line 656 of file q3accel.cpp.

References d, and Q3AccelPrivate::enabled.

Referenced by Q3ActionPrivate::update().

00657 {
00658     d->enabled = enable;
00659 }

uint Q3Accel::count (  )  const

Returns the number of accelerator items in this accelerator.

Definition at line 666 of file q3accel.cpp.

References Q3AccelPrivate::aitems, Q3PtrList< type >::count(), and d.

00667 {
00668     return d->aitems.count();
00669 }

Here is the call graph for this function:

int Q3Accel::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.

        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

Definition at line 697 of file q3accel.cpp.

References Q3AccelPrivate::aitems, d, get_seq_id(), Q3PtrList< type >::insert(), and key().

Referenced by Q3Wizard::Q3Wizard(), and Q3Action::setAccel().

00698 {
00699     if (id == -1)
00700         id = get_seq_id();
00701     d->aitems.insert(0, new Q3AccelItem(key,id));
00702     return id;
00703 }

Here is the call graph for this function:

void Q3Accel::removeItem ( int  id  ) 

Removes the accelerator item with the identifier id.

Definition at line 709 of file q3accel.cpp.

References Q3AccelPrivate::aitems, d, find_id(), and Q3PtrList< type >::remove().

00710 {
00711     if (find_id(d->aitems, id))
00712         d->aitems.remove();
00713 }

Here is the call graph for this function:

void Q3Accel::clear (  ) 

Removes all accelerator items.

Definition at line 720 of file q3accel.cpp.

References Q3AccelPrivate::aitems, Q3PtrList< type >::clear(), and d.

00721 {
00722     d->aitems.clear();
00723 }

Here is the call graph for this function:

QKeySequence Q3Accel::key ( int  id  ) 

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

Definition at line 731 of file q3accel.cpp.

References Q3AccelPrivate::aitems, d, find_id(), and Q3AccelItem::key.

Referenced by findKey(), and insertItem().

00732 {
00733     Q3AccelItem *item = find_id(d->aitems, id);
00734     return item ? item->key : QKeySequence(0);
00735 }

Here is the call graph for this function:

int Q3Accel::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.

Definition at line 743 of file q3accel.cpp.

References Q3AccelPrivate::aitems, d, find_key(), Q3AccelItem::id, and key().

00744 {
00745     Q3AccelItem *item = find_key(d->aitems, key);
00746     return item ? item->id : -1;
00747 }

Here is the call graph for this function:

bool Q3Accel::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(), isEnabled()

Definition at line 757 of file q3accel.cpp.

References Q3AccelPrivate::aitems, d, Q3AccelItem::enabled, and find_id().

00758 {
00759     Q3AccelItem *item = find_id(d->aitems, id);
00760     return item ? item->enabled : false;
00761 }

Here is the call graph for this function:

void Q3Accel::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 Q3Accel.

See also:
isItemEnabled(), isEnabled()

Definition at line 773 of file q3accel.cpp.

References Q3AccelPrivate::aitems, d, Q3AccelItem::enabled, and find_id().

Referenced by Q3Wizard::setBackEnabled(), and Q3Wizard::setNextEnabled().

00774 {
00775     Q3AccelItem *item = find_id(d->aitems, id);
00776     if (item)
00777         item->enabled = enable;
00778 }

Here is the call graph for this function:

bool Q3Accel::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.

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

Definition at line 801 of file q3accel.cpp.

References Q3AccelPrivate::aitems, Q3Signal::connect(), d, find_id(), and Q3AccelItem::signal.

Referenced by Q3Wizard::Q3Wizard(), and Q3Action::setAccel().

00802 {
00803     Q3AccelItem *item = find_id(d->aitems, id);
00804     if (item) {
00805         if (!item->signal) {
00806             item->signal = new Q3Signal;
00807             Q_CHECK_PTR(item->signal);
00808         }
00809         return item->signal->connect(receiver, member);
00810     }
00811     return false;
00812 }

Here is the call graph for this function:

bool Q3Accel::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()

Definition at line 821 of file q3accel.cpp.

References Q3AccelPrivate::aitems, d, Q3Signal::disconnect(), find_id(), and Q3AccelItem::signal.

00823 {
00824     Q3AccelItem *item = find_id(d->aitems, id);
00825     if (item && item->signal)
00826         return item->signal->disconnect(receiver, member);
00827     return false;
00828 }

Here is the call graph for this function:

void Q3Accel::repairEventFilter (  )  [inline]

Definition at line 62 of file q3accel.h.

00062 {}

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

See also:
whatsThis(), QWhatsThis::inWhatsThisMode(), QAction::setWhatsThis()

Definition at line 946 of file q3accel.cpp.

References Q3AccelPrivate::aitems, d, find_id(), and Q3AccelItem::whatsthis.

Referenced by Q3ActionPrivate::update().

00947 {
00948     Q3AccelItem *item = find_id(d->aitems, id);
00949     if (item)
00950         item->whatsthis = text;
00951 }

Here is the call graph for this function:

QString Q3Accel::whatsThis ( int  id  )  const

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

See also:
setWhatsThis()

Definition at line 959 of file q3accel.cpp.

References Q3AccelPrivate::aitems, d, find_id(), and Q3AccelItem::whatsthis.

00960 {
00961 
00962     Q3AccelItem *item = find_id(d->aitems, id);
00963     return item? item->whatsthis : QString();
00964 }

Here is the call graph for this function:

void Q3Accel::setIgnoreWhatsThis ( bool   ) 

Definition at line 967 of file q3accel.cpp.

References d, and Q3AccelPrivate::ignorewhatsthis.

00968 {
00969     d->ignorewhatsthis = b;
00970 }

bool Q3Accel::ignoreWhatsThis (  )  const

Definition at line 973 of file q3accel.cpp.

References d, and Q3AccelPrivate::ignorewhatsthis.

00974 {
00975     return d->ignorewhatsthis;
00976 }

QKeySequence Q3Accel::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 QKeySequence(Qt::ALT + Qt::Key_X), shortcutKey("&Quit") returns QKeySequence(Qt::ALT + Qt::Key_Q), and shortcutKey("Quit") returns QKeySequence().

Definition at line 862 of file q3accel.cpp.

References Qt::ALT, c, Qt::Key_A, Qt::Key_Z, QString::length(), p, qt_accel_no_shortcuts, and Qt::UNICODE_ACCEL.

00863 {
00864     if(qt_accel_no_shortcuts)
00865         return QKeySequence();
00866 
00867     int p = 0;
00868     while (p >= 0) {
00869         p = str.find('&', p) + 1;
00870         if (p <= 0 || p >= (int)str.length())
00871             return 0;
00872         if (str[p] != '&') {
00873             QChar c = str[p];
00874             if (c.isPrint()) {
00875                 char ltr = c.upper().latin1();
00876                 if (ltr >= (char)Key_A && ltr <= (char)Key_Z)
00877                     c = ltr;
00878                 else
00879                     c = c.lower();
00880                 return QKeySequence(c.unicode() + ALT + UNICODE_ACCEL);
00881             }
00882         }
00883         p++;
00884     }
00885     return QKeySequence();
00886 }

Here is the call graph for this function:

QString Q3Accel::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 "Q3Accel" context.

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

Definition at line 897 of file q3accel.cpp.

00898 {
00899     return (QString) k;
00900 }

QKeySequence Q3Accel::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 "Q3Accel" 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:

    Q3PopupMenu *file = new Q3PopupMenu(this);
    file->insertItem(p1, tr("&Open..."), this, SLOT(open()),
                      Q3Accel::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(), {Internationalization with Qt}

Definition at line 928 of file q3accel.cpp.

References s.

00929 {
00930     return QKeySequence(s);
00931 }

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

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

See also:
activatedAmbiguously()

Referenced by Q3AccelPrivate::activate().

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

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 also:
activated()

Referenced by Q3AccelPrivate::activateAmbiguously().

Friends And Related Function Documentation

friend class Q3AccelPrivate [friend]

Definition at line 82 of file q3accel.h.

Referenced by Q3Accel().

friend class Q3AccelManager [friend]

Definition at line 83 of file q3accel.h.

Member Data Documentation

Q3AccelPrivate* Q3Accel::d [private]

Definition at line 78 of file q3accel.h.

Referenced by clear(), connectItem(), count(), disconnectItem(), findKey(), ignoreWhatsThis(), insertItem(), isEnabled(), isItemEnabled(), key(), Q3Accel(), removeItem(), setEnabled(), setIgnoreWhatsThis(), setItemEnabled(), setWhatsThis(), whatsThis(), and ~Q3Accel().

The documentation for this class was generated from the following files:
Generated on Thu Mar 15 15:39:15 2007 for Qt 4.2 User's Guide by  doxygen 1.5.1