src/imports/testlib/signalspy.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the test suite of the Qt Toolkit.
   8 **
   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.
  17 **
  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.
  21 **
  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.
  29 **
  30 ** Other Usage
  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.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \qmlclass SignalSpy SignalSpy
  44     \brief The SignalSpy item enables introspection of signal emission.
  45     \since 4.8
  46     \ingroup qtest::qml
  47
  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.
  51
  52     \code
  53     Button {
  54         id: button
  55         SignalSpy {
  56             id: spy
  57             target: button
  58             signalName: "clicked"
  59         }
  60         TestCase {
  61             name: "ButtonClick"
  62             function test_click() {
  63                 compare(spy.count, 0)
  64                 button.clicked();
  65                 compare(spy.count, 1)
  66             }
  67         }
  68     }
  69     \endcode
  70
  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).
  74
  75     \sa TestCase
  76 */
  77
  78 /*!
  79     \qmlproperty object SignalSpy::target
  80
  81     This property defines the target object that will be used to
  82     listen for emissions of the \l signalName signal.
  83
  84     \sa signalName, count
  85 */
  86
  87 /*!
  88     \qmlproperty string SignalSpy::signalName
  89
  90     This property defines the name of the signal on \l target to
  91     listen for.
  92
  93     \sa target, count
  94 */
  95
  96 /*!
  97     \qmlproperty int SignalSpy::count
  98
  99     This property defines the number of times that \l signalName has
 100     been emitted from \l target since the last call to clear().
 101
 102     \sa target, signalName, clear()
 103 */
 104
 105 /*!
 106     \qmlmethod SignalSpy::clear()
 107
 108     Clears \l count to 0.
 109
 110     \sa count, wait()
 111 */
 112
 113 /*!
 114     \qmlmethod SignalSpy::wait(timeout = 5000)
 115
 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.
 119
 120     \code
 121     SignalSpy {
 122         id: spy
 123         target: button
 124         signalName: "clicked"
 125     }
 126
 127     function test_async_click() {
 128         ...
 129         // do something that will cause clicked() to be emitted
 130         ...
 131         spy.wait()
 132         compare(spy.count, 1)
 133     }
 134     \endcode
 135
 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.
 140
 141     The clear() method can be used to discard information about signals
 142     that have already occurred to synchronize wait() with future signal
 143     emissions.
 144
 145     \sa clear(), TestCase::tryCompare()
 146 */