1QPushButton(3qt)                                              QPushButton(3qt)
2
3
4

NAME

6       QPushButton - Command button
7

SYNOPSIS

9       #include <qpushbutton.h>
10
11       Inherits QButton.
12
13   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
34   Public Slots
35       virtual void setOn ( bool )
36
37   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
60   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

DESCRIPTION

72       The QPushButton widget provides a command button.
73
74       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
79       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
84               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
88       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
95       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
100       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
109       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
115       The most important modes or states are:
116
117       Available or not (grayed out, disabled).
118
119       Standard push button, toggling push button or menu button.
120
121       On or off (only for toggling push buttons).
122
123       Default or normal. The default button in a dialog can generally be
124       "clicked" using the Enter or Return key.
125
126       Auto-repeat or not.
127
128       Pressed down or not.
129
130       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
139       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
144       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
149       Other classes of buttons are option buttons (see QRadioButton) and
150       check boxes (see QCheckBox).
151
152                                   [Image Omitted]
153
154                                   [Image Omitted]
155
156       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
160       See also QToolButton, QRadioButton, QCheckBox, GUI Design Handbook:
161       Push Button, and Basic Widgets.
162

MEMBER FUNCTION DOCUMENTATION

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

165       Constructs a push button with no text.
166
167       The parent and name arguments are sent on to the QWidget constructor.
168

QPushButton::QPushButton ( const QString & text, QWidget * parent, const char

170       * name = 0 )
171       Constructs a push button called name with the parent parent and the
172       text text.
173

QPushButton::QPushButton ( const QIconSet & icon, const QString & text,

175       QWidget * parent, const char * name = 0 )
176       Constructs a push button with an icon and a text.
177
178       Note that you can also pass a QPixmap object as an icon (thanks to the
179       implicit type conversion provided by C++).
180
181       The parent and name arguments are sent to the QWidget constructor.
182

QPushButton::~QPushButton ()

184       Destroys the push button.
185

QKeySequence QButton::accel () const

187       Returns the accelerator associated with the button. See the "accel"
188       property for details.
189

bool QPushButton::autoDefault () const

191       Returns TRUE if the push button is the auto default button; otherwise
192       returns FALSE. See the "autoDefault" property for details.
193

bool QButton::autoRepeat () const

195       Returns TRUE if autoRepeat is enabled; otherwise returns FALSE. See the
196       "autoRepeat" property for details.
197

void QButton::clicked () [signal]

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
204       The QButtonGroup::clicked() signal does the same job, if you want to
205       connect several buttons to the same slot.
206
207       Warning: Don't launch a model dialog in response to this signal for a
208       button that has autoRepeat turned on.
209
210       See also pressed(), released(), toggled(), autoRepeat, and down.
211
212       Examples:
213

QButtonGroup * QButton::group () const

215       Returns the group that this button belongs to.
216
217       If the button is not a member of any QButtonGroup, this function
218       returns 0.
219
220       See also QButtonGroup.
221

QIconSet * QPushButton::iconSet () const

223       Returns the icon set on the push button. See the "iconSet" property for
224       details.
225

bool QPushButton::isDefault () const

227       Returns TRUE if the push button is the default button; otherwise
228       returns FALSE. See the "default" property for details.
229

bool QButton::isDown () const

231       Returns TRUE if the button is pressed; otherwise returns FALSE. See the
232       "down" property for details.
233

bool QButton::isExclusiveToggle () const

235       Returns TRUE if the button is an exclusive toggle; otherwise returns
236       FALSE. See the "exclusiveToggle" property for details.
237

bool QPushButton::isFlat () const

239       Returns TRUE if the border is disabled; otherwise returns FALSE. See
240       the "flat" property for details.
241

bool QPushButton::isMenuButton () const

243       Returns TRUE if the push button has a menu button on it; otherwise
244       returns FALSE. See the "menuButton" property for details.
245

bool QButton::isOn () const

247       Returns TRUE if the button is toggled; otherwise returns FALSE. See the
248       "on" property for details.
249

bool QButton::isToggleButton () const

251       Returns TRUE if the button is a toggle button; otherwise returns FALSE.
252       See the "toggleButton" property for details.
253

const QPixmap * QButton::pixmap () const

255       Returns the pixmap shown on the button. See the "pixmap" property for
256       details.
257

QPopupMenu * QPushButton::popup () const

259       Returns the button's associated popup menu or 0 if no popup menu has
260       been set.
261
262       See also setPopup().
263

void QButton::pressed () [signal]

265       This signal is emitted when the button is pressed down.
266
267       See also released() and clicked().
268
269       Examples:
270

void QButton::released () [signal]

272       This signal is emitted when the button is released.
273
274       See also pressed(), clicked(), and toggled().
275

void QButton::setAccel ( const QKeySequence & ) [virtual]

277       Sets the accelerator associated with the button. See the "accel"
278       property for details.
279

void QPushButton::setAutoDefault ( bool autoDef ) [virtual]

281       Sets whether the push button is the auto default button to autoDef. See
282       the "autoDefault" property for details.
283

void QButton::setAutoRepeat ( bool ) [virtual]

285       Sets whether autoRepeat is enabled. See the "autoRepeat" property for
286       details.
287

