Qt logo

QAccel Class Reference


The QAccel class handles keyboard accelerator and shortcut keys. More...

#include <qaccel.h>

Inherits QObject.

List of all member functions.

Public Members

Signals

Static Public Members

Protected Members


Detailed Description

The QAccel class handles keyboard accelerator and shortcut keys.

A QAccel contains a list of accelerator items. 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.

When pressed, an accelerator key 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()).

A QAccel object handles key events to the top level window containing parent, and hence to any child widgets of that window. Note that the accelerator will be deleted only when the 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() and GUI Design Handbook: Keyboard Shortcuts,


Member Function Documentation

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

Creates a QAccel object with a parent widget and a name.

QAccel::~QAccel()

Destroys the accelerator object.

voidQAccel::activated(intid) [signal]

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

voidQAccel::clear()

Removes all accelerator items.

boolQAccel::connectItem(intid, constQObject*receiver, constchar*member)

Connects an accelerator item to a slot/signal in another object.

Arguments:

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

See also: disconnectItem().

uintQAccel::count()const

Returns the number of accelerator items.

boolQAccel::disconnectItem(intid, constQObject*receiver, constchar*member)

Disconnects an accelerator item from a function in another object.

See also: connectItem().

boolQAccel::eventFilter(QObject*, QEvent*e) [virtualprotected]

Processes accelerator events intended for the top level widget.

Reimplemented from QObject.

intQAccel::findKey(intkey)const

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

intQAccel::insertItem(intkey, intid=-1)

Inserts an accelerator item and returns the item's identifier.

Arguments:

If id is negative, then the item will be assigned a unique 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 id 3
    a->insertItem( Key_P + CTRL + SHIFT );      // gets id 4

boolQAccel::isEnabled()const

Returns TRUE if the accelerator is enabled, or FALSE if it is disabled.

See also: setEnabled() and isItemEnabled().

boolQAccel::isItemEnabled(intid)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().

intQAccel::key(intid)

Returns the key code of the accelerator item with the identifier id, or zero if the id cannot be found.

QStringQAccel::keyToString(intk) [static]

Creates an accelerator string for the key k. For instance CTRL+Key_O gives "Ctrl+O". The "Ctrl" etc. are translated in the "QAccel" scope.

See also: stringToKey().

voidQAccel::removeItem(intid)

Removes the accelerator item with the identifier id.

voidQAccel::repairEventFilter()

Make sure that the accelerator is watching the correct event filter. Used by QWidget::reparent().

voidQAccel::setEnabled(boolenable)

Enables the accelerator if enable is TRUE, or disables it if enable is FALSE.

Individual keys can also be enabled or disabled.

See also: isEnabled() and setItemEnabled().

voidQAccel::setItemEnabled(intid, boolenable)

Enables or disables an accelerator item.

Arguments:

See also: isItemEnabled() and isEnabled().

voidQAccel::setWhatsThis(intid, constQString&text)

Sets a Whats This help for a certain accelerator.

Arguments:

The text will be shown when the application is in What's This mode and the user either hits the respective accelerator key or selects a menu item that has been attached to this accelerator.

See also: whatsThis() and QWhatsThis::inWhatsThisMode().

intQAccel::shortcutKey(constQString&str) [static]

Returns the shortcut key for string, or 0 if string has no shortcut sequence.

For example, acceleratorKey("E&xit") returns ALT+Key_X, shortcutChar("&Exit") returns ALT+Key_E and shortcutChar("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.).

intQAccel::stringToKey(constQString&s) [static]

Creates an accelerator code for the string s. For example "Ctrl+O" gives CTRL+UNICODE_ACCEL+'O'. The strings "Ctrl", "Shift", "Alt" and their translated equivalents in the "QAccel" scope are recognized.

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

Note that this function currently only supports character accelerators (unlike keyToString() which can produce Ctrl+Backspace, etc. from the appropriate key codes).

QStringQAccel::whatsThis(intid)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().


Search the documentation, FAQ, qt-interest archive and more (uses www.troll.no):


This file is part of the Qt toolkit, copyright © 1995-99 Troll Tech, all rights reserved.


Copyright 1999 Troll TechTrademarks
Qt version 2.0.2