PendingReply QML Type

An object representing asynchronous results. More...

Import Statement: import QtInterfaceFramework 1.0
Instantiates: QIfPendingReply

Properties

Methods

Detailed Description

A PendingReply is a way for providing asynchronous results. It can be used as a return value for asynchronous functions.

The QML API is very similar to JavaScript Promises.

This documentation shows how to use the PendingReply from within QML and how to execute code once the asynchronous result is ready.

Note: It is not supported to create a PendingReply from QML. The object is supposed to be created from C++ and returned to QML as a result. For more information on how to use it from C++ see the QIfPendingReply documentation.

When a PendingReply is created from C++ it doesn't have a result set yet and the resultAvailable property is false. A result for the pending reply can only be set once and it either indicates a failed(setFailed) or a successful(setSuccess) call. This can be checked using the success property. The actual result is available from the value property, which returns undefined if no result is available or the reply failed.

Using a PendingReply

As explained above, the PendingReply is supposed to be used as a return value for asynchronous operations done in C++. To inform about when a reply result is available there are two ways:

The then method

Similar to a JavaScript Promise the PendingReply is then-able, which means it provides a then method. This method can be used to add callbacks which are executed when the reply succeeds or fails.

import QtQuick
import QtInterfaceFramework

Text {
    id: root
    text: "not ready"

    Component.onCompleted: {
        var asyncReply = TestObject.asyncFunction();
        asyncReply.then(function(value) {
                            root.text = "reply ready: " + value
                        },
                        function() {
                            root.text = "reply failed"
                        })
    }
}

This simple QML snippet calls the C++ function TestObject::asyncFunction() which returns a PendingReply. See the C++ part on how to write such a function and use the PendingReply from C++.

The then method is used to register two callbacks. The first callback is the result callback and takes the reply value as an argument. This will update the text element accordingly. The second argument is the failed callback, which doesn't take an argument as there is no valid reply value.

If the failed state is not of interest it is also possible to not add any callback for it e.g.

asyncReply.then(function(value) {
                    root.text = "reply ready: " + value
                })

In a similar way only the failed callback can be registered by passing undefined to the function as the first argument:

asyncReply.then(undefined,
                function() {
                    root.text = "reply failed"
                })

Synchronous results

When a PendingReply object is used in an API the corresponding function cannot provide the result immediately. But especially for input validation the function can return an error state right away. For this the PendingReply object offers the properties resultAvailable and success to check for this when the object is given for QML.

Checking this for every PendingReply use in QML can be tedious and produces a lot of boiler-plate code. Because of this the PendingReply works similar to a JavaScript Promise and will execute the callbacks although the result is already available.

Signals and Slots

Although the then method is the recommended way from QML, the PendingReply also provides signals. To make the PendingReply as lightweight as possible it is using Q_GADGET and cannot provide signals directly, but provides it through the QIfPendingReplyWatcher class. The QIfPendingReplyWatcher can be accessed using the watcher property.

Note: The QIfPendingReplyWatcher is owned by the PendingReply. Saving the watcher outside of of the PendingReply is not safe as it is destroyed once all copies of this PendingReply object are destroyed.

Property Documentation

resultAvailable : bool

Holds whether a result has been set

This property is true once a result has been set by using setSuccess() or setFailed().


success : bool

Holds whether the reply succeeded

This property is true if the reply has a valid result set by calling setSuccess().


valid : bool

Holds whether the PendingReply is valid

A watcher can be invalid if a PendingReply is manually created not using the template class QIfPendingReply.


value : var

Holds the current value of the PendingReply

If no result is available yet or the reply failed, a default constructed QVariant() is returned. Otherwise a QVariant holding the result is returned.


watcher : QIfPendingReplyWatcher*

Holds the watcher for the PendingReply

Note: The QIfPendingReplyWatcher returned is owned by the PendingReply and all its copies. If all copies of the PendingReply get deleted its QIfPendingReplyWatcher gets deleted as well.


Method Documentation

setFailed()

Marks the reply as failed.

Note: a result can only be set once and cannot be changed again later.

See also setSuccess.


setSuccess(var value)

Sets the result of the reply to value and marks the reply as succeeded.

The given value needs to be of the same type as the reply or be convertible to that type.

Note: a result can only be set once and cannot be changed again later.

See also setFailed.


then(success, failed)

Sets the JavaScript callbacks to be called once a result is delivered. If the reply succeeded the success callback is called, otherwise the failed callback.

The success callback can take the reply value as an argument.

See The then method for example usage.

Calling this function multiple times will override the existing callbacks.


© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.