DialogButtonBox QML Type▲
-
Import Statement: import QtQuick.Controls
-
Inherits: Container
-
Group: DialogButtonBox is part of qtquickcontrols-dialogs
Detailed Description▲
Dialogs and message boxes typically present buttons in an order that conforms to the interface guidelines for that platform. Invariably, different platforms have their dialog buttons in different orders. DialogButtonBox allows a developer to add buttons to it and will automatically use the appropriate order for the user's platform.
Most buttons for a dialog follow certain roles. Such roles include:
-
Accepting or rejecting the dialog.
-
Asking for help.
-
Performing actions on the dialog itself (such as resetting fields or applying changes).
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. OK and Cancel buttons). It is sometimes convenient to create these buttons in a standard way.
There are a couple ways of using DialogButtonBox. One way is to specify the standard buttons (e.g. OK, Cancel, Save) and let the button box setup the buttons.
DialogButtonBox {
standardButtons: DialogButtonBox.Ok | DialogButtonBox.Cancel
onAccepted: console.log("Ok clicked")
onRejected: console.log("Cancel clicked")
}Alternatively, buttons and their roles can be specified by hand:
DialogButtonBox {
Button {
text: qsTr("Save")
DialogButtonBox.buttonRole: DialogButtonBox.AcceptRole
}
Button {
text: qsTr("Close")
DialogButtonBox.buttonRole: DialogButtonBox.DestructiveRole
}
}You can also mix and match normal buttons and standard buttons.
When a button is clicked in the button box, the clicked() signal is emitted for the actual button that is pressed. In addition, the following signals are automatically emitted when a button with the respective role(s) is pressed:
|
Role |
Signal |
|---|---|
|
AcceptRole, YesRole |
accepted() |
|
ApplyRole |
applied() |
|
DiscardRole |
|
|
HelpRole |
|
|
RejectRole, NoRole |
rejected() |
|
ResetRole |
reset() |
See Also▲
See also Dialog
Property Documentation▲
alignment : flags▲
This property holds the alignment of the buttons.
Possible values:
|
Constant |
Description |
|---|---|
|
undefined |
The buttons are resized to fill the available space. |
|
Qt.AlignLeft |
The buttons are aligned to the left. |
|
Qt.AlignHCenter |
The buttons are horizontally centered. |
|
Qt.AlignRight |
The buttons are aligned to the right. |
|
Qt.AlignTop |
The buttons are aligned to the top. |
|
Qt.AlignVCenter |
The buttons are vertically centered. |
|
Qt.AlignBottom |
The buttons are aligned to the bottom. |
The default value is undefined.
This property assumes a horizontal layout of the buttons. The DialogButtonBox for the iOS style uses a vertical layout when there are more than two buttons, and if set to a value other than undefined, the layout of its buttons will be done horizontally.
[since QtQuick.Controls 2.5 (Qt 5.12)] buttonLayout : enumeration▲
Available values:
|
Constant |
Description |
|---|---|
|
DialogButtonBox.WinLayout |
Use a policy appropriate for applications on Windows. |
|
DialogButtonBox.MacLayout |
Use a policy appropriate for applications on macOS. |
|
DialogButtonBox.KdeLayout |
Use a policy appropriate for applications on KDE. |
|
DialogButtonBox.GnomeLayout |
Use a policy appropriate for applications on GNOME. |
|
DialogButtonBox.AndroidLayout |
Use a policy appropriate for applications on Android. |
This property was introduced in QtQuick.Controls 2.5 (Qt 5.12).
delegate : Component▲
position : enumeration▲
This property holds the position of the button box.
If the button box is assigned as a header or footer of ApplicationWindow or Page, the appropriate position is set automatically.
Possible values:
|
Constant |
Description |
|---|---|
|
DialogButtonBox.Header |
The button box is at the top, as a window or page header. |
|
DialogButtonBox.Footer |
The button box is at the bottom, as a window or page footer. |
The default value is Footer.
See Also▲
See also Dialog::header, Dialog::footer
standardButtons : enumeration▲
This property holds a combination of standard buttons that are used by the button box.
DialogButtonBox {
standardButtons: DialogButtonBox.Ok | DialogButtonBox.Cancel
onAccepted: console.log("Ok clicked")
onRejected: console.log("Cancel clicked")
}The buttons will be positioned in the appropriate order for the user's platform.
Possible flags:
|
Constant |
Description |
|---|---|
|
DialogButtonBox.Ok |
An "OK" button defined with the AcceptRole. |
|
DialogButtonBox.Open |
An "Open" button defined with the AcceptRole. |
|
DialogButtonBox.Save |
A "Save" button defined with the AcceptRole. |
|
DialogButtonBox.Cancel |
A "Cancel" button defined with the RejectRole. |
|
DialogButtonBox.Close |
A "Close" button defined with the RejectRole. |
|
DialogButtonBox.Discard |
A "Discard" or "Don't Save" button, depending on the platform, defined with the DestructiveRole. |
|
DialogButtonBox.Apply |
An "Apply" button defined with the ApplyRole. |
|
DialogButtonBox.Reset |
A "Reset" button defined with the ResetRole. |
|
DialogButtonBox.RestoreDefaults |
A "Restore Defaults" button defined with the ResetRole. |
|
DialogButtonBox.Help |
A "Help" button defined with the HelpRole. |
|
DialogButtonBox.SaveAll |
A "Save All" button defined with the AcceptRole. |
|
DialogButtonBox.Yes |
A "Yes" button defined with the YesRole. |
|
DialogButtonBox.YesToAll |
A "Yes to All" button defined with the YesRole. |
|
DialogButtonBox.No |
A "No" button defined with the NoRole. |
|
DialogButtonBox.NoToAll |
A "No to All" button defined with the NoRole. |
|
DialogButtonBox.Abort |
An "Abort" button defined with the RejectRole. |
|
DialogButtonBox.Retry |
A "Retry" button defined with the AcceptRole. |
|
DialogButtonBox.Ignore |
An "Ignore" button defined with the AcceptRole. |
|
DialogButtonBox.NoButton |
An invalid button. |
See Also▲
See also standardButton()
Attached Property Documentation▲
[read-only] DialogButtonBox.buttonBox : DialogButtonBox▲
DialogButtonBox.buttonRole : enumeration▲
DialogButtonBox {
Button {
text: qsTr("Save")
DialogButtonBox.buttonRole: DialogButtonBox.AcceptRole
}
Button {
text: qsTr("Close")
DialogButtonBox.buttonRole: DialogButtonBox.DestructiveRole
}
}Available values:
|
Constant |
Description |
|---|---|
|
DialogButtonBox.InvalidRole |
The button is invalid. |
|
DialogButtonBox.AcceptRole |
Clicking the button causes the dialog to be accepted (e.g. OK). |
|
DialogButtonBox.RejectRole |
Clicking the button causes the dialog to be rejected (e.g. Cancel). |
|
DialogButtonBox.DestructiveRole |
Clicking the button causes a destructive change (e.g. for discarding changes) and closes the dialog. |
|
DialogButtonBox.ActionRole |
Clicking the button causes changes to the elements within the dialog. |
|
DialogButtonBox.HelpRole |
The button can be clicked to request help. |
|
DialogButtonBox.YesRole |
The button is a "Yes"-like button. |
|
DialogButtonBox.NoRole |
The button is a "No"-like button. |
|
DialogButtonBox.ResetRole |
The button resets the dialog's fields to default values. |
|
DialogButtonBox.ApplyRole |
The button applies current changes. |
Signal Documentation▲
accepted()▲
This signal is emitted when a button defined with the AcceptRole or YesRole is clicked.
The corresponding handler is onAccepted.
See Also▲
See also rejected(), clicked(), helpRequested()
[since QtQuick.Controls 2.3 (Qt 5.10)] applied()▲
This signal is emitted when a button defined with the ApplyRole is clicked.
The corresponding handler is onApplied.
This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).
See Also▲
clicked(AbstractButton button)▲
This signal is emitted when a button inside the button box is clicked.
The corresponding handler is onClicked.
See Also▲
See also accepted(), rejected(), helpRequested()
[since QtQuick.Controls 2.3 (Qt 5.10)] discarded()▲
This signal is emitted when a button defined with the DiscardRole is clicked.
The corresponding handler is onDiscarded.
This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).
See Also▲
helpRequested()▲
This signal is emitted when a button defined with the HelpRole is clicked.
The corresponding handler is onHelpRequested.
See Also▲
rejected()▲
This signal is emitted when a button defined with the RejectRole or NoRole is clicked.
The corresponding handler is onRejected.
See Also▲
See also accepted(), helpRequested(), clicked()
[since QtQuick.Controls 2.3 (Qt 5.10)] reset()▲
Method Documentation▲
AbstractButton standardButton(StandardButton button)▲
Returns the specified standard button, or null if it does not exist.
See Also▲
See also standardButtons