API Documentation

Documentation for developing SailfishOS applications

Dialog QML Type

A page that is closed by a confirmation or cancelation action More...

Import Statement:	import Sailfish.Silica 1.0
Inherits:	Page
Inherited By:	ColorPickerDialog

List of all members, including inherited members

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

accept()
close()
open(replace, immediate)
reject()

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

acceptDestination : var

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.

acceptDestinationAction : enumeration

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.

acceptDestinationProperties : var

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.

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.

acceptPending : bool

True when the user is performing an action which, if completed, will cause the dialog to be accepted.

canAccept : bool

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().

result : enumeration

Provides the result of closing the dialog. This value is one of:

DialogResult.Accepted - the dialog was accepted by the user or by calling accept()
DialogResult.Rejected - the dialog was rejected by the user or by calling reject()
DialogResult.None - the dialog was closed without accepting or rejecting; for example, by calling close()

status : enumeration

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

acceptBlocked()

This signal handler is called when dialog accept is attempted while canAccept is false.

onAccepted()

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.

onDone()

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.

onOpened()

This handler is useful for dialog implementors. It is invoked when the dialog opens, and may be used to populate initial values in the dialog, for example.

See also open() and onDone.

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

accept()

Sets result to DialogResult.Accepted and closes the dialog, removing it from the application PageStack.

See also onAccepted and canAccept.

close()

Closes the dialog without setting a result, and removes the dialog from the application PageStack.

open(replace, immediate)

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().

reject()

Sets result to DialogResult.Rejected and closes the dialog, removing it from the application PageStack.

See also onRejected.