1QAccel(3qt)                                                        QAccel(3qt)
2
3
4

NAME

6       QAccel - Handles keyboard accelerator and shortcut keys
7

SYNOPSIS

9       #include <qaccel.h>
10
11       Inherits QObject.
12
13   Public Members
14       QAccel ( QWidget * parent, const char * name = 0 )
15       QAccel ( QWidget * watch, QObject * parent, const char * name = 0 )
16       ~QAccel ()
17       bool isEnabled () const
18       void setEnabled ( bool enable )
19       uint count () const
20       int insertItem ( const QKeySequence & key, int id = -1 )
21       void removeItem ( int id )
22       void clear ()
23       QKeySequence key ( int id )
24       int findKey ( const QKeySequence & key ) const
25       bool isItemEnabled ( int id ) const
26       void setItemEnabled ( int id, bool enable )
27       bool connectItem ( int id, const QObject * receiver, const char *
28           member )
29       bool disconnectItem ( int id, const QObject * receiver, const char *
30           member )
31       void repairEventFilter ()  (obsolete)
32       void setWhatsThis ( int id, const QString & text )
33       QString whatsThis ( int id ) const
34
35   Signals
36       void activated ( int id )
37       void activatedAmbiguously ( int id )
38
39   Static Public Members
40       QKeySequence shortcutKey ( const QString & str )
41       QString keyToString ( QKeySequence k )  (obsolete)
42       QKeySequence stringToKey ( const QString & s )  (obsolete)
43
44   Protected Members
45       virtual bool eventFilter ( QObject *, QEvent * )  (obsolete)
46

DESCRIPTION

48       The QAccel class handles keyboard accelerator and shortcut keys.
49
50       A keyboard accelerator triggers an action when a certain key
51       combination is pressed. The accelerator handles all keyboard activity
52       for all the children of one top-level widget, so it is not affected by
53       the keyboard focus.
54
55       In most cases, you will not need to use this class directly. Use the
56       QAction class to create actions with accelerators that can be used in
57       both menus and toolbars. If you're only interested in menus use
58       QMenuData::insertItem() or QMenuData::setAccel() to make accelerators
59       for operations that are also available on menus. Many widgets
60       automatically generate accelerators, such as QButton, QGroupBox, QLabel
61       (with QLabel::setBuddy()), QMenuBar and QTabBar. Example:
62
63               QPushButton p( "&Exit", parent ); // automatic shortcut ALT+Key_E
64               QPopupMenu *fileMenu = new fileMenu( parent );
65               fileMenu->insertItem( "Undo", parent, SLOT(undo()), CTRL+Key_Z );
66
67       A QAccel contains a list of accelerator items that can be manipulated
68       using insertItem(), removeItem(), clear(), key() and findKey().
69
70       Each accelerator item consists of an identifier and a QKeySequence. A
71       single key sequence consists of a keyboard code combined with modifiers
72       (SHIFT, CTRL, ALT or UNICODE_ACCEL). For example, CTRL + Key_P could be
73       a shortcut for printing a document. The key codes are listed in
74       qnamespace.h. As an alternative, use UNICODE_ACCEL with the unicode
75       code point of the character. For example, UNICODE_ACCEL + 'A' gives the
76       same accelerator as Key_A.
77
78       When an accelerator key is pressed, the accelerator sends out the
79       signal activated() with a number that identifies this particular
80       accelerator item. Accelerator items can also be individually connected,
81       so that two different keys will activate two different slots (see
82       connectItem() and disconnectItem()).
83
84       The activated() signal is not emitted when two or more accelerators
85       match the same key. Instead, the first matching accelerator sends out
86       the activatedAmbiguously() signal. By pressing the key multiple times,
87       users can navigate between all matching accelerators. Some standard
88       controls like QPushButton and QCheckBox connect the
89       activatedAmbiguously() signal to the harmless setFocus() slot, whereas
90       activated() is connected to a slot invoking the button's action. Most
91       controls, like QLabel and QTabBar, treat activated() and
92       activatedAmbiguously() as equivalent.
93
94       Use setEnabled() to enable or disable all the items in an accelerator,
95       or setItemEnabled() to enable or disable individual items. An item is
96       active only when both the QAccel and the item itself are enabled.
97
98       The function setWhatsThis() specifies a help text that appears when the
99       user presses an accelerator key in What's This mode.
100
101       The accelerator will be deleted when parent is deleted, and will
102       consume relevant key events until then.
103
104       Please note that the accelerator
105
106               accelerator->insertItem( QKeySequence("M") );
107       can be triggered with both the 'M' key, and with Shift+M, unless a
108       second accelerator is defined for the Shift+M combination.
109
110       Example:
111
112               QAccel *a = new QAccel( myWindow );        // create accels for myWindow
113               a->connectItem( a->insertItem(Key_P+CTRL), // adds Ctrl+P accelerator
114                               myWindow,                  // connected to myWindow's
115                               SLOT(printDoc()) );        // printDoc() slot
116
117       See also QKeyEvent, QWidget::keyPressEvent(), QMenuData::setAccel(),
118       QButton::accel, QLabel::setBuddy(), QKeySequence, GUI Design Handbook:
119       Keyboard Shortcuts, and Miscellaneous Classes.
120

