src/imports/testlib/signalspy.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the test suite of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \qmltype SignalSpy
  44     \instantiates SignalSpy
  45     \brief Enables introspection of signal emission
  46     \ingroup qtquick-utility
  47     \since 4.8
  48     \ingroup qtest::qml
  49
  50     In the following example, a SignalSpy is installed to watch the
  51     "clicked" signal on a user-defined Button element.  When the signal
  52     is emitted, the \l count property on the spy will be increased.
  53
  54     \code
  55     Button {
  56         id: button
  57         SignalSpy {
  58             id: spy
  59             target: button
  60             signalName: "clicked"
  61         }
  62         TestCase {
  63             name: "ButtonClick"
  64             function test_click() {
  65                 compare(spy.count, 0)
  66                 button.clicked();
  67                 compare(spy.count, 1)
  68             }
  69         }
  70     }
  71     \endcode
  72
  73     The above style of test is suitable for signals that are emitted
  74     synchronously.  For asynchronous signals, the wait() method can be
  75     used to block the test until the signal occurs (or a timeout expires).
  76
  77     \sa TestCase
  78 */
  79
  80 /*!
  81     \qmlproperty object SignalSpy::target
  82
  83     This property defines the target object that will be used to
  84     listen for emissions of the \l signalName signal.
  85
  86     \sa signalName, count
  87 */
  88
  89 /*!
  90     \qmlproperty string SignalSpy::signalName
  91
  92     This property defines the name of the signal on \l target to
  93     listen for.
  94
  95     \sa target, count
  96 */
  97
  98 /*!
  99     \qmlproperty list SignalSpy::signalArguments
 100
 101     This property holds a list of emitted signal arguments. Each emission of the signal will append one item to the list, containing the arguments of the signal.
 102     When connecting to a new \l target or new \l signalName or calling the \l clear() method, the \l signalArguments will be reset to empty.
 103
 104     \sa signalName, clear()
 105     \readonly
 106 */
 107
 108 /*!
 109     \qmlproperty bool SignalSpy::valid
 110
 111     This property defines the current signal connection status. It will be true when the \l signalName of the \l target is connected successfully, otherwise it will be false.
 112
 113     \sa count, target, signalName, clear()
 114     \readonly
 115 */
 116
 117 /*!
 118     \qmlproperty int SignalSpy::count
 119
 120     This property defines the number of times that \l signalName has
 121     been emitted from \l target since the last call to clear().
 122
 123     \sa target, signalName, clear()
 124     \readonly
 125 */
 126
 127 /*!
 128     \qmlmethod SignalSpy::clear()
 129
 130     Clears \l count to 0, resets \l valid to false and clears the \l signalArguments to empty.
 131
 132     \sa count, wait()
 133 */
 134
 135 /*!
 136     \qmlmethod SignalSpy::wait(timeout = 5000)
 137
 138     Waits for the signal \l signalName on \l target to be emitted,
 139     for up to \a timeout milliseconds.  The test case will fail if
 140     the signal is not emitted.
 141
 142     \code
 143     SignalSpy {
 144         id: spy
 145         target: button
 146         signalName: "clicked"
 147     }
 148
 149     function test_async_click() {
 150         ...
 151         // do something that will cause clicked() to be emitted
 152         ...
 153         spy.wait()
 154         compare(spy.count, 1)
 155     }
 156     \endcode
 157
 158     There are two possible scenarios: the signal has already been
 159     emitted when wait() is called, or the signal has not yet been
 160     emitted.  The wait() function handles the first scenario by immediately
 161     returning if the signal has already occurred.
 162
 163     The clear() method can be used to discard information about signals
 164     that have already occurred to synchronize wait() with future signal
 165     emissions.
 166
 167     \sa clear(), TestCase::tryCompare()
 168 */