1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Old-style Signal and Slot Support — PyQt 4.12.1 Reference Guide</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '4.12.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/logo_tn.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Things to be Aware Of" href="gotchas.html" />
<link rel="prev" title="New-style Signal and Slot Support" href="new_style_signals_slots.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="gotchas.html" title="Things to be Aware Of"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="new_style_signals_slots.html" title="New-style Signal and Slot Support"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">PyQt 4.12.1 Reference Guide</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="old-style-signal-and-slot-support">
<h1>Old-style Signal and Slot Support<a class="headerlink" href="#old-style-signal-and-slot-support" title="Permalink to this headline">¶</a></h1>
<p>This section describes the older style for connecting signals and slots. It
uses the same API that a C++ application would use. This has a number of
advantages.</p>
<ul class="simple">
<li>It is well understood and documented.</li>
<li>Any future changes to the C++ API should be easily included.</li>
</ul>
<p>It also has a number of disadvantages.</p>
<ul class="simple">
<li>It requires knowledge of the C++ types of signal arguments.</li>
<li>It is error prone in that if you mis-type the signal name or signature then
no exception is raised, either when the signal is connected or emitted.</li>
<li>It is verbose.</li>
<li>It is not Pythonic.</li>
</ul>
<p>This older style of connecting signals and slots will continue to be supported
throughout the life of PyQt4.</p>
<div class="section" id="pyqt4-signals-and-qt-signals">
<h2>PyQt4 Signals and Qt Signals<a class="headerlink" href="#pyqt4-signals-and-qt-signals" title="Permalink to this headline">¶</a></h2>
<p>Qt signals are statically defined as part of a C++ class. They are referenced
using the <code class="docutils literal"><span class="pre">QtCore.SIGNAL()</span></code> function. This method takes a single string
argument that is the name of the signal and its C++ signature. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">QtCore</span><span class="o">.</span><span class="n">SIGNAL</span><span class="p">(</span><span class="s1">'finished(int)'</span><span class="p">)</span>
</pre></div>
</div>
<p>The returned value is normally passed to the <code class="docutils literal"><span class="pre">QtCore.QObject.connect()</span></code>
method.</p>
<p>PyQt4 allows new signals to be defined dynamically. The act of emitting a
PyQt4 signal implicitly defines it. PyQt4 signals are also referenced using
the <code class="docutils literal"><span class="pre">QtCore.SIGNAL()</span></code> function.</p>
</div>
<div class="section" id="the-pyqt-pyobject-signal-argument-type">
<h2>The <code class="docutils literal"><span class="pre">PyQt_PyObject</span></code> Signal Argument Type<a class="headerlink" href="#the-pyqt-pyobject-signal-argument-type" title="Permalink to this headline">¶</a></h2>
<p>It is possible to pass any Python object as a signal argument by specifying
<code class="docutils literal"><span class="pre">PyQt_PyObject</span></code> as the type of the argument in the signature. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">QtCore</span><span class="o">.</span><span class="n">SIGNAL</span><span class="p">(</span><span class="s1">'finished(PyQt_PyObject)'</span><span class="p">)</span>
</pre></div>
</div>
<p>While this would normally be used for passing objects like lists and
dictionaries as signal arguments, it can be used for any Python type. Its
advantage when passing, for example, an integer is that the normal conversions
from a Python object to a C++ integer and back again are not required.</p>
<p>The reference count of the object being passed is maintained automatically.
There is no need for the emitter of a signal to keep a reference to the object
after the call to <code class="docutils literal"><span class="pre">QtCore.QObject.emit()</span></code>, even if a connection is queued.</p>
</div>
<div class="section" id="short-circuit-signals">
<h2>Short-circuit Signals<a class="headerlink" href="#short-circuit-signals" title="Permalink to this headline">¶</a></h2>
<p>There is also a special form of a PyQt4 signal known as a short-circuit signal.
Short-circut signals implicitly declare each argument as being of type
<code class="docutils literal"><span class="pre">PyQt_PyObject</span></code>.</p>
<p>Short-circuit signals do not have a list of arguments or the surrounding
parentheses.</p>
<p>Short-circuit signals may only be connected to slots that have been implemented
in Python. They cannot be connected to Qt slots or the Python callables that
wrap Qt slots.</p>
</div>
<div class="section" id="pyqt4-slots-and-qt-slots">
<h2>PyQt4 Slots and Qt Slots<a class="headerlink" href="#pyqt4-slots-and-qt-slots" title="Permalink to this headline">¶</a></h2>
<p>Qt slots are statically defined as part of a C++ class. They are referenced
using the <code class="docutils literal"><span class="pre">QtCore.SLOT()</span></code> function. This method takes a single string
argument that is the name of the slot and its C++ signature. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">QtCore</span><span class="o">.</span><span class="n">SLOT</span><span class="p">(</span><span class="s1">'done(int)'</span><span class="p">)</span>
</pre></div>
</div>
<p>The returned value is normally passed to the <code class="docutils literal"><span class="pre">QtCore.QObject.connect()</span></code>
method.</p>
<p>PyQt4 allows any Python callable to be used as a slot, not just Qt slots. This
is done by simply referencing the callable. Because Qt slots are implemented
as class methods they are also available as Python callables. Therefore it is
not usually necessary to use <code class="docutils literal"><span class="pre">QtCore.SLOT()</span></code> for Qt slots. However, doing so
is more efficient as it avoids a conversion to Python and back to C++.</p>
<p>Qt allows a signal to be connected to a slot that requires fewer arguments than
the signal passes. The extra arguments are quietly discarded. PyQt4 slots can
be used in the same way.</p>
<p>Note that when a slot is a Python callable its reference count is not
increased. This means that a class instance can be deleted without having to
explicitly disconnect any signals connected to its methods. However, if a slot
is a lambda function or a partial function then its reference count is
automatically incremented to prevent it from being immediately garbage
collected.</p>
</div>
<div class="section" id="connecting-signals-and-slots">
<h2>Connecting Signals and Slots<a class="headerlink" href="#connecting-signals-and-slots" title="Permalink to this headline">¶</a></h2>
<p>Connections between signals and slots (and other signals) are made using the
<code class="docutils literal"><span class="pre">QtCore.QObject.connect()</span></code> method. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">QtCore</span><span class="o">.</span><span class="n">QObject</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">SIGNAL</span><span class="p">(</span><span class="s1">'QtSig()'</span><span class="p">),</span> <span class="n">pyFunction</span><span class="p">)</span>
<span class="n">QtCore</span><span class="o">.</span><span class="n">QObject</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">SIGNAL</span><span class="p">(</span><span class="s1">'QtSig()'</span><span class="p">),</span> <span class="n">pyClass</span><span class="o">.</span><span class="n">pyMethod</span><span class="p">)</span>
<span class="n">QtCore</span><span class="o">.</span><span class="n">QObject</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">SIGNAL</span><span class="p">(</span><span class="s1">'QtSig()'</span><span class="p">),</span> <span class="n">b</span><span class="p">,</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">SLOT</span><span class="p">(</span><span class="s1">'QtSlot()'</span><span class="p">))</span>
<span class="n">QtCore</span><span class="o">.</span><span class="n">QObject</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">SIGNAL</span><span class="p">(</span><span class="s1">'PySig()'</span><span class="p">),</span> <span class="n">b</span><span class="p">,</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">SLOT</span><span class="p">(</span><span class="s1">'QtSlot()'</span><span class="p">))</span>
<span class="n">QtCore</span><span class="o">.</span><span class="n">QObject</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">QtCore</span><span class="o">.</span><span class="n">SIGNAL</span><span class="p">(</span><span class="s1">'PySig'</span><span class="p">),</span> <span class="n">pyFunction</span><span class="p">)</span>
</pre></div>
</div>
<p>Disconnecting signals works in exactly the same way using the
<code class="docutils literal"><span class="pre">QtCore.QObject.disconnect()</span></code> method. However, not all the variations of
that method are supported by PyQt4. Signals must be disconnected one at a
time.</p>
</div>
<div class="section" id="emitting-signals">
<h2>Emitting Signals<a class="headerlink" href="#emitting-signals" title="Permalink to this headline">¶</a></h2>
<p>Any instance of a class that is derived from the <code class="docutils literal"><span class="pre">QtCore.QObject</span></code> class can
emit a signal using its <code class="docutils literal"><span class="pre">emit()</span></code> method. This takes a minimum of one
argument which is the signal. Any other arguments are passed to the connected
slots as the signal arguments. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">a</span><span class="o">.</span><span class="n">emit</span><span class="p">(</span><span class="n">QtCore</span><span class="o">.</span><span class="n">SIGNAL</span><span class="p">(</span><span class="s1">'clicked()'</span><span class="p">))</span>
<span class="n">a</span><span class="o">.</span><span class="n">emit</span><span class="p">(</span><span class="n">QtCore</span><span class="o">.</span><span class="n">SIGNAL</span><span class="p">(</span><span class="s1">'pySig'</span><span class="p">),</span> <span class="s2">"Hello"</span><span class="p">,</span> <span class="s2">"World"</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="the-qtcore-pyqtsignature-decorator">
<h2>The <code class="docutils literal"><span class="pre">QtCore.pyqtSignature()</span></code> Decorator<a class="headerlink" href="#the-qtcore-pyqtsignature-decorator" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal"><span class="pre">QtCore.pyqtSignature()</span></code> serves the same purpose as the
<a class="reference internal" href="new_style_signals_slots.html#PyQt4.QtCore.pyqtSlot" title="PyQt4.QtCore.pyqtSlot"><code class="xref py py-func docutils literal"><span class="pre">pyqtSlot()</span></code></a> decorator but has a less Pythonic API.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/logo.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Old-style Signal and Slot Support</a><ul>
<li><a class="reference internal" href="#pyqt4-signals-and-qt-signals">PyQt4 Signals and Qt Signals</a></li>
<li><a class="reference internal" href="#the-pyqt-pyobject-signal-argument-type">The <code class="docutils literal"><span class="pre">PyQt_PyObject</span></code> Signal Argument Type</a></li>
<li><a class="reference internal" href="#short-circuit-signals">Short-circuit Signals</a></li>
<li><a class="reference internal" href="#pyqt4-slots-and-qt-slots">PyQt4 Slots and Qt Slots</a></li>
<li><a class="reference internal" href="#connecting-signals-and-slots">Connecting Signals and Slots</a></li>
<li><a class="reference internal" href="#emitting-signals">Emitting Signals</a></li>
<li><a class="reference internal" href="#the-qtcore-pyqtsignature-decorator">The <code class="docutils literal"><span class="pre">QtCore.pyqtSignature()</span></code> Decorator</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="new_style_signals_slots.html"
title="previous chapter">New-style Signal and Slot Support</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="gotchas.html"
title="next chapter">Things to be Aware Of</a></p>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="gotchas.html" title="Things to be Aware Of"
>next</a> |</li>
<li class="right" >
<a href="new_style_signals_slots.html" title="New-style Signal and Slot Support"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">PyQt 4.12.1 Reference Guide</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2016 Riverbank Computing Limited.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.2.
</div>
</body>
</html>
|
