<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- SignalSpy.qml -->
<title>SignalSpy QML Type | Qt Quick 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qtquick-index.html">Qt Quick</a></td><td ><a href="qtquick-qmlmodule.html">QML Types</a></td><td >SignalSpy QML Type</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level1"><a href="#methods">Methods</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">SignalSpy QML Type</h1>
<span class="subtitle"></span>
<!-- $$$SignalSpy-brief -->
<p>Enables introspection of signal emission <a href="#details">More...</a></p>
<!-- @@@SignalSpy -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Import Statement:</td><td class="memItemRight bottomAlign"> import QtTest 1.1</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 4.8</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Inherits:</td><td class="memItemRight bottomAlign"> <p><a href="qml-qtquick-item.html">Item</a></p>
</td></tr></table></div><ul>
<li><a href="qml-qttest-signalspy-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="properties"></a>
<h2 id="properties">Properties</h2>
<ul>
<li class="fn"><b><b><a href="qml-qttest-signalspy.html#count-prop">count</a></b></b> : int</li>
<li class="fn"><b><b><a href="qml-qttest-signalspy.html#signalArguments-prop">signalArguments</a></b></b> : list</li>
<li class="fn"><b><b><a href="qml-qttest-signalspy.html#signalName-prop">signalName</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qttest-signalspy.html#target-prop">target</a></b></b> : var</li>
<li class="fn"><b><b><a href="qml-qttest-signalspy.html#valid-prop">valid</a></b></b> : bool</li>
</ul>
<a name="methods"></a>
<h2 id="methods">Methods</h2>
<ul>
<li class="fn"><b><b><a href="qml-qttest-signalspy.html#clear-method">clear</a></b></b>()</li>
<li class="fn"><b><b><a href="qml-qttest-signalspy.html#wait-method">wait</a></b></b>(<i>timeout</i>)</li>
</ul>
<!-- $$$SignalSpy-description -->
<a name="details"></a>
<h2 id="details">Detailed Description</h2>
<p>In the following example, a <a href="qml-qttest-signalspy.html">SignalSpy</a> is installed to watch the "clicked" signal on a user-defined Button type. When the signal is emitted, the <a href="qml-qttest-signalspy.html#count-prop">count</a> property on the spy will be increased.</p>
<pre class="cpp">
Button {
id: button
SignalSpy {
id: spy
target: button
signalName: <span class="string">"clicked"</span>
}
TestCase {
name: <span class="string">"ButtonClick"</span>
function test_click() {
compare(spy<span class="operator">.</span>count<span class="operator">,</span> <span class="number">0</span>)
button<span class="operator">.</span>clicked();
compare(spy<span class="operator">.</span>count<span class="operator">,</span> <span class="number">1</span>)
}
}
}
</pre>
<p>The above style of test is suitable for signals that are emitted synchronously. For asynchronous signals, the <a href="qml-qttest-signalspy.html#wait-method">wait()</a> method can be used to block the test until the signal occurs (or a timeout expires).</p>
<p><b>See also </b><a href="qml-qttest-testcase.html">TestCase</a> and Qt Quick Test Reference Documentation.</p>
<!-- @@@SignalSpy -->
<h2>Property Documentation</h2>
<!-- $$$count -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="count-prop">
<td class="tblQmlPropNode"><p>
<a name="count-prop"></a><span class="qmlreadonly">[read-only] </span><span class="name">count</span> : <span class="type">int</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This property defines the number of times that <a href="qml-qttest-signalspy.html#signalName-prop">signalName</a> has been emitted from <a href="qml-qttest-signalspy.html#target-prop">target</a> since the last call to <a href="qml-qttest-signalspy.html#clear-method">clear()</a>.</p>
<p><b>See also </b><a href="qml-qttest-signalspy.html#target-prop">target</a>, <a href="qml-qttest-signalspy.html#signalName-prop">signalName</a>, and <a href="qml-qttest-signalspy.html#clear-method">clear()</a>.</p>
</div></div><!-- @@@count -->
<br/>
<!-- $$$signalArguments -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="signalArguments-prop">
<td class="tblQmlPropNode"><p>
<a name="signalArguments-prop"></a><span class="qmlreadonly">[read-only] </span><span class="name">signalArguments</span> : <span class="type">list</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>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. When connecting to a new <a href="qml-qttest-signalspy.html#target-prop">target</a> or new <a href="qml-qttest-signalspy.html#signalName-prop">signalName</a> or calling the <a href="qml-qttest-signalspy.html#clear-method">clear()</a> method, the signalArguments will be reset to empty.</p>
<p><b>See also </b><a href="qml-qttest-signalspy.html#signalName-prop">signalName</a> and <a href="qml-qttest-signalspy.html#clear-method">clear()</a>.</p>
</div></div><!-- @@@signalArguments -->
<br/>
<!-- $$$signalName -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="signalName-prop">
<td class="tblQmlPropNode"><p>
<a name="signalName-prop"></a><span class="name">signalName</span> : <span class="type">string</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This property defines the name of the signal on <a href="qml-qttest-signalspy.html#target-prop">target</a> to listen for.</p>
<p><b>See also </b><a href="qml-qttest-signalspy.html#target-prop">target</a> and <a href="qml-qttest-signalspy.html#count-prop">count</a>.</p>
</div></div><!-- @@@signalName -->
<br/>
<!-- $$$target -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="target-prop">
<td class="tblQmlPropNode"><p>
<a name="target-prop"></a><span class="name">target</span> : <span class="type">var</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This property defines the target object that will be used to listen for emissions of the <a href="qml-qttest-signalspy.html#signalName-prop">signalName</a> signal.</p>
<p><b>See also </b><a href="qml-qttest-signalspy.html#signalName-prop">signalName</a> and <a href="qml-qttest-signalspy.html#count-prop">count</a>.</p>
</div></div><!-- @@@target -->
<br/>
<!-- $$$valid -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="valid-prop">
<td class="tblQmlPropNode"><p>
<a name="valid-prop"></a><span class="qmlreadonly">[read-only] </span><span class="name">valid</span> : <span class="type">bool</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This property defines the current signal connection status. It will be true when the <a href="qml-qttest-signalspy.html#signalName-prop">signalName</a> of the <a href="qml-qttest-signalspy.html#target-prop">target</a> is connected successfully, otherwise it will be false.</p>
<p><b>See also </b><a href="qml-qttest-signalspy.html#count-prop">count</a>, <a href="qml-qttest-signalspy.html#target-prop">target</a>, <a href="qml-qttest-signalspy.html#signalName-prop">signalName</a>, and <a href="qml-qttest-signalspy.html#clear-method">clear()</a>.</p>
</div></div><!-- @@@valid -->
<br/>
<h2>Method Documentation</h2>
<!-- $$$clear -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="clear-method">
<td class="tblQmlFuncNode"><p>
<a name="clear-method"></a><span class="name">clear</span>()</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Clears <a href="qml-qttest-signalspy.html#count-prop">count</a> to 0, resets <a href="qml-qttest-signalspy.html#valid-prop">valid</a> to false and clears the <a href="qml-qttest-signalspy.html#signalArguments-prop">signalArguments</a> to empty.</p>
<p><b>See also </b><a href="qml-qttest-signalspy.html#count-prop">count</a> and <a href="qml-qttest-signalspy.html#wait-method">wait()</a>.</p>
</div></div><!-- @@@clear -->
<br/>
<!-- $$$wait -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="wait-method">
<td class="tblQmlFuncNode"><p>
<a name="wait-method"></a><span class="name">wait</span>(<i>timeout</i> = 5000)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Waits for the signal <a href="qml-qttest-signalspy.html#signalName-prop">signalName</a> on <a href="qml-qttest-signalspy.html#target-prop">target</a> to be emitted, for up to <i>timeout</i> milliseconds. The test case will fail if the signal is not emitted.</p>
<pre class="cpp">
SignalSpy {
id: spy
target: button
signalName: <span class="string">"clicked"</span>
}
function test_async_click() {
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="comment">// do something that will cause clicked() to be emitted</span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
spy<span class="operator">.</span>wait()
compare(spy<span class="operator">.</span>count<span class="operator">,</span> <span class="number">1</span>)
}
</pre>
<p>There are two possible scenarios: the signal has already been emitted when wait() is called, or the signal has not yet been emitted. The wait() function handles the first scenario by immediately returning if the signal has already occurred.</p>
<p>The <a href="qml-qttest-signalspy.html#clear-method">clear()</a> method can be used to discard information about signals that have already occurred to synchronize wait() with future signal emissions.</p>
<p><b>See also </b><a href="qml-qttest-signalspy.html#clear-method">clear()</a> and <a href="qml-qttest-testcase.html#tryCompare-method">TestCase::tryCompare()</a>.</p>
</div></div><!-- @@@wait -->
<br/>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
