QPushButton - Command button
#include <qpushbutton.h>
Inherits QButton.
Public Members
QPushButton ( QWidget * parent, const char * name=0 )
QPushButton ( const QString & text, QWidget * parent,
const char * name=0 )
QPushButton ( const QIconSet & icon, const QString & text,
QWidget * parent, const char * name=0 )
~QPushButton ()
virtual void setToggleButton ( bool )
bool autoDefault () const
virtual void setAutoDefault ( bool autoDef )
bool isDefault () const
virtual void setDefault ( bool def )
virtual void setIsMenuButton ( bool ) (obsolete)
bool isMenuButton () const (obsolete)
void setPopup ( QPopupMenu * popup )
QPopupMenu* popup () const
void setIconSet ( const QIconSet & )
QIconSet* iconSet () const
void setFlat ( bool )
bool isFlat () const
Public Slots
virtual void setOn ( bool )
void toggle ()
Important Inherited Members
QString text () const
virtual void setText ( const QString & text )
QString text () const
const QPixmap* pixmap () const
virtual void setPixmap ( const QPixmap & pixmap )
int accel () const
virtual void setAccel ( int key )
bool isToggleButton () const
virtual void setDown ( bool enable )
bool isDown () const
bool isOn () const
bool autoRepeat () const
bool isExclusiveToggle () const
QButtonGroup* group () const
virtual void setAutoRepeat ( bool enable )
void toggle ()
void pressed ()
void released ()
void clicked ()
void toggled ( bool on )
Properties
Type Name READ WRITE Options
-----------------------------------------------------------------
bool autoDefault autoDefault setAutoDefault
bool default isDefault setDefault
bool menuButton isMenuButton
QIconSet iconSet iconSet setIconSet
bool flat isFlat setFlat
DESCRIPTION
The QPushButton widget provides a command button.
The push button, also referred to as command button, is
perhaps the most central widget in any graphical user
interface: Push it to command the computer to perform some
action. Typical actions are Ok, Apply, Cancel, Close or
Help.
A command button is rectangular (ca. 80x22 pixel) and
typically displays a text label describing its action. An
underscored character in the label, marked with an
ampersand in the text, signals an accelerator key.
This code creates a push button labelled "Rock & Roll".
Due to the first ampersand, the c displays underscored and
the button gets the automatic accelerator key, Alt-C:
QPushButton *p = new QPushButton( "Ro&ck && Roll", this );
The text can be changed anytime later with setText(). You
can also define a pixmap with setPixmap(). The text/pixmap
is manipulated as necessary to create "disabled"
appearance according to the respective GUI style when the
button is disabled. A command button can, in addition to
the text or pixmap label, also display a little icon. Use
the extended constructor or setIconSet() to define this
icon.
A push button emits the signal clicked() when it is
activated, either with the mouse, the spacebar or a
keyboard accelerator. Connect to this signal to perform
the button's action. Other signals of less importance are
pressed() when the button is pressed down and released()
when it is released, respectively.
Command buttons in dialogs are by default auto-default
buttons, i.e. they become the default push button
automatically when they receive the keyboard input focus.
A default button is a command button that is activated
when the users hits the Enter or Return key in a dialog.
Adjust this behaviour with setAutoDefault(). Note that
necessary to draw a default-button indicator. If you do
not want this space around your buttons, call
setAutoDefault( FALSE ).
Being so central, the widget has grown to accomodate a
great many variations in the past decade, and by now the
Microsoft style guide shows about ten different states of
Windows push buttons, and the text implies that there are
dozens more when all the combinations of features are
taken into consideration.
The most important modes or states are, sorted roughly by
importance:
Available or not ("grayed out", disabled).
Standard push button, toggling push button or menu button.
On or off (only for toggling push buttons).
Default or normal. The default button in a dialog can
generally be "clicked" using the Enter or Return
key.
Auto-repeat or not.
Pressed down or not.
As a general rule, use a push button when the application
or dialog window performs an action when the user clicks
on it (like Apply, Cancel, Close, Help, ...) and when the
widget is supposed to have a wide, rectangular shape with
a text label. Small, typically square buttons that change
the state of the window rather than performing an action
(like for example the buttons in the top/right corner of
the QFileDialog), are not command buttons, but tool
buttons. Qt provides a special class QToolButton for
these.
Also, if you need toggle behaviour (see setToggleButton())
or a button that auto-repeats the activation signal when
being pushed down like the arrows in a scrollbar (see
setAutoRepeat()), a command button is probably not what
you want. In case of doubt, go with a tool button.
A variation of a command button is a menu button. It
provides not just one command, but several. Use the method
setPopup() to associate a popup menu with a push button.
Other classes of buttons are option buttons (see
QRadioButton) and check boxes (see QCheckBox).
[Image Omitted]
In Qt, the QButton class provides most of the modes and
other API, and QPushButton provides GUI logic. See QButton
for more information about the API.
See also QToolButton, QRadioButton, QCheckBox and GUI
Design Handbook: Push Button
Examples: xform/xform.cpp layout/layout.cpp i18n/main.cpp
drawdemo/drawdemo.cpp popup/popup.cpp qmag/qmag.cpp
rot13/rot13.cpp scrollview/scrollview.cpp
customlayout/main.cpp
MEMBER FUNCTION DOCUMENTATION
QPushButton::QPushButton ( QWidget * parent, const char * name=0
)
Constructs a push button with no text.
The parent and name arguments are sent to the QWidget
constructor.
QPushButton::QPushButton ( const QIconSet & icon, const QString &
text, QWidget * parent, const char * name=0 )
Constructs a push button with an icon and a text.
Note that you can also pass a QPixmap object as icon
(thanks to C++' implicit type conversion).
The parent and name arguments are sent to the QWidget
constructor.
QPushButton::QPushButton ( const QString & text, QWidget *
parent, const char * name=0 )
Constructs a push button with a text.
The parent and name arguments are sent to the QWidget
constructor.
QPushButton::~QPushButton ()
Destructs the push button.
bool QPushButton::autoDefault () const
Returns TRUE if the button is an auto-default button.
See also setAutoDefault().
void QPushButton::drawButton ( QPainter * paint ) [virtual
protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QButton.
protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QButton.
void QPushButton::focusInEvent ( QFocusEvent * e ) [virtual
protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
void QPushButton::focusOutEvent ( QFocusEvent * e ) [virtual
protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
QIconSet* QPushButton::iconSet () const
Returns the button's icon or 0 if no icon has been
defined.
See also setIconSet().
bool QPushButton::isDefault () const
Returns TRUE if the button is currently default.
See also setDefault().
bool QPushButton::isFlat () const
Returns whether the border is disabled.
See also setFlat().
bool QPushButton::isMenuButton () const
This function is obsolete. It is provided to keep old
source working, and will probably be removed in a future
version of Qt. We strongly advise against using it in new
code.
Returns TRUE if this button indicates to the user that
pressing it will pop up a menu, and FALSE otherwise. The
default is FALSE.
See also setIsMenuButton().
void QPushButton::move ( const QPoint & p )
Reimplemented for internal reasons; the API is not
affected.
Reimplemented for internal reasons; the API is not
affected.
Examples: drawdemo/drawdemo.cpp
Reimplemented from QWidget.
QPopupMenu* QPushButton::popup () const
Returns the associated popup menu or 0 if no popup menu
has been defined.
See also setPopup().
void QPushButton::resize ( const QSize & s )
Reimplemented for internal reasons; the API is not
affected.
void QPushButton::resize ( int w, int h )
Reimplemented for internal reasons; the API is not
affected.
Examples: drawdemo/drawdemo.cpp
void QPushButton::resizeEvent ( QResizeEvent * ) [virtual
protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
void QPushButton::setAutoDefault ( bool enable ) [virtual]
Sets the push buttons to an auto-default button if enable
is TRUE, or to a normal button if enable is FALSE.
An auto-default button becomes automatically the default
push button in a dialog when it receives the keyboard
input focus.
In some GUI styles, a default button is drawn with an
extra frame around it, up to 3 pixels or more. Qt
automatically keeps this space free around auto-default
buttons, i.e. auto-default buttons may have a slightly
larger size hint.
See also autoDefault() and setDefault().
void QPushButton::setDefault ( bool enable ) [virtual]
Sets this button to be the current default button of a
dialog if enable is TRUE, or to be a normal button if
enable is FALSE.
The current default button gets clicked when the user
presses the" Enter" key, independently of which widget in
one push button can at any time be the default button.
This button is then displayed with an additional frame (
depending on the GUI style ).
The default button behaviour is only provided in dialogs.
Buttons can always be clicked from the keyboard by
pressing return or the spacebar when the button has focus.
See also isDefault(), setAutoDefault() and QDialog.
void QPushButton::setFlat ( bool f )
Disable the border.
See also flat().
void QPushButton::setGeometry ( const QRect & r ) [virtual]
Reimplemented for internal reasons; the API is not
affected.
Examples: popup/popup.cpp qmag/qmag.cpp
void QPushButton::setGeometry ( int x, int y, int w, int h )
[virtual]
Reimplemented for internal reasons; the API is not
affected.
void QPushButton::setIconSet ( const QIconSet & icon )
Sets the button to display the icon icon in addition to
its text or pixmap
See also iconSet().
void QPushButton::setIsMenuButton ( bool enable ) [virtual]
This function is obsolete. It is provided to keep old
source working, and will probably be removed in a future
version of Qt. We strongly advise against using it in new
code.
Tells this button to draw a menu indication triangle if
enable is TRUE, and to not draw one if enable is FALSE
(the default).
setIsMenuButton() does not cause the button to do anything
other than draw the menu indication.
See also isMenuButton().
void QPushButton::setOn ( bool enable ) [virtual slot]
Switches a toggle button on if enable is TRUE or off if
enable is FALSE.
See also isOn(), toggle(), toggled() and isToggleButton().
void QPushButton::setPopup ( QPopupMenu * popup )
Associates the popup menu popup with this push button and
thus turns it into a menu button.
Ownership of the popup menu is not transferred.
See also popup().
void QPushButton::setToggleButton ( bool enable ) [virtual]
Makes the push button a toggle button if enable is TRUE,
or a normal push button if enable is FALSE.
Toggle buttons have an on/off state similar to check
boxes. A push button is initially not a toggle button.
See also setOn(), toggle(), isToggleButton() and
toggled().
Examples: qmag/qmag.cpp
QSize QPushButton::sizeHint () const [virtual]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
QSizePolicy QPushButton::sizePolicy () const [virtual]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
void QPushButton::toggle () [important inherited]
Toggles the state of a toggle button.
See also isOn(), setOn(), toggled() and isToggleButton().
void QPushButton::updateMask () [virtual protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
SEE ALSO
http://doc.trolltech.com/qpushbutton.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page
(qpushbutton.3qt) and the Qt version (2.3.1).
Man(1) output converted with
man2html