MEMBER FUNCTION DOCUMENTATION

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

123       Constructs a QAccel object called name, with parent parent. The
124       accelerator operates on parent.
125

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

127       Constructs a QAccel object called name, that operates on watch, and is
128       a child of parent.
129
130       This constructor is not needed for normal application programming.
131

QAccel::~QAccel ()

133       Destroys the accelerator object and frees all allocated resources.
134

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

136       This signal is emitted when an accelerator key is pressed. id is a
137       number that identifies this particular accelerator item.
138
139       See also activatedAmbiguously().
140

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

142       This signal is emitted when an accelerator key is pressed. id is a
143       number that identifies this particular accelerator item.
144
145       See also activated().
146

void QAccel::clear ()

148       Removes all accelerator items.
149

bool QAccel::connectItem ( int id, const QObject * receiver, const char *

151       member )
152       Connects the accelerator item id to the slot member of receiver.
153
154               a->connectItem( 201, mainView, SLOT(quit()) );
155
156       Of course, you can also send a signal as member.
157
158       Normally accelerators are connected to slots which then receive the
159       activated(int id) signal with the id of the accelerator item that was
160       activated. If you choose to connect a specific accelerator item using
161       this function, the activated() signal is emitted if the associated key
162       sequence is pressed but no activated(int id) signal is emitted.
163
164       See also disconnectItem().
165
166       Example: t14/gamebrd.cpp.
167

uint QAccel::count () const

169       Returns the number of accelerator items in this accelerator.
170

bool QAccel::disconnectItem ( int id, const QObject * receiver, const char *

172       member )
173       Disconnects an accelerator item with id id from the function called
174       member in the receiver object.
175
176       See also connectItem().
177

bool QAccel::eventFilter ( QObject *, QEvent * ) [virtual protected]

179       This function is obsolete. It is provided to keep old source working.
180       We strongly advise against using it in new code. serves no purpose
181       anymore
182
183       Reimplemented from QObject.
184

int QAccel::findKey ( const QKeySequence & key ) const

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

int QAccel::insertItem ( const QKeySequence & key, int id = -1 )

190       Inserts an accelerator item and returns the item's identifier.
191
192       key is a key code and an optional combination of SHIFT, CTRL and ALT.
193       id is the accelerator item id.
194
195       If id is negative, then the item will be assigned a unique negative
196       identifier less than -1.
197
198               QAccel *a = new QAccel( myWindow );        // create accels for myWindow
199               a->insertItem( CTRL + Key_P, 200 );        // Ctrl+P, e.g. to print document
200               a->insertItem( ALT + Key_X, 201 );         // Alt+X, e.g. to quit
201               a->insertItem( UNICODE_ACCEL + 'q', 202 ); // Unicode 'q', e.g. to quit
202               a->insertItem( Key_D );                    // gets a unique negative id < -1
203               a->insertItem( CTRL + SHIFT + Key_P );     // gets a unique negative id < -1
204
205       Example: t14/gamebrd.cpp.
206

bool QAccel::isEnabled () const

208       Returns TRUE if the accelerator is enabled; otherwise returns FALSE.
209
210       See also setEnabled() and isItemEnabled().
211

bool QAccel::isItemEnabled ( int id ) const

213       Returns TRUE if the accelerator item with the identifier id is enabled.
214       Returns FALSE if the item is disabled or cannot be found.
215
216       See also setItemEnabled() and isEnabled().
217

QKeySequence QAccel::key ( int id )

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

QString QAccel::keyToString ( QKeySequence k ) [static]