void QPushButton::setDefault ( bool def ) [virtual]

289       Sets whether the push button is the default button to def. See the
290       "default" property for details.
291

void QButton::setDown ( bool ) [virtual]

293       Sets whether the button is pressed. See the "down" property for
294       details.
295

void QPushButton::setFlat ( bool )

297       Sets whether the border is disabled. See the "flat" property for
298       details.
299

void QPushButton::setIconSet ( const QIconSet & )

301       Sets the icon set on the push button. See the "iconSet" property for
302       details.
303

void QPushButton::setIsMenuButton ( bool enable ) [virtual]

305       This function is obsolete. It is provided to keep old source working.
306       We strongly advise against using it in new code.
307

void QPushButton::setOn ( bool ) [virtual slot]

309       Sets whether the push button is toggled. See the "on" property for
310       details.
311

void QButton::setPixmap ( const QPixmap & ) [virtual]

313       Sets the pixmap shown on the button. See the "pixmap" property for
314       details.
315

void QPushButton::setPopup ( QPopupMenu * popup )

317       Associates the popup menu popup with this push button. This turns the
318       button into a menu button.
319
320       Ownership of the popup menu is not transferred to the push button.
321
322       See also popup().
323
324       Examples:
325

void QButton::setText ( const QString & ) [virtual]

327       Sets the text shown on the button. See the "text" property for details.
328

void QPushButton::setToggleButton ( bool )

330       Sets whether the button is a toggle button. See the "toggleButton"
331       property for details.
332

ToggleState QButton::state () const

334       Returns the state of the toggle button. See the "toggleState" property
335       for details.
336

void QButton::stateChanged ( int state ) [signal]

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
342       This may be the result of a user action, toggle() slot activation,
343       setState(), or because setOn() was called.
344
345       See also clicked() and QButton::ToggleState.
346

QString QButton::text () const

348       Returns the text shown on the button. See the "text" property for
349       details.
350

void QButton::toggle () [slot]

352       Toggles the state of a toggle button.
353
354       See also on, on, toggled(), and toggleButton.
355

void QButton::toggled ( bool on ) [signal]

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
360       This may be the result of a user action, toggle() slot activation, or
361       because setOn() was called.
362
363       See also clicked().
364
365       Example: listbox/listbox.cpp.
366
367   Property Documentation

QKeySequence accel

369       This property holds the accelerator associated with the button.
370
371       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
374       Set this property's value with setAccel() and get this property's value
375       with accel().
376

bool autoDefault

378       This property holds whether the push button is the auto default button.
379
380       If this property is set to TRUE then the push button is the auto
381       default button in a dialog.
382
383       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
388       This property's default is TRUE for buttons that have a QDialog parent;
389       otherwise it defaults to FALSE.
390
391       See the default property for details of how default and auto-default
392       interact.
393
394       Set this property's value with setAutoDefault() and get this property's
395       value with autoDefault().
396

bool autoMask

398       This property holds whether the button is automatically masked.
399
400       See also QWidget::autoMask.
401

bool autoRepeat

403       This property holds whether autoRepeat is enabled.
404
405       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
409       Set this property's value with setAutoRepeat() and get this property's
410       value with autoRepeat().
411

bool default

413       This property holds whether the push button is the default button.
414
415       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
418       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
425       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
429       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
433       This property's default is FALSE.
434
435       Set this property's value with setDefault() and get this property's
436       value with isDefault().
437

bool flat

439       This property holds whether the border is disabled.
440
441       This property's default is FALSE.
442
443       Set this property's value with setFlat() and get this property's value
444       with isFlat().
445

QIconSet iconSet

447       This property holds the icon set on the push button.
448
449       This property will return 0 if the push button has no iconset.
450
451       Set this property's value with setIconSet() and get this property's
452       value with iconSet().
453

bool menuButton

455       This property holds whether the push button has a menu button on it.
456
457       This property is obsolete. It is provided to keep old source working.
458       We strongly advise against using it in new code.
459
460       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
464       Get this property's value with isMenuButton().
465

bool on

467       This property holds whether the push button is toggled.
468
469       This property should only be set for toggle push buttons. The default
470       value is FALSE.
471
472       See also on, toggle(), toggled(), and toggleButton.
473
474       Set this property's value with setOn().
475

QPixmap pixmap

477       This property holds the pixmap shown on the button.
478
479       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
484       pixmap() returns 0 if no pixmap was set.
485
486       Set this property's value with setPixmap() and get this property's
487       value with pixmap().
488

QString text

490       This property holds the text shown on the button.
491
492       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
498       There is no default text.
499
500       Set this property's value with setText() and get this property's value
501       with text().
502

bool toggleButton

504       This property holds whether the button is a toggle button.
505
506       Toggle buttons have an on/off state similar to check boxes. A push
507       button is initially not a toggle button.
508
509       See also on, toggle(), toggleButton, and toggled().
510
511       Set this property's value with setToggleButton().
512
513

SEE ALSO

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

AUTHOR

524       Generated automatically from the source code.
525

BUGS

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
531       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
537       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).
540
541
542
543Trolltech AS                    2 February 2007               QPushButton(3qt)
Impressum