API Documentation
Documentation for developing SailfishOS applicationsDialog QML Type
A page that is closed by a confirmation or cancelation action More...
| Import Statement: | import Sailfish.Silica 1.0 |
| Inherits: | |
| Inherited By: |
Properties
- acceptDestination : var
- acceptDestinationAction : enumeration
- acceptDestinationInstance : Page
- acceptDestinationProperties : var
- acceptDestinationReplaceTarget : Page
- acceptPending : bool
- canAccept : bool
- result : enumeration
- status : enumeration
Signals
- acceptBlocked()
- onAccepted()
- onDone()
- onOpened()
- onRejected()
Methods
Detailed Description
The Dialog type is a generic container for displaying a dialog that accepts user input.
Opening a dialog causes a modal dialog box to be added to the top of a PageStack. A Dialog object is simply a Page with modified user interface appearance and behavior. Dialogs contain visual indicators at the top-left and top-right; the user can accept a dialog — that is, confirm any user modifications or input, and proceed — by pushing the page from right to left, or tapping the acceptText in a DialogHeader. Conversely, the user can reject a dialog, signalling a cancel-type action, by pushing the page from left to right, or tapping the cancelText in a DialogHeader.
Below is a simple dialog defined in NameInputDialog.qml:
// NameInputDialog.qml
import QtQuick 2.2
import Sailfish.Silica 1.0
Dialog {
property string name
Column {
width: parent.width
DialogHeader { }
TextField {
id: nameField
width: parent.width
placeholderText: "What's your name?"
label: "Name"
}
}
onDone: {
if (result == DialogResult.Accepted) {
name = nameField.text
}
}
}Here is a simple application that loads an instance of that dialog:
import QtQuick 2.2
import Sailfish.Silica 1.0
ApplicationWindow {
initialPage: Component {
Page {
PageHeader { id: header }
Button {
text: "Ask me"
anchors {
top: header.bottom
horizontalCenter: parent.horizontalCenter
}
onClicked: {
var dialog = pageStack.push(Qt.resolvedUrl("NameInputDialog.qml"),
{"name": header.title})
dialog.accepted.connect(function() {
header.title = "My name: " + dialog.name
})
}
}
}
}
}Above, the NameInputDialog internally implements the onDone signal handler (which is invoked when a dialog closes) to set its name property value if the dialog is accepted. In main.qml, the button is set to call PageStack::push() when clicked, and open an instance of the "NameInputDialog.qml" dialog with the specified name property value. Additionally, the Dialog accepted signal, which signifies that the the dialog was accepted by the user, is connected to update the displayedName value.
When a Dialog is accepted, the onAccepted signal handler is called and result is set to DialogResult.Accepted; when it is rejected, the onRejected signal handler is called and result is set to DialogResult.Rejected. A dialog may also be accepted or rejected programmatically through the accept() and reject() methods. Additionally the close() method allows the dialog to be closed without either accepting or rejecting it.
DialogHeader should be used to provide standard page indicators at the top of the dialog page.
Property Documentation
This property may be used to specify the page that is set as the top of the page stack when the dialog is accepted. If the destination is set via this property, the page stack will not visually return to the page from which the dialog was invoked, which would occur if the destination page was pushed onto the stack from the onAccepted handler.
This property may be one of the following:
- An item
- A Component object
- The URL of a Page-type component (for example, "MyPage.qml")
- The URI of a Sailfish Silica dialog (for example, "Sailfish.Silica.TimePickerDialog")
The property acceptDestinationAction determines how the accept action is effected.
See also acceptDestinationProperties, acceptDestinationAction, and PageStack::push.
When an acceptDestination is specified for a dialog, acceptDestinationAction can be used to specify what action should be taken when the dialog is accepted.
The value must be one of:
- PageStackAction.Push - the destination will be pushed onto the stack
- PageStackAction.Replace - the destination will replace the page that was previously on top of the stack
- PageStackAction.Pop - all pages above the destination will be popped from the stack
If the action is PageStackAction.Pop, the acceptDestination must refer to a page that is already present in the page stack.
The default action is PageStackAction.Push.
See also acceptDestination.
acceptDestinationInstance : Page |
When an acceptDestination is specified for a dialog, the page that is instantiated from the destination can be accessed via this property.
See also acceptDestination and acceptPending.
When an acceptDestination is specified for a dialog, any additional properties that should be set on the instantiated destination page should be provided via this property.
The acceptDestination is instantiated immediately after the dialog is opened, so the values in acceptDestinationProperties cannot be deferred until the dialog is accepted. To react to the user starting to accept the dialog via a gesture, handle changes to the acceptPending property.
See also acceptDestination, acceptDestinationInstance, and acceptPending.
acceptDestinationReplaceTarget : Page |
When acceptDestinationAction is PageStackAction.Replace, this property can additionally be set to control the pages to be replaced when the dialog is accepted.
If acceptDestinationReplaceTarget refers to a page currently on the stack, accepting the dialog will replace all pages above this specified page, so that navigating back from the destination will move to this page.
If acceptDestinationReplaceTarget is null, accepting the dialog will remove all pages currently on the stack, replacing them with the destination page.
See also acceptDestination, acceptDestinationAction, and PageStack::replaceAbove().
True when the user is performing an action which, if completed, will cause the dialog to be accepted.
Sets whether the user can accept the dialog or not, in its current state. If canAccept is false, the dialog will not respond to attempts to accept the content.
See also accept().
Provides the result of closing the dialog. This value is one of:
Provides the current status of the dialog. This value is one of:
- DialogStatus.Closed - the dialog is not active, and not visible
- DialogStatus.Opening - the dialog is transitioning to the Opened state
- DialogStatus.Opened - the dialog is active
- DialogStatus.Closing - the dialog is transitioning to the Closed state
See also result.
Signal Documentation
This signal handler is called when dialog accept is attempted while canAccept is false.
This signal handler is called when the dialog is accepted.
A dialog is accepted if the user taps the top right acceptText in a DialogHeader or pushes the dialog page from right to left, or if accept() is called.
This handler is useful for dialog implementors. It is invoked when the dialog is about to close, before the onAccepted and onRejected handlers are invoked.
See also onOpened, onAccepted, and onRejected.
This signal handler is called when the dialog is rejected.
A dialog is rejected if the user taps the top left cancelText in a DialogHeader or pushes the dialog page from left to right, or if reject() is called.
Method Documentation
Sets result to DialogResult.Accepted and closes the dialog, removing it from the application PageStack.
See also onAccepted and canAccept.
Displays the dialog by pushing it to the top of the application PageStack.
By default, the dialog is added through an animated transition; this animation can be disabled by specifying the immediate parameter as true. Instead of pushing the dialog above the existing page stack contents, replace may be specified as true to replace the page that is currently on the top of the stack.
See also onOpened, PageStack::push(), and PageStack::replace().
Sets result to DialogResult.Rejected and closes the dialog, removing it from the application PageStack.
See also onRejected.