1QButton(3qt)                                                      QButton(3qt)
2
3
4

NAME

6       QButton - The abstract base class of button widgets, providing
7       functionality common to buttons
8

SYNOPSIS

10       #include <qbutton.h>
11
12       Inherits QWidget.
13
14       Inherited by QCheckBox, QPushButton, QRadioButton, and QToolButton.
15
16   Public Members
17       QButton ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )
18       ~QButton ()
19       QString text () const
20       virtual void setText ( const QString & )
21       const QPixmap * pixmap () const
22       virtual void setPixmap ( const QPixmap & )
23       QKeySequence accel () const
24       virtual void setAccel ( const QKeySequence & )
25       bool isToggleButton () const
26       enum ToggleType { SingleShot, Toggle, Tristate }
27       ToggleType toggleType () const
28       virtual void setDown ( bool )
29       bool isDown () const
30       bool isOn () const
31       enum ToggleState { Off, NoChange, On }
32       ToggleState state () const
33       bool autoResize () const  (obsolete)
34       void setAutoResize ( bool )  (obsolete)
35       bool autoRepeat () const
36       virtual void setAutoRepeat ( bool )
37       bool isExclusiveToggle () const
38       QButtonGroup * group () const
39
40   Public Slots
41       void animateClick ()
42       void toggle ()
43
44   Signals
45       void pressed ()
46       void released ()
47       void clicked ()
48       void toggled ( bool on )
49       void stateChanged ( int state )
50
51   Properties
52       QKeySequence accel - the accelerator associated with the button
53       bool autoRepeat - whether autoRepeat is enabled
54       bool autoResize - whether autoResize is enabled  (obsolete)
55       bool down - whether the button is pressed
56       bool exclusiveToggle - whether the button is an exclusive toggle  (read
57           only)
58       bool on - whether the button is toggled  (read only)
59       QPixmap pixmap - the pixmap shown on the button
60       QString text - the text shown on the button
61       bool toggleButton - whether the button is a toggle button  (read only)
62       ToggleState toggleState - the state of the toggle button  (read only)
63       ToggleType toggleType - the type of toggle on the button  (read only)
64
65   Protected Members
66       void setToggleButton ( bool b )
67       virtual void setToggleType ( ToggleType type )
68       void setOn ( bool on )
69       virtual void setState ( ToggleState s )
70       virtual bool hitButton ( const QPoint & pos ) const
71       virtual void drawButton ( QPainter * )
72       virtual void drawButtonLabel ( QPainter * )
73       virtual void paintEvent ( QPaintEvent * )
74

DESCRIPTION