223       This function is obsolete. It is provided to keep old source working.
224       We strongly advise against using it in new code.
225
226       Creates an accelerator string for the key k. For instance CTRL+Key_O
227       gives "Ctrl+O". The "Ctrl" etc. are translated (using QObject::tr()) in
228       the "QAccel" context.
229
230       The function is superfluous. Cast the QKeySequence k to a QString for
231       the same effect.
232

void QAccel::removeItem ( int id )

234       Removes the accelerator item with the identifier id.
235

void QAccel::repairEventFilter ()

237       This function is obsolete. It is provided to keep old source working.
238       We strongly advise against using it in new code. serves no purpose
239       anymore
240

void QAccel::setEnabled ( bool enable )

242       Enables the accelerator if enable is TRUE, or disables it if enable is
243       FALSE.
244
245       Individual keys can also be enabled or disabled using setItemEnabled().
246       To work, a key must be an enabled item in an enabled QAccel.
247
248       See also isEnabled() and setItemEnabled().
249

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

251       Enables the accelerator item with the identifier id if enable is TRUE,
252       and disables item id if enable is FALSE.
253
254       To work, an item must be enabled and be in an enabled QAccel.
255
256       See also isItemEnabled() and isEnabled().
257

void QAccel::setWhatsThis ( int id, const QString & text )

259       Sets a What's This help text for the accelerator item id to text.
260
261       The text will be shown when the application is in What's This mode and
262       the user hits the accelerator key.
263
264       To set What's This help on a menu item (with or without an accelerator
265       key), use QMenuData::setWhatsThis().
266
267       See also whatsThis(), QWhatsThis::inWhatsThisMode(),
268       QMenuData::setWhatsThis(), and QAction::whatsThis.
269

QKeySequence QAccel::shortcutKey ( const QString & str ) [static]

271       Returns the shortcut key sequence for str, or an invalid key sequence
272       (0) if str has no shortcut sequence.
273
274       For example, shortcutKey("E&xit") returns ALT+Key_X,
275       shortcutKey("&Quit") returns ALT+Key_Q and shortcutKey("Quit") returns
276       0. (In code that does not inherit the Qt namespace class, you must
277       write e.g. Qt::ALT+Qt::Key_Q.)
278
279       We provide a list of common accelerators in English. At the time of
280       writing, Microsoft and Open Group do not appear to have issued
281       equivalent recommendations for other languages.
282

QKeySequence QAccel::stringToKey ( const QString & s ) [static]

284       This function is obsolete. It is provided to keep old source working.
285       We strongly advise against using it in new code.
286
287       Returns an accelerator code for the string s. For example" Ctrl+O"
288       gives CTRL+UNICODE_ACCEL+'O'. The strings "Ctrl"," Shift", "Alt" are
289       recognized, as well as their translated equivalents in the "QAccel"
290       context (using QObject::tr()). Returns 0 if s is not recognized.
291
292       This function is typically used with tr(), so that accelerator keys can
293       be replaced in translations:
294
295           QPopupMenu *file = new QPopupMenu( this );
296           file->insertItem( p1, tr("&Open..."), this, SLOT(open()),
297                             QAccel::stringToKey(tr("Ctrl+O", "File|Open")) );
298
299       Notice the "File|Open" translator comment. It is by no means necessary,
300       but it provides some context for the human translator.
301
302       The function is superfluous. Construct a QKeySequence from the string s
303       for the same effect.
304
305       See also QObject::tr() and Internationalization with Qt.
306
307       Example: i18n/mywidget.cpp.
308

QString QAccel::whatsThis ( int id ) const

310       Returns the What's This help text for the specified item id or
311       QString::null if no text has been specified.
312
313       See also setWhatsThis().
314
315

SEE ALSO

317       http://doc.trolltech.com/qaccel.html
318       http://www.trolltech.com/faq/tech.html
319
321       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
322       license file included in the distribution for a complete license
323       statement.
324

AUTHOR

326       Generated automatically from the source code.
327

BUGS

329       If you find a bug in Qt, please report it as described in
330       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
331       help you. Thank you.
332
333       The definitive Qt documentation is provided in HTML format; it is
334       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
335       web browser. This man page is provided as a convenience for those users
336       who prefer man pages, although this format is not officially supported
337       by Trolltech.
338
339       If you find errors in this manual page, please report them to qt-
340       bugs@trolltech.com.  Please include the name of the manual page
341       (qaccel.3qt) and the Qt version (3.3.8).
342
343
344
345Trolltech AS                    2 February 2007                    QAccel(3qt)
Impressum