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
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
|
<!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>New-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="Old-style Signal and Slot Support" href="old_style_signals_slots.html" />
<link rel="prev" title="Support for Qt Properties" href="qt_properties.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="old_style_signals_slots.html" title="Old-style Signal and Slot Support"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="qt_properties.html" title="Support for Qt Properties"
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="new-style-signal-and-slot-support">
<h1>New-style Signal and Slot Support<a class="headerlink" href="#new-style-signal-and-slot-support" title="Permalink to this headline">¶</a></h1>
<p>This section describes the new style of connecting signals and slots
introduced in PyQt4 v4.5.</p>
<p>One of the key features of Qt is its use of signals and slots to communicate
between objects. Their use encourages the development of reusable components.</p>
<p>A signal is emitted when something of potential interest happens. A slot is a
Python callable. If a signal is connected to a slot then the slot is called
when the signal is emitted. If a signal isn’t connected then nothing happens.
The code (or component) that emits the signal does not know or care if the
signal is being used.</p>
<p>The signal/slot mechanism has the following features.</p>
<ul class="simple">
<li>A signal may be connected to many slots.</li>
<li>A signal may also be connected to another signal.</li>
<li>Signal arguments may be any Python type.</li>
<li>A slot may be connected to many signals.</li>
<li>Connections may be direct (ie. synchronous) or queued (ie. asynchronous).</li>
<li>Connections may be made across threads.</li>
<li>Signals may be disconnected.</li>
</ul>
<div class="section" id="unbound-and-bound-signals">
<h2>Unbound and Bound Signals<a class="headerlink" href="#unbound-and-bound-signals" title="Permalink to this headline">¶</a></h2>
<p>A signal (specifically an unbound signal) is an attribute of a class that is a
sub-class of <code class="docutils literal"><span class="pre">QObject</span></code>. When a signal is referenced as an attribute of an
instance of the class then PyQt4 automatically binds the instance to the signal
in order to create a <em>bound signal</em>. This is the same mechanism that Python
itself uses to create bound methods from class functions.</p>
<p>A bound signal has <code class="docutils literal"><span class="pre">connect()</span></code>, <code class="docutils literal"><span class="pre">disconnect()</span></code> and <code class="docutils literal"><span class="pre">emit()</span></code> methods that
implement the associated functionality. It also has a <code class="docutils literal"><span class="pre">signal</span></code> attribute
that is the signature of the signal that would be returned by Qt’s <code class="docutils literal"><span class="pre">SIGNAL()</span></code>
macro.</p>
<p>A signal may be overloaded, ie. a signal with a particular name may support
more than one signature. A signal may be indexed with a signature in order to
select the one required. A signature is a sequence of types. A type is either
a Python type object or a string that is the name of a C++ type. The name of a
C++ type is automatically normalised so that, for example, <code class="docutils literal"><span class="pre">QString</span></code> can be
used instead of the non-normalised <code class="docutils literal"><span class="pre">const</span> <span class="pre">QString</span> <span class="pre">&</span></code>.</p>
<p>If a signal is overloaded then it will have a default that will be used if no
index is given.</p>
<p>When a signal is emitted then any arguments are converted to C++ types if
possible. If an argument doesn’t have a corresponding C++ type then it is
wrapped in a special C++ type that allows it to be passed around Qt’s meta-type
system while ensuring that its reference count is properly maintained.</p>
</div>
<div class="section" id="defining-new-signals-with-pyqtsignal">
<h2>Defining New Signals with <a class="reference internal" href="#PyQt4.QtCore.pyqtSignal" title="PyQt4.QtCore.pyqtSignal"><code class="xref py py-func docutils literal"><span class="pre">pyqtSignal()</span></code></a><a class="headerlink" href="#defining-new-signals-with-pyqtsignal" title="Permalink to this headline">¶</a></h2>
<p>PyQt4 automatically defines signals for all Qt’s built-in signals. New signals
can be defined as class attributes using the <a class="reference internal" href="#PyQt4.QtCore.pyqtSignal" title="PyQt4.QtCore.pyqtSignal"><code class="xref py py-func docutils literal"><span class="pre">pyqtSignal()</span></code></a>
factory.</p>
<dl class="function">
<dt id="PyQt4.QtCore.pyqtSignal">
<code class="descclassname">PyQt4.QtCore.</code><code class="descname">pyqtSignal</code><span class="sig-paren">(</span><em>types</em><span class="optional">[</span>, <em>name</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#PyQt4.QtCore.pyqtSignal" title="Permalink to this definition">¶</a></dt>
<dd><p>Create one or more overloaded unbound signals as a class attribute.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>types</strong> – the types that define the C++ signature of the signal. Each type may
be a Python type object or a string that is the name of a C++ type.
Alternatively each may be a sequence of type arguments. In this case
each sequence defines the signature of a different signal overload.
The first overload will be the default.</li>
<li><strong>name</strong> – the name of the signal. If it is omitted then the name of the class
attribute is used. This may only be given as a keyword argument.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last">an unbound signal</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<p>The following example shows the definition of a number of new signals:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PyQt4.QtCore</span> <span class="k">import</span> <span class="n">QObject</span><span class="p">,</span> <span class="n">pyqtSignal</span>
<span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="n">QObject</span><span class="p">):</span>
<span class="c1"># This defines a signal called 'closed' that takes no arguments.</span>
<span class="n">closed</span> <span class="o">=</span> <span class="n">pyqtSignal</span><span class="p">()</span>
<span class="c1"># This defines a signal called 'rangeChanged' that takes two</span>
<span class="c1"># integer arguments.</span>
<span class="n">range_changed</span> <span class="o">=</span> <span class="n">pyqtSignal</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="nb">int</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">'rangeChanged'</span><span class="p">)</span>
<span class="c1"># This defines a signal called 'valueChanged' that has two overloads,</span>
<span class="c1"># one that takes an integer argument and one that takes a QString</span>
<span class="c1"># argument. Note that because we use a string to specify the type of</span>
<span class="c1"># the QString argument then this code will run under Python v2 and v3.</span>
<span class="n">valueChanged</span> <span class="o">=</span> <span class="n">pyqtSignal</span><span class="p">([</span><span class="nb">int</span><span class="p">],</span> <span class="p">[</span><span class="s1">'QString'</span><span class="p">])</span>
</pre></div>
</div>
<p>New signals should only be defined in sub-classes of <code class="docutils literal"><span class="pre">QObject</span></code>. They must be
part of the class definition and cannot be dynamically added as class
attributes after the class has been defined.</p>
<p>New signals defined in this way will be automatically added to the class’s
<code class="docutils literal"><span class="pre">QMetaObject</span></code>. This means that they will appear in Qt Designer and can be
introspected using the <code class="docutils literal"><span class="pre">QMetaObject</span></code> API.</p>
<p>Overloaded signals should be used with care when an argument has a Python type
that has no corresponding C++ type. PyQt4 uses the same internal C++ class to
represent such objects and so it is possible to have overloaded signals with
different Python signatures that are implemented with identical C++ signatures
with unexpected results. The following is an example of this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="n">QObject</span><span class="p">):</span>
<span class="c1"># This will cause problems because each has the same C++ signature.</span>
<span class="n">valueChanged</span> <span class="o">=</span> <span class="n">pyqtSignal</span><span class="p">([</span><span class="nb">dict</span><span class="p">],</span> <span class="p">[</span><span class="nb">list</span><span class="p">])</span>
</pre></div>
</div>
</div>
<div class="section" id="connecting-disconnecting-and-emitting-signals">
<h2>Connecting, Disconnecting and Emitting Signals<a class="headerlink" href="#connecting-disconnecting-and-emitting-signals" title="Permalink to this headline">¶</a></h2>
<p>Signals are connected to slots using the <a class="reference internal" href="#connect" title="connect"><code class="xref py py-meth docutils literal"><span class="pre">connect()</span></code></a> method of a bound
signal.</p>
<dl class="method">
<dt id="connect">
<code class="descname">connect</code><span class="sig-paren">(</span><em>slot</em><span class="optional">[</span>, <em>type=PyQt4.QtCore.Qt.AutoConnection</em><span class="optional">[</span>, <em>no_receiver_check=False</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Connect a signal to a slot. An exception will be raised if the connection
failed.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>slot</strong> – the slot to connect to, either a Python callable or another bound
signal.</li>
<li><strong>type</strong> – the type of the connection to make.</li>
<li><strong>no_receiver_check</strong> – suppress the check that the underlying C++ receiver instance still
exists and deliver the signal anyway.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<p>Signals are disconnected from slots using the <a class="reference internal" href="#disconnect" title="disconnect"><code class="xref py py-meth docutils literal"><span class="pre">disconnect()</span></code></a> method of a
bound signal.</p>
<dl class="method">
<dt id="disconnect">
<code class="descname">disconnect</code><span class="sig-paren">(</span><span class="optional">[</span><em>slot</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#disconnect" title="Permalink to this definition">¶</a></dt>
<dd><p>Disconnect one or more slots from a signal. An exception will be raised if
the slot is not connected to the signal or if the signal has no connections
at all.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>slot</strong> – the optional slot to disconnect from, either a Python callable or
another bound signal. If it is omitted then all slots connected to the
signal are disconnected.</td>
</tr>
</tbody>
</table>
</dd></dl>
<p>Signals are emitted from using the <a class="reference internal" href="#emit" title="emit"><code class="xref py py-meth docutils literal"><span class="pre">emit()</span></code></a> method of a bound signal.</p>
<dl class="method">
<dt id="emit">
<code class="descname">emit</code><span class="sig-paren">(</span><em>*args</em><span class="sig-paren">)</span><a class="headerlink" href="#emit" title="Permalink to this definition">¶</a></dt>
<dd><p>Emit a signal.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>args</strong> – the optional sequence of arguments to pass to any connected slots.</td>
</tr>
</tbody>
</table>
</dd></dl>
<p>The following code demonstrates the definition, connection and emit of a
signal without arguments:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PyQt4.QtCore</span> <span class="k">import</span> <span class="n">QObject</span><span class="p">,</span> <span class="n">pyqtSignal</span>
<span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="n">QObject</span><span class="p">):</span>
<span class="c1"># Define a new signal called 'trigger' that has no arguments.</span>
<span class="n">trigger</span> <span class="o">=</span> <span class="n">pyqtSignal</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">connect_and_emit_trigger</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># Connect the trigger signal to a slot.</span>
<span class="bp">self</span><span class="o">.</span><span class="n">trigger</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">handle_trigger</span><span class="p">)</span>
<span class="c1"># Emit the signal.</span>
<span class="bp">self</span><span class="o">.</span><span class="n">trigger</span><span class="o">.</span><span class="n">emit</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">handle_trigger</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># Show that the slot has been called.</span>
<span class="nb">print</span> <span class="s2">"trigger signal received"</span>
</pre></div>
</div>
<p>The following code demonstrates the connection of overloaded signals:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PyQt4.QtGui</span> <span class="k">import</span> <span class="n">QComboBox</span>
<span class="k">class</span> <span class="nc">Bar</span><span class="p">(</span><span class="n">QComboBox</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">connect_activated</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># The PyQt4 documentation will define what the default overload is.</span>
<span class="c1"># In this case it is the overload with the single integer argument.</span>
<span class="bp">self</span><span class="o">.</span><span class="n">activated</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">handle_int</span><span class="p">)</span>
<span class="c1"># For non-default overloads we have to specify which we want to</span>
<span class="c1"># connect. In this case the one with the single string argument.</span>
<span class="c1"># (Note that we could also explicitly specify the default if we</span>
<span class="c1"># wanted to.)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">activated</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">handle_string</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">handle_int</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">index</span><span class="p">):</span>
<span class="nb">print</span> <span class="s2">"activated signal passed integer"</span><span class="p">,</span> <span class="n">index</span>
<span class="k">def</span> <span class="nf">handle_string</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">text</span><span class="p">):</span>
<span class="nb">print</span> <span class="s2">"activated signal passed QString"</span><span class="p">,</span> <span class="n">text</span>
</pre></div>
</div>
</div>
<div class="section" id="connecting-signals-using-keyword-arguments">
<h2>Connecting Signals Using Keyword Arguments<a class="headerlink" href="#connecting-signals-using-keyword-arguments" title="Permalink to this headline">¶</a></h2>
<p>It is also possible to connect signals by passing a slot as a keyword argument
corresponding to the name of the signal when creating an object, or using the
<code class="docutils literal"><span class="pre">pyqtConfigure()</span></code> method of <code class="docutils literal"><span class="pre">QObject</span></code>. For example the following three
fragments are equivalent:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">act</span> <span class="o">=</span> <span class="n">QtGui</span><span class="o">.</span><span class="n">QAction</span><span class="p">(</span><span class="s2">"Action"</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span>
<span class="n">act</span><span class="o">.</span><span class="n">triggered</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">on_triggered</span><span class="p">)</span>
<span class="n">act</span> <span class="o">=</span> <span class="n">QtGui</span><span class="o">.</span><span class="n">QAction</span><span class="p">(</span><span class="s2">"Action"</span><span class="p">,</span> <span class="bp">self</span><span class="p">,</span> <span class="n">triggered</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">on_triggered</span><span class="p">)</span>
<span class="n">act</span> <span class="o">=</span> <span class="n">QtGui</span><span class="o">.</span><span class="n">QAction</span><span class="p">(</span><span class="s2">"Action"</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span>
<span class="n">act</span><span class="o">.</span><span class="n">pyqtConfigure</span><span class="p">(</span><span class="n">triggered</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">on_triggered</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="the-pyqtslot-decorator">
<h2>The <a class="reference internal" href="#PyQt4.QtCore.pyqtSlot" title="PyQt4.QtCore.pyqtSlot"><code class="xref py py-func docutils literal"><span class="pre">pyqtSlot()</span></code></a> Decorator<a class="headerlink" href="#the-pyqtslot-decorator" title="Permalink to this headline">¶</a></h2>
<p>Although PyQt4 allows any Python callable to be used as a slot when connecting
signals, it is sometimes necessary to explicitly mark a Python method as being
a Qt slot and to provide a C++ signature for it. PyQt4 provides the
<a class="reference internal" href="#PyQt4.QtCore.pyqtSlot" title="PyQt4.QtCore.pyqtSlot"><code class="xref py py-func docutils literal"><span class="pre">pyqtSlot()</span></code></a> function decorator to do this.</p>
<dl class="function">
<dt id="PyQt4.QtCore.pyqtSlot">
<code class="descclassname">PyQt4.QtCore.</code><code class="descname">pyqtSlot</code><span class="sig-paren">(</span><em>types</em><span class="optional">[</span>, <em>name</em><span class="optional">[</span>, <em>result</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#PyQt4.QtCore.pyqtSlot" title="Permalink to this definition">¶</a></dt>
<dd><p>Decorate a Python method to create a Qt slot.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>types</strong> – the types that define the C++ signature of the slot. Each type may be
a Python type object or a string that is the name of a C++ type.</li>
<li><strong>name</strong> – the name of the slot that will be seen by C++. If omitted the name of
the Python method being decorated will be used. This may only be given
as a keyword argument.</li>
<li><strong>result</strong> – the type of the result and may be a Python type object or a string that
specifies a C++ type. This may only be given as a keyword argument.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<p>Connecting a signal to a decorated Python method also has the advantage of
reducing the amount of memory used and is slightly faster.</p>
<p>For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PyQt4.QtCore</span> <span class="k">import</span> <span class="n">QObject</span><span class="p">,</span> <span class="n">pyqtSlot</span>
<span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="n">QObject</span><span class="p">):</span>
<span class="nd">@pyqtSlot</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">""" C++: void foo() """</span>
<span class="nd">@pyqtSlot</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg1</span><span class="p">,</span> <span class="n">arg2</span><span class="p">):</span>
<span class="sd">""" C++: void foo(int, QString) """</span>
<span class="nd">@pyqtSlot</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg1</span><span class="p">):</span>
<span class="sd">""" C++: void bar(int) """</span>
<span class="nd">@pyqtSlot</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">result</span><span class="o">=</span><span class="nb">int</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg1</span><span class="p">):</span>
<span class="sd">""" C++: int foo(int) """</span>
<span class="nd">@pyqtSlot</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">QObject</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg1</span><span class="p">):</span>
<span class="sd">""" C++: int foo(int, QObject *) """</span>
</pre></div>
</div>
<p>It is also possible to chain the decorators in order to define a Python method
several times with different signatures. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">PyQt4.QtCore</span> <span class="k">import</span> <span class="n">QObject</span><span class="p">,</span> <span class="n">pyqtSlot</span>
<span class="k">class</span> <span class="nc">Foo</span><span class="p">(</span><span class="n">QObject</span><span class="p">):</span>
<span class="nd">@pyqtSlot</span><span class="p">(</span><span class="nb">int</span><span class="p">)</span>
<span class="nd">@pyqtSlot</span><span class="p">(</span><span class="s1">'QString'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">valueChanged</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
<span class="sd">""" Two slots will be defined in the QMetaObject. """</span>
</pre></div>
</div>
</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">finished</span> <span class="o">=</span> <span class="n">pyqtSignal</span><span class="p">(</span><span class="s1">'PyQt_PyObject'</span><span class="p">)</span>
</pre></div>
</div>
<p>This would normally be used for passing objects where the actual Python type
isn’t known. It can also be used to pass an integer, for example, so 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">finished.emit()</span></code>, even if a connection is queued.</p>
</div>
<div class="section" id="connecting-slots-by-name">
<h2>Connecting Slots By Name<a class="headerlink" href="#connecting-slots-by-name" title="Permalink to this headline">¶</a></h2>
<p>PyQt4 supports the <code class="docutils literal"><span class="pre">QtCore.QMetaObject.connectSlotsByName()</span></code> function that
is most commonly used by <strong class="program">pyuic4</strong> generated Python code to
automatically connect signals to slots that conform to a simple naming
convention. However, where a class has overloaded Qt signals (ie. with the
same name but with different arguments) PyQt4 needs additional information in
order to automatically connect the correct signal.</p>
<p>For example the <code class="docutils literal"><span class="pre">QtGui.QSpinBox</span></code> class has the following signals:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">void</span> <span class="n">valueChanged</span><span class="p">(</span><span class="nb">int</span> <span class="n">i</span><span class="p">);</span>
<span class="n">void</span> <span class="n">valueChanged</span><span class="p">(</span><span class="n">const</span> <span class="n">QString</span> <span class="o">&</span><span class="n">text</span><span class="p">);</span>
</pre></div>
</div>
<p>When the value of the spin box changes both of these signals will be emitted.
If you have implemented a slot called <code class="docutils literal"><span class="pre">on_spinbox_valueChanged</span></code> (which
assumes that you have given the <code class="docutils literal"><span class="pre">QSpinBox</span></code> instance the name <code class="docutils literal"><span class="pre">spinbox</span></code>)
then it will be connected to both variations of the signal. Therefore, when
the user changes the value, your slot will be called twice - once with an
integer argument, and once with a unicode or <code class="docutils literal"><span class="pre">QString</span></code> argument.</p>
<p>This also happens with signals that take optional arguments. Qt implements
this using multiple signals. For example, <code class="docutils literal"><span class="pre">QtGui.QAbstractButton</span></code> has the
following signal:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">void</span> <span class="n">clicked</span><span class="p">(</span><span class="nb">bool</span> <span class="n">checked</span> <span class="o">=</span> <span class="n">false</span><span class="p">);</span>
</pre></div>
</div>
<p>Qt implements this as the following:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">void</span> <span class="n">clicked</span><span class="p">();</span>
<span class="n">void</span> <span class="n">clicked</span><span class="p">(</span><span class="nb">bool</span> <span class="n">checked</span><span class="p">);</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="#PyQt4.QtCore.pyqtSlot" title="PyQt4.QtCore.pyqtSlot"><code class="xref py py-func docutils literal"><span class="pre">pyqtSlot()</span></code></a> decorator can be used to specify which of
the signals should be connected to the slot.</p>
<p>For example, if you were only interested in the integer variant of the signal
then your slot definition would look like the following:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nd">@pyqtSlot</span><span class="p">(</span><span class="nb">int</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">on_spinbox_valueChanged</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">):</span>
<span class="c1"># i will be an integer.</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>If you wanted to handle both variants of the signal, but with different Python
methods, then your slot definitions might look like the following:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nd">@pyqtSlot</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">'on_spinbox_valueChanged'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">spinbox_int_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">):</span>
<span class="c1"># i will be an integer.</span>
<span class="k">pass</span>
<span class="nd">@pyqtSlot</span><span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s1">'on_spinbox_valueChanged'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">spinbox_qstring_value</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">s</span><span class="p">):</span>
<span class="c1"># s will be a Python string object (or a QString if they are enabled).</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>The following shows an example using a button when you are not interested in
the optional argument:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nd">@pyqtSlot</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">on_button_clicked</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">pass</span>
</pre></div>
</div>
</div>
<div class="section" id="mixing-new-style-and-old-style-connections">
<h2>Mixing New-style and Old-style Connections<a class="headerlink" href="#mixing-new-style-and-old-style-connections" title="Permalink to this headline">¶</a></h2>
<p>The implementation of new-style connections is slightly different to the
implementation of old-style connections. An application can freely use both
styles subject to the restriction that any individual new-style connection
should only be disconnected using the new style. Similarly any individual
old-style connection should only be disconnected using the old style.</p>
<p>You should also be aware that <strong class="program">pyuic4</strong> generates code that uses
old-style connections.</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="#">New-style Signal and Slot Support</a><ul>
<li><a class="reference internal" href="#unbound-and-bound-signals">Unbound and Bound Signals</a></li>
<li><a class="reference internal" href="#defining-new-signals-with-pyqtsignal">Defining New Signals with <code class="docutils literal"><span class="pre">pyqtSignal()</span></code></a></li>
<li><a class="reference internal" href="#connecting-disconnecting-and-emitting-signals">Connecting, Disconnecting and Emitting Signals</a></li>
<li><a class="reference internal" href="#connecting-signals-using-keyword-arguments">Connecting Signals Using Keyword Arguments</a></li>
<li><a class="reference internal" href="#the-pyqtslot-decorator">The <code class="docutils literal"><span class="pre">pyqtSlot()</span></code> Decorator</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="#connecting-slots-by-name">Connecting Slots By Name</a></li>
<li><a class="reference internal" href="#mixing-new-style-and-old-style-connections">Mixing New-style and Old-style Connections</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="qt_properties.html"
title="previous chapter">Support for Qt Properties</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="old_style_signals_slots.html"
title="next chapter">Old-style Signal and Slot Support</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="old_style_signals_slots.html" title="Old-style Signal and Slot Support"
>next</a> |</li>
<li class="right" >
<a href="qt_properties.html" title="Support for Qt Properties"
>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>
|
