qaccel.3qt

Trolltech公司发布的基于C++图形开发环境

'\" t
.TH QAccel 3qt "24 January 2005" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QAccel \- Handles keyboard accelerator and shortcut keys
.br
.PP
\fC#include <qaccel.h>\fR
.PP
Inherits QObject.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQAccel\fR ( QWidget * " "parent" ", const char * " "name" "=0 ) "
.br
.ti -1c
.BI "\fBQAccel\fR ( QWidget * " "watch" ", QObject * " "parent" ", const char * " "name" "=0 ) "
.br
.ti -1c
.BI "\fB~QAccel\fR () "
.br
.ti -1c
.BI "bool \fBisEnabled\fR () const"
.br
.ti -1c
.BI "void \fBsetEnabled\fR ( bool ) "
.br
.ti -1c
.BI "uint \fBcount\fR () const"
.br
.ti -1c
.BI "int \fBinsertItem\fR ( int " "key" ", int " "id" "=-1 ) "
.br
.ti -1c
.BI "void \fBremoveItem\fR ( int id ) "
.br
.ti -1c
.BI "void \fBclear\fR () "
.br
.ti -1c
.BI "int \fBkey\fR ( int id ) "
.br
.ti -1c
.BI "int \fBfindKey\fR ( int key ) const"
.br
.ti -1c
.BI "bool \fBisItemEnabled\fR ( int id ) const"
.br
.ti -1c
.BI "void \fBsetItemEnabled\fR ( int " "id" ", bool enable ) "
.br
.ti -1c
.BI "bool \fBconnectItem\fR ( int " "id" ", const QObject * " "receiver" ", const char * member ) "
.br
.ti -1c
.BI "bool \fBdisconnectItem\fR ( int " "id" ", const QObject * " "receiver" ", const char * member ) "
.br
.ti -1c
.BI "void \fBrepairEventFilter\fR () "
.br
.ti -1c
.BI "void \fBsetWhatsThis\fR ( int " "id" ", const QString & ) "
.br
.ti -1c
.BI "QString \fBwhatsThis\fR ( int id ) const"
.br
.ti -1c
.BI "void \fBsetIgnoreWhatsThis\fR ( bool ) (internal)"
.br
.ti -1c
.BI "bool \fBignoreWhatsThis\fR () const (internal)"
.br
.in -1c
.SS "Signals"
.in +1c
.ti -1c
.BI "void \fBactivated\fR ( int id ) "
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "int \fBshortcutKey\fR ( const QString & ) "
.br
.ti -1c
.BI "QString \fBkeyToString\fR ( int k ) "
.br
.ti -1c
.BI "int \fBstringToKey\fR ( const QString & ) "
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "virtual bool \fBeventFilter\fR ( QObject *, QEvent * ) "
.br
.in -1c
.SH DESCRIPTION
The QAccel class handles keyboard accelerator and shortcut keys.
.PP
A keyboard accelerator triggers an action when a certain key combination is pressed. The accelerator handles all keyboard activity for all children of one top level widget, so it is not affected by the keyboard focus.
.PP
In most cases, you will not need to use this class directly. 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:
.PP
.nf
.br
     QPushButton p( "&Exit", parent ); //automatic shortcut ALT+Key_E
.br
     QPopupMenu *fileMenu = new fileMenu( parent );
.br
     fileMenu->insertItem( "Undo", parent, SLOT(undo()), CTRL+Key_Z );
.fi
.PP
A QAccel contains a list of accelerator items. The following functions manipulate the list: insertItem(), removeItem(), clear(), key(), findKey().
.PP
Each accelerator item consists of an identifier and a keyboard code combined with modifiers (\fCSHIFT, CTRL, ALT\fR or \fCUNICODE_ACCEL).\fR For example, \fCCTRL + Key_P\fR could be a shortcut for printing a document. The key codes are listed in qnamespace.h. As an alternative, use \fCUNICODE_ACCEL\fR with the unicode code point of the character. For example, \fCUNICODE_ACCEL + 'A'\fR gives the same accelerator as \fCKey_A.\fR
.PP
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()).
.PP
Use setEnabled() to enable/disable all items in the accelerator, or setItemEnabled() to enable/disable individual items. An item is active only when the QAccel is enabled and the item itself is.
.PP
The function setWhatsThis() specifies the What's This text for an accelerator item.
.PP
A QAccel object handles key events to the QWidget::topLevelWidget() containing \fIparent,\fR and hence to any child widgets of that window. The accelerator will be deleted when \fIparent\fR is deleted, and will consume relevant key events until then.
.PP
Example:
.PP
.nf
.br
     QAccel *a = new QAccel( myWindow );        // create accels for myWindow