76       The QButton class is the abstract base class of button widgets,
77       providing functionality common to buttons.
78
79       If you want to create a button use QPushButton.
80
81       The QButton class implements an abstract button, and lets subclasses
82       specify how to reply to user actions and how to draw the button.
83
84       QButton provides both push and toggle buttons. The QRadioButton and
85       QCheckBox classes provide only toggle buttons; QPushButton and
86       QToolButton provide both toggle and push buttons.
87
88       Any button can have either a text or pixmap label. setText() sets the
89       button to be a text button and setPixmap() sets it to be a pixmap
90       button. The text/pixmap is manipulated as necessary to create the
91       "disabled" appearance when the button is disabled.
92
93       QButton provides most of the states used for buttons:
94
95       isDown() indicates whether the button is pressed down.
96
97       isOn() indicates whether the button is on. Only toggle buttons can be
98       switched on and off (see below).
99
100       isEnabled() indicates whether the button can be pressed by the user.
101
102       setAutoRepeat() sets whether the button will auto-repeat if the user
103       holds it down.
104
105       setToggleButton() sets whether the button is a toggle button or not.
106
107       The difference between isDown() and isOn() is as follows: When the user
108       clicks a toggle button to toggle it on, the button is first pressed and
109       then released into the on state. When the user clicks it again (to
110       toggle it off), the button moves first to the pressed state, then to
111       the off state (isOn() and isDown() are both FALSE).
112
113       Default buttons (as used in many dialogs) are provided by
114       QPushButton::setDefault() and QPushButton::setAutoDefault().
115
116       QButton provides five signals: <ol type=1>
117
118       pressed() is emitted when the button is pressed. E.g. with the mouse or
119       when animateClick() is called.
120
121       released() is emitted when the button is released. E.g. when the mouse
122       is released or the cursor is moved outside the widget.
123
124       clicked() is emitted when the button is first pressed and then released
125       when the accelerator key is typed, or when animateClick() is called.
126
127       toggled(bool) is emitted when the state of a toggle button changes.
128
129       stateChanged(int) is emitted when the state of a tristate toggle button
130       changes.
131
132       If the button is a text button with an ampersand (&) in its text,
133       QButton creates an automatic accelerator key. This code creates a push
134       button labelled "Ro<u>c</u>k & Roll" (where the c is underlined). The
135       button gets an automatic accelerator key, Alt+C:
136
137               QPushButton *p = new QPushButton( "Ro&ck && Roll", this );
138
139       In this example, when the user presses Alt+C the button will call
140       animateClick().
141
142       You can also set a custom accelerator using the setAccel() function.
143       This is useful mostly for pixmap buttons because they have no automatic
144       accelerator.
145
146               p->setPixmap( QPixmap("print.png") );
147               p->setAccel( ALT+Key_F7 );
148
149       All of the buttons provided by Qt (QPushButton, QToolButton, QCheckBox
150       and QRadioButton) can display both text and pixmaps.
151
152       To subclass QButton, you must reimplement at least drawButton() (to
153       draw the button's outline) and drawButtonLabel() (to draw its text or
154       pixmap). It is generally advisable to reimplement sizeHint() as well,
155       and sometimes hitButton() (to determine whether a button press is
156       within the button).
157
158       To reduce flickering, QButton::paintEvent() sets up a pixmap that the
159       drawButton() function draws in. You should not reimplement paintEvent()
160       for a subclass of QButton unless you want to take over all drawing.
161
162       See also QButtonGroup and Abstract Widget Classes.
163
164   Member Type Documentation

QButton::ToggleState

166       This enum defines the state of a toggle button.
167
168       QButton::Off - the button is in the "off" state
169
170       QButton::NoChange - the button is in the default/unchanged state
171
172       QButton::On - the button is in the "on" state
173

QButton::ToggleType

175       This enum type defines what a button can do in response to a
176       mouse/keyboard press:
177
178       QButton::SingleShot - pressing the button causes an action, then the
179       button returns to the unpressed state.
180
181       QButton::Toggle - pressing the button toggles it between an On and an
182       Off state.
183
184       QButton::Tristate - pressing the button cycles between the three states
185       On, Off and NoChange
186

MEMBER FUNCTION DOCUMENTATION

QButton::QButton ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )

189
190       Constructs a standard button called name with parent parent, using the
191       widget flags f.
192
193       If parent is a QButtonGroup, this constructor calls
194       QButtonGroup::insert().
195

QButton::~QButton ()

197       Destroys the button.
198

QKeySequence QButton::accel () const

200       Returns the accelerator associated with the button. See the "accel"
201       property for details.
202

void QButton::animateClick () [slot]

204       Performs an animated click: the button is pressed and released a short
205       while later.
206
207       The pressed(), released(), clicked(), toggled(), and stateChanged()
208       signals are emitted as appropriate.
209
210       This function does nothing if the button is disabled.
211
212       See also accel.
213

bool QButton::autoRepeat () const

215       Returns TRUE if autoRepeat is enabled; otherwise returns FALSE. See the
216       "autoRepeat" property for details.
217

bool QButton::autoResize () const

219       Returns TRUE if autoResize is enabled; otherwise returns FALSE. See the
220       "autoResize" property for details.
221

void QButton::clicked () [signal]

223       This signal is emitted when the button is activated (i.e. first pressed
224       down and then released when the mouse cursor is inside the button),
225       when the accelerator key is typed or when animateClick() is called.
226       This signal is not emitted if you call setDown().
227
228       The QButtonGroup::clicked() signal does the same job, if you want to
229       connect several buttons to the same slot.
230
231       Warning: Don't launch a model dialog in response to this signal for a
232       button that has autoRepeat turned on.
233
234       See also pressed(), released(), toggled(), autoRepeat, and down.
235
236       Examples:
237

void QButton::drawButton ( QPainter * ) [virtual protected]

239       Draws the button. The default implementation does nothing.
240
241       This virtual function is reimplemented by subclasses to draw real
242       buttons. At some point, these reimplementations should call
243       drawButtonLabel().
244
245       See also drawButtonLabel() and paintEvent().
246

