1QButton(3qt) QButton(3qt)
2
6 QButton - The abstract base class of button widgets, providing
7 functionality common to buttons
8
10 #include <qbutton.h>
11 Inherits QWidget.
13 Inherited by QCheckBox, QPushButton, QRadioButton, and QToolButton.
15 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 Public Slots
41 void animateClick ()
42 void toggle ()
43 Signals
45 void pressed ()
46 void released ()
47 void clicked ()
48 void toggled ( bool on )
49 void stateChanged ( int state )
50 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 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
76 The QButton class is the abstract base class of button widgets,
77 providing functionality common to buttons.
78 If you want to create a button use QPushButton.
80 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 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 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 QButton provides most of the states used for buttons:
94 isDown() indicates whether the button is pressed down.
96 isOn() indicates whether the button is on. Only toggle buttons can be
98 switched on and off (see below).
99 isEnabled() indicates whether the button can be pressed by the user.
101 setAutoRepeat() sets whether the button will auto-repeat if the user
103 holds it down.
104 setToggleButton() sets whether the button is a toggle button or not.
106 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 Default buttons (as used in many dialogs) are provided by
114 QPushButton::setDefault() and QPushButton::setAutoDefault().
115 QButton provides five signals: <ol type=1>
117 pressed() is emitted when the button is pressed. E.g. with the mouse or
119 when animateClick() is called.
120 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 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 toggled(bool) is emitted when the state of a toggle button changes.
128 stateChanged(int) is emitted when the state of a tristate toggle button
130 changes.
131 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 QPushButton *p = new QPushButton( "Ro&ck && Roll", this );
138 In this example, when the user presses Alt+C the button will call
140 animateClick().
141 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 p->setPixmap( QPixmap("print.png") );
147 p->setAccel( ALT+Key_F7 );
148 All of the buttons provided by Qt (QPushButton, QToolButton, QCheckBox
150 and QRadioButton) can display both text and pixmaps.
151 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 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 See also QButtonGroup and Abstract Widget Classes.
163 Member Type Documentation
166 This enum defines the state of a toggle button.
167 QButton::Off - the button is in the "off" state
169 QButton::NoChange - the button is in the default/unchanged state
171 QButton::On - the button is in the "on" state
173
175 This enum type defines what a button can do in response to a
176 mouse/keyboard press:
177 QButton::SingleShot - pressing the button causes an action, then the
179 button returns to the unpressed state.
180 QButton::Toggle - pressing the button toggles it between an On and an
182 Off state.
183 QButton::Tristate - pressing the button cycles between the three states
185 On, Off and NoChange
186
189 Constructs a standard button called name with parent parent, using the
191 widget flags f.
192 If parent is a QButtonGroup, this constructor calls
194 QButtonGroup::insert().
195
197 Destroys the button.
198
200 Returns the accelerator associated with the button. See the "accel"
201 property for details.
202
204 Performs an animated click: the button is pressed and released a short
205 while later.
206 The pressed(), released(), clicked(), toggled(), and stateChanged()
208 signals are emitted as appropriate.
209 This function does nothing if the button is disabled.
211 See also accel.
213
215 Returns TRUE if autoRepeat is enabled; otherwise returns FALSE. See the
216 "autoRepeat" property for details.
217
219 Returns TRUE if autoResize is enabled; otherwise returns FALSE. See the
220 "autoResize" property for details.
221
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 The QButtonGroup::clicked() signal does the same job, if you want to
229 connect several buttons to the same slot.
230 Warning: Don't launch a model dialog in response to this signal for a
232 button that has autoRepeat turned on.
233 See also pressed(), released(), toggled(), autoRepeat, and down.
235 Examples:
237
239 Draws the button. The default implementation does nothing.
240 This virtual function is reimplemented by subclasses to draw real
242 buttons. At some point, these reimplementations should call
243 drawButtonLabel().
244 See also drawButtonLabel() and paintEvent().
246
248 Draws the button text or pixmap.
249 This virtual function is reimplemented by subclasses to draw real
251 buttons. It is invoked by drawButton().
252 See also drawButton() and paintEvent().
254
256 Returns the group that this button belongs to.
257 If the button is not a member of any QButtonGroup, this function
259 returns 0.
260 See also QButtonGroup.
262
264 Returns TRUE if pos is inside the clickable button rectangle; otherwise
265 returns FALSE.
266 By default, the clickable area is the entire widget. Subclasses may
268 reimplement it, though.
269
271 Returns TRUE if the button is pressed; otherwise returns FALSE. See the
272 "down" property for details.
273
275 Returns TRUE if the button is an exclusive toggle; otherwise returns
276 FALSE. See the "exclusiveToggle" property for details.
277
279 Returns TRUE if the button is toggled; otherwise returns FALSE. See the
280 "on" property for details.
281
283 Returns TRUE if the button is a toggle button; otherwise returns FALSE.
284 See the "toggleButton" property for details.
285
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 See also drawButton() and drawButtonLabel().
292 Reimplemented from QWidget.
294
296 Returns the pixmap shown on the button. See the "pixmap" property for
297 details.
298
300 This signal is emitted when the button is pressed down.
301 See also released() and clicked().
303 Examples:
305
307 This signal is emitted when the button is released.
308 See also pressed(), clicked(), and toggled().
310
312 Sets the accelerator associated with the button. See the "accel"
313 property for details.
314
316 Sets whether autoRepeat is enabled. See the "autoRepeat" property for
317 details.
318
320 Sets whether autoResize is enabled. See the "autoResize" property for
321 details.
322
324 Sets whether the button is pressed. See the "down" property for
325 details.
326
328 Sets the state of this button to On if on is TRUE; otherwise to Off.
329 See also toggleState.
331
333 Sets the pixmap shown on the button. See the "pixmap" property for
334 details.
335
337 Sets the toggle state of the button to s. s can be Off, NoChange or On.
338
340 Sets the text shown on the button. See the "text" property for details.
341
343 If b is TRUE, this button becomes a toggle button; if b is FALSE, this
344 button becomes a command button.
345 See also toggleButton.
347
349 Sets the toggle type of the button to type.
350 type can be set to SingleShot, Toggle and Tristate.
352
354 Returns the state of the toggle button. See the "toggleState" property
355 for details.
356
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 This may be the result of a user action, toggle() slot activation,
363 setState(), or because setOn() was called.
364 See also clicked() and QButton::ToggleState.
366
368 Returns the text shown on the button. See the "text" property for
369 details.
370
372 Toggles the state of a toggle button.
373 See also on, setOn(), toggled(), and toggleButton.
375
377 Returns the type of toggle on the button. See the "toggleType" property
378 for details.
379
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 This may be the result of a user action, toggle() slot activation, or
385 because setOn() was called.
386 See also clicked().
388 Example: listbox/listbox.cpp.
390 Property Documentation
393 This property holds the accelerator associated with the button.
394 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 Set this property's value with setAccel() and get this property's value
399 with accel().
400
402 This property holds whether autoRepeat is enabled.
403 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 Set this property's value with setAutoRepeat() and get this property's
409 value with autoRepeat().
410
412 This property holds whether autoResize is enabled.
413 This property is obsolete. It is provided to keep old source working.
415 We strongly advise against using it in new code.
416 If autoResize is enabled then the button will resize itself whenever
418 the contents are changed.
419 Set this property's value with setAutoResize() and get this property's
421 value with autoResize().
422
424 This property holds whether the button is pressed.
425 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 Set this property's value with setDown() and get this property's value
431 with isDown().
432
434 This property holds whether the button is an exclusive toggle.
435 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 Get this property's value with isExclusiveToggle().
441
443 This property holds whether the button is toggled.
444 This property should only be set for toggle buttons.
446 Get this property's value with isOn().
448
450 This property holds the pixmap shown on the button.
451 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 pixmap() returns 0 if no pixmap was set.
458 Set this property's value with setPixmap() and get this property's
460 value with pixmap().
461
463 This property holds the text shown on the button.
464 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 There is no default text.
472 Set this property's value with setText() and get this property's value
474 with text().
475
477 This property holds whether the button is a toggle button.
478 The default value is FALSE.
480 Get this property's value with isToggleButton().
482
484 This property holds the state of the toggle button.
485 If this property is changed then it does not cause the button to be
487 repainted.
488 Get this property's value with state().
490
492 This property holds the type of toggle on the button.
493 The default toggle type is SingleShot.
495 See also QButton::ToggleType.
497 Get this property's value with toggleType().
499
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
511 Generated automatically from the source code.
512
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 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 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).
527Trolltech AS 2 February 2007 QButton(3qt)