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

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

updated docs...
florianlink -
r149:2c08e22f6b54
parent child
Show More
Show file before | Show file after | Hide comments
@@ -1,525 +1,532
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
74 - \ref Download
75 - \ref License
76 - \ref Developer
77 - \ref Building
78 - \ref Examples
79
73 \page Features Features
80 \page Features Features
74
81
75 \section Builtin Built-in Features
82 \section Builtin Built-in Features
76
83
77 The following are the built-in features of the PythonQt library:
84 The following are the built-in features of the PythonQt library:
78
85
79 - 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
80 - 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++)
81 - 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.
82 - Convenient conversions to/from QVariant for PythonQtObjectPtr.
89 - Convenient conversions to/from QVariant for PythonQtObjectPtr.
83 - 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
84 - 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)
85 - StdOut/Err redirection to Qt signals instead of cout
92 - StdOut/Err redirection to Qt signals instead of cout
86 - 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)
87 - 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
88 - 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
89 - Support for Qt namespace (with all enumerators)
96 - Support for Qt namespace (with all enumerators)
90 - 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
91 - 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)
92 - 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)
93 - 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)
94 - 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!)
95 - 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
96 - 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)
97
104
98 \section FeaturesQtAll Features with wrapper generator
105 \section FeaturesQtAll Features with wrapper generator
99
106
100 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.
101 This offers the following features:
108 This offers the following features:
102
109
103 - Complete Qt API wrapped and accessible
110 - Complete Qt API wrapped and accessible
104 - The following modules are available as submodules of the PythonQt module:
111 - The following modules are available as submodules of the PythonQt module:
105 - QtCore
112 - QtCore
106 - QtGui
113 - QtGui
107 - QtNetwork
114 - QtNetwork
108 - QtOpenGL
115 - QtOpenGL
109 - QtSql
116 - QtSql
110 - QtSvg
117 - QtSvg
111 - QtUiTools
118 - QtUiTools
112 - QtWebKit
119 - QtWebKit
113 - QtXml
120 - QtXml
114 - (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)
115 - 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
116 - 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!)
117 - Polymorphic downcasting on QEvent, QGraphicsItem, QStyleOption, ...
124 - Polymorphic downcasting on QEvent, QGraphicsItem, QStyleOption, ...
118 - 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)
119
126
120 \section Comparison Comparison with PyQt/PySide
127 \section Comparison Comparison with PyQt/PySide
121
128
122 - 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
123 - 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
124 - 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)
125 - 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
126 - 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
127 - 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)
128 - 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)
129 - 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()
130 - 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.
131 - 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).
132 - 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.
133 - 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).
134
141
135 \page Download Download
142 \page Download Download
136
143
137 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>.
138
145
139 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/.
140 Alternatively you can get the latest version from the svn repository.
147 Alternatively you can get the latest version from the svn repository.
141
148
142 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/
143
150
144 \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
145 platforms (Windows/Linux/MacOs), architectures (32/64 bit) and Python versions.
152 platforms (Windows/Linux/MacOs), architectures (32/64 bit) and Python versions.
146
153
147 \page License License
154 \page License License
148
155
149 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
150 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.
151
158
152 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,
153 located in the "generator" directory.
160 located in the "generator" directory.
154
161
155 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.
156 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
157 Qt typesystem files!
164 Qt typesystem files!
158
165
159 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.
160
167
161 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
162 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.
163 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),
164 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).
165
172
166
173
167 \page Developer Developer
174 \page Developer Developer
168
175
169 \section Interface Interface
176 \section Interface Interface
170
177
171 The main interface to PythonQt is the PythonQt singleton.
178 The main interface to PythonQt is the PythonQt singleton.
172 PythonQt needs to be initialized via PythonQt::init() once.
179 PythonQt needs to be initialized via PythonQt::init() once.
173 Afterwards you communicate with the singleton via PythonQt::self().
180 Afterwards you communicate with the singleton via PythonQt::self().
174 PythonQt offers a complete Qt binding, which
181 PythonQt offers a complete Qt binding, which
175 needs to be enabled via PythonQt_QtAll::init().
182 needs to be enabled via PythonQt_QtAll::init().
176
183
177
184
178 \section Datatype Datatype Mapping
185 \section Datatype Datatype Mapping
179
186
180 The following table shows the mapping between Python and Qt objects:
187 The following table shows the mapping between Python and Qt objects:
181 <table>
188 <table>
182 <tr><th>Qt/C++</th><th>Python</th></tr>
189 <tr><th>Qt/C++</th><th>Python</th></tr>
183 <tr><td>bool</td><td>bool</td></tr>
190 <tr><td>bool</td><td>bool</td></tr>
184 <tr><td>double</td><td>float</td></tr>
191 <tr><td>double</td><td>float</td></tr>
185 <tr><td>float</td><td>float</td></tr>
192 <tr><td>float</td><td>float</td></tr>
186 <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>
187 <tr><td>long</td><td>integer</td></tr>
194 <tr><td>long</td><td>integer</td></tr>
188 <tr><td>ulong,longlong,ulonglong</td><td>long</td></tr>
195 <tr><td>ulong,longlong,ulonglong</td><td>long</td></tr>
189 <tr><td>QString</td><td>unicode string</td></tr>
196 <tr><td>QString</td><td>unicode string</td></tr>
190 <tr><td>QByteArray</td><td>QByteArray wrapper</td></tr>
197 <tr><td>QByteArray</td><td>QByteArray wrapper</td></tr>
191 <tr><td>char*</td><td>str</td></tr>
198 <tr><td>char*</td><td>str</td></tr>
192 <tr><td>QStringList</td><td>tuple of unicode strings</td></tr>
199 <tr><td>QStringList</td><td>tuple of unicode strings</td></tr>
193 <tr><td>QVariantList</td><td>tuple of objects</td></tr>
200 <tr><td>QVariantList</td><td>tuple of objects</td></tr>
194 <tr><td>QVariantMap</td><td>dict of objects</td></tr>
201 <tr><td>QVariantMap</td><td>dict of objects</td></tr>
195 <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>
196 <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>
197 <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>
198 <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>
199 <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>
200 <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>
201 <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>
202 <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>
203 <tr><td>PyObject</td><td>PyObject</td></tr>
210 <tr><td>PyObject</td><td>PyObject</td></tr>
204 </table>
211 </table>
205
212
206 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
207 a Qt slot that uses PyObject* as its argument/return value.
214 a Qt slot that uses PyObject* as its argument/return value.
208 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
209 contain lists of dictionaries of doubles.
216 contain lists of dictionaries of doubles.
210 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.
211
218
212 \section QObject QObject Wrapping
219 \section QObject QObject Wrapping
213
220
214 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
215 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
216 - the PythonQt::addObject() method
223 - the PythonQt::addObject() method
217 - 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
218 - 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
219
226
220 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
221 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().
222 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
223 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
224 parents).
231 parents).
225
232
226 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
227 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
228 properties of the objects as if they where normal python properties.
235 properties of the objects as if they where normal python properties.
229
236
230 In addition to this, the wrapped objects support
237 In addition to this, the wrapped objects support
231 - className() - returns a string that reprents the classname of the QObject
238 - className() - returns a string that reprents the classname of the QObject
232 - 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
233 - 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++)
234 - 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
235 - 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
236 - 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
237 - 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
238 - children() - returns the children of the object
245 - children() - returns the children of the object
239 - setParent(QObject) - set the parent
246 - setParent(QObject) - set the parent
240 - QObject* parent() - get the parent
247 - QObject* parent() - get the parent
241
248
242 The below example shows how to connect signals in Python:
249 The below example shows how to connect signals in Python:
243
250
244 \code
251 \code
245 # define a signal handler function
252 # define a signal handler function
246 def someFunction(flag):
253 def someFunction(flag):
247 print flag
254 print flag
248
255
249 # 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()
250 # connect the clicked signal to a python function:
257 # connect the clicked signal to a python function:
251 button1.connect("clicked(bool)", someFunction)
258 button1.connect("clicked(bool)", someFunction)
252
259
253 \endcode
260 \endcode
254
261
255 \section CPP CPP Wrapping
262 \section CPP CPP Wrapping
256
263
257 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
258 and adding your factory via addWrapperFactory().
265 and adding your factory via addWrapperFactory().
259 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)
260 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
261 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
262 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
263
270
264 \section MetaObject Meta Object/Class access
271 \section MetaObject Meta Object/Class access
265
272
266 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
267 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.
268
275
269 A Meta class supports:
276 A Meta class supports:
270
277
271 - access to all declared enum values
278 - access to all declared enum values
272 - constructors
279 - constructors
273 - static methods
280 - static methods
274 - unbound non-static methods
281 - unbound non-static methods
275 - help() and className()
282 - help() and className()
276
283
277 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.
278
285
279 \code
286 \code
280 from PythonQt import QtCore
287 from PythonQt import QtCore
281
288
282 # namespace access:
289 # namespace access:
283 print QtCore.Qt.AlignLeft
290 print QtCore.Qt.AlignLeft
284
291
285 # constructors
292 # constructors
286 a = QtCore.QSize(12,13)
293 a = QtCore.QSize(12,13)
287 b = QtCore.QFont()
294 b = QtCore.QFont()
288
295
289 # static method
296 # static method
290 QtCore.QDate.currentDate()
297 QtCore.QDate.currentDate()
291
298
292 # enum value
299 # enum value
293 QtCore.QFont.UltraCondensed
300 QtCore.QFont.UltraCondensed
294
301
295 \endcode
302 \endcode
296
303
297 \section Decorators Decorator slots
304 \section Decorators Decorator slots
298
305
299 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
300
307
301 - constructors
308 - constructors
302 - destructors (for CPP objects)
309 - destructors (for CPP objects)
303 - additional slots
310 - additional slots
304 - static slots (callable on both the Meta object and the instances)
311 - static slots (callable on both the Meta object and the instances)
305
312
306 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
307 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
308 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.
309 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
310 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.
311
318
312 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
313 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.
314 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.
315
322
316 - 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)
317 - 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
318 - 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
319 - 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.
320
327
321 The below example shows all kinds of decorators in action:
328 The below example shows all kinds of decorators in action:
322
329
323 \code
330 \code
324
331
325 // an example CPP object
332 // an example CPP object
326 class YourCPPObject {
333 class YourCPPObject {
327 public:
334 public:
328 YourCPPObject(int arg1, float arg2) { a = arg1; b = arg2; }
335 YourCPPObject(int arg1, float arg2) { a = arg1; b = arg2; }
329
336
330 float doSomething(int arg1) { return arg1*a*b; };
337 float doSomething(int arg1) { return arg1*a*b; };
331
338
332 private:
339 private:
333
340
334 int a;
341 int a;
335 float b;
342 float b;
336 };
343 };
337
344
338 // an example decorator
345 // an example decorator
339 class ExampleDecorator : public QObject
346 class ExampleDecorator : public QObject
340 {
347 {
341 Q_OBJECT
348 Q_OBJECT
342
349
343 public slots:
350 public slots:
344 // add a constructor to QSize that takes a QPoint
351 // add a constructor to QSize that takes a QPoint
345 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()); }
346
353
347 // 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
348 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); }
349
356
350 // add a constructor for a CPP object
357 // add a constructor for a CPP object
351 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); }
352
359
353 // add a destructor for a CPP object
360 // add a destructor for a CPP object
354 void delete_YourCPPObject(YourCPPObject* obj) { delete obj; }
361 void delete_YourCPPObject(YourCPPObject* obj) { delete obj; }
355
362
356 // add a static method to QWidget
363 // add a static method to QWidget
357 QWidget* static_QWidget_mouseGrabber() { return QWidget::mouseGrabber(); }
364 QWidget* static_QWidget_mouseGrabber() { return QWidget::mouseGrabber(); }
358
365
359 // 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)
360 void move(QWidget* w, const QPoint& p) { w->move(p); }
367 void move(QWidget* w, const QPoint& p) { w->move(p); }
361
368
362 // add an additional slot to QWidget, overloading the above move method
369 // add an additional slot to QWidget, overloading the above move method
363 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); }
364
371
365 // add a method to your own CPP object
372 // add a method to your own CPP object
366 int doSomething(YourCPPObject* obj, int arg1) { return obj->doSomething(arg1); }
373 int doSomething(YourCPPObject* obj, int arg1) { return obj->doSomething(arg1); }
367 };
374 };
368
375
369 ...
376 ...
370
377
371 PythonQt::self()->addDecorators(new ExampleDecorator());
378 PythonQt::self()->addDecorators(new ExampleDecorator());
372 PythonQt::self()->registerCPPClass("YourCPPObject");
379 PythonQt::self()->registerCPPClass("YourCPPObject");
373
380
374 \endcode
381 \endcode
375
382
376 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
377 (all these calls are mapped to the above decorator slots):
384 (all these calls are mapped to the above decorator slots):
378
385
379 \code
386 \code
380 from PythonQt import QtCore, QtGui, YourCPPObject
387 from PythonQt import QtCore, QtGui, YourCPPObject
381
388
382 # call our new constructor of QSize
389 # call our new constructor of QSize
383 size = QtCore.QSize(QPoint(1,2));
390 size = QtCore.QSize(QPoint(1,2));
384
391
385 # call our new QPushButton constructor
392 # call our new QPushButton constructor
386 button = QtGui.QPushButton("sometext");
393 button = QtGui.QPushButton("sometext");
387
394
388 # call the move slot (overload1)
395 # call the move slot (overload1)
389 button.move(QPoint(0,0))
396 button.move(QPoint(0,0))
390
397
391 # call the move slot (overload2)
398 # call the move slot (overload2)
392 button.move(0,0)
399 button.move(0,0)
393
400
394 # call the static method
401 # call the static method
395 grabber = QtGui.QWidget.mouseWrapper();
402 grabber = QtGui.QWidget.mouseWrapper();
396
403
397 # create a CPP object via constructor
404 # create a CPP object via constructor
398 yourCpp = YourCPPObject(1,11.5)
405 yourCpp = YourCPPObject(1,11.5)
399
406
400 # call the wrapped method on CPP object
407 # call the wrapped method on CPP object
401 print yourCpp.doSomething(1);
408 print yourCpp.doSomething(1);
402
409
403 # destructor will be called:
410 # destructor will be called:
404 yourCpp = None
411 yourCpp = None
405
412
406 \endcode
413 \endcode
407
414
408 \page Building Building
415 \page Building Building
409
416
410 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.
411 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
412 the python2x.[lib | dll | so | dynlib].
419 the python2x.[lib | dll | so | dynlib].
413 The build scripts a currently set to use Python 2.6.
420 The build scripts a currently set to use Python 2.6.
414 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.
415
422
416 \subsection Windows
423 \subsection Windows
417
424
418 On Windows, the (non-source) Python Windows installer can be used.
425 On Windows, the (non-source) Python Windows installer can be used.
419 Make sure that you use the same compiler, the current Python distribution is built
426 Make sure that you use the same compiler, the current Python distribution is built
420 with Visual Studio 2003. If you want to use another compiler, you will need to build
427 with Visual Studio 2003. If you want to use another compiler, you will need to build
421 Python yourself, using your compiler.
428 Python yourself, using your compiler.
422
429
423 To build PythonQt, you need to set the environment variable \b PYTHON_PATH to point to the root
430 To build PythonQt, you need to set the environment variable \b PYTHON_PATH to point to the root
424 dir of the python installation and \b PYTHON_LIB to point to
431 dir of the python installation and \b PYTHON_LIB to point to
425 the directory where the python lib file is located.
432 the directory where the python lib file is located.
426
433
427 When using the prebuild Python installer, this will be:
434 When using the prebuild Python installer, this will be:
428
435
429 \code
436 \code
430 > set PYTHON_PATH = c:\Python26
437 > set PYTHON_PATH = c:\Python26
431 > set PYTHON_LIB = c:\Python26\libs
438 > set PYTHON_LIB = c:\Python26\libs
432 \endcode
439 \endcode
433
440
434 When using the python sources, this will be something like:
441 When using the python sources, this will be something like:
435
442
436 \code
443 \code
437 > set PYTHON_PATH = c:\yourDir\Python-2.6.1\
444 > set PYTHON_PATH = c:\yourDir\Python-2.6.1\
438 > set PYTHON_LIB = c:\yourDir\Python-2.6.1\PCbuild8\Win32
445 > set PYTHON_LIB = c:\yourDir\Python-2.6.1\PCbuild8\Win32
439 \endcode
446 \endcode
440
447
441 To build all, do the following (after setting the above variables):
448 To build all, do the following (after setting the above variables):
442
449
443 \code
450 \code
444 > cd PythonQtRoot
451 > cd PythonQtRoot
445 > vcvars32
452 > vcvars32
446 > qmake
453 > qmake
447 > nmake
454 > nmake
448 \endcode
455 \endcode
449
456
450 This should build everything. If Python can not be linked or include files can not be found,
457 This should build everything. If Python can not be linked or include files can not be found,
451 you probably need to tweak \b build/python.prf
458 you probably need to tweak \b build/python.prf
452
459
453 The tests and examples are located in PythonQt/lib.
460 The tests and examples are located in PythonQt/lib.
454
461
455 \subsection Linux
462 \subsection Linux
456
463
457 On Linux, you need to install a Python-dev package.
464 On Linux, you need to install a Python-dev package.
458 If Python can not be linked or include files can not be found,
465 If Python can not be linked or include files can not be found,
459 you probably need to tweak \b build/python.prf
466 you probably need to tweak \b build/python.prf
460
467
461 To build PythonQt, just do a:
468 To build PythonQt, just do a:
462
469
463 \code
470 \code
464 > cd PythonQtRoot
471 > cd PythonQtRoot
465 > qmake
472 > qmake
466 > make all
473 > make all
467 \endcode
474 \endcode
468
475
469 The tests and examples are located in PythonQt/lib.
476 The tests and examples are located in PythonQt/lib.
470 You should add PythonQt/lib to your LD_LIBRARY_PATH so that the runtime
477 You should add PythonQt/lib to your LD_LIBRARY_PATH so that the runtime
471 linker can find the *.so files.
478 linker can find the *.so files.
472
479
473 \subsection MacOsX
480 \subsection MacOsX
474
481
475 On Mac, Python is installed as a Framework, so you should not need to install it.
482 On Mac, Python is installed as a Framework, so you should not need to install it.
476 To build PythonQt, just do a:
483 To build PythonQt, just do a:
477
484
478 \code
485 \code
479 > cd PythonQtRoot
486 > cd PythonQtRoot
480 > qmake
487 > qmake
481 > make all
488 > make all
482 \endcode
489 \endcode
483
490
484 \section Tests
491 \section Tests
485
492
486 There is a unit test that tests most features of PythonQt, see the \b tests subdirectory for details.
493 There is a unit test that tests most features of PythonQt, see the \b tests subdirectory for details.
487
494
488 \page Examples Examples
495 \page Examples Examples
489
496
490 Examples are available in the \b examples directory. The PyScriptingConsole implements a simple
497 Examples are available in the \b examples directory. The PyScriptingConsole implements a simple
491 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.
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.
492
499
493 The following shows a simple example on how to integrate PythonQt into your Qt application:
500 The following shows a simple example on how to integrate PythonQt into your Qt application:
494
501
495 \code
502 \code
496 #include "PythonQt.h"
503 #include "PythonQt.h"
497 #include <QApplication>
504 #include <QApplication>
498 ...
505 ...
499
506
500 int main( int argc, char **argv )
507 int main( int argc, char **argv )
501 {
508 {
502
509
503 QApplication qapp(argc, argv);
510 QApplication qapp(argc, argv);
504
511
505 // init PythonQt and Python itself
512 // init PythonQt and Python itself
506 PythonQt::init();
513 PythonQt::init();
507
514
508 // get a smart pointer to the __main__ module of the Python interpreter
515 // get a smart pointer to the __main__ module of the Python interpreter
509 PythonQtObjectPtr context = PythonQt::self()->getMainModule();
516 PythonQtObjectPtr context = PythonQt::self()->getMainModule();
510
517
511 // add a QObject as variable of name "example" to the namespace of the __main__ module
518 // add a QObject as variable of name "example" to the namespace of the __main__ module
512 PyExampleObject example;
519 PyExampleObject example;
513 context.addObject("example", &example);
520 context.addObject("example", &example);
514
521
515 // do something
522 // do something
516 context.evalScript("print example");
523 context.evalScript("print example");
517 context.evalScript("def multiply(a,b):\n return a*b;\n");
524 context.evalScript("def multiply(a,b):\n return a*b;\n");
518 QVariantList args;
525 QVariantList args;
519 args << 42 << 47;
526 args << 42 << 47;
520 QVariant result = context.call("multiply", args);
527 QVariant result = context.call("multiply", args);
521 ...
528 ...
522 \endcode
529 \endcode
523
530
524
531
525 */
532 */
General Comments 0
You need to be logged in to leave comments. Login now