QtBase
v6.3.1
|
The QDialogButtonBox class is a widget that presents buttons in a layout that is appropriate to the current widget style. More...
#include <qdialogbuttonbox.h>
Public Types | |
enum | ButtonRole { InvalidRole = -1 , AcceptRole , RejectRole , DestructiveRole , ActionRole , HelpRole , YesRole , NoRole , ResetRole , ApplyRole , NRoles } |
enum | StandardButton { NoButton = 0x00000000 , Ok = 0x00000400 , Save = 0x00000800 , SaveAll = 0x00001000 , Open = 0x00002000 , Yes = 0x00004000 , YesToAll = 0x00008000 , No = 0x00010000 , NoToAll = 0x00020000 , Abort = 0x00040000 , Retry = 0x00080000 , Ignore = 0x00100000 , Close = 0x00200000 , Cancel = 0x00400000 , Discard = 0x00800000 , Help = 0x01000000 , Apply = 0x02000000 , Reset = 0x04000000 , RestoreDefaults = 0x08000000 , FirstButton = Ok , LastButton = RestoreDefaults } |
enum | ButtonLayout { WinLayout , MacLayout , KdeLayout , GnomeLayout , AndroidLayout } |
Public Types inherited from QWidget | |
enum | RenderFlag { DrawWindowBackground = 0x1 , DrawChildren = 0x2 , IgnoreMask = 0x4 } |
Public Types inherited from QPaintDevice | |
enum | PaintDeviceMetric { PdmWidth = 1 , PdmHeight , PdmWidthMM , PdmHeightMM , PdmNumColors , PdmDepth , PdmDpiX , PdmDpiY , PdmPhysicalDpiX , PdmPhysicalDpiY , PdmDevicePixelRatio , PdmDevicePixelRatioScaled } |
Signals | |
void | clicked (QAbstractButton *button) |
void | accepted () |
void | helpRequested () |
void | rejected () |
Signals inherited from QWidget | |
void | windowTitleChanged (const QString &title) |
void | windowIconChanged (const QIcon &icon) |
void | windowIconTextChanged (const QString &iconText) |
void | customContextMenuRequested (const QPoint &pos) |
Signals inherited from QObject | |
void | destroyed (QObject *=nullptr) |
void | objectNameChanged (const QString &objectName, QPrivateSignal) |
Properties | |
Qt::Orientation | orientation |
the orientation of the button box More... | |
StandardButtons | standardButtons |
collection of standard buttons in the button box More... | |
bool | centerButtons |
whether the buttons in the button box are centered More... | |
Properties inherited from QWidget | |
bool | modal |
whether the widget is a modal widget More... | |
Qt::WindowModality | windowModality |
which windows are blocked by the modal widget More... | |
bool | enabled |
whether the widget is enabled More... | |
QRect | geometry |
the geometry of the widget relative to its parent and excluding the window frame More... | |
QRect | frameGeometry |
geometry of the widget relative to its parent including any window frame More... | |
QRect | normalGeometry |
the geometry of the widget as it will appear when shown as a normal (not maximized or full screen) top-level widget More... | |
int | x |
the x coordinate of the widget relative to its parent including any window frame More... | |
int | y |
the y coordinate of the widget relative to its parent and including any window frame More... | |
QPoint | pos |
the position of the widget within its parent widget More... | |
QSize | frameSize |
the size of the widget including any window frame More... | |
QSize | size |
the size of the widget excluding any window frame More... | |
int | width |
the width of the widget excluding any window frame More... | |
int | height |
the height of the widget excluding any window frame More... | |
QRect | rect |
the internal geometry of the widget excluding any window frame More... | |
QRect | childrenRect |
the bounding rectangle of the widget's children More... | |
QRegion | childrenRegion |
the combined region occupied by the widget's children More... | |
QSizePolicy | sizePolicy |
the default layout behavior of the widget More... | |
QSize | minimumSize |
the widget's minimum size More... | |
QSize | maximumSize |
the widget's maximum size in pixels More... | |
int | minimumWidth |
the widget's minimum width in pixels More... | |
int | minimumHeight |
the widget's minimum height in pixels More... | |
int | maximumWidth |
the widget's maximum width in pixels More... | |
int | maximumHeight |
the widget's maximum height in pixels More... | |
QSize | sizeIncrement |
the size increment of the widget More... | |
QSize | baseSize |
the base size of the widget More... | |
QPalette | palette |
the widget's palette More... | |
QFont | font |
the font currently set for the widget More... | |
QCursor | cursor |
the cursor shape for this widget More... | |
bool | mouseTracking |
whether mouse tracking is enabled for the widget More... | |
bool | tabletTracking |
whether tablet tracking is enabled for the widget More... | |
bool | isActiveWindow |
whether this widget's window is the active window More... | |
Qt::FocusPolicy | focusPolicy |
the way the widget accepts keyboard focus More... | |
bool | focus |
whether this widget (or its focus proxy) has the keyboard input focus More... | |
Qt::ContextMenuPolicy | contextMenuPolicy |
how the widget shows a context menu More... | |
bool | updatesEnabled |
whether updates are enabled More... | |
bool | visible |
whether the widget is visible More... | |
bool | minimized |
whether this widget is minimized (iconified) More... | |
bool | maximized |
whether this widget is maximized More... | |
bool | fullScreen |
whether the widget is shown in full screen mode More... | |
QSize | sizeHint |
the recommended size for the widget More... | |
QSize | minimumSizeHint |
the recommended minimum size for the widget More... | |
bool | acceptDrops |
whether drop events are enabled for this widget More... | |
QString | windowTitle |
the window title (caption) More... | |
QIcon | windowIcon |
the widget's icon More... | |
QString | windowIconText |
the text to be displayed on the icon of a minimized window More... | |
double | windowOpacity |
The level of opacity for the window. More... | |
bool | windowModified |
whether the document shown in the window has unsaved changes More... | |
QString | accessibleName |
the widget's name as seen by assistive technologies More... | |
QString | accessibleDescription |
the widget's description as seen by assistive technologies More... | |
Qt::LayoutDirection | layoutDirection |
the layout direction for this widget. More... | |
bool | autoFillBackground |
whether the widget background is filled automatically More... | |
QString | styleSheet |
the widget's style sheet More... | |
QLocale | locale |
the widget's locale More... | |
QString | windowFilePath |
the file path associated with a widget More... | |
Qt::InputMethodHints | inputMethodHints |
What input method specific hints the widget has. More... | |
Properties inherited from QObject | |
QString | objectName |
the name of this object More... | |
The QDialogButtonBox class is a widget that presents buttons in a layout that is appropriate to the current widget style.
\inmodule QtWidgets
Dialogs and message boxes typically present buttons in a layout that conforms to the interface guidelines for that platform. Invariably, different platforms have different layouts for their dialogs. QDialogButtonBox allows a developer to add buttons to it and will automatically use the appropriate layout for the user's desktop environment.
Most buttons for a dialog follow certain roles. Such roles include:
\list
There can also be alternate ways of dismissing the dialog which may cause destructive results.
Most dialogs have buttons that can almost be considered standard (e.g. \uicontrol OK and \uicontrol Cancel buttons). It is sometimes convenient to create these buttons in a standard way.
There are a couple ways of using QDialogButtonBox. One ways is to create the buttons (or button texts) yourself and add them to the button box, specifying their role.
Alternatively, QDialogButtonBox provides several standard buttons (e.g. OK, Cancel, Save) that you can use. They exist as flags so you can OR them together in the constructor.
You can mix and match normal buttons and standard buttons.
Currently the buttons are laid out in the following way if the button box is horizontal: \table \row
The buttons are laid out the following way if the button box is vertical:
\table \row
Additionally, button boxes that contain only buttons with ActionRole or HelpRole can be considered modeless and have an alternate look on \macos:
\table \row
When a button is clicked in the button box, the clicked() signal is emitted for the actual button is that is pressed. For convenience, if the button has an AcceptRole, RejectRole, or HelpRole, the accepted(), rejected(), or helpRequested() signals are emitted respectively.
If you want a specific button to be default you need to call QPushButton::setDefault() on it yourself. However, if there is no default button set and to preserve which button is the default button across platforms when using the QPushButton::autoDefault property, the first push button with the accept role is made the default button when the QDialogButtonBox is shown,
Definition at line 55 of file qdialogbuttonbox.h.
This enum describes the layout policy to be used when arranging the buttons contained in the button box.
\value WinLayout Use a policy appropriate for applications on Windows. \value MacLayout Use a policy appropriate for applications on \macos. \value KdeLayout Use a policy appropriate for applications on KDE. \value GnomeLayout Use a policy appropriate for applications on GNOME. \value AndroidLayout Use a policy appropriate for applications on Android. This enum value was added in Qt 5.10.
The button layout is specified by the \l{style()}{current style}. However, on the X11 platform, it may be influenced by the desktop environment.
Enumerator | |
---|---|
WinLayout | |
MacLayout | |
KdeLayout | |
GnomeLayout | |
AndroidLayout |
Definition at line 110 of file qdialogbuttonbox.h.
Enumerator | |
---|---|
InvalidRole | |
AcceptRole | |
RejectRole | |
DestructiveRole | |
ActionRole | |
HelpRole | |
YesRole | |
NoRole | |
ResetRole | |
ApplyRole | |
NRoles |
Definition at line 63 of file qdialogbuttonbox.h.
\enum QDialogButtonBox::ButtonRole
! [buttonrole-enum] This enum describes the roles that can be used to describe buttons in the button box. Combinations of these roles are as flags used to describe different aspects of their behavior.
\value InvalidRole The button is invalid. \value AcceptRole Clicking the button causes the dialog to be accepted (e.g. OK). \value RejectRole Clicking the button causes the dialog to be rejected (e.g. Cancel). \value DestructiveRole Clicking the button causes a destructive change (e.g. for Discarding Changes) and closes the dialog. \value ActionRole Clicking the button causes changes to the elements within the dialog. \value HelpRole The button can be clicked to request help. \value YesRole The button is a "Yes"-like button. \value NoRole The button is a "No"-like button. \value ApplyRole The button applies current changes. \value ResetRole The button resets the dialog's fields to default values.
\omitvalue NRoles
These enums describe flags for standard buttons. Each button has a defined \l ButtonRole.
\value Ok An "OK" button defined with the \l AcceptRole. \value Open An "Open" button defined with the \l AcceptRole. \value Save A "Save" button defined with the \l AcceptRole. \value Cancel A "Cancel" button defined with the \l RejectRole. \value Close A "Close" button defined with the \l RejectRole. \value Discard A "Discard" or "Don't Save" button, depending on the platform, defined with the \l DestructiveRole. \value Apply An "Apply" button defined with the \l ApplyRole. \value Reset A "Reset" button defined with the \l ResetRole. \value RestoreDefaults A "Restore Defaults" button defined with the \l ResetRole. \value Help A "Help" button defined with the \l HelpRole. \value SaveAll A "Save All" button defined with the \l AcceptRole. \value Yes A "Yes" button defined with the \l YesRole. \value YesToAll A "Yes to All" button defined with the \l YesRole. \value No A "No" button defined with the \l NoRole. \value NoToAll A "No to All" button defined with the \l NoRole. \value Abort An "Abort" button defined with the \l RejectRole. \value Retry A "Retry" button defined with the \l AcceptRole. \value Ignore An "Ignore" button defined with the \l AcceptRole.
\value NoButton An invalid button.
\omitvalue FirstButton \omitvalue LastButton
Enumerator | |
---|---|
NoButton | |
Ok | |
Save | |
SaveAll | |
Open | |
Yes | |
YesToAll | |
No | |
NoToAll | |
Abort | |
Retry | |
Ignore | |
Close | |
Cancel | |
Discard | |
Help | |
Apply | |
Reset | |
RestoreDefaults | |
FirstButton | |
LastButton |
Definition at line 79 of file qdialogbuttonbox.h.
Constructs an empty, horizontal button box with the given parent.
Definition at line 474 of file qdialogbuttonbox.cpp.
QDialogButtonBox::QDialogButtonBox | ( | Qt::Orientation | orientation, |
QWidget * | parent = nullptr |
||
) |
Constructs an empty button box with the given orientation and parent.
Definition at line 484 of file qdialogbuttonbox.cpp.
Constructs a horizontal button box with the given parent, containing the standard buttons specified by buttons.
Definition at line 498 of file qdialogbuttonbox.cpp.
QDialogButtonBox::QDialogButtonBox | ( | StandardButtons | buttons, |
Qt::Orientation | orientation, | ||
QWidget * | parent = nullptr |
||
) |
Constructs a button box with the given orientation and parent, containing the standard buttons specified by buttons.
Definition at line 509 of file qdialogbuttonbox.cpp.
QDialogButtonBox::~QDialogButtonBox | ( | ) |
Destroys the button box.
Definition at line 519 of file qdialogbuttonbox.cpp.
|
signal |
This signal is emitted when a button inside the button box is clicked, as long as it was defined with the \l AcceptRole or \l YesRole.
QPushButton * QDialogButtonBox::addButton | ( | const QString & | text, |
ButtonRole | role | ||
) |
Creates a push button with the given text, adds it to the button box for the specified role, and returns the corresponding push button. If role is invalid, no button is created, and zero is returned.
Definition at line 780 of file qdialogbuttonbox.cpp.
void QDialogButtonBox::addButton | ( | QAbstractButton * | button, |
ButtonRole | role | ||
) |
Adds the given button to the button box with the specified role. If the role is invalid, the button is not added.
If the button has already been added, it is removed and added again with the new role.
Definition at line 761 of file qdialogbuttonbox.cpp.
QPushButton * QDialogButtonBox::addButton | ( | StandardButton | button | ) |
Adds a standard button to the button box if it is valid to do so, and returns a push button. If button is invalid, it is not added to the button box, and zero is returned.
Definition at line 799 of file qdialogbuttonbox.cpp.
QPushButton * QDialogButtonBox::button | ( | StandardButton | which | ) | const |
Returns the QPushButton corresponding to the standard button which, or \nullptr if the standard button doesn't exist in this button box.
Definition at line 841 of file qdialogbuttonbox.cpp.
QDialogButtonBox::ButtonRole QDialogButtonBox::buttonRole | ( | QAbstractButton * | button | ) | const |
Returns the button role for the specified button. This function returns \l InvalidRole if button is \nullptr or has not been added to the button box.
Definition at line 706 of file qdialogbuttonbox.cpp.
QList< QAbstractButton * > QDialogButtonBox::buttons | ( | ) | const |
Returns a list of all the buttons that have been added to the button box.
Definition at line 688 of file qdialogbuttonbox.cpp.
bool QDialogButtonBox::centerButtons | ( | ) | const |
Definition at line 922 of file qdialogbuttonbox.cpp.
\reimp
Reimplemented from QWidget.
Definition at line 931 of file qdialogbuttonbox.cpp.
void QDialogButtonBox::clear | ( | ) |
Clears the button box, deleting all buttons within it.
Definition at line 667 of file qdialogbuttonbox.cpp.
|
signal |
This signal is emitted when a button inside the button box is clicked. The specific button that was pressed is specified by button.
|
overrideprotectedvirtual |
\reimp
Reimplemented from QWidget.
Definition at line 960 of file qdialogbuttonbox.cpp.
|
signal |
This signal is emitted when a button inside the button box is clicked, as long as it was defined with the \l HelpRole.
Qt::Orientation QDialogButtonBox::orientation | ( | ) | const |
Definition at line 647 of file qdialogbuttonbox.cpp.
|
signal |
This signal is emitted when a button inside the button box is clicked, as long as it was defined with the \l RejectRole or \l NoRole.
void QDialogButtonBox::removeButton | ( | QAbstractButton * | button | ) |
Removes button from the button box without deleting it and sets its parent to zero.
Definition at line 724 of file qdialogbuttonbox.cpp.
void QDialogButtonBox::setCenterButtons | ( | bool | center | ) |
Definition at line 913 of file qdialogbuttonbox.cpp.
void QDialogButtonBox::setOrientation | ( | Qt::Orientation | orientation | ) |
void QDialogButtonBox::setStandardButtons | ( | StandardButtons | buttons | ) |
Definition at line 813 of file qdialogbuttonbox.cpp.
QDialogButtonBox::StandardButton QDialogButtonBox::standardButton | ( | QAbstractButton * | button | ) | const |
Returns the standard button enum value corresponding to the given button, or NoButton if the given button isn't a standard button.
Definition at line 853 of file qdialogbuttonbox.cpp.
QDialogButtonBox::StandardButtons QDialogButtonBox::standardButtons | ( | ) | const |
Definition at line 823 of file qdialogbuttonbox.cpp.
|
readwrite |
whether the buttons in the button box are centered
By default, this property is false
. This behavior is appropriate for most types of dialogs. A notable exception is message boxes on most platforms (e.g. Windows), where the button box is centered horizontally.
Definition at line 165 of file qdialogbuttonbox.h.
|
readwrite |
the orientation of the button box
By default, the orientation is horizontal (i.e. the buttons are laid out side by side). The possible orientations are Qt::Horizontal and Qt::Vertical.
Definition at line 165 of file qdialogbuttonbox.h.
|
readwrite |
collection of standard buttons in the button box
This property controls which standard buttons are used by the button box.
Definition at line 165 of file qdialogbuttonbox.h.