.br
     a->connectItem( a->insertItem(Key_P+CTRL), // adds Ctrl+P accelerator
.br
                     myWindow,                  // connected to myWindow's
.br
                     SLOT(printDoc()) );        // printDoc() slot
.fi
.PP
See also QKeyEvent, QWidget::keyPressEvent(), QMenuData::setAccel(), QButton::setAccel(), QLabel::setBuddy() and GUI Design Handbook: Keyboard Shortcuts
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QAccel::QAccel ( QWidget * parent, const char * name=0 )"
Constructs a QAccel object with parent \fIparent\fR and name \fIname.\fR The accelerator operates on \fIparent.\fR
.SH "QAccel::QAccel ( QWidget * watch, QObject * parent, const char * name=0 )"
Constructs a QAccel object that operates on \fIwatch,\fR but is a child of \fIparent.\fR
.PP
This constructor is not needed for normal application programming.
.SH "QAccel::~QAccel ()"
Destructs the accelerator object and frees all allocated resources.
.SH "void QAccel::activated ( int id ) \fC[signal]\fR"
This signal is emitted when an accelerator key is pressed. \fIid\fR is a number that identifies this particular accelerator item.
.SH "void QAccel::clear ()"
Removes all accelerator items.
.SH "bool QAccel::connectItem ( int id, const QObject * receiver, const char * member )"
Connects the accelerator item \fIid\fR to the slot \fImember\fR of \fIreceiver.\fR
.PP
.nf
.br
    a->connectItem( 201, mainView, SLOT(quit()) );
.fi
.PP
Of course, you can also send a signal as \fImember.\fR
.PP
See also disconnectItem().
.SH "uint QAccel::count () const"
Returns the number of accelerator items in this accelerator.
.SH "bool QAccel::disconnectItem ( int id, const QObject * receiver, const char * member )"
Disconnects an accelerator item from a function in another object.
.PP
See also connectItem().
.SH "bool QAccel::eventFilter ( QObject * o, QEvent * e ) \fC[virtual protected]\fR"
Processes accelerator events intended for the top level widget.
.PP
Reimplemented from QObject.
.SH "int QAccel::findKey ( int key ) const"
Returns the identifier of the accelerator item with the key code \fIkey,\fR or -1 if the item cannot be found.
.SH "int QAccel::insertItem ( int key, int id=-1 )"
Inserts an accelerator item and returns the item's identifier.
.PP
\fIkey\fR is a key code plus a combination of SHIFT, CTRL and ALT. \fIid\fR is the accelerator item id.
.PP
If \fIid\fR is negative, then the item will be assigned a unique negative identifier.
.PP
.nf
.br
    QAccel *a = new QAccel( myWindow );         // create accels for myWindow
.br
    a->insertItem( Key_P + CTRL, 200 );         // Ctrl+P to print document
.br
    a->insertItem( Key_X + ALT , 201 );         // Alt+X  to quit
.br
    a->insertItem( UNICODE_ACCEL + 'q', 202 );  // Unicode 'q' to quit
.br
    a->insertItem( Key_D );                     // gets a unique negative id
.br
    a->insertItem( Key_P + CTRL + SHIFT );      // gets a unique negative id
