QObject: add a single shot connection flag

If one needed to listen to a signal just once, one had to
store the QMetaObject::Connection object returned by connect()
and use it to disconnect the slot after the first signal
activation.

This has led to a proliferation of using wrappers (and enough
TMP); they usually look like this:

1) create a shared_ptr<QMO::Connection>, allocating its payload;
2) create a lambda, capturing the shared_ptr by value;
3) in the lambda, disconnect the connection (through the shared_ptr),
   and call the actual slot;
4) connect the signal to the lambda, storing the returned
   QMO::Connection into the shared_ptr.

This is expensive, error prone for newcomers, and tricky to
support as a general facility inside one's projects.
We can do better, just support single shot connections right
in QObject.

[ChangeLog][QtCore][QObject] Added the Qt::SingleShotConnection
flag. When a connection is established with this flag set,
the slot is going to be activated at most once; when the signal
is emitted, the connection gets automatically broken by Qt.

Change-Id: I5f5feeae7f76c9c3d6323d841efba81c8f98ce7e
Fixes: QTBUG-44219
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>

2 files changed, 9 insertions, 1 deletions

diff --git a/src/corelib/global/qnamespace.h b/src/corelib/global/qnamespace.h
index 9b5af17f7c..a531bc627b 100644
--- a/src/corelib/global/qnamespace.h
+++ b/src/corelib/global/qnamespace.h
@@ -1301,7 +1301,8 @@ namespace Qt {
         DirectConnection,
         QueuedConnection,
         BlockingQueuedConnection,
-        UniqueConnection =  0x80
+        UniqueConnection =  0x80,
+        SingleShotConnection = 0x100,
     };
 
     enum ShortcutContext {
diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index b5830173f8..95a73c4439 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -638,6 +638,13 @@
            (i.e. if the same signal is already connected to the same slot
            for the same pair of objects). This flag was introduced in Qt 4.6.
 
+    \value SingleShotConnection
+           This is a flag that can be combined with any one of the above
+           connection types, using a bitwise OR. When Qt::SingleShotConnection
+           is set, the slot is going to be called only once; the connection
+           will be automatically broken when the signal is emitted.
+           This flag was introduced in Qt 6.0.
+
     With queued connections, the parameters must be of types that are
     known to Qt's meta-object system, because Qt needs to copy the
     arguments to store them in an event behind the scenes. If you try