void QButton::drawButtonLabel ( QPainter * ) [virtual protected]

248       Draws the button text or pixmap.
249
250       This virtual function is reimplemented by subclasses to draw real
251       buttons. It is invoked by drawButton().
252
253       See also drawButton() and paintEvent().
254

QButtonGroup * QButton::group () const

256       Returns the group that this button belongs to.
257
258       If the button is not a member of any QButtonGroup, this function
259       returns 0.
260
261       See also QButtonGroup.
262

bool QButton::hitButton ( const QPoint & pos ) const [virtual protected]

264       Returns TRUE if pos is inside the clickable button rectangle; otherwise
265       returns FALSE.
266
267       By default, the clickable area is the entire widget. Subclasses may
268       reimplement it, though.
269

bool QButton::isDown () const

271       Returns TRUE if the button is pressed; otherwise returns FALSE. See the
272       "down" property for details.
273

bool QButton::isExclusiveToggle () const

275       Returns TRUE if the button is an exclusive toggle; otherwise returns
276       FALSE. See the "exclusiveToggle" property for details.
277

bool QButton::isOn () const

279       Returns TRUE if the button is toggled; otherwise returns FALSE. See the
280       "on" property for details.
281

bool QButton::isToggleButton () const

283       Returns TRUE if the button is a toggle button; otherwise returns FALSE.
284       See the "toggleButton" property for details.
285

void QButton::paintEvent ( QPaintEvent * ) [virtual protected]

287       Handles paint events for buttons. Small and typically complex buttons
288       are painted double-buffered to reduce flicker. The actually drawing is
289       done in the virtual functions drawButton() and drawButtonLabel().
290
291       See also drawButton() and drawButtonLabel().
292
293       Reimplemented from QWidget.
294

const QPixmap * QButton::pixmap () const

296       Returns the pixmap shown on the button. See the "pixmap" property for
297       details.
298

void QButton::pressed () [signal]

300       This signal is emitted when the button is pressed down.
301
302       See also released() and clicked().
303
304       Examples:
305

void QButton::released () [signal]

307       This signal is emitted when the button is released.
308
309       See also pressed(), clicked(), and toggled().
310

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

312       Sets the accelerator associated with the button. See the "accel"
313       property for details.
314

void QButton::setAutoRepeat ( bool ) [virtual]

316       Sets whether autoRepeat is enabled. See the "autoRepeat" property for
317       details.
318

void QButton::setAutoResize ( bool )

320       Sets whether autoResize is enabled. See the "autoResize" property for
321       details.
322

void QButton::setDown ( bool ) [virtual]

324       Sets whether the button is pressed. See the "down" property for
325       details.
326

void QButton::setOn ( bool on ) [protected]

328       Sets the state of this button to On if on is TRUE; otherwise to Off.
329
330       See also toggleState.
331

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

333       Sets the pixmap shown on the button. See the "pixmap" property for
334       details.
335

void QButton::setState ( ToggleState s ) [virtual protected]

337       Sets the toggle state of the button to s. s can be Off, NoChange or On.
338

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

340       Sets the text shown on the button. See the "text" property for details.
341

void QButton::setToggleButton ( bool b ) [protected]

343       If b is TRUE, this button becomes a toggle button; if b is FALSE, this
344       button becomes a command button.
345
346       See also toggleButton.
347

void QButton::setToggleType ( ToggleType type ) [virtual protected]

349       Sets the toggle type of the button to type.
350
351       type can be set to SingleShot, Toggle and Tristate.
352

ToggleState QButton::state () const

354       Returns the state of the toggle button. See the "toggleState" property
355       for details.
356

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

358       This signal is emitted whenever a toggle button changes state. state is
359       On if the button is on, NoChange if it is in the" no change" state or
360       Off if the button is off.
361
362       This may be the result of a user action, toggle() slot activation,
363       setState(), or because setOn() was called.
364
365       See also clicked() and QButton::ToggleState.
366

QString QButton::text () const

368       Returns the text shown on the button. See the "text" property for
369       details.
370

void QButton::toggle () [slot]

372       Toggles the state of a toggle button.
373
374       See also on, setOn(), toggled(), and toggleButton.
375

ToggleType QButton::toggleType () const

377       Returns the type of toggle on the button. See the "toggleType" property
378       for details.
379

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

