Differential D18758 Diff 58398 kdevplatform/3rdparty/qtpromise/qtpromise-0.5.0/docs/qtpromise/qtsignals.md
Changeset View
Changeset View
Standalone View
Standalone View
kdevplatform/3rdparty/qtpromise/qtpromise-0.5.0/docs/qtpromise/qtsignals.md
- This file was added.
1 | # Qt Signals | ||||
---|---|---|---|---|---|
2 | | ||||
3 | QtPromise supports creating promises that are resolved or rejected by regular [Qt signals](https://doc.qt.io/qt-5/signalsandslots.html). | ||||
4 | | ||||
5 | ::: warning IMPORTANT | ||||
6 | A promise connected to a signal will be resolved (fulfilled or rejected) **only one time**, no matter if the signals are emitted multiple times. Internally, the promise is disconnected from all signals as soon as one signal is emitted. | ||||
7 | ::: | ||||
8 | | ||||
9 | ## Resolve Signal | ||||
10 | | ||||
11 | The [`QtPromise::connect()`](helpers/connect.md) helper allows to create a promise resolved from a single signal: | ||||
12 | | ||||
13 | ```cpp | ||||
14 | // [signal] Object::finished(const QByteArray&) | ||||
15 | auto output = QtPromise::connect(obj, &Object::finished); | ||||
16 | | ||||
17 | // output type: QPromise<QByteArray> | ||||
18 | output.then([](const QByteArray& data) { | ||||
19 | // {...} | ||||
20 | }); | ||||
21 | ``` | ||||
22 | | ||||
23 | If the signal doesn't provide any argument, a `QPromise<void>` is returned: | ||||
24 | | ||||
25 | ```cpp | ||||
26 | // [signal] Object::done() | ||||
27 | auto output = QtPromise::connect(obj, &Object::done); | ||||
28 | | ||||
29 | // output type: QPromise<void> | ||||
30 | output.then([]() { | ||||
31 | // {...} | ||||
32 | }); | ||||
33 | ``` | ||||
34 | | ||||
35 | ::: tip NOTE | ||||
36 | QtPromise currently only supports single argument signals, which means that only the first argument is used to fulfill or reject the connected promise, other arguments being ignored. | ||||
37 | ::: | ||||
38 | | ||||
39 | ## Reject Signal | ||||
40 | | ||||
41 | The [`QtPromise::connect()`](helpers/connect.md) helper also allows to reject the promise from another signal: | ||||
42 | | ||||
43 | ```cpp | ||||
44 | // [signal] Object::finished(const QByteArray& data) | ||||
45 | // [signal] Object::error(ObjectError error) | ||||
46 | auto output = QtPromise::connect(obj, &Object::finished, &Object::error); | ||||
47 | | ||||
48 | // output type: QPromise<QByteArray> | ||||
49 | output.then([](const QByteArray& data) { | ||||
50 | // {...} | ||||
51 | }).fail(const ObjectError& error) { | ||||
52 | // {...} | ||||
53 | }); | ||||
54 | ``` | ||||
55 | | ||||
56 | If the rejection signal doesn't provide any argument, the promise will be rejected | ||||
57 | with [`QPromiseUndefinedException`](../exceptions/undefined), for example: | ||||
58 | | ||||
59 | ```cpp | ||||
60 | // [signal] Object::finished() | ||||
61 | // [signal] Object::error() | ||||
62 | auto output = QtPromise::connect(obj, &Object::finished, &Object::error); | ||||
63 | | ||||
64 | // output type: QPromise<QByteArray> | ||||
65 | output.then([]() { | ||||
66 | // {...} | ||||
67 | }).fail(const QPromiseUndefinedException& error) { | ||||
68 | // {...} | ||||
69 | }); | ||||
70 | ``` | ||||
71 | | ||||
72 | A third variant allows to connect the resolve and reject signals from different objects: | ||||
73 | | ||||
74 | ```cpp | ||||
75 | // [signal] ObjectA::finished(const QByteArray& data) | ||||
76 | // [signal] ObjectB::error(ObjectBError error) | ||||
77 | auto output = QtPromise::connect(objA, &ObjectA::finished, objB, &ObjectB::error); | ||||
78 | | ||||
79 | // output type: QPromise<QByteArray> | ||||
80 | output.then([](const QByteArray& data) { | ||||
81 | // {...} | ||||
82 | }).fail(const ObjectBError& error) { | ||||
83 | // {...} | ||||
84 | }); | ||||
85 | ``` | ||||
86 | | ||||
87 | Additionally to the rejection signal, promises created using [`QtPromise::connect()`](helpers/connect.md) are automatically rejected with [`QPromiseContextException`](exceptions/context.md) if the sender is destroyed before fulfilling the promise. | ||||
88 | | ||||
89 | See [`QtPromise::connect()`](helpers/connect.md) for more details. |