1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: http://www.qt-project.org/
7 ** This file is part of the test suite of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
43 \qmlclass SignalSpy SignalSpy
44 \brief The SignalSpy item enables introspection of signal emission.
48 In the following example, a SignalSpy is installed to watch the
49 "clicked" signal on a user-defined Button element. When the signal
50 is emitted, the \l count property on the spy will be increased.
62 function test_click() {
71 The above style of test is suitable for signals that are emitted
72 synchronously. For asynchronous signals, the wait() method can be
73 used to block the test until the signal occurs (or a timeout expires).
79 \qmlproperty object SignalSpy::target
81 This property defines the target object that will be used to
82 listen for emissions of the \l signalName signal.
88 \qmlproperty string SignalSpy::signalName
90 This property defines the name of the signal on \l target to
97 \qmlproperty int SignalSpy::count
99 This property defines the number of times that \l signalName has
100 been emitted from \l target since the last call to clear().
102 \sa target, signalName, clear()
106 \qmlmethod SignalSpy::clear()
108 Clears \l count to 0.
114 \qmlmethod SignalSpy::wait(timeout = 5000)
116 Waits for the signal \l signalName on \l target to be emitted,
117 for up to \a timeout milliseconds. The test case will fail if
118 the signal is not emitted.
124 signalName: "clicked"
127 function test_async_click() {
129 // do something that will cause clicked() to be emitted
132 compare(spy.count, 1)
136 There are two possible scenarios: the signal has already been
137 emitted when wait() is called, or the signal has not yet been
138 emitted. The wait() function handles the first scenario by immediately
139 returning if the signal has already occurred.
141 The clear() method can be used to discard information about signals
142 that have already occurred to synchronize wait() with future signal
145 \sa clear(), TestCase::tryCompare()