1QPushButton(3qt) QPushButton(3qt)
2
6 QPushButton - Command button
7
9 #include <qpushbutton.h>
10 Inherits QButton.
12 Public Members
14 QPushButton ( QWidget * parent, const char * name = 0 )
15 QPushButton ( const QString & text, QWidget * parent, const char * name
16 = 0 )
17 QPushButton ( const QIconSet & icon, const QString & text, QWidget *
18 parent, const char * name = 0 )
19 ~QPushButton ()
20 void setToggleButton ( bool )
21 bool autoDefault () const
22 virtual void setAutoDefault ( bool autoDef )
23 bool isDefault () const
24 virtual void setDefault ( bool def )
25 virtual void setIsMenuButton ( bool enable ) (obsolete)
26 bool isMenuButton () const (obsolete)
27 void setPopup ( QPopupMenu * popup )
28 QPopupMenu * popup () const
29 void setIconSet ( const QIconSet & )
30 QIconSet * iconSet () const
31 void setFlat ( bool )
32 bool isFlat () const
33 Public Slots
35 virtual void setOn ( bool )
36 Important Inherited Members
38 QString text () const
39 virtual void setText ( const QString & )
40 const QPixmap * pixmap () const
41 virtual void setPixmap ( const QPixmap & )
42 QKeySequence accel () const
43 virtual void setAccel ( const QKeySequence & )
44 bool isToggleButton () const
45 virtual void setDown ( bool )
46 bool isDown () const
47 bool isOn () const
48 ToggleState state () const
49 bool autoRepeat () const
50 virtual void setAutoRepeat ( bool )
51 bool isExclusiveToggle () const
52 QButtonGroup * group () const
53 void toggle ()
54 void pressed ()
55 void released ()
56 void clicked ()
57 void toggled ( bool on )
58 void stateChanged ( int state )
59 Properties
61 bool autoDefault - whether the push button is the auto default button
62 bool autoMask - whether the button is automatically masked (read only)
63 bool default - whether the push button is the default button
64 bool flat - whether the border is disabled
65 QIconSet iconSet - the icon set on the push button
66 bool menuButton - whether the push button has a menu button on it
67 (read only) (obsolete)
68 bool on - whether the push button is toggled
69 bool toggleButton - whether the button is a toggle button
70
72 The QPushButton widget provides a command button.
73 The push button, or command button, is perhaps the most commonly used
75 widget in any graphical user interface. Push (click) a button to
76 command the computer to perform some action, or to answer a question.
77 Typical buttons are OK, Apply, Cancel, Close, Yes, No and Help.
78 A command button is rectangular and typically displays a text label
80 describing its action. An underlined character in the label (signified
81 by preceding it with an ampersand in the text) indicates an accelerator
82 key, e.g.
83 QPushButton *pb = new QPushButton( "&Download", this );
85 In this example the accelerator is Alt+D, and the label text will be
86 displayed as <u>D</u>ownload.
87 Push buttons can display a textual label or a pixmap, and optionally a
89 small icon. These can be set using the constructors and changed later
90 using setText(), setPixmap() and setIconSet(). If the button is
91 disabled the appearance of the text or pixmap and iconset will be
92 manipulated with respect to the GUI style to make the button look
93 "disabled".
94 A push button emits the signal clicked() when it is activated by the
96 mouse, the Spacebar or by a keyboard accelerator. Connect to this
97 signal to perform the button's action. Push buttons also provide less
98 commonly used signals, for example, pressed() and released().
99 Command buttons in dialogs are by default auto-default buttons, i.e.
101 they become the default push button automatically when they receive the
102 keyboard input focus. A default button is a push button that is
103 activated when the user presses the Enter or Return key in a dialog.
104 You can change this with setAutoDefault(). Note that auto-default
105 buttons reserve a little extra space which is necessary to draw a
106 default-button indicator. If you do not want this space around your
107 buttons, call setAutoDefault(FALSE).
108 Being so central, the button widget has grown to accommodate a great
110 many variations in the past decade. The Microsoft style guide now shows
111 about ten different states of Windows push buttons and the text implies
112 that there are dozens more when all the combinations of features are
113 taken into consideration.
114 The most important modes or states are:
116 Available or not (grayed out, disabled).
118 Standard push button, toggling push button or menu button.
120 On or off (only for toggling push buttons).
122 Default or normal. The default button in a dialog can generally be
124 "clicked" using the Enter or Return key.
125 Auto-repeat or not.
127 Pressed down or not.
129 As a general rule, use a push button when the application or dialog
131 window performs an action when the user clicks on it (such as Apply,
132 Cancel, Close and Help) and when the widget is supposed to have a wide,
133 rectangular shape with a text label. Small, typically square buttons
134 that change the state of the window rather than performing an action
135 (such as the buttons in the top-right corner of the QFileDialog) are
136 not command buttons, but tool buttons. Qt provides a special class
137 (QToolButton) for these buttons.
138 If you need toggle behavior (see setToggleButton()) or a button that
140 auto-repeats the activation signal when being pushed down like the
141 arrows in a scroll bar (see setAutoRepeat()), a command button is
142 probably not what you want. When in doubt, use a tool button.
143 A variation of a command button is a menu button. These provide not
145 just one command, but several, since when they are clicked they pop up
146 a menu of options. Use the method setPopup() to associate a popup menu
147 with a push button.
148 Other classes of buttons are option buttons (see QRadioButton) and
150 check boxes (see QCheckBox).
151 [Image Omitted]
153 [Image Omitted]
155 In Qt, the QButton abstract base class provides most of the modes and
157 other API, and QPushButton provides GUI logic. See QButton for more
158 information about the API.
159 See also QToolButton, QRadioButton, QCheckBox, GUI Design Handbook:
161 Push Button, and Basic Widgets.
162
165 Constructs a push button with no text.
166 The parent and name arguments are sent on to the QWidget constructor.
168
170 * name = 0 )
171 Constructs a push button called name with the parent parent and the
172 text text.
173
175 QWidget * parent, const char * name = 0 )
176 Constructs a push button with an icon and a text.
177 Note that you can also pass a QPixmap object as an icon (thanks to the
179 implicit type conversion provided by C++).
180 The parent and name arguments are sent to the QWidget constructor.
182
184 Destroys the push button.
185
187 Returns the accelerator associated with the button. See the "accel"
188 property for details.
189
191 Returns TRUE if the push button is the auto default button; otherwise
192 returns FALSE. See the "autoDefault" property for details.
193
195 Returns TRUE if autoRepeat is enabled; otherwise returns FALSE. See the
196 "autoRepeat" property for details.
197
199 This signal is emitted when the button is activated (i.e. first pressed
200 down and then released when the mouse cursor is inside the button),
201 when the accelerator key is typed or when animateClick() is called.
202 This signal is not emitted if you call setDown().
203 The QButtonGroup::clicked() signal does the same job, if you want to
205 connect several buttons to the same slot.
206 Warning: Don't launch a model dialog in response to this signal for a
208 button that has autoRepeat turned on.
209 See also pressed(), released(), toggled(), autoRepeat, and down.
211 Examples:
213
215 Returns the group that this button belongs to.
216 If the button is not a member of any QButtonGroup, this function
218 returns 0.
219 See also QButtonGroup.
221
223 Returns the icon set on the push button. See the "iconSet" property for
224 details.
225
227 Returns TRUE if the push button is the default button; otherwise
228 returns FALSE. See the "default" property for details.
229
231 Returns TRUE if the button is pressed; otherwise returns FALSE. See the
232 "down" property for details.
233
235 Returns TRUE if the button is an exclusive toggle; otherwise returns
236 FALSE. See the "exclusiveToggle" property for details.
237
239 Returns TRUE if the border is disabled; otherwise returns FALSE. See
240 the "flat" property for details.
241
243 Returns TRUE if the push button has a menu button on it; otherwise
244 returns FALSE. See the "menuButton" property for details.
245
247 Returns TRUE if the button is toggled; otherwise returns FALSE. See the
248 "on" property for details.
249
251 Returns TRUE if the button is a toggle button; otherwise returns FALSE.
252 See the "toggleButton" property for details.
253
255 Returns the pixmap shown on the button. See the "pixmap" property for
256 details.
257
259 Returns the button's associated popup menu or 0 if no popup menu has
260 been set.
261 See also setPopup().
263
265 This signal is emitted when the button is pressed down.
266 See also released() and clicked().
268 Examples:
270
272 This signal is emitted when the button is released.
273 See also pressed(), clicked(), and toggled().
275
277 Sets the accelerator associated with the button. See the "accel"
278 property for details.
279
281 Sets whether the push button is the auto default button to autoDef. See
282 the "autoDefault" property for details.
283
285 Sets whether autoRepeat is enabled. See the "autoRepeat" property for
286 details.
287
289 Sets whether the push button is the default button to def. See the
290 "default" property for details.
291
293 Sets whether the button is pressed. See the "down" property for
294 details.
295
297 Sets whether the border is disabled. See the "flat" property for
298 details.
299
301 Sets the icon set on the push button. See the "iconSet" property for
302 details.
303
305 This function is obsolete. It is provided to keep old source working.
306 We strongly advise against using it in new code.
307
309 Sets whether the push button is toggled. See the "on" property for
310 details.
311
313 Sets the pixmap shown on the button. See the "pixmap" property for
314 details.
315
317 Associates the popup menu popup with this push button. This turns the
318 button into a menu button.
319 Ownership of the popup menu is not transferred to the push button.
321 See also popup().
323 Examples:
325
327 Sets the text shown on the button. See the "text" property for details.
328
330 Sets whether the button is a toggle button. See the "toggleButton"
331 property for details.
332
334 Returns the state of the toggle button. See the "toggleState" property
335 for details.
336
338 This signal is emitted whenever a toggle button changes state. state is
339 On if the button is on, NoChange if it is in the" no change" state or
340 Off if the button is off.
341 This may be the result of a user action, toggle() slot activation,
343 setState(), or because setOn() was called.
344 See also clicked() and QButton::ToggleState.
346
348 Returns the text shown on the button. See the "text" property for
349 details.
350
352 Toggles the state of a toggle button.
353 See also on, on, toggled(), and toggleButton.
355
357 This signal is emitted whenever a toggle button changes status. on is
358 TRUE if the button is on, or FALSE if the button is off.
359 This may be the result of a user action, toggle() slot activation, or
361 because setOn() was called.
362 See also clicked().
364 Example: listbox/listbox.cpp.
366 Property Documentation
369 This property holds the accelerator associated with the button.
370 This property is 0 if there is no accelerator set. If you set this
372 property to 0 then any current accelerator is removed.
373 Set this property's value with setAccel() and get this property's value
375 with accel().
376
378 This property holds whether the push button is the auto default button.
379 If this property is set to TRUE then the push button is the auto
381 default button in a dialog.
382 In some GUI styles a default button is drawn with an extra frame around
384 it, up to 3 pixels or more. Qt automatically keeps this space free
385 around auto-default buttons, i.e. auto-default buttons may have a
386 slightly larger size hint.
387 This property's default is TRUE for buttons that have a QDialog parent;
389 otherwise it defaults to FALSE.
390 See the default property for details of how default and auto-default
392 interact.
393 Set this property's value with setAutoDefault() and get this property's
395 value with autoDefault().
396
398 This property holds whether the button is automatically masked.
399 See also QWidget::autoMask.
401
403 This property holds whether autoRepeat is enabled.
404 If autoRepeat is enabled then the clicked() signal is emitted at
406 regular intervals if the button is down. This property has no effect on
407 toggle buttons. autoRepeat is off by default.
408 Set this property's value with setAutoRepeat() and get this property's
410 value with autoRepeat().
411
413 This property holds whether the push button is the default button.
414 If this property is set to TRUE then the push button will be pressed if
416 the user presses the Enter (or Return) key in a dialog.
417 Regardless of focus, if the user presses Enter: If there is a default
419 button the default button is pressed; otherwise, if there are one or
420 more autoDefault buttons the first autoDefault button that is next in
421 the tab order is pressed. If there are no default or autoDefault
422 buttons only pressing Space on a button with focus, mouse clicking, or
423 using an accelerator will press a button.
424 In a dialog, only one push button at a time can be the default button.
426 This button is then displayed with an additional frame (depending on
427 the GUI style).
428 The default button behavior is provided only in dialogs. Buttons can
430 always be clicked from the keyboard by pressing Enter (or Return) or
431 the Spacebar when the button has focus.
432 This property's default is FALSE.
434 Set this property's value with setDefault() and get this property's
436 value with isDefault().
437
439 This property holds whether the border is disabled.
440 This property's default is FALSE.
442 Set this property's value with setFlat() and get this property's value
444 with isFlat().
445
447 This property holds the icon set on the push button.
448 This property will return 0 if the push button has no iconset.
450 Set this property's value with setIconSet() and get this property's
452 value with iconSet().
453
455 This property holds whether the push button has a menu button on it.
456 This property is obsolete. It is provided to keep old source working.
458 We strongly advise against using it in new code.
459 If this property is set to TRUE, then a down arrow is drawn on the push
461 button to indicate that a menu will pop up if the user clicks on the
462 arrow.
463 Get this property's value with isMenuButton().
465
467 This property holds whether the push button is toggled.
468 This property should only be set for toggle push buttons. The default
470 value is FALSE.
471 See also on, toggle(), toggled(), and toggleButton.
473 Set this property's value with setOn().
475
477 This property holds the pixmap shown on the button.
478 If the pixmap is monochrome (i.e. it is a QBitmap or its depth is 1)
480 and it does not have a mask, this property will set the pixmap to be
481 its own mask. The purpose of this is to draw transparent bitmaps which
482 are important for toggle buttons, for example.
483 pixmap() returns 0 if no pixmap was set.
485 Set this property's value with setPixmap() and get this property's
487 value with pixmap().
488
490 This property holds the text shown on the button.
491 This property will return a QString::null if the button has no text. If
493 the text has an ampersand (&) in it, then an accelerator is
494 automatically created for it using the character that follows the '&'
495 as the accelerator key. Any previous accelerator will be overwritten,
496 or cleared if no accelerator is defined by the text.
497 There is no default text.
499 Set this property's value with setText() and get this property's value
501 with text().
502
504 This property holds whether the button is a toggle button.
505 Toggle buttons have an on/off state similar to check boxes. A push
507 button is initially not a toggle button.
508 See also on, toggle(), toggleButton, and toggled().
510 Set this property's value with setToggleButton().
512
515 http://doc.trolltech.com/qpushbutton.html
516 http://www.trolltech.com/faq/tech.html
517
519 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
520 license file included in the distribution for a complete license
521 statement.
522
524 Generated automatically from the source code.
525
527 If you find a bug in Qt, please report it as described in
528 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
529 help you. Thank you.
530 The definitive Qt documentation is provided in HTML format; it is
532 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
533 web browser. This man page is provided as a convenience for those users
534 who prefer man pages, although this format is not officially supported
535 by Trolltech.
536 If you find errors in this manual page, please report them to qt-
538 bugs@trolltech.com. Please include the name of the manual page
539 (qpushbutton.3qt) and the Qt version (3.3.8).
540Trolltech AS 2 February 2007 QPushButton(3qt)