##// END OF EJS Templates
GIT_REPOSITORIES » LPP » PythonQt
RSS

Clone from https://github.com/Orochimarufan/PythonQt.git

updated docs...
florianlink -
r185:55d7d678fe32
parent child
Show More
Show file before | Show file after | Hide comments
@@ -1,532 +1,535
1 #ifndef _PYTHONQTDOC_H
1 #ifndef _PYTHONQTDOC_H
2 #define _PYTHONQTDOC_H
2 #define _PYTHONQTDOC_H
3
3
4 /*
4 /*
5 *
5 *
6 * Copyright (C) 2010 MeVis Medical Solutions AG All Rights Reserved.
6 * Copyright (C) 2010 MeVis Medical Solutions AG All Rights Reserved.
7 *
7 *
8 * This library is free software; you can redistribute it and/or
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
11 * version 2.1 of the License, or (at your option) any later version.
12 *
12 *
13 * This library is distributed in the hope that it will be useful,
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
16 * Lesser General Public License for more details.
17 *
17 *
18 * Further, this software is distributed without any warranty that it is
18 * Further, this software is distributed without any warranty that it is
19 * free of the rightful claim of any third person regarding infringement
19 * free of the rightful claim of any third person regarding infringement
20 * or the like. Any license provided herein, whether implied or
20 * or the like. Any license provided herein, whether implied or
21 * otherwise, applies only to this software file. Patent licenses, if
21 * otherwise, applies only to this software file. Patent licenses, if
22 * any, provided herein do not apply to combinations of this program with
22 * any, provided herein do not apply to combinations of this program with
23 * other software, or any other product whatsoever.
23 * other software, or any other product whatsoever.
24 *
24 *
25 * You should have received a copy of the GNU Lesser General Public
25 * You should have received a copy of the GNU Lesser General Public
26 * License along with this library; if not, write to the Free Software
26 * License along with this library; if not, write to the Free Software
27 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
27 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
28 *
28 *
29 * Contact information: MeVis Medical Solutions AG, Universitaetsallee 29,
29 * Contact information: MeVis Medical Solutions AG, Universitaetsallee 29,
30 * 28359 Bremen, Germany or:
30 * 28359 Bremen, Germany or:
31 *
31 *
32 * http://www.mevis.de
32 * http://www.mevis.de
33 *
33 *
34 */
34 */
35
35
36 //----------------------------------------------------------------------------------
36 //----------------------------------------------------------------------------------
37 /*!
37 /*!
38 // \file PythonQtDoc.h
38 // \file PythonQtDoc.h
39 // \author Florian Link
39 // \author Florian Link
40 // \author Last changed by $Author: florian $
40 // \author Last changed by $Author: florian $
41 // \date 2006-10
41 // \date 2006-10
42 */
42 */
43 //----------------------------------------------------------------------------------
43 //----------------------------------------------------------------------------------
44
44
45 /*!
45 /*!
46 \if USE_GLOBAL_DOXYGEN_DOC
46 \if USE_GLOBAL_DOXYGEN_DOC
47 \page PythonQtPage PythonQt Overview
47 \page PythonQtPage PythonQt Overview
48 \else
48 \else
49 \mainpage notitle
49 \mainpage notitle
50 \endif
50 \endif
51
51
52 \image html PythonQt.jpg
52 \image html PythonQt.jpg
53
53
54 \section Introduction
54 \section Introduction
55
55
56 \b PythonQt is a dynamic <a href="http://www.python.org" target="_blank">
56 \b PythonQt is a dynamic <a href="http://www.python.org" target="_blank">
57 Python</a> binding for the <a href="http://qt.nokia.com" target="_blank">
57 Python</a> binding for the <a href="http://qt.nokia.com" target="_blank">
58 Qt framework</a>.
58 Qt framework</a>.
59 It offers an easy way to embed the Python scripting language into
59 It offers an easy way to embed the Python scripting language into
60 your C++ Qt applications. It makes heavy use of the QMetaObject system and thus requires Qt 4.x.
60 your C++ Qt applications. It makes heavy use of the QMetaObject system and thus requires Qt 4.x.
61
61
62 The focus of PythonQt is on embedding Python into an existing C++ application, not on writing the whole
62 The focus of PythonQt is on embedding Python into an existing C++ application, not on writing the whole
63 application completely in Python. If you want to write your whole application in Python,
63 application completely in Python. If you want to write your whole application in Python,
64 you should use <a href="http://www.riverbankcomputing.co.uk/pyqt/" target="_blank">PyQt</a> or <a href="http://www.pyside.org" target="_blank">PySide</a> instead.
64 you should use <a href="http://www.riverbankcomputing.co.uk/pyqt/" target="_blank">PyQt</a> or <a href="http://www.pyside.org" target="_blank">PySide</a> instead.
65
65
66 If you are looking for a simple way to embed Python objects into your C++/Qt Application
66 If you are looking for a simple way to embed Python objects into your C++/Qt Application
67 and to script parts of your application via Python, PythonQt is the way to go!
67 and to script parts of your application via Python, PythonQt is the way to go!
68
68
69 PythonQt is a stable library that was developed to make the
69 PythonQt is a stable library that was developed to make the
70 Image Processing and Visualization platform <a href="http://www.mevislab.de" target="_blank">MeVisLab</a>
70 Image Processing and Visualization platform <a href="http://www.mevislab.de" target="_blank">MeVisLab</a>
71 scriptable from Python.
71 scriptable from Python.
72
72
73 - \ref Features
73 - \ref Features
74 - \ref Download
74 - \ref Download
75 - \ref License
75 - \ref License
76 - \ref Developer
76 - \ref Developer
77 - \ref Building
77 - \ref Building
78 - \ref Examples
78 - \ref Examples
79
79
80 \page Features Features
80 \page Features Features
81
81
82 \section Builtin Built-in Features
82 \section Builtin Built-in Features
83
83
84 The following are the built-in features of the PythonQt library:
84 The following are the built-in features of the PythonQt library:
85
85
86 - Access all \b slots, \b properties, children and registered enums of any QObject derived class from Python
86 - Access all \b slots, \b properties, children and registered enums of any QObject derived class from Python
87 - Connecting Qt Signals to Python functions (both from within Python and from C++)
87 - Connecting Qt Signals to Python functions (both from within Python and from C++)
88 - Easy wrapping of Python objects from C++ with smart, reference-counting PythonQtObjectPtr.
88 - Easy wrapping of Python objects from C++ with smart, reference-counting PythonQtObjectPtr.
89 - Convenient conversions to/from QVariant for PythonQtObjectPtr.
89 - Convenient conversions to/from QVariant for PythonQtObjectPtr.
90 - Wrapping of C++ objects (which are not derived from QObject) via PythonQtCppWrapperFactory
90 - Wrapping of C++ objects (which are not derived from QObject) via PythonQtCppWrapperFactory
91 - Extending C++ and QObject derived classes with additional slots, static methods and constructors (see Decorators)
91 - Extending C++ and QObject derived classes with additional slots, static methods and constructors (see Decorators)
92 - StdOut/Err redirection to Qt signals instead of cout
92 - StdOut/Err redirection to Qt signals instead of cout
93 - Interface for creating your own \c import replacement, so that Python scripts can be e.g. signed/verified before they are executed (PythonQtImportFileInterface)
93 - Interface for creating your own \c import replacement, so that Python scripts can be e.g. signed/verified before they are executed (PythonQtImportFileInterface)
94 - Mapping of plain-old-datatypes and ALL QVariant types to and from Python
94 - Mapping of plain-old-datatypes and ALL QVariant types to and from Python
95 - Support for wrapping of user QVariant types which are registerd via QMetaType
95 - Support for wrapping of user QVariant types which are registerd via QMetaType
96 - Support for Qt namespace (with all enumerators)
96 - Support for Qt namespace (with all enumerators)
97 - All PythonQt wrapped objects support the dir() statement, so that you can see easily which attributes a QObject, CPP object or QVariant has
97 - All PythonQt wrapped objects support the dir() statement, so that you can see easily which attributes a QObject, CPP object or QVariant has
98 - No preprocessing/wrapping tool needs to be started, PythonQt can script any QObject without prior knowledge about it (except for the MetaObject information from the \b moc)
98 - No preprocessing/wrapping tool needs to be started, PythonQt can script any QObject without prior knowledge about it (except for the MetaObject information from the \b moc)
99 - Multiple inheritance for C++ objects (e.g. a QWidget is derived from QObject and QPaintDevice, PythonQt will automatically cast a QWidget to a QPaintDevice when needed)
99 - Multiple inheritance for C++ objects (e.g. a QWidget is derived from QObject and QPaintDevice, PythonQt will automatically cast a QWidget to a QPaintDevice when needed)
100 - Polymorphic downcasting (if e.g. PythonQt sees a QEvent, it can downcast it depending on the type(), so the Python e.g. sees a QPaintEvent instead of a plain QEvent)
100 - Polymorphic downcasting (if e.g. PythonQt sees a QEvent, it can downcast it depending on the type(), so the Python e.g. sees a QPaintEvent instead of a plain QEvent)
101 - Deriving C++ objects from Python and overwriting virtual method with a Python implementation (requires usage of wrapper generator or manual work!)
101 - Deriving C++ objects from Python and overwriting virtual method with a Python implementation (requires usage of wrapper generator or manual work!)
102 - Extensible handler for Python/C++ conversion of complex types, e.g. mapping of QVector<SomeObject> to/from a Python array
102 - Extensible handler for Python/C++ conversion of complex types, e.g. mapping of QVector<SomeObject> to/from a Python array
103 - Setting of dynamic QObject properties via setProperty(), dynamic properties can be accessed for reading and writing like normal Python attributes (but creating a new property needs to be done with setProperty(), to distinguish from normal Python attributes)
103 - Setting of dynamic QObject properties via setProperty(), dynamic properties can be accessed for reading and writing like normal Python attributes (but creating a new property needs to be done with setProperty(), to distinguish from normal Python attributes)
104
104
105 \section FeaturesQtAll Features with wrapper generator
105 \section FeaturesQtAll Features with wrapper generator
106
106
107 Thanks to the new wrapper generator, PythonQt now offers the additional PythonQt_QtAll library which wraps the complete Qt API, including all C++ classes and all non-slots on QObject derived classes.
107 Thanks to the new wrapper generator, PythonQt now offers the additional PythonQt_QtAll library which wraps the complete Qt API, including all C++ classes and all non-slots on QObject derived classes.
108 This offers the following features:
108 This offers the following features:
109
109
110 - Complete Qt API wrapped and accessible
110 - Complete Qt API wrapped and accessible
111 - The following modules are available as submodules of the PythonQt module:
111 - The following modules are available as submodules of the PythonQt module:
112 - QtCore
112 - QtCore
113 - QtGui
113 - QtGui
114 - QtNetwork
114 - QtNetwork
115 - QtOpenGL
115 - QtOpenGL
116 - QtSql
116 - QtSql
117 - QtSvg
117 - QtSvg
118 - QtUiTools
118 - QtUiTools
119 - QtWebKit
119 - QtWebKit
120 - QtXml
120 - QtXml
121 - (QtXmlPatterns, QtScript, QtHelp, phonon, assistant, designer are currently not supported, this would require some additional effort on the code generator)
121 - (QtXmlPatterns, QtScript, QtHelp, phonon, assistant, designer are currently not supported, this would require some additional effort on the code generator)
122 - For convenience, all classes are also available in the PythonQt.Qt module, for people who do not care in which module a class is located
122 - For convenience, all classes are also available in the PythonQt.Qt module, for people who do not care in which module a class is located
123 - Any Qt class that has virtual methods can be easily derived from Python and the virtual methods can be reimplemented in Python (this feature is considered experimental!)
123 - Any Qt class that has virtual methods can be easily derived from Python and the virtual methods can be reimplemented in Python (this feature is considered experimental!)
124 - Polymorphic downcasting on QEvent, QGraphicsItem, QStyleOption, ...
124 - Polymorphic downcasting on QEvent, QGraphicsItem, QStyleOption, ...
125 - Multiple inheritance support (e.g., QGraphicsTextItem is a QObject AND a QGraphicsItem, PythonQt will handle this well)
125 - Multiple inheritance support (e.g., QGraphicsTextItem is a QObject AND a QGraphicsItem, PythonQt will handle this well)
126
126
127 \section Comparison Comparison with PyQt/PySide
127 \section Comparison Comparison with PyQt/PySide
128
128
129 - PythonQt is not as pythonic as PyQt in many details (e.g. buffer protocol, pickling, translation support, ...) and it is mainly thought for embedding and intercommunication between Qt/Cpp and Python
129 - PythonQt is not as pythonic as PyQt in many details (e.g. buffer protocol, pickling, translation support, ...) and it is mainly thought for embedding and intercommunication between Qt/Cpp and Python
130 - PythonQt allows to communicate in both directions, e.g., calling a Python object from C++ AND calling a C++ method from Python, while PyQt only handles the Python->C++ direction
130 - PythonQt allows to communicate in both directions, e.g., calling a Python object from C++ AND calling a C++ method from Python, while PyQt only handles the Python->C++ direction
131 - PythonQt offers properties as Python attributes, while PyQt offers them as setter/getter methods (e.g. QWidget.width is a property in PythonQt and a method in PyQt)
131 - PythonQt offers properties as Python attributes, while PyQt offers them as setter/getter methods (e.g. QWidget.width is a property in PythonQt and a method in PyQt)
132 - PythonQt currently does not support instanceof checks for Qt classes, except for the exact match and derived Python classes
132 - PythonQt currently does not support instanceof checks for Qt classes, except for the exact match and derived Python classes
133 - QObject.emit to emit Qt signals from Python is not yet implemented but PythonQt allows to just emit a signal by calling it like a normal slot
133 - QObject.emit to emit Qt signals from Python is not yet implemented but PythonQt allows to just emit a signal by calling it like a normal slot
134 - PythonQt does not (yet) offer to add new signals to Python/C++ objects and it does not yet support the newstyle PyQt signals (so you need to connect via C++ string signatures)
134 - PythonQt does not (yet) offer to add new signals to Python/C++ objects and it does not yet support the newstyle PyQt signals (so you need to connect via C++ string signatures)
135 - Ownership of objects is a bit different in PythonQt, currently Python classes derived from a C++ class need to be manually referenced in Python to not get deleted too early (this will be fixed in a future version)
135 - Ownership of objects is a bit different in PythonQt, currently Python classes derived from a C++ class need to be manually referenced in Python to not get deleted too early (this will be fixed in a future version)
136 - QStrings are always converted to unicode Python objects, QByteArray always stays a QByteArray and can be converted using str()
136 - QStrings are always converted to unicode Python objects, QByteArray always stays a QByteArray and can be converted using str()
137 - There are many details in the generated wrappers that could need some polishing, e.g., methods that use pointer arguments for additional return values could return a results tuple.
137 - There are many details in the generated wrappers that could need some polishing, e.g., methods that use pointer arguments for additional return values could return a results tuple.
138 - Not all types of QList/QVector/QHash templates are supported, some Qt methods use those as arguments/return values (but you can add your own handlers to handle them if you need them).
138 - Not all types of QList/QVector/QHash templates are supported, some Qt methods use those as arguments/return values (but you can add your own handlers to handle them if you need them).
139 - Probably there are lots of details that differ, I do not know PyQt that well to list them all.
139 - Probably there are lots of details that differ, I do not know PyQt that well to list them all.
140 - In the long run, PythonQt will consider using/extending PySide with the features of PythonQt to get rid of its own generator and typesystem files, alternatively the KDE Smoke generator might be used in the future (this has not yet been decided, the current PythonQt generator works well and there is no hurry to switch).
140 - In the long run, PythonQt will consider using/extending PySide with the features of PythonQt to get rid of its own generator and typesystem files, alternatively the KDE Smoke generator might be used in the future (this has not yet been decided, the current PythonQt generator works well and there is no hurry to switch).
141
141
142 \page Download Download
142 \page Download Download
143
143
144 PythonQt is hosted on <a href="http://sourceforge.net/projects/pythonqt/" target="_blank">SourceForge</a>.
144 PythonQt is hosted on <a href="http://sourceforge.net/projects/pythonqt/" target="_blank">SourceForge</a>.
145
145
146 You can download the source code as a tarball at http://sourceforge.net/projects/pythonqt/files/.
146 You can download the source code as a tarball at http://sourceforge.net/projects/pythonqt/files/.
147 Alternatively you can get the latest version from the svn repository.
147 Alternatively you can get the latest version from the svn repository.
148
148
149 You can also browse the source code online via ViewVC: http://pythonqt.svn.sourceforge.net/viewvc/pythonqt/trunk/
149 You can also browse the source code online via ViewVC: http://pythonqt.svn.sourceforge.net/viewvc/pythonqt/trunk/
150
150
151 \note We do not offer prebuilt binaries, since there are so many possible combinations of
151 \note We do not offer prebuilt binaries, since there are so many possible combinations of
152 platforms (Windows/Linux/MacOs), architectures (32/64 bit) and Python versions.
152 platforms (Windows/Linux/MacOs), architectures (32/64 bit) and Python versions.
153
153
154 \page License License
154 \page License License
155
155
156 PythonQt is distributed under the LGPL license, so it pairs well with the LGPL of the Qt 4.5 release and allows
156 PythonQt is distributed under the LGPL license, so it pairs well with the LGPL of the Qt 4.5 release and allows
157 to be used in commercial applications when following the LGPL 2.1 obligations.
157 to be used in commercial applications when following the LGPL 2.1 obligations.
158
158
159 The build system of PythonQt makes use of a modified version of the LGPL'ed QtScript generator,
159 The build system of PythonQt makes use of a modified version of the LGPL'ed QtScript generator,
160 located in the "generator" directory.
160 located in the "generator" directory.
161
161
162 See http://qt.gitorious.org/qt-labs/qtscriptgenerator for details on the original project.
162 See http://qt.gitorious.org/qt-labs/qtscriptgenerator for details on the original project.
163 Thanks a lot to the QtJambi guys and the QtScript Generator project for the C++ parser and
163 Thanks a lot to the QtJambi guys and the QtScript Generator project for the C++ parser and
164 Qt typesystem files!
164 Qt typesystem files!
165
165
166 The PythonQt wrappers generated by the generator located in the "generated_cpp" directory are free to be used without any licensing restrictions.
166 The PythonQt wrappers generated by the generator located in the "generated_cpp" directory are free to be used without any licensing restrictions.
167
167
168 The generated wrappers are pre-generated and checked-in for Qt 4.6.1, so you only need to build and run the
168 The generated wrappers are pre-generated and checked-in for Qt 4.6.1, so you only need to build and run the
169 generator when you want to build additional wrappers or you want to upgrade/downgrade to another Qt version.
169 generator when you want to build additional wrappers or you want to upgrade/downgrade to another Qt version.
170 You may use the generator to generate C++ bindings for your own C++ classes (e.g., to make them inheritable in Python),
170 You may use the generator to generate C++ bindings for your own C++ classes (e.g., to make them inheritable in Python),
171 but this is currently not documented and involves creating your own typesystem files (although the Qt Jambi examples might help you).
171 but this is currently not documented and involves creating your own typesystem files (although the Qt Jambi examples might help you).
172
172
173
173
174 \page Developer Developer
174 \page Developer Developer
175
175
176 \section Interface Interface
176 \section Interface Interface
177
177
178 The main interface to PythonQt is the PythonQt singleton.
178 The main interface to PythonQt is the PythonQt singleton.
179 PythonQt needs to be initialized via PythonQt::init() once.
179 PythonQt needs to be initialized via PythonQt::init() once.
180 Afterwards you communicate with the singleton via PythonQt::self().
180 Afterwards you communicate with the singleton via PythonQt::self().
181 PythonQt offers a complete Qt binding, which
181 PythonQt offers a complete Qt binding, which
182 needs to be enabled via PythonQt_QtAll::init().
182 needs to be enabled via PythonQt_QtAll::init().
183
183
184
184
185 \section Datatype Datatype Mapping
185 \section Datatype Datatype Mapping
186
186
187 The following table shows the mapping between Python and Qt objects:
187 The following table shows the mapping between Python and Qt objects:
188 <table>
188 <table>
189 <tr><th>Qt/C++</th><th>Python</th></tr>
189 <tr><th>Qt/C++</th><th>Python</th></tr>
190 <tr><td>bool</td><td>bool</td></tr>
190 <tr><td>bool</td><td>bool</td></tr>
191 <tr><td>double</td><td>float</td></tr>
191 <tr><td>double</td><td>float</td></tr>
192 <tr><td>float</td><td>float</td></tr>
192 <tr><td>float</td><td>float</td></tr>
193 <tr><td>char/uchar,int/uint,short,ushort,QChar</td><td>integer</td></tr>
193 <tr><td>char/uchar,int/uint,short,ushort,QChar</td><td>integer</td></tr>
194 <tr><td>long</td><td>integer</td></tr>
194 <tr><td>long</td><td>integer</td></tr>
195 <tr><td>ulong,longlong,ulonglong</td><td>long</td></tr>
195 <tr><td>ulong,longlong,ulonglong</td><td>long</td></tr>
196 <tr><td>QString</td><td>unicode string</td></tr>
196 <tr><td>QString</td><td>unicode string</td></tr>
197 <tr><td>QByteArray</td><td>QByteArray wrapper</td></tr>
197 <tr><td>QByteArray</td><td>QByteArray wrapper</td></tr>
198 <tr><td>char*</td><td>str</td></tr>
198 <tr><td>char*</td><td>str</td></tr>
199 <tr><td>QStringList</td><td>tuple of unicode strings</td></tr>
199 <tr><td>QStringList</td><td>tuple of unicode strings</td></tr>
200 <tr><td>QVariantList</td><td>tuple of objects</td></tr>
200 <tr><td>QVariantList</td><td>tuple of objects</td></tr>
201 <tr><td>QVariantMap</td><td>dict of objects</td></tr>
201 <tr><td>QVariantMap</td><td>dict of objects</td></tr>
202 <tr><td>QVariant</td><td>depends on type, see below</td></tr>
202 <tr><td>QVariant</td><td>depends on type, see below</td></tr>
203 <tr><td>QSize, QRect and all other standard Qt QVariants</td><td>variant wrapper that supports complete API of the respective Qt classes</td></tr>
203 <tr><td>QSize, QRect and all other standard Qt QVariants</td><td>variant wrapper that supports complete API of the respective Qt classes</td></tr>
204 <tr><td>OwnRegisteredMetaType</td><td>C++ wrapper, optionally with additional information/wrapping provided by registerCPPClass()</td></tr>
204 <tr><td>OwnRegisteredMetaType</td><td>C++ wrapper, optionally with additional information/wrapping provided by registerCPPClass()</td></tr>
205 <tr><td>QList<AnyObject*></td><td>converts to a list of CPP wrappers</td></tr>
205 <tr><td>QList<AnyObject*></td><td>converts to a list of CPP wrappers</td></tr>
206 <tr><td>QVector<AnyObject*></td><td>converts to a list of CPP wrappers</td></tr>
206 <tr><td>QVector<AnyObject*></td><td>converts to a list of CPP wrappers</td></tr>
207 <tr><td>EnumType</td><td>Enum wrapper derived from python integer</td></tr>
207 <tr><td>EnumType</td><td>Enum wrapper derived from python integer</td></tr>
208 <tr><td>QObject (and derived classes)</td><td>QObject wrapper</td></tr>
208 <tr><td>QObject (and derived classes)</td><td>QObject wrapper</td></tr>
209 <tr><td>C++ object</td><td>CPP wrapper, either wrapped via PythonQtCppWrapperFactory or just decorated with decorators</td></tr>
209 <tr><td>C++ object</td><td>CPP wrapper, either wrapped via PythonQtCppWrapperFactory or just decorated with decorators</td></tr>
210 <tr><td>PyObject</td><td>PyObject</td></tr>
210 <tr><td>PyObject</td><td>PyObject</td></tr>
211 </table>
211 </table>
212
212
213 PyObject is passed as direct pointer, which allows to pass/return any Python object directly to/from
213 PyObject is passed as direct pointer, which allows to pass/return any Python object directly to/from
214 a Qt slot that uses PyObject* as its argument/return value.
214 a Qt slot that uses PyObject* as its argument/return value.
215 QVariants are mapped recursively as given above, e.g. a dictionary can
215 QVariants are mapped recursively as given above, e.g. a dictionary can
216 contain lists of dictionaries of doubles.
216 contain lists of dictionaries of doubles.
217 All Qt QVariant types are implemented, PythonQt supports the complete Qt API for these object.
217 All Qt QVariant types are implemented, PythonQt supports the complete Qt API for these object.
218
218
219 \section QObject QObject Wrapping
219 \section QObject QObject Wrapping
220
220
221 All classes derived from QObject are automatically wrapped with a python wrapper class
221 All classes derived from QObject are automatically wrapped with a python wrapper class
222 when they become visible to the Python interpreter. This can happen via
222 when they become visible to the Python interpreter. This can happen via
223 - the PythonQt::addObject() method
223 - the PythonQt::addObject() method
224 - when a Qt \b slot returns a QObject derived object to python
224 - when a Qt \b slot returns a QObject derived object to python
225 - when a Qt \b signal contains a QObject and is connected to a python function
225 - when a Qt \b signal contains a QObject and is connected to a python function
226
226
227 It is important that you call PythonQt::registerClass() for any QObject derived class
227 It is important that you call PythonQt::registerClass() for any QObject derived class
228 that may become visible to Python, except when you add it via PythonQt::addObject().
228 that may become visible to Python, except when you add it via PythonQt::addObject().
229 This will register the complete parent hierachy of the registered class, so that
229 This will register the complete parent hierachy of the registered class, so that
230 when you register e.g. a QPushButton, QWidget will be registered as well (and all intermediate
230 when you register e.g. a QPushButton, QWidget will be registered as well (and all intermediate
231 parents).
231 parents).
232
232
233 From Python, you can talk to the returned QObjects in a natural way by calling
233 From Python, you can talk to the returned QObjects in a natural way by calling
234 their slots and receiving the return values. You can also read/write all
234 their slots and receiving the return values. You can also read/write all
235 properties of the objects as if they where normal python properties.
235 properties of the objects as if they where normal python properties.
236
236
237 In addition to this, the wrapped objects support
237 In addition to this, the wrapped objects support
238 - className() - returns a string that reprents the classname of the QObject
238 - className() - returns a string that reprents the classname of the QObject
239 - help() - shows all properties, slots, enums, decorator slots and constructors of the object, in a printable form
239 - help() - shows all properties, slots, enums, decorator slots and constructors of the object, in a printable form
240 - delete() - deletes the object (use with care, especially if you passed the ownership to C++)
240 - delete() - deletes the object (use with care, especially if you passed the ownership to C++)
241 - connect(signal, function) - connect the signal of the given object to a python function
241 - connect(signal, function) - connect the signal of the given object to a python function
242 - connect(signal, qobject, slot) - connect the signal of the given object to a slot of another QObject
242 - connect(signal, qobject, slot) - connect the signal of the given object to a slot of another QObject
243 - disconnect(signal, function) - disconnect the signal of the given object from a python function
243 - disconnect(signal, function) - disconnect the signal of the given object from a python function
244 - disconnect(signal, qobject, slot) - disconnect the signal of the given object from a slot of another QObject
244 - disconnect(signal, qobject, slot) - disconnect the signal of the given object from a slot of another QObject
245 - children() - returns the children of the object
245 - children() - returns the children of the object
246 - setParent(QObject) - set the parent
246 - setParent(QObject) - set the parent
247 - QObject* parent() - get the parent
247 - QObject* parent() - get the parent
248
248
249 The below example shows how to connect signals in Python:
249 The below example shows how to connect signals in Python:
250
250
251 \code
251 \code
252 # define a signal handler function
252 # define a signal handler function
253 def someFunction(flag):
253 def someFunction(flag):
254 print flag
254 print flag
255
255
256 # button1 is a QPushButton that has been added to Python via addObject()
256 # button1 is a QPushButton that has been added to Python via addObject()
257 # connect the clicked signal to a python function:
257 # connect the clicked signal to a python function:
258 button1.connect("clicked(bool)", someFunction)
258 button1.connect("clicked(bool)", someFunction)
259
259
260 \endcode
260 \endcode
261
261
262 \section CPP CPP Wrapping
262 \section CPP CPP Wrapping
263
263
264 You can create dedicated wrapper QObjects for any C++ class. This is done by deriving from PythonQtCppWrapperFactory
264 You can create dedicated wrapper QObjects for any C++ class. This is done by deriving from PythonQtCppWrapperFactory
265 and adding your factory via addWrapperFactory().
265 and adding your factory via addWrapperFactory().
266 Whenever PythonQt encounters a CPP pointer (e.g. on a slot or signal)
266 Whenever PythonQt encounters a CPP pointer (e.g. on a slot or signal)
267 and it does not known it as a QObject derived class, it will create a generic CPP wrapper. So even unknown C++ objects
267 and it does not known it as a QObject derived class, it will create a generic CPP wrapper. So even unknown C++ objects
268 can be passed through Python. If the wrapper factory supports the CPP class, a QObject wrapper will be created for each
268 can be passed through Python. If the wrapper factory supports the CPP class, a QObject wrapper will be created for each
269 instance that enters Python. An alternative to a complete wrapper via the wrapper factory are decorators, see \ref Decorators
269 instance that enters Python. An alternative to a complete wrapper via the wrapper factory are decorators, see \ref Decorators
270
270
271 \section MetaObject Meta Object/Class access
271 \section MetaObject Meta Object/Class access
272
272
273 For each known C++ class, PythonQt provides a Python class. These classes are visible
273 For each known C++ class, PythonQt provides a Python class. These classes are visible
274 inside of the "PythonQt" python module or in subpackages if a package is given when the class is registered.
274 inside of the "PythonQt" python module or in subpackages if a package is given when the class is registered.
275
275
276 A Meta class supports:
276 A Meta class supports:
277
277
278 - access to all declared enum values
278 - access to all declared enum values
279 - constructors
279 - constructors
280 - static methods
280 - static methods
281 - unbound non-static methods
281 - unbound non-static methods
282 - help() and className()
282 - help() and className()
283
283
284 From within Python, you can import the module "PythonQt" to access these classes and the Qt namespace.
284 From within Python, you can import the module "PythonQt" to access these classes and the Qt namespace.
285
285
286 \code
286 \code
287 from PythonQt import QtCore
287 from PythonQt import QtCore
288
288
289 # namespace access:
289 # namespace access:
290 print QtCore.Qt.AlignLeft
290 print QtCore.Qt.AlignLeft
291
291
292 # constructors
292 # constructors
293 a = QtCore.QSize(12,13)
293 a = QtCore.QSize(12,13)
294 b = QtCore.QFont()
294 b = QtCore.QFont()
295
295
296 # static method
296 # static method
297 QtCore.QDate.currentDate()
297 QtCore.QDate.currentDate()
298
298
299 # enum value
299 # enum value
300 QtCore.QFont.UltraCondensed
300 QtCore.QFont.UltraCondensed
301
301
302 \endcode
302 \endcode
303
303
304 \section Decorators Decorator slots
304 \section Decorators Decorator slots
305
305
306 PythonQt introduces a new generic approach to extend any wrapped QObject or CPP object with
306 PythonQt introduces a new generic approach to extend any wrapped QObject or CPP object with
307
307
308 - constructors
308 - constructors
309 - destructors (for CPP objects)
309 - destructors (for CPP objects)
310 - additional slots
310 - additional slots
311 - static slots (callable on both the Meta object and the instances)
311 - static slots (callable on both the Meta object and the instances)
312
312
313 The idea behind decorators is that we wanted to make it as easy as possible to extend
313 The idea behind decorators is that we wanted to make it as easy as possible to extend
314 wrapped objects. Since we already have an implementation for invoking any Qt Slot from
314 wrapped objects. Since we already have an implementation for invoking any Qt Slot from
315 Python, it looked promising to use this approach for the extension of wrapped objects as well.
315 Python, it looked promising to use this approach for the extension of wrapped objects as well.
316 This avoids that the PythonQt user needs to care about how Python arguments are mapped from/to
316 This avoids that the PythonQt user needs to care about how Python arguments are mapped from/to
317 Qt when he wants to create static methods, constructors and additional member functions.
317 Qt when he wants to create static methods, constructors and additional member functions.
318
318
319 The basic idea about decorators is to create a QObject derived class that implements slots
319 The basic idea about decorators is to create a QObject derived class that implements slots
320 which take one of the above roles (e.g. constructor, destructor etc.) via a naming convention.
320 which take one of the above roles (e.g. constructor, destructor etc.) via a naming convention.
321 These slots are then assigned to other classes via the naming convention.
321 These slots are then assigned to other classes via the naming convention.
322
322
323 - SomeClassName* new_SomeClassName(...) - defines a constructor for "SomeClassName" that returns a new object of type SomeClassName (where SomeClassName can be any CPP class, not just QObject classes)
323 - SomeClassName* new_SomeClassName(...) - defines a constructor for "SomeClassName" that returns a new object of type SomeClassName (where SomeClassName can be any CPP class, not just QObject classes)
324 - void delete_SomeClassName(SomeClassName* o) - defines a destructor, which should delete the passed in object o
324 - void delete_SomeClassName(SomeClassName* o) - defines a destructor, which should delete the passed in object o
325 - anything static_SomeClassName_someMethodName(...) - defines a static method that is callable on instances and the meta class
325 - anything static_SomeClassName_someMethodName(...) - defines a static method that is callable on instances and the meta class
326 - anything someMethodName(SomeClassName* o, ...) - defines a slot that will be available on SomeClassName instances (and derived instances). When such a slot is called the first argument is the pointer to the instance and the rest of the arguments can be used to make a call on the instance.
326 - anything someMethodName(SomeClassName* o, ...) - defines a slot that will be available on SomeClassName instances (and derived instances). When such a slot is called the first argument is the pointer to the instance and the rest of the arguments can be used to make a call on the instance.
327
327
328 The below example shows all kinds of decorators in action:
328 The below example shows all kinds of decorators in action:
329
329
330 \code
330 \code
331
331
332 // an example CPP object
332 // an example CPP object
333 class YourCPPObject {
333 class YourCPPObject {
334 public:
334 public:
335 YourCPPObject(int arg1, float arg2) { a = arg1; b = arg2; }
335 YourCPPObject(int arg1, float arg2) { a = arg1; b = arg2; }
336
336
337 float doSomething(int arg1) { return arg1*a*b; };
337 float doSomething(int arg1) { return arg1*a*b; };
338
338
339 private:
339 private:
340
340
341 int a;
341 int a;
342 float b;
342 float b;
343 };
343 };
344
344
345 // an example decorator
345 // an example decorator
346 class ExampleDecorator : public QObject
346 class ExampleDecorator : public QObject
347 {
347 {
348 Q_OBJECT
348 Q_OBJECT
349
349
350 public slots:
350 public slots:
351 // add a constructor to QSize that takes a QPoint
351 // add a constructor to QSize that takes a QPoint
352 QSize* new_QSize(const QPoint& p) { return new QSize(p.x(), p.y()); }
352 QSize* new_QSize(const QPoint& p) { return new QSize(p.x(), p.y()); }
353
353
354 // add a constructor for QPushButton that takes a text and a parent widget
354 // add a constructor for QPushButton that takes a text and a parent widget
355 QPushButton* new_QPushButton(const QString& text, QWidget* parent=NULL) { return new QPushButton(text, parent); }
355 QPushButton* new_QPushButton(const QString& text, QWidget* parent=NULL) { return new QPushButton(text, parent); }
356
356
357 // add a constructor for a CPP object
357 // add a constructor for a CPP object
358 YourCPPObject* new_YourCPPObject(int arg1, float arg2) { return new YourCPPObject(arg1, arg2); }
358 YourCPPObject* new_YourCPPObject(int arg1, float arg2) { return new YourCPPObject(arg1, arg2); }
359
359
360 // add a destructor for a CPP object
360 // add a destructor for a CPP object
361 void delete_YourCPPObject(YourCPPObject* obj) { delete obj; }
361 void delete_YourCPPObject(YourCPPObject* obj) { delete obj; }
362
362
363 // add a static method to QWidget
363 // add a static method to QWidget
364 QWidget* static_QWidget_mouseGrabber() { return QWidget::mouseGrabber(); }
364 QWidget* static_QWidget_mouseGrabber() { return QWidget::mouseGrabber(); }
365
365
366 // add an additional slot to QWidget (make move() callable, which is not declared as a slot in QWidget)
366 // add an additional slot to QWidget (make move() callable, which is not declared as a slot in QWidget)
367 void move(QWidget* w, const QPoint& p) { w->move(p); }
367 void move(QWidget* w, const QPoint& p) { w->move(p); }
368
368
369 // add an additional slot to QWidget, overloading the above move method
369 // add an additional slot to QWidget, overloading the above move method
370 void move(QWidget* w, int x, int y) { w->move(x,y); }
370 void move(QWidget* w, int x, int y) { w->move(x,y); }
371
371
372 // add a method to your own CPP object
372 // add a method to your own CPP object
373 int doSomething(YourCPPObject* obj, int arg1) { return obj->doSomething(arg1); }
373 int doSomething(YourCPPObject* obj, int arg1) { return obj->doSomething(arg1); }
374 };
374 };
375
375
376 ...
376 ...
377
377
378 PythonQt::self()->addDecorators(new ExampleDecorator());
378 PythonQt::self()->addDecorators(new ExampleDecorator());
379 PythonQt::self()->registerCPPClass("YourCPPObject");
379 PythonQt::self()->registerCPPClass("YourCPPObject");
380
380
381 \endcode
381 \endcode
382
382
383 After you have registered an instance of the above ExampleDecorator, you can do the following from Python
383 After you have registered an instance of the above ExampleDecorator, you can do the following from Python
384 (all these calls are mapped to the above decorator slots):
384 (all these calls are mapped to the above decorator slots):
385
385
386 \code
386 \code
387 from PythonQt import QtCore, QtGui, YourCPPObject
387 from PythonQt import QtCore, QtGui, YourCPPObject
388
388
389 # call our new constructor of QSize
389 # call our new constructor of QSize
390 size = QtCore.QSize(QPoint(1,2));
390 size = QtCore.QSize(QPoint(1,2));
391
391
392 # call our new QPushButton constructor
392 # call our new QPushButton constructor
393 button = QtGui.QPushButton("sometext");
393 button = QtGui.QPushButton("sometext");
394
394
395 # call the move slot (overload1)
395 # call the move slot (overload1)
396 button.move(QPoint(0,0))
396 button.move(QPoint(0,0))
397
397
398 # call the move slot (overload2)
398 # call the move slot (overload2)
399 button.move(0,0)
399 button.move(0,0)
400
400
401 # call the static method
401 # call the static method
402 grabber = QtGui.QWidget.mouseWrapper();
402 grabber = QtGui.QWidget.mouseWrapper();
403
403
404 # create a CPP object via constructor
404 # create a CPP object via constructor
405 yourCpp = YourCPPObject(1,11.5)
405 yourCpp = YourCPPObject(1,11.5)
406
406
407 # call the wrapped method on CPP object
407 # call the wrapped method on CPP object
408 print yourCpp.doSomething(1);
408 print yourCpp.doSomething(1);
409
409
410 # destructor will be called:
410 # destructor will be called:
411 yourCpp = None
411 yourCpp = None
412
412
413 \endcode
413 \endcode
414
414
415 \page Building Building
415 \page Building Building
416
416
417 PythonQt requires at least Qt 4.6.1 (for earlier Qt versions, you will need to run the pythonqt_gerenator, Qt 4.3 is the absolute minimum) and Python 2.5.x or 2.6.x on Windows, Linux and MacOS X. It has not yet been tested with Python 3.x, but it should only require minor changes.
417 PythonQt requires at least Qt 4.6.1 (for earlier Qt versions, you will need to run the pythonqt_gerenator, Qt 4.3 is the absolute minimum) and Python 2.5.x or 2.6.x on Windows, Linux and MacOS X. It has not yet been tested with Python 3.x, but it should only require minor changes.
418 To compile PythonQt, you will need a python developer installation which includes Python's header files and
418 To compile PythonQt, you will need a python developer installation which includes Python's header files and
419 the python2x.[lib | dll | so | dynlib].
419 the python2x.[lib | dll | so | dynlib].
420 The build scripts a currently set to use Python 2.6.
420 The build scripts a currently set to use Python 2.6.
421 You may need to tweak the \b build/python.prf file to set the correct Python includes and libs on your system.
421 You may need to tweak the \b build/python.prf file to set the correct Python includes and libs on your system.
422
422
423 \note In addition to the qmake profiles, PythonQt now offers building via Cmake. Just use the provided
424 CMakeLists.txt in the root directory of the project. This build option has not been well tested yet.
425
423 \subsection Windows
426 \subsection Windows
424
427
425 On Windows, the (non-source) Python Windows installer can be used.
428 On Windows, the (non-source) Python Windows installer can be used.
426 Make sure that you use the same compiler, the current Python distribution is built
429 Make sure that you use the same compiler, the current Python distribution is built
427 with Visual Studio 2003. If you want to use another compiler, you will need to build
430 with Visual Studio 2003. If you want to use another compiler, you will need to build
428 Python yourself, using your compiler.
431 Python yourself, using your compiler.
429
432
430 To build PythonQt, you need to set the environment variable \b PYTHON_PATH to point to the root
433 To build PythonQt, you need to set the environment variable \b PYTHON_PATH to point to the root
431 dir of the python installation and \b PYTHON_LIB to point to
434 dir of the python installation and \b PYTHON_LIB to point to
432 the directory where the python lib file is located.
435 the directory where the python lib file is located.
433
436
434 When using the prebuild Python installer, this will be:
437 When using the prebuild Python installer, this will be:
435
438
436 \code
439 \code
437 > set PYTHON_PATH = c:\Python26
440 > set PYTHON_PATH = c:\Python26
438 > set PYTHON_LIB = c:\Python26\libs
441 > set PYTHON_LIB = c:\Python26\libs
439 \endcode
442 \endcode
440
443
441 When using the python sources, this will be something like:
444 When using the python sources, this will be something like:
442
445
443 \code
446 \code
444 > set PYTHON_PATH = c:\yourDir\Python-2.6.1\
447 > set PYTHON_PATH = c:\yourDir\Python-2.6.1\
445 > set PYTHON_LIB = c:\yourDir\Python-2.6.1\PCbuild8\Win32
448 > set PYTHON_LIB = c:\yourDir\Python-2.6.1\PCbuild8\Win32
446 \endcode
449 \endcode
447
450
448 To build all, do the following (after setting the above variables):
451 To build all, do the following (after setting the above variables):
449
452
450 \code
453 \code
451 > cd PythonQtRoot
454 > cd PythonQtRoot
452 > vcvars32
455 > vcvars32
453 > qmake
456 > qmake
454 > nmake
457 > nmake
455 \endcode
458 \endcode
456
459
457 This should build everything. If Python can not be linked or include files can not be found,
460 This should build everything. If Python can not be linked or include files can not be found,
458 you probably need to tweak \b build/python.prf
461 you probably need to tweak \b build/python.prf
459
462
460 The tests and examples are located in PythonQt/lib.
463 The tests and examples are located in PythonQt/lib.
461
464
462 \subsection Linux
465 \subsection Linux
463
466
464 On Linux, you need to install a Python-dev package.
467 On Linux, you need to install a Python-dev package.
465 If Python can not be linked or include files can not be found,
468 If Python can not be linked or include files can not be found,
466 you probably need to tweak \b build/python.prf
469 you probably need to tweak \b build/python.prf
467
470
468 To build PythonQt, just do a:
471 To build PythonQt, just do a:
469
472
470 \code
473 \code
471 > cd PythonQtRoot
474 > cd PythonQtRoot
472 > qmake
475 > qmake
473 > make all
476 > make all
474 \endcode
477 \endcode
475
478
476 The tests and examples are located in PythonQt/lib.
479 The tests and examples are located in PythonQt/lib.
477 You should add PythonQt/lib to your LD_LIBRARY_PATH so that the runtime
480 You should add PythonQt/lib to your LD_LIBRARY_PATH so that the runtime
478 linker can find the *.so files.
481 linker can find the *.so files.
479
482
480 \subsection MacOsX
483 \subsection MacOsX
481
484
482 On Mac, Python is installed as a Framework, so you should not need to install it.
485 On Mac, Python is installed as a Framework, so you should not need to install it.
483 To build PythonQt, just do a:
486 To build PythonQt, just do a:
484
487
485 \code
488 \code
486 > cd PythonQtRoot
489 > cd PythonQtRoot
487 > qmake
490 > qmake
488 > make all
491 > make all
489 \endcode
492 \endcode
490
493
491 \section Tests
494 \section Tests
492
495
493 There is a unit test that tests most features of PythonQt, see the \b tests subdirectory for details.
496 There is a unit test that tests most features of PythonQt, see the \b tests subdirectory for details.
494
497
495 \page Examples Examples
498 \page Examples Examples
496
499
497 Examples are available in the \b examples directory. The PyScriptingConsole implements a simple
500 Examples are available in the \b examples directory. The PyScriptingConsole implements a simple
498 interactive scripting console that shows how to script a simple application. The PyLauncher application can be used to run arbitrary PythonQt scripts given on the commandline.
501 interactive scripting console that shows how to script a simple application. The PyLauncher application can be used to run arbitrary PythonQt scripts given on the commandline.
499
502
500 The following shows a simple example on how to integrate PythonQt into your Qt application:
503 The following shows a simple example on how to integrate PythonQt into your Qt application:
501
504
502 \code
505 \code
503 #include "PythonQt.h"
506 #include "PythonQt.h"
504 #include <QApplication>
507 #include <QApplication>
505 ...
508 ...
506
509
507 int main( int argc, char **argv )
510 int main( int argc, char **argv )
508 {
511 {
509
512
510 QApplication qapp(argc, argv);
513 QApplication qapp(argc, argv);
511
514
512 // init PythonQt and Python itself
515 // init PythonQt and Python itself
513 PythonQt::init();
516 PythonQt::init();
514
517
515 // get a smart pointer to the __main__ module of the Python interpreter
518 // get a smart pointer to the __main__ module of the Python interpreter
516 PythonQtObjectPtr context = PythonQt::self()->getMainModule();
519 PythonQtObjectPtr context = PythonQt::self()->getMainModule();
517
520
518 // add a QObject as variable of name "example" to the namespace of the __main__ module
521 // add a QObject as variable of name "example" to the namespace of the __main__ module
519 PyExampleObject example;
522 PyExampleObject example;
520 context.addObject("example", &example);
523 context.addObject("example", &example);
521
524
522 // do something
525 // do something
523 context.evalScript("print example");
526 context.evalScript("print example");
524 context.evalScript("def multiply(a,b):\n return a*b;\n");
527 context.evalScript("def multiply(a,b):\n return a*b;\n");
525 QVariantList args;
528 QVariantList args;
526 args << 42 << 47;
529 args << 42 << 47;
527 QVariant result = context.call("multiply", args);
530 QVariant result = context.call("multiply", args);
528 ...
531 ...
529 \endcode
532 \endcode
530
533
531
534
532 */
535 */
General Comments 0
You need to be logged in to leave comments. Login now