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     \qmlclass SignalSpy SignalSpy
  44     \brief Enables introspection of signal emission
  45     \ingroup qtquick-utility
  46     \since 4.8
  47     \ingroup qtest::qml
  48
  49     In the following example, a SignalSpy is installed to watch the
  50     "clicked" signal on a user-defined Button element.  When the signal
  51     is emitted, the \l count property on the spy will be increased.
  52
  53     \code
  54     Button {
  55         id: button
  56         SignalSpy {
  57             id: spy
  58             target: button
  59             signalName: "clicked"
  60         }
  61         TestCase {
  62             name: "ButtonClick"
  63             function test_click() {
  64                 compare(spy.count, 0)
  65                 button.clicked();
  66                 compare(spy.count, 1)
  67             }
  68         }
  69     }
  70     \endcode
  71
  72     The above style of test is suitable for signals that are emitted
  73     synchronously.  For asynchronous signals, the wait() method can be
  74     used to block the test until the signal occurs (or a timeout expires).
  75
  76     \sa TestCase
  77 */
  78
  79 /*!
  80     \qmlproperty object SignalSpy::target
  81
  82     This property defines the target object that will be used to
  83     listen for emissions of the \l signalName signal.
  84
  85     \sa signalName, count
  86 */
  87
  88 /*!
  89     \qmlproperty string SignalSpy::signalName
  90
  91     This property defines the name of the signal on \l target to
  92     listen for.
  93
  94     \sa target, count
  95 */
  96
  97 /*!
  98     \qmlproperty list SignalSpy::signalArguments
  99
 100     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.
 101     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.
 102
 103     \sa signalName, clear()
 104     \readonly
 105 */
 106
 107 /*!
 108     \qmlproperty bool SignalSpy::valid
 109
 110     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.
 111
 112     \sa count, target, signalName, clear()
 113     \readonly
 114 */
 115
 116 /*!
 117     \qmlproperty int SignalSpy::count
 118
 119     This property defines the number of times that \l signalName has
 120     been emitted from \l target since the last call to clear().
 121
 122     \sa target, signalName, clear()
 123     \readonly
 124 */
 125
 126 /*!
 127     \qmlmethod SignalSpy::clear()
 128
 129     Clears \l count to 0, resets \l valid to false and clears the \l signalArguments to empty.
 130
 131     \sa count, wait()
 132 */
 133
 134 /*!
 135     \qmlmethod SignalSpy::wait(timeout = 5000)
 136
 137     Waits for the signal \l signalName on \l target to be emitted,
 138     for up to \a timeout milliseconds.  The test case will fail if
 139     the signal is not emitted.
 140
 141     \code
 142     SignalSpy {
 143         id: spy
 144         target: button
 145         signalName: "clicked"
 146     }
 147
 148     function test_async_click() {
 149         ...
 150         // do something that will cause clicked() to be emitted
 151         ...
 152         spy.wait()
 153         compare(spy.count, 1)
 154     }
 155     \endcode
 156
 157     There are two possible scenarios: the signal has already been
 158     emitted when wait() is called, or the signal has not yet been
 159     emitted.  The wait() function handles the first scenario by immediately
 160     returning if the signal has already occurred.
 161
 162     The clear() method can be used to discard information about signals
 163     that have already occurred to synchronize wait() with future signal
 164     emissions.
 165
 166     \sa clear(), TestCase::tryCompare()
 167 */