.fi
.SH "bool QAccel::isEnabled () const"
Returns TRUE if the accelerator is enabled, or FALSE if it is disabled.
.PP
See also setEnabled() and isItemEnabled().
.SH "bool QAccel::isItemEnabled ( int id ) const"
Returns TRUE if the accelerator item with the identifier \fIid\fR is enabled. Returns FALSE if the item is disabled or cannot be found.
.PP
See also setItemEnabled() and isEnabled().
.SH "int QAccel::key ( int id )"
Returns the key code of the accelerator item with the identifier \fIid,\fR or zero if the id cannot be found.
.SH "QString QAccel::keyToString ( int k ) \fC[static]\fR"
Creates an accelerator string for the key \fIk.\fR For instance CTRL+Key_O gives "Ctrl+O". The "Ctrl" etc. are translated (using QObject::tr()) in the "QAccel" scope.
.PP
See also stringToKey().
.SH "void QAccel::removeItem ( int id )"
Removes the accelerator item with the identifier \fIid.\fR
.SH "void QAccel::repairEventFilter ()"
Makes sure that the accelerator is watching the correct event filter. This function is called automatically; you should not need to call it in application code.
.SH "void QAccel::setEnabled ( bool enable )"
Enables the accelerator if \fIenable\fR is TRUE, or disables it if \fIenable\fR is FALSE.
.PP
Individual keys can also be enabled or disabled using setItemEnabled(). To work, a key must be an enabled item in an enabled QAccel.
.PP
See also isEnabled() and setItemEnabled().
.SH "void QAccel::setItemEnabled ( int id, bool enable )"
Enables the accelerator key \fIitem\fR if \fIenable\fR is TRUE, and disables \fIitem\fR if \fIenable\fR is FALSE.
.PP
To work, a key must be an enabled item in an enabled QAccel.
.PP
See also isItemEnabled() and isEnabled().
.SH "void QAccel::setWhatsThis ( int id, const QString & text )"
Sets a Whats This help for the accelerator item \fIid\fR to \fItext.\fR
.PP
The text will be shown when the application is in What's This mode and the user hits the accelerator key.
.PP
To set Whats This help on a menu item (with or without an accelerator key) use QMenuData::setWhatsThis().
.PP
See also whatsThis(), QWhatsThis::inWhatsThisMode() and QMenuData::setWhatsThis().
.SH "int QAccel::shortcutKey ( const QString & str ) \fC[static]\fR"
Returns the shortcut key for \fIstring,\fR or 0 if \fIstring\fR has no shortcut sequence.
.PP
For example, shortcutKey("E&xit") returns ALT+Key_X, shortcutKey("&Exit") returns ALT+Key_E and shortcutKey("Exit") returns 0. (In code that does not inherit the Qt namespace class, you need to write e.g. Qt::ALT+Qt::Key_X.)
.PP
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.
.SH "int QAccel::stringToKey ( const QString & s ) \fC[static]\fR"
Returns an accelerator code for the string \fIs.\fR 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" scope (using QObject::tr()). Returns 0 if \fIs\fR is not recognized.
.PP
A common usage of this function is to provide translatable accelerator values for menus:
.PP
.nf
.br
        QPopupMenu* file = new QPopupMenu(this);
.br
        file->insertItem( p1, tr("&Open..."), this, SLOT(open()),
.br
            QAccel::stringToKey(tr("Ctrl+O")) );
.fi
.SH "QString QAccel::whatsThis ( int id ) const"
Returns the Whats This help text for the specified item \fIid\fR or QString::null if no text has been defined yet.
.PP
See also setWhatsThis().
.SH "bool QAccel::ignoreWhatsThis () const"
For internal use only.
.SH "void QAccel::setIgnoreWhatsThis ( bool b )"
For internal use only.
.SH "SEE ALSO"
.BR http://doc.trolltech.com/qaccel.html
.BR http://www.trolltech.com/faq/tech.html
.SH COPYRIGHT
Copyright 1992-2001 Trolltech AS, http://www.trolltech.com.  See the
license file included in the distribution for a complete license
statement.
.SH AUTHOR
Generated automatically from the source code.
.SH BUGS
If you find a bug in Qt, please report it as described in
.BR http://doc.trolltech.com/bughowto.html .
Good bug reports make our job much simpler. Thank you.
.P
In case of content or formattting problems with this manual page, please
report them to
.BR [e-mail] .
Please include the name of the manual page (qaccel.3qt) and the Qt
version (2.3.10).