DialogButtonBox QML Type

A button box used in dialogs. More...

Import Statement:	import QtQuick.Controls
Since:	Qt 5.8
Inherits:	Container

• List of all members, including inherited members

Properties

• alignment : flags
• buttonLayout : enumeration
• delegate : Component
• position : enumeration
• standardButtons : enumeration

Attached Properties

• buttonBox : DialogButtonBox
• buttonRole : enumeration

Signals

• accepted()
• applied()
• clicked(AbstractButton button)
• discarded()
• helpRequested()
• rejected()
• reset()

Methods

• AbstractButton standardButton(StandardButton button)

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	discarded()
HelpRole	helpRequested()
RejectRole, NoRole	rejected()
ResetRole	reset()

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.

[since QtQuick.Controls 2.5 (Qt 5.12)] buttonLayout : enumeration

This property holds the button layout policy to be used when arranging the buttons contained in the button box. The default value is platform-specific.

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

This property holds a delegate for creating standard buttons.

See also standardButtons.

position : enumeration

This property holds the position of the button box.

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 header.

The default value is Footer.

See also Dialog::header and 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 standardButton().

Attached Property Documentation

[read-only] DialogButtonBox.buttonBox : DialogButtonBox

This attached property holds the button box that manages this button, or null if the button is not in a button box.

DialogButtonBox.buttonRole : enumeration

This attached property holds the role of each button in a button box.

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.

Note: The corresponding handler is onAccepted.

See also rejected(), clicked(), and helpRequested().

[since QtQuick.Controls 2.3 (Qt 5.10)] applied()

This signal is emitted when a button defined with the ApplyRole is clicked.

Note: The corresponding handler is onApplied.

This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).

See also discarded() and reset().

clicked(AbstractButton button)

This signal is emitted when a button inside the button box is clicked.

Note: The corresponding handler is onClicked.

See also accepted(), rejected(), and helpRequested().

[since QtQuick.Controls 2.3 (Qt 5.10)] discarded()

This signal is emitted when a button defined with the DiscardRole is clicked.

Note: The corresponding handler is onDiscarded.

This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).

See also reset() and applied().

helpRequested()

This signal is emitted when a button defined with the HelpRole is clicked.

Note: The corresponding handler is onHelpRequested.

See also accepted(), rejected(), and clicked().

rejected()

This signal is emitted when a button defined with the RejectRole or NoRole is clicked.

Note: The corresponding handler is onRejected.

See also accepted(), helpRequested(), and clicked().

[since QtQuick.Controls 2.3 (Qt 5.10)] reset()

This signal is emitted when a button defined with the ResetRole is clicked.

Note: The corresponding handler is onReset.

This signal was introduced in QtQuick.Controls 2.3 (Qt 5.10).

See also discarded() and applied().

Method Documentation

AbstractButton standardButton(StandardButton button)

Returns the specified standard button, or null if it does not exist.

See also standardButtons.