1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\class QSignalSpy
\inmodule QtTest
\brief The QSignalSpy class enables introspection of signal emission.
QSignalSpy can connect to any signal of any object and records its emission.
QSignalSpy itself is a list of QVariant lists. Each emission of the signal
will append one item to the list, containing the arguments of the signal.
The following example records all signal emissions for the \c clicked() signal
of a QCheckBox:
\snippet code/doc_src_qsignalspy.cpp 0
\c{spy.takeFirst()} returns the arguments for the first emitted signal, as a
list of QVariant objects. The \c clicked() signal has a single bool argument,
which is stored as the first entry in the list of arguments.
The example below catches a signal from a custom object:
\snippet code/doc_src_qsignalspy.cpp 1
\note Non-standard data types need to be registered, using
the qRegisterMetaType() function, before you can create a
QSignalSpy. For example:
\snippet code/doc_src_qsignalspy.cpp 2
To retrieve the instance, you can use qvariant_cast:
\snippet code/doc_src_qsignalspy.cpp 3
\section1 Verifying Signal Emissions
The QSignalSpy class provides an elegant mechanism for capturing the list
of signals emitted by an object. However, you should verify its validity
after construction. The constructor does a number of sanity checks, such as
verifying that the signal to be spied upon actually exists. To make the
diagnosis of test failures easier, the results of these checks should be
checked by calling \c QVERIFY(spy.isValid()) before proceeding further with
a test.
\sa QVERIFY()
*/
/*! \fn QSignalSpy::QSignalSpy(const QObject *object, const char *signal)
Constructs a new QSignalSpy that listens for emissions of the \a signal
from the QObject \a object. If QSignalSpy is not able to listen for a
valid signal (for example, because \a object is \nullptr or \a signal does
not denote a valid signal of \a object), an explanatory warning message
will be output using qWarning() and subsequent calls to \c isValid() will
return false.
Example:
\snippet code/doc_src_qsignalspy.cpp 4
*/
/*! \fn template <typename PointerToMemberFunction> QSignalSpy::QSignalSpy(const QObject *object, PointerToMemberFunction signal)
\since 5.4
Constructs a new QSignalSpy that listens for emissions of the \a signal
from the QObject \a object. If QSignalSpy is not able to listen for a
valid signal (for example, because \a object is \nullptr or \a signal does
not denote a valid signal of \a object), an explanatory warning message
will be output using qWarning() and subsequent calls to \c isValid() will
return false.
Example:
\snippet code/doc_src_qsignalspy.cpp 6
*/
/*! \fn QSignalSpy::QSignalSpy(const QObject *obj, const QMetaMethod &signal)
\since 5.14
Constructs a new QSignalSpy that listens for emissions of the \a signal
from the QObject \a obj. If QSignalSpy is not able to listen for a
valid signal (for example, because \a obj is \nullptr or \a signal does
not denote a valid signal of \a obj), an explanatory warning message
will be output using qWarning() and subsequent calls to \c isValid() will
return false.
This constructor is convenient to use when Qt's meta-object system is
heavily used in a test.
Basic usage example:
\snippet code/doc_src_qsignalspy.cpp 7
Imagine we need to check whether all properties of the QWindow class
that represent minimum and maximum dimensions are properly writable.
The following example demonstrates one of the approaches:
\snippet code/doc_src_qsignalspy.cpp 8
*/
/*! \fn QSignalSpy::isValid() const
Returns \c true if the signal spy listens to a valid signal, otherwise false.
*/
/*! \fn QSignalSpy::signal() const
Returns the normalized signal the spy is currently listening to.
*/
/*! \fn int QSignalSpy::qt_metacall(QMetaObject::Call call, int id, void **a)
\internal
*/
/*! \fn QSignalSpy::wait(int timeout)
\since 5.0
Starts an event loop that runs until the given signal is received.
Optionally the event loop can return earlier on a \a timeout (in milliseconds).
Returns \c true if the signal was emitted at least once in \a timeout milliseconds, otherwise returns \c false.
Example:
\snippet code/doc_src_qsignalspy.cpp 5
*/
|