381       This signal is emitted whenever a toggle button changes status. on is
382       TRUE if the button is on, or FALSE if the button is off.
383
384       This may be the result of a user action, toggle() slot activation, or
385       because setOn() was called.
386
387       See also clicked().
388
389       Example: listbox/listbox.cpp.
390
391   Property Documentation

QKeySequence accel

393       This property holds the accelerator associated with the button.
394
395       This property is 0 if there is no accelerator set. If you set this
396       property to 0 then any current accelerator is removed.
397
398       Set this property's value with setAccel() and get this property's value
399       with accel().
400

bool autoRepeat

402       This property holds whether autoRepeat is enabled.
403
404       If autoRepeat is enabled then the clicked() signal is emitted at
405       regular intervals if the button is down. This property has no effect on
406       toggle buttons. autoRepeat is off by default.
407
408       Set this property's value with setAutoRepeat() and get this property's
409       value with autoRepeat().
410

bool autoResize

412       This property holds whether autoResize is enabled.
413
414       This property is obsolete. It is provided to keep old source working.
415       We strongly advise against using it in new code.
416
417       If autoResize is enabled then the button will resize itself whenever
418       the contents are changed.
419
420       Set this property's value with setAutoResize() and get this property's
421       value with autoResize().
422

bool down

424       This property holds whether the button is pressed.
425
426       If this property is TRUE, the button is pressed down. The signals
427       pressed() and clicked() are not emitted if you set this property to
428       TRUE. The default is FALSE.
429
430       Set this property's value with setDown() and get this property's value
431       with isDown().
432

bool exclusiveToggle

434       This property holds whether the button is an exclusive toggle.
435
436       If this property is TRUE and the button is in a QButtonGroup, the
437       button can only be toggled off by another one being toggled on. The
438       default is FALSE.
439
440       Get this property's value with isExclusiveToggle().
441

bool on

443       This property holds whether the button is toggled.
444
445       This property should only be set for toggle buttons.
446
447       Get this property's value with isOn().
448

QPixmap pixmap

450       This property holds the pixmap shown on the button.
451
452       If the pixmap is monochrome (i.e. it is a QBitmap or its depth is 1)
453       and it does not have a mask, this property will set the pixmap to be
454       its own mask. The purpose of this is to draw transparent bitmaps which
455       are important for toggle buttons, for example.
456
457       pixmap() returns 0 if no pixmap was set.
458
459       Set this property's value with setPixmap() and get this property's
460       value with pixmap().
461

QString text

463       This property holds the text shown on the button.
464
465       This property will return a QString::null if the button has no text. If
466       the text has an ampersand (&) in it, then an accelerator is
467       automatically created for it using the character that follows the '&'
468       as the accelerator key. Any previous accelerator will be overwritten,
469       or cleared if no accelerator is defined by the text.
470
471       There is no default text.
472
473       Set this property's value with setText() and get this property's value
474       with text().
475

bool toggleButton

477       This property holds whether the button is a toggle button.
478
479       The default value is FALSE.
480
481       Get this property's value with isToggleButton().
482

ToggleState toggleState

484       This property holds the state of the toggle button.
485
486       If this property is changed then it does not cause the button to be
487       repainted.
488
489       Get this property's value with state().
490

ToggleType toggleType

492       This property holds the type of toggle on the button.
493
494       The default toggle type is SingleShot.
495
496       See also QButton::ToggleType.
497
498       Get this property's value with toggleType().
499
500

SEE ALSO

502       http://doc.trolltech.com/qbutton.html
503       http://www.trolltech.com/faq/tech.html
504
506       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
507       license file included in the distribution for a complete license
508       statement.
509

AUTHOR

511       Generated automatically from the source code.
512

BUGS

514       If you find a bug in Qt, please report it as described in
515       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
516       help you. Thank you.
517
518       The definitive Qt documentation is provided in HTML format; it is
519       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
520       web browser. This man page is provided as a convenience for those users
521       who prefer man pages, although this format is not officially supported
522       by Trolltech.
523
524       If you find errors in this manual page, please report them to qt-
525       bugs@trolltech.com.  Please include the name of the manual page
526       (qbutton.3qt) and the Qt version (3.3.8).
527
528
529
530Trolltech AS                    2 February 2007                   QButton(3qt)
Impressum