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
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
|
<?xml version="1.0" encoding="utf-8" ?>
<!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" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
<title>PyQt v4 - Python Bindings for Qt v4</title>
<meta name="copyright" content="Copyright (c) 2006 Riverbank Computing Limited" />
<link rel="stylesheet" href="default.css" type="text/css" />
</head>
<body>
<div class="document" id="pyqt-v4-python-bindings-for-qt-v4">
<h1 class="title">PyQt v4 - Python Bindings for Qt v4</h1>
<h2 class="subtitle" id="reference-guide">Reference Guide</h2>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference" href="mailto:info@riverbankcomputing.co.uk">info@riverbankcomputing.co.uk</a></td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>4.0.1</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>Copyright (c) 2006 Riverbank Computing Limited</td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#introduction" id="id1" name="id1">1 Introduction</a><ul class="auto-toc">
<li><a class="reference" href="#license" id="id2" name="id2">1.1 License</a></li>
<li><a class="reference" href="#pyqt-components" id="id3" name="id3">1.2 PyQt Components</a></li>
</ul>
</li>
<li><a class="reference" href="#installing-pyqt" id="id4" name="id4">2 Installing PyQt</a><ul class="auto-toc">
<li><a class="reference" href="#downloading-sip" id="id5" name="id5">2.1 Downloading SIP</a></li>
<li><a class="reference" href="#downloading-pyqt" id="id6" name="id6">2.2 Downloading PyQt</a></li>
<li><a class="reference" href="#configuring-pyqt" id="id7" name="id7">2.3 Configuring PyQt</a></li>
<li><a class="reference" href="#building-pyqt" id="id8" name="id8">2.4 Building PyQt</a></li>
</ul>
</li>
<li><a class="reference" href="#signal-and-slot-support" id="id9" name="id9">3 Signal and Slot Support</a><ul class="auto-toc">
<li><a class="reference" href="#pyqt-signals-and-qt-signals" id="id10" name="id10">3.1 PyQt Signals and Qt Signals</a></li>
<li><a class="reference" href="#short-circuit-signals" id="id11" name="id11">3.2 Short-circuit Signals</a></li>
<li><a class="reference" href="#pyqt-slots-and-qt-slots" id="id12" name="id12">3.3 PyQt Slots and Qt Slots</a></li>
<li><a class="reference" href="#connecting-signals-and-slots" id="id13" name="id13">3.4 Connecting Signals and Slots</a></li>
<li><a class="reference" href="#emitting-signals" id="id14" name="id14">3.5 Emitting Signals</a></li>
<li><a class="reference" href="#the-qtcore-pyqtsignature-decorator" id="id15" name="id15">3.6 The <tt class="docutils literal"><span class="pre">QtCore.pyqtSignature()</span></tt> Decorator</a></li>
</ul>
</li>
<li><a class="reference" href="#using-qt-designer" id="id16" name="id16">4 Using Qt Designer</a><ul class="auto-toc">
<li><a class="reference" href="#using-the-generated-code" id="id17" name="id17">4.1 Using the Generated Code</a></li>
<li><a class="reference" href="#the-uic-module" id="id18" name="id18">4.2 The <tt class="docutils literal"><span class="pre">uic</span></tt> Module</a></li>
<li><a class="reference" href="#pyuic4" id="id19" name="id19">4.3 pyuic4</a></li>
</ul>
</li>
<li><a class="reference" href="#the-pyqt-resource-system" id="id20" name="id20">5 The PyQt Resource System</a><ul class="auto-toc">
<li><a class="reference" href="#pyrcc4" id="id21" name="id21">5.1 pyrcc4</a></li>
</ul>
</li>
<li><a class="reference" href="#internationalisation-of-pyqt-applications" id="id22" name="id22">6 Internationalisation of PyQt Applications</a><ul class="auto-toc">
<li><a class="reference" href="#pylupdate4" id="id23" name="id23">6.1 pylupdate4</a></li>
<li><a class="reference" href="#differences-between-pyqt-and-qt" id="id24" name="id24">6.2 Differences Between PyQt and Qt</a></li>
</ul>
</li>
<li><a class="reference" href="#things-to-be-aware-of" id="id25" name="id25">7 Things to be Aware Of</a><ul class="auto-toc">
<li><a class="reference" href="#python-strings-qt-strings-and-unicode" id="id26" name="id26">7.1 Python Strings, Qt Strings and Unicode</a></li>
<li><a class="reference" href="#garbage-collection" id="id27" name="id27">7.2 Garbage Collection</a></li>
<li><a class="reference" href="#multiple-inheritance" id="id28" name="id28">7.3 Multiple Inheritance</a></li>
<li><a class="reference" href="#access-to-protected-member-functions" id="id29" name="id29">7.4 Access to Protected Member Functions</a></li>
<li><a class="reference" href="#none-and-null" id="id30" name="id30">7.5 <tt class="docutils literal"><span class="pre">None</span></tt> and <tt class="docutils literal"><span class="pre">NULL</span></tt></a></li>
<li><a class="reference" href="#support-for-void" id="id31" name="id31">7.6 Support for <tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt></a></li>
<li><a class="reference" href="#super-and-pyqt-classes" id="id32" name="id32">7.7 <tt class="docutils literal"><span class="pre">super</span></tt> and PyQt Classes</a></li>
</ul>
</li>
<li><a class="reference" href="#deploying-commercial-pyqt-applications" id="id33" name="id33">8 Deploying Commercial PyQt Applications</a></li>
<li><a class="reference" href="#the-pyqt-build-system" id="id34" name="id34">9 The PyQt Build System</a><ul class="auto-toc">
<li><a class="reference" href="#pyqtconfig-classes" id="id35" name="id35">9.1 <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt> Classes</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id1" name="introduction">1 Introduction</a></h1>
<p>This is the reference guide for PyQt 4.0.1. PyQt v4 is a set of
<a class="reference" href="http://www.python.org">Python</a> bindings for v4 of the Qt application
framework from <a class="reference" href="http://www.trolltech.com">Trolltech</a>.</p>
<p>There is a separate <a class="reference" href="html/classes.html">PyQt API Reference</a>.</p>
<p>Qt is a set of C++ libraries and development tools that includes platform
independent abstractions for graphical user interfaces, networking, threads,
Unicode, regular expressions, SQL databases, SVG, OpenGL, XML, and user and
application settings. PyQt implements 440 of these classes as a set of
Python modules.</p>
<p>PyQt supports the Windows, Linux, UNIX and MacOS/X platforms.</p>
<p>PyQt does not include Qt itself - you must obtain it separately.</p>
<p>The homepage for PyQt is <a class="reference" href="http://www.riverbankcomputing.co.uk/pyqt/">http://www.riverbankcomputing.co.uk/pyqt/</a>. Here you
will always find the latest stable version, current development snapshots, and
the latest version of this documentation.</p>
<p>PyQt is built using the <a class="reference" href="http://www.riverbankcomputing.co.uk/sip/">SIP bindings generator</a>. SIP must be installed in order
to build and use PyQt.</p>
<p>Earlier versions of Qt are supported by PyQt v3.</p>
<div class="section" id="license">
<h2><a class="toc-backref" href="#id2" name="license">1.1 License</a></h2>
<p>Like Qt v4, PyQt is licensed on all platforms under a commercial license and
the GPL v2. Your PyQt license must be the same as your Qt license, ie. use
either the commercial versions of both or the GPL versions of both. If you
use the GPL versions then your own code must also be licensed under the GPL.</p>
<p>You can purchase a commercial PyQt license <a class="reference" href="http://www.riverbankcomputing.co.uk/pyqt/buy.php">here</a>.</p>
</div>
<div class="section" id="pyqt-components">
<h2><a class="toc-backref" href="#id3" name="pyqt-components">1.2 PyQt Components</a></h2>
<p>PyQt comprises a number of different components. First of all there are a
number of Python extension modules. These are all installed in the <tt class="docutils literal"><span class="pre">PyQt4</span></tt>
Python package.</p>
<blockquote>
<ul class="simple">
<li>The <tt class="docutils literal"><span class="pre">QtCore</span></tt> module. This contains the core non-GUI classes, including
the event loop and Qt's signal and slot mechanism. It also includes
platform independent abstractions for Unicode, threads, regular
expressions, and user and application settings.</li>
<li>The <tt class="docutils literal"><span class="pre">QtGui</span></tt> module. This contains the majority of the GUI classes.</li>
<li>The <tt class="docutils literal"><span class="pre">QtNetwork</span></tt> module. This module contains classes for writing UDP
and TCP clients and servers. It includes classes that implement FTP and
HTTP clients and support DNS lookups.</li>
<li>The <tt class="docutils literal"><span class="pre">QtOpenGL</span></tt> module. This module contains classes that enable the
use of OpenGL in rendering 3D graphics in PyQt applications.</li>
<li>The <tt class="docutils literal"><span class="pre">QtSql</span></tt> module. This module contains classes that integrate with
SQL databases. It includes editable data models for database tables that
can be used with GUI classes. It also includes an implementation of
<a class="reference" href="http://www.sqlite.org">SQLite</a>.</li>
<li>The <tt class="docutils literal"><span class="pre">QtSvg</span></tt> module. This module contains classes for displaying the
contents of SVG files.</li>
<li>The <tt class="docutils literal"><span class="pre">QtXml</span></tt> module. This module contains classes that implement SAX
and DOM interfaces to Qt's XML parser.</li>
<li>The <tt class="docutils literal"><span class="pre">QtAssistant</span></tt> module. This module contains classes that allow Qt
Assistant to be integrated with a PyQt application to provide online
help.</li>
<li>The <tt class="docutils literal"><span class="pre">Qt</span></tt> module. This module consolidates the classes contained in all
of the modules described above into a single module. This has the
advantage that you don't have to worry about which underlying module
contains a particular class. It has the disadvantage that it loads the
whole of the Qt framework, thereby increasing the memory footprint of an
application. Whether you use this consolidated module, or the individual
component modules is down to personal taste.</li>
<li>The <tt class="docutils literal"><span class="pre">uic</span></tt> module. This module contains classes for handling the
<tt class="docutils literal"><span class="pre">.ui</span></tt> files created by Qt Designer that describe the whole or part of a
graphical user interface. It includes classes that load a <tt class="docutils literal"><span class="pre">.ui</span></tt> file
and render it directly, and classes that generate Python code from a
<tt class="docutils literal"><span class="pre">.ui</span></tt> file for later execution. It is covered in detail in <a class="reference" href="#the-uic-module">The uic
Module</a>.</li>
<li>The <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt> module is an extention of the SIP build system and is
created when PyQt is configured. It encapsulates all the necessary
information about your Qt installation and makes it easier to write
installation scripts for bindings built on top of PyQt. It is covered
in detail in <a class="reference" href="#the-pyqt-build-system">The PyQt Build System</a>.</li>
</ul>
</blockquote>
<p>PyQt also contains a number of utility programs.</p>
<blockquote>
<ul class="simple">
<li><a class="reference" href="#pyuic4">pyuic4</a> corresponds to the Qt <tt class="docutils literal"><span class="pre">uic</span></tt> utility. It converts GUIs
created using Qt Designer to Python code. It is covered in detail in
<a class="reference" href="#pyuic4">pyuic4</a>.</li>
<li><a class="reference" href="#pyrcc4">pyrcc4</a> corresponds to the Qt <tt class="docutils literal"><span class="pre">rcc</span></tt> utility. It embeds arbitrary
resources (eg. icons, images, translation files) described by a resource
collection file in a Python module. It is covered in detail in
<a class="reference" href="#pyrcc4">pyrcc4</a>. (<em>Note</em> It will only be included if your copy of Qt includes
the XML module.)</li>
<li><a class="reference" href="#pylupdate4">pylupdate4</a> corresponds to the Qt <tt class="docutils literal"><span class="pre">lupdate</span></tt> utility. It extracts
all of the translatable strings from Python code and creates or updates
<tt class="docutils literal"><span class="pre">.ts</span></tt> translation files. These are then used by Qt Linguist to manage
the translation of those strings. It is covered in detail in
<a class="reference" href="#pylupdate4">pylupdate4</a>. (<em>Note</em> It will only be included if your copy of Qt
includes the XML module.)</li>
</ul>
</blockquote>
<p>PyQt includes a large number of examples. These are ports to Python of many
of the C++ examples provided with Qt. They can be found in the <tt class="docutils literal"><span class="pre">examples</span></tt>
directory.</p>
<p>Finally, PyQt contains the <tt class="docutils literal"><span class="pre">.sip</span></tt> files used by SIP to generate PyQt
itself. These can be used by developers of bindings of other Qt based class
libraries - for example <a class="reference" href="http://pyqwt.sourceforge.net/">PyQwt and PyQwt3D</a>.</p>
</div>
</div>
<div class="section" id="installing-pyqt">
<h1><a class="toc-backref" href="#id4" name="installing-pyqt">2 Installing PyQt</a></h1>
<div class="section" id="downloading-sip">
<h2><a class="toc-backref" href="#id5" name="downloading-sip">2.1 Downloading SIP</a></h2>
<p>SIP must be installed before building and using PyQt. You can get the latest
release of the SIP source code from
<a class="reference" href="http://www.riverbankcomputing.co.uk/sip/download.php">http://www.riverbankcomputing.co.uk/sip/download.php</a>.</p>
<p>The SIP documentation can be found at
<a class="reference" href="http://www.riverbankcomputing.com/Docs/sip4/sipref.html">http://www.riverbankcomputing.com/Docs/sip4/sipref.html</a>.</p>
</div>
<div class="section" id="downloading-pyqt">
<h2><a class="toc-backref" href="#id6" name="downloading-pyqt">2.2 Downloading PyQt</a></h2>
<p>You can get the latest release of the GPL version of the PyQt source code from
<a class="reference" href="http://www.riverbankcomputing.co.uk/pyqt/download.php">http://www.riverbankcomputing.co.uk/pyqt/download.php</a>.</p>
<p>If you are using the commercial version of PyQt then you should use the
download instructions which were sent to you when you made your purchase. You
must also download your license file.</p>
</div>
<div class="section" id="configuring-pyqt">
<h2><a class="toc-backref" href="#id7" name="configuring-pyqt">2.3 Configuring PyQt</a></h2>
<p>After unpacking the source package (either a <tt class="docutils literal"><span class="pre">.tar.gz</span></tt> or a <tt class="docutils literal"><span class="pre">.zip</span></tt> file
depending on your platform) you should then check for any <tt class="docutils literal"><span class="pre">README</span></tt> files
that relate to your platform.</p>
<p>If you are using the commercial version of PyQt then you must copy your
license file to the <tt class="docutils literal"><span class="pre">sip</span></tt> directory.</p>
<p>You need to make sure your environment variables are set properly for your
development environment. For example, if you are using a binary distribution
of Qt on Windows then make sure you have run the <tt class="docutils literal"><span class="pre">qtvars.bat</span></tt> file. For
other platforms it is normally enough to ensure that Qt's <tt class="docutils literal"><span class="pre">bin</span></tt> directory is
on your <tt class="docutils literal"><span class="pre">PATH</span></tt>.</p>
<p>Next you need to configure SIP by executing the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script. For
example:</p>
<pre class="literal-block">
python configure.py
</pre>
<p>This assumes that the Python interpreter is on your path. Something like the
following may be appropriate on Windows:</p>
<pre class="literal-block">
c:\python24\python configure.py
</pre>
<p>If you have multiple versions of Python installed then make sure you use the
interpreter for which you wish to build PyQt for.</p>
<p>The full set of command line options is:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td>
<kbd><span class="option">-h</span></kbd></td>
<td>Display a help message.</td></tr>
<tr><td>
<kbd><span class="option">-b</span> <var>dir</var></kbd></td>
<td>The <tt class="docutils literal"><span class="pre">pyuic4</span></tt>, <tt class="docutils literal"><span class="pre">pyrcc4</span></tt> and <tt class="docutils literal"><span class="pre">pylupdate4</span></tt> utilities will be
installed in the directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr>
<tr><td>
<kbd><span class="option">-c</span></kbd></td>
<td>The C++ source files for a Python module will be concatenated. This
results in significantly reduced compilation times. Most, but not
all, C++ compilers can handle the large files that result. It is
recommended that you use this option if you are using GCC v3.x or
MSVC v7.x. See also the <tt class="docutils literal"><span class="pre">-j</span></tt> option.</td></tr>
<tr><td>
<kbd><span class="option">-d</span> <var>dir</var></kbd></td>
<td>The PyQt modules will be installed in the directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr>
<tr><td>
<kbd><span class="option">-i</span></kbd></td>
<td>The checking of signed Python interpreters using the <a class="reference" href="http://www.riverbankcomputing.co.uk/vendorid/">VendorID
package</a> is
enabled. See also the <tt class="docutils literal"><span class="pre">-l</span></tt> and <tt class="docutils literal"><span class="pre">-m</span></tt> options and <a class="reference" href="#deploying-commercial-pyqt-applications">Deploying
Commercial PyQt Applications</a>.</td></tr>
<tr><td>
<kbd><span class="option">-j</span> <var>n</var></kbd></td>
<td>If the <tt class="docutils literal"><span class="pre">-c</span></tt> option is used to concatenate the C++ source files then
this option determines how many files are created. The default is 1.</td></tr>
<tr><td>
<kbd><span class="option">-k</span></kbd></td>
<td>The PyQt modules will be built as static libraries. This is useful
when building a custom interpreter with the PyQt modules built in to
interpreter.</td></tr>
<tr><td>
<kbd><span class="option">-l</span> <var>dir</var></kbd></td>
<td>The header file of the VendorID package can be found in the directory
<tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr>
<tr><td>
<kbd><span class="option">-m</span> <var>dir</var></kbd></td>
<td>The library of the VendorID package can be found in the directory
<tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr>
<tr><td>
<kbd><span class="option">-q</span> <var>exe</var></kbd></td>
<td>Qt's <tt class="docutils literal"><span class="pre">qmake</span></tt> program is used to determine how your Qt installation
is laid out. Normally <tt class="docutils literal"><span class="pre">qmake</span></tt> is found on your <tt class="docutils literal"><span class="pre">PATH</span></tt>. This
option can be used to specify a particular instance of <tt class="docutils literal"><span class="pre">qmake</span></tt> to
use.</td></tr>
<tr><td>
<kbd><span class="option">-r</span></kbd></td>
<td>The generated PyQt modules contain additional tracing code that is
enabled using SIP's <tt class="docutils literal"><span class="pre">sip.settracemask()</span></tt> function.</td></tr>
<tr><td>
<kbd><span class="option">-u</span></kbd></td>
<td>The PyQt modules will be built with debugging symbols. On Windows
this requires that a debug version of Python is installed.</td></tr>
<tr><td>
<kbd><span class="option">-v</span> <var>dir</var></kbd></td>
<td>The <tt class="docutils literal"><span class="pre">.sip</span></tt> files for the PyQt modules will be installed in the
directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr>
<tr><td>
<kbd><span class="option">-w</span></kbd></td>
<td>Compiler commands and any output issued during configuration is
displayed instead of being suppressed. Use this if <tt class="docutils literal"><span class="pre">configure.py</span></tt>
is having problems to see what exactly is going wrong.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="building-pyqt">
<h2><a class="toc-backref" href="#id8" name="building-pyqt">2.4 Building PyQt</a></h2>
<p>The next step is to build PyQt by running your platform's <tt class="docutils literal"><span class="pre">make</span></tt> command.
For example:</p>
<pre class="literal-block">
make
</pre>
<p>The final step is to install PyQt by running the following command:</p>
<pre class="literal-block">
make install
</pre>
<p>(Depending on your system you may require root or administrator privileges.)</p>
<p>This will install the various PyQt components.</p>
</div>
</div>
<div class="section" id="signal-and-slot-support">
<h1><a class="toc-backref" href="#id9" name="signal-and-slot-support">3 Signal and Slot Support</a></h1>
<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 a particular event occurs. A slot is a function (in
PyQt a slot is any Python callable). If a signal is connected to a slot
(using the <tt class="docutils literal"><span class="pre">QtCore.QObject.connect()</span></tt> method) 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>A signal may be connected to many slots.</p>
<p>A signal may also be connected to another signal.</p>
<p>A slot may be connected to many signals.</p>
<p>In PyQt signals are emitted using the <tt class="docutils literal"><span class="pre">QtCore.QObject.emit()</span></tt> method.</p>
<p>Connections may be direct (ie. synchronous) or queued (ie. asynchronous).</p>
<p>Connections may be made across threads.</p>
<p>Signals are disconnected using the <tt class="docutils literal"><span class="pre">QtCore.QObject.disconnect()</span></tt> method.</p>
<div class="section" id="pyqt-signals-and-qt-signals">
<h2><a class="toc-backref" href="#id10" name="pyqt-signals-and-qt-signals">3.1 PyQt Signals and Qt Signals</a></h2>
<p>Qt signals are statically defined as part of a C++ class. They are referenced
using the <tt class="docutils literal"><span class="pre">QtCore.SIGNAL()</span></tt> function. This method takes a single string
argument that is the name of the signal and its C++ signature. For example:</p>
<pre class="literal-block">
QtCore.SIGNAL("finished(int)")
</pre>
<p>The returned value is normally passed to the <tt class="docutils literal"><span class="pre">QtCore.QObject.connect()</span></tt>
method.</p>
<p>PyQt allows new signals to be defined dynamically. The act of emitting a
PyQt signal implicitly defines it. PyQt v4 signals are also referenced using
the <tt class="docutils literal"><span class="pre">QtCore.SIGNAL()</span></tt> function.</p>
</div>
<div class="section" id="short-circuit-signals">
<h2><a class="toc-backref" href="#id11" name="short-circuit-signals">3.2 Short-circuit Signals</a></h2>
<p>There is also a special form of PyQt v4 signal known as a short-circuit signal.
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>
<p>Short-circuit signals do not have a list of arguments or the surrounding
parentheses. Their advantage is that they are very efficient as the arguments
are passed as Python arguments without any conversions to C++ data types and
back again.</p>
</div>
<div class="section" id="pyqt-slots-and-qt-slots">
<h2><a class="toc-backref" href="#id12" name="pyqt-slots-and-qt-slots">3.3 PyQt Slots and Qt Slots</a></h2>
<p>Qt slots are statically defined as part of a C++ class. They are referenced
using the <tt class="docutils literal"><span class="pre">QtCore.SLOT()</span></tt> function. This method takes a single string
argument that is the name of the slot and its C++ signature. For example:</p>
<pre class="literal-block">
QtCore.SLOT("done(int)")
</pre>
<p>The returned value is normally passed to the <tt class="docutils literal"><span class="pre">QtCore.QObject.connect()</span></tt>
method.</p>
<p>PyQt 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
never actually necessary to use <tt class="docutils literal"><span class="pre">QtCore.SLOT()</span></tt> for Qt slots. However, doing
so is more efficient as signal delivery happens at the C++ level and 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. PyQt 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, it also
means that using lambda expressions as slots will not work unless you keep a
separate reference to the expression to prevent it from being immediately
garbage collected.</p>
</div>
<div class="section" id="connecting-signals-and-slots">
<h2><a class="toc-backref" href="#id13" name="connecting-signals-and-slots">3.4 Connecting Signals and Slots</a></h2>
<p>Connections between signals and slots (and other signals) are made using the
<tt class="docutils literal"><span class="pre">QtCore.QObject.connect()</span></tt> method. For example:</p>
<pre class="literal-block">
QtCore.QObject.connect(a, QtCore.SIGNAL("QtSig()"), pyFunction)
QtCore.QObject.connect(a, QtCore.SIGNAL("QtSig()"), pyClass.pyMethod)
QtCore.QObject.connect(a, QtCore.SIGNAL("QtSig()"), QtCore.SLOT("QtSlot()"))
QtCore.QObject.connect(a, QtCore.SIGNAL("PySig()"), QtCore.SLOT("QtSlot()"))
QtCore.QObject.connect(a, QtCore.SIGNAL("PySig"), pyFunction)
</pre>
<p>Disconnecting signals works in exactly the same way using the
<tt class="docutils literal"><span class="pre">QtCore.QObject.disconnect()</span></tt> method. However, not all the variations of
that method are supported by PyQt. Signals must be disconnected one at a
time.</p>
</div>
<div class="section" id="emitting-signals">
<h2><a class="toc-backref" href="#id14" name="emitting-signals">3.5 Emitting Signals</a></h2>
<p>Any instance of a class that is derived from the <tt class="docutils literal"><span class="pre">QtCore.QObject</span></tt> class can
emit a signal using its <tt class="docutils literal"><span class="pre">emit()</span></tt> 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>
<pre class="literal-block">
a.emit(QtCore.SIGNAL("clicked()"))
a.emit(QtCore.SIGNAL("pySig"), "Hello", "World")
</pre>
</div>
<div class="section" id="the-qtcore-pyqtsignature-decorator">
<h2><a class="toc-backref" href="#id15" name="the-qtcore-pyqtsignature-decorator">3.6 The <tt class="docutils literal"><span class="pre">QtCore.pyqtSignature()</span></tt> Decorator</a></h2>
<p>PyQt supports the <tt class="docutils literal"><span class="pre">QtCore.QMetaObject.connectSlotsByName()</span></tt> function that
is most commonly used by <a class="reference" href="#pyuic4">pyuic4</a> 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) PyQt needs additional information in order to
automatically connect the correct signal.</p>
<p>For example the <tt class="docutils literal"><span class="pre">QtGui.QSpinBox</span></tt> class has the following signals:</p>
<pre class="literal-block">
void valueChanged(int i);
void valueChanged(const QString &text);
</pre>
<p>When the value of the spin box changes both of these signals will be emitted.
If you have implemented a slot called <tt class="docutils literal"><span class="pre">on_spinbox_valueChanged</span></tt> (which
assumes that you have given the <tt class="docutils literal"><span class="pre">QSpinBox</span></tt> instance the name <tt class="docutils literal"><span class="pre">spinbox</span></tt>)
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 <tt class="docutils literal"><span class="pre">QString</span></tt> argument.</p>
<p>This also happens with signals that take optional arguments. Qt implements
this using multiple signals. For example, <tt class="docutils literal"><span class="pre">QtGui.QAbstractButton</span></tt> has the
following signal:</p>
<pre class="literal-block">
void clicked(bool checked = false);
</pre>
<p>Qt implements this as the following:</p>
<pre class="literal-block">
void clicked();
void clicked(bool checked);
</pre>
<p>PyQt includes a Python function decorator that can be used to specify which of
the signals should be connected to the slot. The decorator takes a string
containing the required signal's signature, excluding the parentheses. If you
were only interested in the integer variant of the signal then your slot
definition would look like the following:</p>
<pre class="literal-block">
@QtCore.pyqtSignature("int")
def on_spinbox_valueChanged(self, i):
# i will be an integer.
pass
</pre>
<p>The following shows an example using a button when you are not interested in
the optional argument:</p>
<pre class="literal-block">
@QtCore.pyqtSignature("")
def on_button_clicked(self):
pass
</pre>
</div>
</div>
<div class="section" id="using-qt-designer">
<h1><a class="toc-backref" href="#id16" name="using-qt-designer">4 Using Qt Designer</a></h1>
<p>Qt Designer is the Qt tool for designing and building graphical user
interfaces. It allows you to design widgets, dialogs or complete main windows
using on-screen forms and a simple drag-and-drop interface. It has the ability
to preview your designs to ensure they work as you intended, and to allow you
to prototype them with your users, before you have to write any code.</p>
<p>Qt Designer uses XML <tt class="docutils literal"><span class="pre">.ui</span></tt> files to store designs and does not generate any
code itself. Qt includes the <tt class="docutils literal"><span class="pre">uic</span></tt> utility that generates the C++ code that
creates the user interface. Qt also includes the <tt class="docutils literal"><span class="pre">QUiLoader</span></tt> class that
allows an application to load a <tt class="docutils literal"><span class="pre">.ui</span></tt> file and to create the corresponding
user interface dynamically.</p>
<p>PyQt does not wrap the <tt class="docutils literal"><span class="pre">QUiLoader</span></tt> class but instead includes the <tt class="docutils literal"><span class="pre">uic</span></tt>
Python module. Like <tt class="docutils literal"><span class="pre">QUiLoader</span></tt> this module can load <tt class="docutils literal"><span class="pre">.ui</span></tt> files to create
a user interface dynamically. Like the <tt class="docutils literal"><span class="pre">uic</span></tt> utility it can also generate
the Python code that will create the user interface. PyQt's <tt class="docutils literal"><span class="pre">pyuic4</span></tt>
utility is a command line interface to the <tt class="docutils literal"><span class="pre">uic</span></tt> module. Both are described
in detail in the following sections.</p>
<div class="section" id="using-the-generated-code">
<h2><a class="toc-backref" href="#id17" name="using-the-generated-code">4.1 Using the Generated Code</a></h2>
<p>The code that is generated has an identical structure to that generated by Qt's
<tt class="docutils literal"><span class="pre">uic</span></tt> and can be used in the same way.</p>
<p>The code is structured as a single class that is derived from the Python
<tt class="docutils literal"><span class="pre">object</span></tt> type. The name of the class is the name of the toplevel object set
in Designer with <tt class="docutils literal"><span class="pre">Ui_</span></tt> prepended. (In the C++ version the class is defined
in the <tt class="docutils literal"><span class="pre">Ui</span></tt> namespace.) We refer to this class as the <em>form class</em>.</p>
<p>The class contains a method called <tt class="docutils literal"><span class="pre">setupUi()</span></tt>. This takes a single argument
which is the widget in which the user interface is created. The type of this
argument (typically <tt class="docutils literal"><span class="pre">QDialog</span></tt>, <tt class="docutils literal"><span class="pre">QWidget</span></tt> or <tt class="docutils literal"><span class="pre">QMainWindow</span></tt>) is set in
Designer. We refer to this type as the <em>Qt base class</em>.</p>
<p>In the following examples we assume that a <tt class="docutils literal"><span class="pre">.ui</span></tt> file has been created
containing a dialog and the name of the <tt class="docutils literal"><span class="pre">QDialog</span></tt> object is <tt class="docutils literal"><span class="pre">ImageDialog</span></tt>.
We also assume that the name of the file containing the generated Python code
is <tt class="docutils literal"><span class="pre">ui_imagedialog.py</span></tt>. The generated code can then be used in a number of
ways.</p>
<p>The first example shows the direct approach where we simply create a simple
application to create the dialog:</p>
<pre class="literal-block">
import sys
from PyQt4 import QtGui
from ui_imagedialog import Ui_ImageDialog
app = QtGui.QApplication(sys.argv)
window = QtGui.QDialog()
ui = Ui_ImageDialog()
ui.setupUi(window)
window.show()
sys.exit(app.exec_())
</pre>
<p>The second example shows the single inheritance approach where we sub-class
<tt class="docutils literal"><span class="pre">QDialog</span></tt> and set up the user interface in the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method:</p>
<pre class="literal-block">
from PyQt4 import QtCore, QtGui
from ui_imagedialog import Ui_ImageDialog
class ImageDialog(QtGui.QDialog):
def __init__(self):
QtGui.QDialog.__init__(self)
# Set up the user interface from Designer.
self.ui = Ui_ImageDialog()
self.ui.setupUi(self)
# Make some local modifications.
self.ui.colorDepthCombo.addItem("2 colors (1 bit per pixel)")
# Connect up the buttons.
self.connect(self.ui.okButton, QtCore.SIGNAL("clicked()"),
self, QtCore.SLOT("accept()"))
self.connect(self.ui.cancelButton, QtCore.SIGNAL("clicked()"),
self, QtCore.SLOT("reject()"))
</pre>
<p>The third example shows the multiple inheritance approach:</p>
<pre class="literal-block">
from PyQt4 import QtCore, QtGui
from ui_imagedialog import Ui_ImageDialog
class ImageDialog(QtGui.QDialog, Ui_ImageDialog):
def __init__(self):
QtGui.QDialog.__init__(self)
# Set up the user interface from Designer.
self.setupUi(self)
# Make some local modifications.
self.colorDepthCombo.addItem("2 colors (1 bit per pixel)")
# Connect up the buttons.
self.connect(self.okButton, QtCore.SIGNAL("clicked()"),
self, QtCore.SLOT("accept()"))
self.connect(self.cancelButton, QtCore.SIGNAL("clicked()"),
self, QtCore.SLOT("reject()"))
</pre>
<p>For a full description see the Qt Designer Manual in the Qt Documentation.</p>
</div>
<div class="section" id="the-uic-module">
<h2><a class="toc-backref" href="#id18" name="the-uic-module">4.2 The <tt class="docutils literal"><span class="pre">uic</span></tt> Module</a></h2>
<p>The <tt class="docutils literal"><span class="pre">uic</span></tt> module contains the following functions.</p>
<dl class="docutils">
<dt>compileUi(uifile, pyfile, execute=False, indent=4)</dt>
<dd><p class="first">This function generates the Python code that will create a user interface
from a Qt Designer <tt class="docutils literal"><span class="pre">.ui</span></tt> file.</p>
<p><tt class="docutils literal"><span class="pre">uifile</span></tt> is a file name or file-like object containing the <tt class="docutils literal"><span class="pre">.ui</span></tt> file.</p>
<p><tt class="docutils literal"><span class="pre">pyfile</span></tt> is the file-like object to which the generated Python code will
be written to.</p>
<p><tt class="docutils literal"><span class="pre">execute</span></tt> is optionally set if a small amount of additional code is to be
generated that will display the user interface if the code is run as a
standalone application.</p>
<p class="last"><tt class="docutils literal"><span class="pre">indent</span></tt> is the optional number of spaces used for indentation in the
generated code. If it is zero then a tab character is used instead.</p>
</dd>
<dt>loadUiType(uifile)</dt>
<dd><p class="first">This function loads a Qt Designer <tt class="docutils literal"><span class="pre">.ui</span></tt> file and returns a tuple of the
generated <em>form class</em> and the <em>Qt base class</em>. These can then be used to
create any number of instances of the user interface without having to
parse the <tt class="docutils literal"><span class="pre">.ui</span></tt> file more than once.</p>
<p class="last"><tt class="docutils literal"><span class="pre">uifile</span></tt> is a file name or file-like object containing the <tt class="docutils literal"><span class="pre">.ui</span></tt> file.</p>
</dd>
<dt>loadUi(uifile, baseinstance=None)</dt>
<dd><p class="first">This function loads a Qt Designer <tt class="docutils literal"><span class="pre">.ui</span></tt> file and returns an instance of
the user interface.</p>
<p><tt class="docutils literal"><span class="pre">uifile</span></tt> is a file name or file-like object containing the <tt class="docutils literal"><span class="pre">.ui</span></tt> file.</p>
<p class="last"><tt class="docutils literal"><span class="pre">baseinstance</span></tt> is an optional instance of the <em>Qt base class</em>. If
specified then the user interface is created in it. Otherwise a new
instance of the base class is automatically created.</p>
</dd>
</dl>
</div>
<div class="section" id="pyuic4">
<h2><a class="toc-backref" href="#id19" name="pyuic4">4.3 pyuic4</a></h2>
<p>The <tt class="docutils literal"><span class="pre">pyuic4</span></tt> utility is a command line interface to the <tt class="docutils literal"><span class="pre">uic</span></tt> module. The
command has the following syntax:</p>
<pre class="literal-block">
pyuic4 [options] .ui-file
</pre>
<p>The full set of command line options is:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td>
<kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
<td>A help message is written to <tt class="docutils literal"><span class="pre">stdout</span></tt>.</td></tr>
<tr><td>
<kbd><span class="option">--version</span></kbd></td>
<td>The version number is written to <tt class="docutils literal"><span class="pre">stdout</span></tt>.</td></tr>
<tr><td colspan="2">
<kbd><span class="option">-i</span> <var>N</var>, <span class="option">--indent</span>=<var>N</var></kbd></td>
</tr>
<tr><td> </td><td>The Python code is generated using an indentation of N
spaces. If N is 0 then a tab is used. The default is
4.</td></tr>
<tr><td colspan="2">
<kbd><span class="option">-o</span> <var>FILE</var>, <span class="option">--output</span>=<var>FILE</var></kbd></td>
</tr>
<tr><td> </td><td>The Python code generated is written to the file FILE.</td></tr>
<tr><td>
<kbd><span class="option">-p</span>, <span class="option">--preview</span></kbd></td>
<td>The GUI is created dynamically and displayed. No
Python code is generated.</td></tr>
<tr><td>
<kbd><span class="option">-x</span>, <span class="option">--execute</span></kbd></td>
<td>The generated Python code includes a small amount of
additional code that creates and displays the GUI when
it is executes as a standalone application.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="the-pyqt-resource-system">
<h1><a class="toc-backref" href="#id20" name="the-pyqt-resource-system">5 The PyQt Resource System</a></h1>
<p>PyQt supports Qt's resource system. This is a facility for embedding
resources such as icons and translation files in an application. This makes
the packaging and distribution of those resources much easier.</p>
<p>A <tt class="docutils literal"><span class="pre">.qrc</span></tt> resource collection file is an XML file used to specify which
resource files are to be embedded. The application then refers to the resource
files by their original names but preceded by a colon.</p>
<p>For a full description, including the format of the <tt class="docutils literal"><span class="pre">.qrc</span></tt> files, see the Qt
Resource System in the Qt documentation.</p>
<div class="section" id="pyrcc4">
<h2><a class="toc-backref" href="#id21" name="pyrcc4">5.1 pyrcc4</a></h2>
<p><tt class="docutils literal"><span class="pre">pyrcc4</span></tt> is PyQt's equivalent to Qt's <tt class="docutils literal"><span class="pre">rcc</span></tt> utility and is used in exactly
the same way. <tt class="docutils literal"><span class="pre">pyrcc4</span></tt> reads the <tt class="docutils literal"><span class="pre">.qrc</span></tt> file, and the resource files, and
generates a Python module that only needs to be <tt class="docutils literal"><span class="pre">import</span></tt> ed by the
application in order for those resources to be made available just as if they
were the original files.</p>
<p><a class="reference" href="#pyrcc4">pyrcc4</a> will only be included if your copy of Qt includes the XML module.</p>
</div>
</div>
<div class="section" id="internationalisation-of-pyqt-applications">
<h1><a class="toc-backref" href="#id22" name="internationalisation-of-pyqt-applications">6 Internationalisation of PyQt Applications</a></h1>
<p>PyQt and Qt include a comprehensive set of tools for translating applications
into local languages. For a full description, see the Qt Linguist Manual in
the Qt documentation.</p>
<p>The process of internationalising an application comprises the following
steps.</p>
<blockquote>
<ul class="simple">
<li>The programmer uses <a class="reference" href="#pylupdate4">pylupdate4</a> to create or update a <tt class="docutils literal"><span class="pre">.ts</span></tt>
translation file for each language that the application is to be
translated into. A <tt class="docutils literal"><span class="pre">.ts</span></tt> file is an XML file that contains the strings
to be translated and the corresponding translations that have already
been made. <a class="reference" href="#pylupdate4">pylupdate4</a> can be run any number of times during
development to update the <tt class="docutils literal"><span class="pre">.ts</span></tt> files with the latest strings for
translation.</li>
<li>The translator uses Qt Linguist to update the <tt class="docutils literal"><span class="pre">.ts</span></tt> files with
translations of the strings.</li>
<li>The release manager then uses Qt's <tt class="docutils literal"><span class="pre">lrelease</span></tt> utility to convert the
<tt class="docutils literal"><span class="pre">.ts</span></tt> files to <tt class="docutils literal"><span class="pre">.qm</span></tt> files which are compact binary equivalents used
by the application. If an application cannot find an appropriate <tt class="docutils literal"><span class="pre">.qm</span></tt>
file, or a particular string hasn't been translated, then the strings
used in the original source code are used instead.</li>
<li>The release manage may optionally use <a class="reference" href="#pyrcc4">pyrcc4</a> to embed the <tt class="docutils literal"><span class="pre">.qm</span></tt>
files, along with other application resources such as icons, in a Python
module. This may make packaging and distribution of the application
easier.</li>
</ul>
</blockquote>
<div class="section" id="pylupdate4">
<h2><a class="toc-backref" href="#id23" name="pylupdate4">6.1 pylupdate4</a></h2>
<p><tt class="docutils literal"><span class="pre">pylupdate4</span></tt> is PyQt's equivalent to Qt's <tt class="docutils literal"><span class="pre">lupdate</span></tt> utility and is used in
exactly the same way. A Qt <tt class="docutils literal"><span class="pre">.pro</span></tt> project file is read that specifies the
Python source files and Qt Designer interface files from which the text that
needs to be translated is extracted. The <tt class="docutils literal"><span class="pre">.pro</span></tt> file also specifies the
<tt class="docutils literal"><span class="pre">.ts</span></tt> translation files that <tt class="docutils literal"><span class="pre">pylupdate4</span></tt> updates (or creates if necessary)
and are subsequently used by Qt Linguist.</p>
<p><a class="reference" href="#pylupdate4">pylupdate4</a> will only be included if your copy of Qt includes the XML module.</p>
</div>
<div class="section" id="differences-between-pyqt-and-qt">
<h2><a class="toc-backref" href="#id24" name="differences-between-pyqt-and-qt">6.2 Differences Between PyQt and Qt</a></h2>
<p>Qt implements internationalisation support through the <tt class="docutils literal"><span class="pre">QTranslator</span></tt> class,
and the <tt class="docutils literal"><span class="pre">QCoreApplication::translate()</span></tt>, <tt class="docutils literal"><span class="pre">QObject::tr()</span></tt> and
<tt class="docutils literal"><span class="pre">QObject::trUtf8()</span></tt> methods. Usually the <tt class="docutils literal"><span class="pre">tr()</span></tt> method is used to obtain
the correct translation of a message. The translation process uses a message
context to allow the same message to be translated differently. <tt class="docutils literal"><span class="pre">tr()</span></tt> is
actually generated by <tt class="docutils literal"><span class="pre">moc</span></tt> and uses the hardcoded class name as the context.
On the other hand, <tt class="docutils literal"><span class="pre">QApplication::translate()</span></tt> allows to context to be
explicitly stated.</p>
<p>Unfortunately, because of the way Qt implements <tt class="docutils literal"><span class="pre">tr()</span></tt> (and <tt class="docutils literal"><span class="pre">trUtf8()</span></tt>) it
is not possible for PyQt to exactly reproduce its behavour. The PyQt
implementation of <tt class="docutils literal"><span class="pre">tr()</span></tt> (and <tt class="docutils literal"><span class="pre">trUtf8()</span></tt>) uses the class name of the
instance as the context. The key difference, and the source of potential
problems, is that the context is determined dynamically in PyQt, but is
hardcoded in Qt. In other words, the context of a translation may change
depending on an instance's class hierarchy. For example:</p>
<pre class="literal-block">
class A(QtCore.QObject):
def hello(self):
return self.tr("Hello")
class B(A):
pass
a = A()
a.hello()
b = B()
b.hello()
</pre>
<p>In the above the message is translated by <tt class="docutils literal"><span class="pre">a.hello()</span></tt> using a context of
<tt class="docutils literal"><span class="pre">A</span></tt>, and by <tt class="docutils literal"><span class="pre">b.hello()</span></tt> using a context of <tt class="docutils literal"><span class="pre">B</span></tt>. In the equivalent C++
version the context would be <tt class="docutils literal"><span class="pre">A</span></tt> in both cases.</p>
<p>The PyQt behaviour is unsatisfactory and may be changed in the future. It is
recommended that <tt class="docutils literal"><span class="pre">QCoreApplication.translate()</span></tt> be used in preference to
<tt class="docutils literal"><span class="pre">tr()</span></tt> (and <tt class="docutils literal"><span class="pre">trUtf8()</span></tt>). This is guaranteed to work with current and
future versions of PyQt and makes it much easier to share message files
between Python and C++ code. Below is the alternative implementation of <tt class="docutils literal"><span class="pre">A</span></tt>
that uses <tt class="docutils literal"><span class="pre">QCoreApplication.translate()</span></tt>:</p>
<pre class="literal-block">
class A(QtCore.QObject):
def hello(self):
return QtCore.QCoreApplication.translate("A", "Hello")
</pre>
</div>
</div>
<div class="section" id="things-to-be-aware-of">
<h1><a class="toc-backref" href="#id25" name="things-to-be-aware-of">7 Things to be Aware Of</a></h1>
<div class="section" id="python-strings-qt-strings-and-unicode">
<h2><a class="toc-backref" href="#id26" name="python-strings-qt-strings-and-unicode">7.1 Python Strings, Qt Strings and Unicode</a></h2>
<p>Unicode support was added to Qt in v2.0 and to Python in v1.6. In Qt, Unicode
support is implemented using the <tt class="docutils literal"><span class="pre">QString</span></tt> class. It is important to
understand that <tt class="docutils literal"><span class="pre">QString</span></tt> instances, Python string objects and Python Unicode
objects are all different but conversions between them are automatic in almost
all cases and easy to achieve manually when needed.</p>
<p>Whenever PyQt expects a <tt class="docutils literal"><span class="pre">QString</span></tt> as a function argument, a Python string
object or a Python Unicode object can be provided instead, and PyQt will do
the necessary conversion automatically.</p>
<p>You may also manually convert Python string and Unicode objects to <tt class="docutils literal"><span class="pre">QString</span></tt>
instances by using the <tt class="docutils literal"><span class="pre">QString</span></tt> constructor as demonstrated in the following
code fragment:</p>
<pre class="literal-block">
qs1 = QtCore.QString("Converted Python string object")
qs2 = QtCore.QString(u"Converted Python Unicode object")
</pre>
<p>In order to convert a <tt class="docutils literal"><span class="pre">QString</span></tt> to a Python string object use the Python
<tt class="docutils literal"><span class="pre">str()</span></tt> builtin. Applying <tt class="docutils literal"><span class="pre">str()</span></tt> to a null <tt class="docutils literal"><span class="pre">QString</span></tt> and an empty
<tt class="docutils literal"><span class="pre">QString</span></tt> both result in an empty Python string object.</p>
<p>In order to convert a <tt class="docutils literal"><span class="pre">QString</span></tt> to a Python Unicode object use the Python
<tt class="docutils literal"><span class="pre">unicode()</span></tt> builtin. Applying <tt class="docutils literal"><span class="pre">unicode()</span></tt> to a null <tt class="docutils literal"><span class="pre">QString</span></tt> and an
empty <tt class="docutils literal"><span class="pre">QString</span></tt> both result in an empty Python Unicode object.</p>
<p><tt class="docutils literal"><span class="pre">QString</span></tt> also implements Python's buffer protocol which means that a
<tt class="docutils literal"><span class="pre">QString</span></tt> can be used in many places where a Python string or Unicode object
is expected without being explicitly converted.</p>
</div>
<div class="section" id="garbage-collection">
<h2><a class="toc-backref" href="#id27" name="garbage-collection">7.2 Garbage Collection</a></h2>
<p>C++ does not garbage collect unreferenced class instances, whereas Python does.
In the following C++ fragment both colours exist even though the first can no
longer be referenced from within the program:</p>
<pre class="literal-block">
col = new QColor();
col = new QColor();
</pre>
<p>In the corresponding Python fragment, the first colour is destroyed when the
second is assigned to <tt class="docutils literal"><span class="pre">col</span></tt>:</p>
<pre class="literal-block">
col = QtGui.QColor()
col = QtGui.QColor()
</pre>
<p>In Python, each colour must be assigned to different names. Typically this is
done within class definitions, so the code fragment would be something like:</p>
<pre class="literal-block">
self.col1 = QtGui.QColor()
self.col2 = QtGui.QColor()
</pre>
<p>Sometimes a Qt class instance will maintain a pointer to another instance and
will eventually call the destructor of that second instance. The most common
example is that a <tt class="docutils literal"><span class="pre">QObject</span></tt> (and any of its sub-classes) keeps pointers to
its children and will automatically call their destructors. In these cases,
the corresponding Python object will also keep a reference to the corresponding
child objects.</p>
<p>So, in the following Python fragment, the first <tt class="docutils literal"><span class="pre">QLabel</span></tt> is not destroyed
when the second is assigned to <tt class="docutils literal"><span class="pre">lab</span></tt> because the parent <tt class="docutils literal"><span class="pre">QWidget</span></tt> still has
a reference to it:</p>
<pre class="literal-block">
parent = QtGui.QWidget()
lab = QtGui.QLabel("First label", parent)
lab = QtGui.QLabel("Second label", parent)
</pre>
</div>
<div class="section" id="multiple-inheritance">
<h2><a class="toc-backref" href="#id28" name="multiple-inheritance">7.3 Multiple Inheritance</a></h2>
<p>It is not possible to define a new Python class that sub-classes from more than
one Qt class.</p>
</div>
<div class="section" id="access-to-protected-member-functions">
<h2><a class="toc-backref" href="#id29" name="access-to-protected-member-functions">7.4 Access to Protected Member Functions</a></h2>
<p>When an instance of a C++ class is not created from Python it is not possible
to access the protected member functions, or emit any signals, of that
instance. Attempts to do so will raise a Python exception. Also, any Python
methods corresponding to the instance's virtual member functions will never be
called.</p>
</div>
<div class="section" id="none-and-null">
<h2><a class="toc-backref" href="#id30" name="none-and-null">7.5 <tt class="docutils literal"><span class="pre">None</span></tt> and <tt class="docutils literal"><span class="pre">NULL</span></tt></a></h2>
<p>Throughout PyQt, the <tt class="docutils literal"><span class="pre">None</span></tt> value can be specified wherever <tt class="docutils literal"><span class="pre">NULL</span></tt> is
acceptable to the underlying C++ code.</p>
<p>Equally, <tt class="docutils literal"><span class="pre">NULL</span></tt> is converted to <tt class="docutils literal"><span class="pre">None</span></tt> whenever it is returned by the
underlying C++ code.</p>
</div>
<div class="section" id="support-for-void">
<h2><a class="toc-backref" href="#id31" name="support-for-void">7.6 Support for <tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt></a></h2>
<p>PyQt (actually SIP) represents <tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt> values as objects of type
<tt class="docutils literal"><span class="pre">sip.voidptr</span></tt>. Such values are often used to pass the addresses of external
objects between different Python modules. To make this easier, a Python
integer (or anything that Python can convert to an integer) can be used
whenever a <tt class="docutils literal"><span class="pre">sip.voidptr</span></tt> is expected.</p>
<p>A <tt class="docutils literal"><span class="pre">sip.voidptr</span></tt> may be converted to a Python integer by using the <tt class="docutils literal"><span class="pre">int()</span></tt>
builtin function.</p>
<p>A <tt class="docutils literal"><span class="pre">sip.voidptr</span></tt> may be converted to a Python string by using its
<tt class="docutils literal"><span class="pre">asstring()</span></tt> method. The <tt class="docutils literal"><span class="pre">asstring()</span></tt> method takes an integer argument
which is the length of the data in bytes.</p>
</div>
<div class="section" id="super-and-pyqt-classes">
<h2><a class="toc-backref" href="#id32" name="super-and-pyqt-classes">7.7 <tt class="docutils literal"><span class="pre">super</span></tt> and PyQt Classes</a></h2>
<p>Internally PyQt implements a lazy technique for attribute lookup where
attributes are only placed in type and instance dictionaries when they are
first referenced. This technique is needed to reduce the time taken to import
large modules such as PyQt.</p>
<p>In most circumstances this technique is transparent to an application. The
exception is when <tt class="docutils literal"><span class="pre">super</span></tt> is used with a PyQt class. The way that <tt class="docutils literal"><span class="pre">super</span></tt>
is currently implemented means that the lazy lookup is bypassed resulting in
<tt class="docutils literal"><span class="pre">AttributeError</span></tt> exceptions unless the attribute has been previously
referenced.</p>
<p>Note that this restriction applies to any class wrapped by SIP and not just
PyQt.</p>
</div>
</div>
<div class="section" id="deploying-commercial-pyqt-applications">
<h1><a class="toc-backref" href="#id33" name="deploying-commercial-pyqt-applications">8 Deploying Commercial PyQt Applications</a></h1>
<p>When deploying commercial PyQt applications it is necessary to discourage
users from accessing the underlying PyQt modules for themselves. A user that
used the modules shipped with your application to develop new applications
would themselves be considered a developer and would need their own commercial
Qt and PyQt licenses.</p>
<p>One solution to this problem is the <a class="reference" href="http://www.riverbankcomputing.co.uk/vendorid/">VendorID</a> package. This allows you to
build Python extension modules that can only be imported by a digitally signed
custom interpreter. The package enables you to create such an interpreter with
your application embedded within it. The result is an interpreter that can
only run your application, and PyQt modules that can only be imported by that
interpreter. You can use the package to similarly restrict access to any
extension module.</p>
<p>In order to build PyQt with support for the VendorID package, pass the <tt class="docutils literal"><span class="pre">-i</span></tt>
command line flag to <tt class="docutils literal"><span class="pre">configure.py</span></tt>.</p>
</div>
<div class="section" id="the-pyqt-build-system">
<h1><a class="toc-backref" href="#id34" name="the-pyqt-build-system">9 The PyQt Build System</a></h1>
<p>The PyQt build system is an extension of the SIP build system and is
implemented by the <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt> module, part of the <tt class="docutils literal"><span class="pre">PyQt4</span></tt> package. It
can be used by configuration scripts of other bindings that build on top of
PyQt and takes care of the details of the Qt installation.</p>
<p>The module contains a number of classes.</p>
<div class="section" id="pyqtconfig-classes">
<h2><a class="toc-backref" href="#id35" name="pyqtconfig-classes">9.1 <tt class="docutils literal"><span class="pre">pyqtconfig</span></tt> Classes</a></h2>
<dl class="docutils">
<dt>Configuration(sipconfig.Configuration)</dt>
<dd><p class="first">This class encapsulates configuration values that can be accessed as
instance objects.</p>
<p>The following configuration values are provided in addition to those
provided by the super-class:</p>
<blockquote>
<dl class="docutils">
<dt>pyqt_bin_dir</dt>
<dd>The name of the directory where the PyQt utilities are installed.</dd>
<dt>pyqt_config_args</dt>
<dd>The command line passed to <tt class="docutils literal"><span class="pre">configure.py</span></tt> when PyQt was
configured.</dd>
<dt>pyqt_mod_dir</dt>
<dd>The name of the directory where the <tt class="docutils literal"><span class="pre">PyQt4</span></tt> Python package is
installed.</dd>
<dt>pyqt_modules</dt>
<dd>A space separated string of installed PyQt modules. The <tt class="docutils literal"><span class="pre">Qt</span></tt>
module is not included.</dd>
<dt>pyqt_sip_dir</dt>
<dd>The name of the base directory where PyQt's <tt class="docutils literal"><span class="pre">.sip</span></tt> files are
installed. Each module's <tt class="docutils literal"><span class="pre">.sip</span></tt> files are installed in a
sub-directory with the same name as the module.</dd>
<dt>pyqt_sip_flags</dt>
<dd>A space separated string of the <tt class="docutils literal"><span class="pre">sip</span></tt> command line arguments used
to build the PyQt modules. These should also be used when
building bindings that <tt class="docutils literal"><span class="pre">%Import</span></tt> any PyQt modules.</dd>
<dt>pyqt_version</dt>
<dd>The PyQt version as a 3 part hexadecimal number (e.g. v4.0.1 is
represented as <tt class="docutils literal"><span class="pre">0x040001</span></tt>).</dd>
<dt>pyqt_version_str</dt>
<dd>The PyQt version as a string. For development snapshots it will
start with <tt class="docutils literal"><span class="pre">snapshot-</span></tt>.</dd>
<dt>qt_data_dir</dt>
<dd>The value of <tt class="docutils literal"><span class="pre">QLibraryInfo::location(DataPath)</span></tt> for the Qt
installation.</dd>
<dt>qt_dir</dt>
<dd>The root directory of the Qt installation (normally the directory
that contains the <tt class="docutils literal"><span class="pre">bin</span></tt> directory).</dd>
<dt>qt_edition</dt>
<dd>The Qt edition.</dd>
<dt>qt_framework</dt>
<dd>Set if Qt is built as a MacOS/X framework.</dd>
<dt>qt_inc_dir</dt>
<dd>The value of <tt class="docutils literal"><span class="pre">QLibraryInfo::location(HeadersPath)</span></tt> for the Qt
installation.</dd>
<dt>qt_lib_dir</dt>
<dd>The value of <tt class="docutils literal"><span class="pre">QLibraryInfo::location(LibrariesPath)</span></tt> for the Qt
installation.</dd>
<dt>qt_threaded</dt>
<dd>Set if Qt is built with thread support (always set for PyQt).</dd>
<dt>qt_version</dt>
<dd>The Qt version as a 3 part hexadecimal number (e.g. v4.1.2 is
represented as <tt class="docutils literal"><span class="pre">0x040102</span></tt>).</dd>
<dt>qt_winconfig</dt>
<dd>Additional Windows specific configuration.</dd>
</dl>
</blockquote>
<dl class="last docutils">
<dt>__init__(self, sub_cfg=None)</dt>
<dd><p class="first">Initialise the instance.</p>
<p class="last"><tt class="docutils literal"><span class="pre">sub_cfg</span></tt> is an optional list of sub-class configurations. It should
only be used by the <tt class="docutils literal"><span class="pre">__init__()</span></tt> method of a sub-class to append its
own dictionary of configuration values before passing the list to its
super-class.</p>
</dd>
</dl>
</dd>
<dt>QtAssistantModuleMakefile(QtNetworkModuleMakefile)</dt>
<dd>This class encapsulates a Makefile to build a SIP generated Python
extension module that is built on the PyQt <tt class="docutils literal"><span class="pre">QtAssistant</span></tt> module.</dd>
<dt>QtCoreModuleMakefile(sipconfig.SIPModuleMakefile)</dt>
<dd>This class encapsulates a Makefile to build a SIP generated Python
extension module that is built on the PyQt <tt class="docutils literal"><span class="pre">QtCore</span></tt> module.</dd>
<dt>QtGuiModuleMakefile(QtCoreModuleMakefile)</dt>
<dd>This class encapsulates a Makefile to build a SIP generated Python
extension module that is built on the PyQt <tt class="docutils literal"><span class="pre">QtGui</span></tt> module.</dd>
<dt>QtNetworkModuleMakefile(QtCoreModuleMakefile)</dt>
<dd>This class encapsulates a Makefile to build a SIP generated Python
extension module that is built on the PyQt <tt class="docutils literal"><span class="pre">QtNetwork</span></tt> module.</dd>
<dt>QtOpenGLModuleMakefile(QtGuiModuleMakefile)</dt>
<dd>This class encapsulates a Makefile to build a SIP generated Python
extension module that is built on the PyQt <tt class="docutils literal"><span class="pre">QtOpenGL</span></tt> module.</dd>
<dt>QtSqlModuleMakefile(QtGuiModuleMakefile)</dt>
<dd>This class encapsulates a Makefile to build a SIP generated Python
extension module that is built on the PyQt <tt class="docutils literal"><span class="pre">QtSql</span></tt> module.</dd>
<dt>QtSvgModuleMakefile(QtGuiModuleMakefile)</dt>
<dd>This class encapsulates a Makefile to build a SIP generated Python
extension module that is built on the PyQt <tt class="docutils literal"><span class="pre">QtSvg</span></tt> module.</dd>
<dt>QtXmlModuleMakefile(QtCoreModuleMakefile)</dt>
<dd>This class encapsulates a Makefile to build a SIP generated Python
extension module that is built on the PyQt <tt class="docutils literal"><span class="pre">QtXml</span></tt> module.</dd>
</dl>
</div>
</div>
</div>
</body>
</html>
|
