1QAccel(3qt) QAccel(3qt)
2
6 QAccel - Handles keyboard accelerator and shortcut keys
7
9 #include <qaccel.h>
10 Inherits QObject.
12 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 Signals
36 void activated ( int id )
37 void activatedAmbiguously ( int id )
38 Static Public Members
40 QKeySequence shortcutKey ( const QString & str )
41 QString keyToString ( QKeySequence k ) (obsolete)
42 QKeySequence stringToKey ( const QString & s ) (obsolete)
43 Protected Members
45 virtual bool eventFilter ( QObject *, QEvent * ) (obsolete)
46
48 The QAccel class handles keyboard accelerator and shortcut keys.
49 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 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 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 A QAccel contains a list of accelerator items that can be manipulated
68 using insertItem(), removeItem(), clear(), key() and findKey().
69 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 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 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 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 The function setWhatsThis() specifies a help text that appears when the
99 user presses an accelerator key in What's This mode.
100 The accelerator will be deleted when parent is deleted, and will
102 consume relevant key events until then.
103 Please note that the accelerator
105 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 Example:
111 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 See also QKeyEvent, QWidget::keyPressEvent(), QMenuData::setAccel(),
118 QButton::accel, QLabel::setBuddy(), QKeySequence, GUI Design Handbook:
119 Keyboard Shortcuts, and Miscellaneous Classes.
120
123 Constructs a QAccel object called name, with parent parent. The
124 accelerator operates on parent.
125
127 Constructs a QAccel object called name, that operates on watch, and is
128 a child of parent.
129 This constructor is not needed for normal application programming.
131
133 Destroys the accelerator object and frees all allocated resources.
134
136 This signal is emitted when an accelerator key is pressed. id is a
137 number that identifies this particular accelerator item.
138 See also activatedAmbiguously().
140
142 This signal is emitted when an accelerator key is pressed. id is a
143 number that identifies this particular accelerator item.
144 See also activated().
146
148 Removes all accelerator items.
149
151 member )
152 Connects the accelerator item id to the slot member of receiver.
153 a->connectItem( 201, mainView, SLOT(quit()) );
155 Of course, you can also send a signal as member.
157 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 See also disconnectItem().
165 Example: t14/gamebrd.cpp.
167
169 Returns the number of accelerator items in this accelerator.
170
172 member )
173 Disconnects an accelerator item with id id from the function called
174 member in the receiver object.
175 See also connectItem().
177
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 Reimplemented from QObject.
184
186 Returns the identifier of the accelerator item with the key code key,
187 or -1 if the item cannot be found.
188
190 Inserts an accelerator item and returns the item's identifier.
191 key is a key code and an optional combination of SHIFT, CTRL and ALT.
193 id is the accelerator item id.
194 If id is negative, then the item will be assigned a unique negative
196 identifier less than -1.
197 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 Example: t14/gamebrd.cpp.
206
208 Returns TRUE if the accelerator is enabled; otherwise returns FALSE.
209 See also setEnabled() and isItemEnabled().
211
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 See also setItemEnabled() and isEnabled().
217
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
223 This function is obsolete. It is provided to keep old source working.
224 We strongly advise against using it in new code.
225 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 The function is superfluous. Cast the QKeySequence k to a QString for
231 the same effect.
232
234 Removes the accelerator item with the identifier id.
235
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
242 Enables the accelerator if enable is TRUE, or disables it if enable is
243 FALSE.
244 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 See also isEnabled() and setItemEnabled().
249
251 Enables the accelerator item with the identifier id if enable is TRUE,
252 and disables item id if enable is FALSE.
253 To work, an item must be enabled and be in an enabled QAccel.
255 See also isItemEnabled() and isEnabled().
257
259 Sets a What's This help text for the accelerator item id to text.
260 The text will be shown when the application is in What's This mode and
262 the user hits the accelerator key.
263 To set What's This help on a menu item (with or without an accelerator
265 key), use QMenuData::setWhatsThis().
266 See also whatsThis(), QWhatsThis::inWhatsThisMode(),
268 QMenuData::setWhatsThis(), and QAction::whatsThis.
269
271 Returns the shortcut key sequence for str, or an invalid key sequence
272 (0) if str has no shortcut sequence.
273 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 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
284 This function is obsolete. It is provided to keep old source working.
285 We strongly advise against using it in new code.
286 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 This function is typically used with tr(), so that accelerator keys can
293 be replaced in translations:
294 QPopupMenu *file = new QPopupMenu( this );
296 file->insertItem( p1, tr("&Open..."), this, SLOT(open()),
297 QAccel::stringToKey(tr("Ctrl+O", "File|Open")) );
298 Notice the "File|Open" translator comment. It is by no means necessary,
300 but it provides some context for the human translator.
301 The function is superfluous. Construct a QKeySequence from the string s
303 for the same effect.
304 See also QObject::tr() and Internationalization with Qt.
306 Example: i18n/mywidget.cpp.
308
310 Returns the What's This help text for the specified item id or
311 QString::null if no text has been specified.
312 See also setWhatsThis().
314
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
326 Generated automatically from the source code.
327
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 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 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).
342Trolltech AS 2 February 2007 QAccel(3qt)