##// END OF EJS Templates
updated license info...
florianlink -
r89:48cbcd0dff79
parent child
Show More
@@ -1,510 +1,509
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) 2006 MeVis Research GmbH All Rights Reserved.
6 * Copyright (C) 2006 MeVis Research GmbH 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 Research GmbH, Universitaetsallee 29,
29 * Contact information: MeVis Research GmbH, 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 PythonQt Overview
49 \mainpage PythonQt Overview
50 \endif
50 \endif
51
51
52 \section Introduction
52 \section Introduction
53
53
54 \b PythonQt is a dynamic Python (http://www.python.org) binding for Qt (http://www.qtsoftware.com).
54 \b PythonQt is a dynamic Python (http://www.python.org) binding for Qt (http://www.qtsoftware.com).
55 It offers an easy way to embed the Python scripting language into
55 It offers an easy way to embed the Python scripting language into
56 your Qt applications. It makes heavy use of the QMetaObject system and thus requires Qt4.x.
56 your Qt applications. It makes heavy use of the QMetaObject system and thus requires Qt4.x.
57
57
58 The focus of PythonQt is on embedding Python into an existing C++ application, not on writing the whole
58 The focus of PythonQt is on embedding Python into an existing C++ application, not on writing the whole
59 application completely in Python. If you want to write your whole application in Python,
59 application completely in Python. If you want to write your whole application in Python,
60 you should use <a href="http://www.riverbankcomputing.co.uk/pyqt/">PyQt</a> instead.
60 you should use <a href="http://www.riverbankcomputing.co.uk/pyqt/">PyQt</a> instead.
61
61
62 If you are looking for a simple way to embed Python objects into your C++/Qt Application
62 If you are looking for a simple way to embed Python objects into your C++/Qt Application
63 and to script parts of your application via Python, PythonQt is the way to go!
63 and to script parts of your application via Python, PythonQt is the way to go!
64
64
65 PythonQt is a stable library that was developed to make the
65 PythonQt is a stable library that was developed to make the
66 Image Processing and Visualization platform MeVisLab (http://www.mevislab.de)
66 Image Processing and Visualization platform MeVisLab (http://www.mevislab.de)
67 scriptable from Python.
67 scriptable from Python.
68
68
69 \section Download
69 \section Download
70
70
71 PythonQt is hosted on SourceForge at http://sourceforge.net/projects/pythonqt , you can access it via SVN
71 PythonQt is hosted on SourceForge at http://sourceforge.net/projects/pythonqt , you can access it via SVN
72 or download a tarball.
72 or download a tarball.
73
73
74 \section Licensing
74 \section Licensing
75
75
76 PythonQt is distributed under the LGPL license, so it pairs well with the LGPL of the Qt 4.5 release and allows
76 PythonQt is distributed under the LGPL license, so it pairs well with the LGPL of the Qt 4.5 release and allows
77 to be used in commercial applications when following the LGPL 2.1 obligations.
77 to be used in commercial applications when following the LGPL 2.1 obligations.
78
78
79 \section LicensingWrapper Licensing of Wrapper Generator
79 \section LicensingWrapper Licensing of Wrapper Generator
80
80
81 The build system of PythonQt makes use of a modified version of the GPL'ed QtScript generator,
81 The build system of PythonQt makes use of a modified version of the LGPL'ed QtScript generator,
82 located in the "generator" directory.
82 located in the "generator" directory.
83
83
84 See http://labs.trolltech.com/page/Projects/QtScript/Generator for details on the original project.
84 See http://qt.gitorious.org/qt-labs/qtscriptgenerator for details on the original project.
85 Thanks a lot to the QtJambi guys and the QtScript Generator project for the C++ parser and
85 Thanks a lot to the QtJambi guys and the QtScript Generator project for the C++ parser and
86 Qt typesystem files!
86 Qt typesystem files!
87
87
88 The PythonQt wrappers generated by the generator located in the "generated_cpp" directory are distributed under the LGPL,
88 The PythonQt wrappers generated by the generator located in the "generated_cpp" directory are distributed under the LGPL as well.
89 they are not restriced by the GPL.
90
89
91 The generated wrappers are pre-generated and checked-in for Qt 4.4.3, so you only need to build and run the
90 The generated wrappers are pre-generated and checked-in for Qt 4.4.3, so you only need to build and run the
92 generator when you want to build additional wrappers or you want to upgrade/downgrade to an newer Qt version.
91 generator when you want to build additional wrappers or you want to upgrade/downgrade to an newer Qt version.
93 You may use the generator to generate C++ bindings for your own C++ classes (e.g. to make them deriveable in Python),
92 You may use the generator to generate C++ bindings for your own C++ classes (e.g. to make them deriveable in Python),
94 , but this is currently not documented and involves creating your own typesystem files.
93 , but this is currently not documented and involves creating your own typesystem files.
95
94
96 \section Features
95 \section Features
97
96
98 The following are the built-in features of the PythonQt library:
97 The following are the built-in features of the PythonQt library:
99
98
100 - Access all \b slots, \b properties, children and registered enums of any QObject derived class from Python
99 - Access all \b slots, \b properties, children and registered enums of any QObject derived class from Python
101 - Connecting Qt Signals to Python functions (both from within Python and from C++)
100 - Connecting Qt Signals to Python functions (both from within Python and from C++)
102 - Easy wrapping of Python objects from C++ with smart, reference-counting PythonQtObjectPtr.
101 - Easy wrapping of Python objects from C++ with smart, reference-counting PythonQtObjectPtr.
103 - Convenient conversions to/from QVariant for PythonQtObjectPtr.
102 - Convenient conversions to/from QVariant for PythonQtObjectPtr.
104 - Wrapping of C++ objects (which are not derived from QObject) via PythonQtCppWrapperFactory
103 - Wrapping of C++ objects (which are not derived from QObject) via PythonQtCppWrapperFactory
105 - Extending C++ and QObject derived classes with additional slots, static methods and constructors (see Decorators)
104 - Extending C++ and QObject derived classes with additional slots, static methods and constructors (see Decorators)
106 - StdOut/Err redirection to Qt signals instead of cout
105 - StdOut/Err redirection to Qt signals instead of cout
107 - Interface for creating your own \c import replacement, so that Python scripts can be e.g. signed/verified before they are executed (PythonQtImportFileInterface)
106 - Interface for creating your own \c import replacement, so that Python scripts can be e.g. signed/verified before they are executed (PythonQtImportFileInterface)
108 - Mapping of plain-old-datatypes and ALL QVariant types to and from Python
107 - Mapping of plain-old-datatypes and ALL QVariant types to and from Python
109 - Support for wrapping of user QVariant types which are registerd via QMetaType
108 - Support for wrapping of user QVariant types which are registerd via QMetaType
110 - Support for Qt namespace (with all enumerators)
109 - Support for Qt namespace (with all enumerators)
111 - All PythonQt wrapped objects support the dir() statement, so that you can see easily which attributes a QObject, CPP object or QVariant has
110 - All PythonQt wrapped objects support the dir() statement, so that you can see easily which attributes a QObject, CPP object or QVariant has
112 - 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)
111 - 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)
113 - 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)
112 - 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)
114 - 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)
113 - 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)
115 - Deriving C++ objects from Python and overwriting virtual method with a Python implementation (requires usage of wrapper generator or manual work!)
114 - Deriving C++ objects from Python and overwriting virtual method with a Python implementation (requires usage of wrapper generator or manual work!)
116 - Extensible handler for Python/C++ conversion of complex types, e.g. mapping of QVector<SomeObject> to/from a Python array
115 - Extensible handler for Python/C++ conversion of complex types, e.g. mapping of QVector<SomeObject> to/from a Python array
117
116
118 \section FeaturesQtAll Features (with PythonQt_QtAll linked in)
117 \section FeaturesQtAll Features (with PythonQt_QtAll linked in)
119
118
120 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.
119 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.
121 This offers the following features:
120 This offers the following features:
122
121
123 - Complete Qt API wrapped and accessible
122 - Complete Qt API wrapped and accessible
124 - The following modules are available as submodule of the PythonQt module:
123 - The following modules are available as submodule of the PythonQt module:
125 - QtCore
124 - QtCore
126 - QtGui
125 - QtGui
127 - QtNetwork
126 - QtNetwork
128 - QtOpenGL
127 - QtOpenGL
129 - QtSql
128 - QtSql
130 - QtSvg
129 - QtSvg
131 - QtUiTools
130 - QtUiTools
132 - QtWebKit
131 - QtWebKit
133 - QtXml
132 - QtXml
134 - QtXmlPatterns
133 - QtXmlPatterns
135 - (phonon, QtHelp, assistant, designer are currently not supported, this would require some additional effort on the code generator)
134 - (phonon, QtHelp, assistant, designer are currently not supported, this would require some additional effort on the code generator)
136 - 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
135 - 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
137 - Any Qt class that has virtual methods can be easily derived from Python and the virtual methods can be reimplemented in Python
136 - Any Qt class that has virtual methods can be easily derived from Python and the virtual methods can be reimplemented in Python
138 - Polymorphic downcasting on QEvent, QGraphicsItem, QStyleOption, ...
137 - Polymorphic downcasting on QEvent, QGraphicsItem, QStyleOption, ...
139 - Multiple inheritance support (e.g. QGraphicsTextItem is a QObject AND a QGraphicsItem, PythonQt will handle this well)
138 - Multiple inheritance support (e.g. QGraphicsTextItem is a QObject AND a QGraphicsItem, PythonQt will handle this well)
140
139
141 \section Comparision Comparision with PyQt
140 \section Comparision Comparision with PyQt
142
141
143 - PythonQt is not as Pythonic as PyQt in many details (e.g. operator mapping, pickling, translation support, ...) and it is mainly thought for embedding and intercommunication between Qt/Cpp and Python
142 - PythonQt is not as Pythonic as PyQt in many details (e.g. operator mapping, pickling, translation support, ...) and it is mainly thought for embedding and intercommunication between Qt/Cpp and Python
144 - 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
143 - 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
145 - 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)
144 - 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)
146 - PythonQt does not support instanceof checks for Qt classes, except for the exact match and derived Python classes
145 - PythonQt does not support instanceof checks for Qt classes, except for the exact match and derived Python classes
147 - QObject.emit to emit Qt signals from Python is not yet implemented but PythonQt allows to just emit a signal by calling it
146 - QObject.emit to emit Qt signals from Python is not yet implemented but PythonQt allows to just emit a signal by calling it
148 - PythonQt does not offer to add new signals to Python/C++ objects
147 - PythonQt does not offer to add new signals to Python/C++ objects
149 - Ownership of objects is a bit different in PythonQt, currently Python classes derived from a C++ class need to be manually references in PythonQt to not get deleted too early (this will be fixed)
148 - Ownership of objects is a bit different in PythonQt, currently Python classes derived from a C++ class need to be manually references in PythonQt to not get deleted too early (this will be fixed)
150 - Probably there are lots of details that differ, I do not know PyQt that well to list them all.
149 - Probably there are lots of details that differ, I do not know PyQt that well to list them all.
151
150
152
151
153 \section Interface
152 \section Interface
154
153
155 The main interface to PythonQt is the PythonQt singleton.
154 The main interface to PythonQt is the PythonQt singleton.
156 PythonQt needs to be initialized via PythonQt::init() once.
155 PythonQt needs to be initialized via PythonQt::init() once.
157 Afterwards you communicate with the singleton via PythonQt::self().
156 Afterwards you communicate with the singleton via PythonQt::self().
158 PythonQt offers a complete Qt binding, which
157 PythonQt offers a complete Qt binding, which
159 needs to be enabled via PythonQt_QtAll::init().
158 needs to be enabled via PythonQt_QtAll::init().
160
159
161
160
162 \section Datatype Datatype Mapping
161 \section Datatype Datatype Mapping
163
162
164 The following table shows the mapping between Python and Qt objects:
163 The following table shows the mapping between Python and Qt objects:
165 <table>
164 <table>
166 <tr><th>Qt/C++</th><th>Python</th></tr>
165 <tr><th>Qt/C++</th><th>Python</th></tr>
167 <tr><td>bool</td><td>bool</td></tr>
166 <tr><td>bool</td><td>bool</td></tr>
168 <tr><td>double</td><td>float</td></tr>
167 <tr><td>double</td><td>float</td></tr>
169 <tr><td>float</td><td>float</td></tr>
168 <tr><td>float</td><td>float</td></tr>
170 <tr><td>char/uchar,int/uint,short,ushort,QChar</td><td>integer</td></tr>
169 <tr><td>char/uchar,int/uint,short,ushort,QChar</td><td>integer</td></tr>
171 <tr><td>long</td><td>integer</td></tr>
170 <tr><td>long</td><td>integer</td></tr>
172 <tr><td>ulong,longlong,ulonglong</td><td>long</td></tr>
171 <tr><td>ulong,longlong,ulonglong</td><td>long</td></tr>
173 <tr><td>QString</td><td>unicode string</td></tr>
172 <tr><td>QString</td><td>unicode string</td></tr>
174 <tr><td>QByteArray</td><td>str</td></tr>
173 <tr><td>QByteArray</td><td>str</td></tr>
175 <tr><td>char*</td><td>str</td></tr>
174 <tr><td>char*</td><td>str</td></tr>
176 <tr><td>QStringList</td><td>tuple of unicode strings</td></tr>
175 <tr><td>QStringList</td><td>tuple of unicode strings</td></tr>
177 <tr><td>QVariantList</td><td>tuple of objects</td></tr>
176 <tr><td>QVariantList</td><td>tuple of objects</td></tr>
178 <tr><td>QVariantMap</td><td>dict of objects</td></tr>
177 <tr><td>QVariantMap</td><td>dict of objects</td></tr>
179 <tr><td>QVariant</td><td>depends on type, see below</td></tr>
178 <tr><td>QVariant</td><td>depends on type, see below</td></tr>
180 <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>
179 <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>
181 <tr><td>OwnRegisteredMetaType</td><td>C++ wrapper, optionally with additional information/wrapping provided by registerCPPClass()</td></tr>
180 <tr><td>OwnRegisteredMetaType</td><td>C++ wrapper, optionally with additional information/wrapping provided by registerCPPClass()</td></tr>
182 <tr><td>QList<AnyObject*></td><td>converts to a list of CPP wrappers</td></tr>
181 <tr><td>QList<AnyObject*></td><td>converts to a list of CPP wrappers</td></tr>
183 <tr><td>EnumType</td><td>integer (all enums that are known via the moc and the Qt namespace are supported)</td></tr>
182 <tr><td>EnumType</td><td>integer (all enums that are known via the moc and the Qt namespace are supported)</td></tr>
184 <tr><td>QObject (and derived classes)</td><td>QObject wrapper</td></tr>
183 <tr><td>QObject (and derived classes)</td><td>QObject wrapper</td></tr>
185 <tr><td>C++ object</td><td>CPP wrapper, either wrapped via PythonQtCppWrapperFactory or just decorated with decorators</td></tr>
184 <tr><td>C++ object</td><td>CPP wrapper, either wrapped via PythonQtCppWrapperFactory or just decorated with decorators</td></tr>
186 <tr><td>PyObject</td><td>PyObject</td></tr>
185 <tr><td>PyObject</td><td>PyObject</td></tr>
187 </table>
186 </table>
188
187
189 PyObject is passed as simple pointer, which allows to pass/return any Python Object directly to/from
188 PyObject is passed as simple pointer, which allows to pass/return any Python Object directly to/from
190 a Qt slot.
189 a Qt slot.
191 QVariants are mapped recursively as given above, e.g. a dictionary can
190 QVariants are mapped recursively as given above, e.g. a dictionary can
192 contain lists of dictionaries of doubles.
191 contain lists of dictionaries of doubles.
193 For example a QVariant of type "String" is mapped to a python unicode string.
192 For example a QVariant of type "String" is mapped to a python unicode string.
194 All Qt QVariant types are implemented, PythonQt supports the complete Qt API for these object.
193 All Qt QVariant types are implemented, PythonQt supports the complete Qt API for these object.
195
194
196 \section QObject QObject Wrapping
195 \section QObject QObject Wrapping
197
196
198 All classes derived from QObject are automatically wrapped with a python wrapper class
197 All classes derived from QObject are automatically wrapped with a python wrapper class
199 when they become visible to the Python interpreter. This can happen via
198 when they become visible to the Python interpreter. This can happen via
200 - the PythonQt::addObject() method
199 - the PythonQt::addObject() method
201 - when a Qt \b slot returns a QObject derived object to python
200 - when a Qt \b slot returns a QObject derived object to python
202 - when a Qt \b signal contains a QObject and is connected to a python function
201 - when a Qt \b signal contains a QObject and is connected to a python function
203
202
204 It is important that you call PythonQt::registerClass() for any QObject derived class
203 It is important that you call PythonQt::registerClass() for any QObject derived class
205 that may become visible to Python, except when you add it via PythonQt::addObject().
204 that may become visible to Python, except when you add it via PythonQt::addObject().
206 This will register the complete parent hierachy of the registered class, so that
205 This will register the complete parent hierachy of the registered class, so that
207 when you register e.g. a QPushButton, QWidget will be registered as well (and all intermediate
206 when you register e.g. a QPushButton, QWidget will be registered as well (and all intermediate
208 parents).
207 parents).
209
208
210 From Python, you can talk to the returned QObjects in a natural way by calling
209 From Python, you can talk to the returned QObjects in a natural way by calling
211 their slots and receiving the return values. You can also read/write all
210 their slots and receiving the return values. You can also read/write all
212 properties of the objects as if they where normal python properties.
211 properties of the objects as if they where normal python properties.
213
212
214 In addition to this, the wrapped objects support
213 In addition to this, the wrapped objects support
215 - className() - returns a string that reprents the classname of the QObject
214 - className() - returns a string that reprents the classname of the QObject
216 - help() - shows all properties, slots, enums, decorator slots and constructors of the object, in a printable form
215 - help() - shows all properties, slots, enums, decorator slots and constructors of the object, in a printable form
217 - delete() - deletes the object (use with care, especially if you passed the ownership to C++)
216 - delete() - deletes the object (use with care, especially if you passed the ownership to C++)
218 - connect(signal, function) - connect the signal of the given object to a python function
217 - connect(signal, function) - connect the signal of the given object to a python function
219 - connect(signal, qobject, slot) - connect the signal of the given object to a slot of another QObject
218 - connect(signal, qobject, slot) - connect the signal of the given object to a slot of another QObject
220 - disconnect(signal, function) - disconnect the signal of the given object from a python function
219 - disconnect(signal, function) - disconnect the signal of the given object from a python function
221 - disconnect(signal, qobject, slot) - disconnect the signal of the given object from a slot of another QObject
220 - disconnect(signal, qobject, slot) - disconnect the signal of the given object from a slot of another QObject
222 - children() - returns the children of the object
221 - children() - returns the children of the object
223 - setParent(QObject) - set the parent
222 - setParent(QObject) - set the parent
224 - QObject* parent() - get the parent
223 - QObject* parent() - get the parent
225
224
226 The below example shows how to connect signals in Python:
225 The below example shows how to connect signals in Python:
227
226
228 \code
227 \code
229 # define a signal handler function
228 # define a signal handler function
230 def someFunction(flag):
229 def someFunction(flag):
231 print flag
230 print flag
232
231
233 # button1 is a QPushButton that has been added to Python via addObject()
232 # button1 is a QPushButton that has been added to Python via addObject()
234 # connect the clicked signal to a python function:
233 # connect the clicked signal to a python function:
235 button1.connect("clicked(bool)", someFunction)
234 button1.connect("clicked(bool)", someFunction)
236
235
237 \endcode
236 \endcode
238
237
239 \section CPP CPP Wrapping
238 \section CPP CPP Wrapping
240
239
241 You can create dedicated wrapper QObjects for any C++ class. This is done by deriving from PythonQtCppWrapperFactory
240 You can create dedicated wrapper QObjects for any C++ class. This is done by deriving from PythonQtCppWrapperFactory
242 and adding your factory via addWrapperFactory().
241 and adding your factory via addWrapperFactory().
243 Whenever PythonQt encounters a CPP pointer (e.g. on a slot or signal)
242 Whenever PythonQt encounters a CPP pointer (e.g. on a slot or signal)
244 and it does not known it as a QObject derived class, it will create a generic CPP wrapper. So even unknown C++ objects
243 and it does not known it as a QObject derived class, it will create a generic CPP wrapper. So even unknown C++ objects
245 can be passed through Python. If the wrapper factory supports the CPP class, a QObject wrapper will be created for each
244 can be passed through Python. If the wrapper factory supports the CPP class, a QObject wrapper will be created for each
246 instance that enters Python. An alternative to a complete wrapper via the wrapper factory are decorators, see \ref Decorators
245 instance that enters Python. An alternative to a complete wrapper via the wrapper factory are decorators, see \ref Decorators
247
246
248 \section MetaObject Meta Object/Class access
247 \section MetaObject Meta Object/Class access
249
248
250 For each known C++ class, PythonQt provides a Python class. These classes are visible
249 For each known C++ class, PythonQt provides a Python class. These classes are visible
251 inside of the "PythonQt" python module or in subpackages if a package is given when the class is registered.
250 inside of the "PythonQt" python module or in subpackages if a package is given when the class is registered.
252
251
253 A Meta class supports:
252 A Meta class supports:
254
253
255 - access to all declared enum values
254 - access to all declared enum values
256 - constructors
255 - constructors
257 - static methods
256 - static methods
258 - unbound non-static methods
257 - unbound non-static methods
259 - help() and className()
258 - help() and className()
260
259
261 From within Python, you can import the module "PythonQt" to access these classes and the Qt namespace.
260 From within Python, you can import the module "PythonQt" to access these classes and the Qt namespace.
262
261
263 \code
262 \code
264 from PythonQt import QtCore
263 from PythonQt import QtCore
265
264
266 # namespace access:
265 # namespace access:
267 print QtCore.Qt.AlignLeft
266 print QtCore.Qt.AlignLeft
268
267
269 # constructors
268 # constructors
270 a = QtCore.QSize(12,13)
269 a = QtCore.QSize(12,13)
271 b = QtCore.QFont()
270 b = QtCore.QFont()
272
271
273 # static method
272 # static method
274 QtCore.QDate.currentDate()
273 QtCore.QDate.currentDate()
275
274
276 # enum value
275 # enum value
277 QtCore.QFont.UltraCondensed
276 QtCore.QFont.UltraCondensed
278
277
279 \endcode
278 \endcode
280
279
281 \section Decorators Decorator slots
280 \section Decorators Decorator slots
282
281
283 PythonQt introduces a new generic approach to extend any wrapped QObject or CPP object with
282 PythonQt introduces a new generic approach to extend any wrapped QObject or CPP object with
284
283
285 - constructors
284 - constructors
286 - destructors (for CPP objects)
285 - destructors (for CPP objects)
287 - additional slots
286 - additional slots
288 - static slots (callable on both the Meta object and the instances)
287 - static slots (callable on both the Meta object and the instances)
289
288
290 The idea behind decorators is that we wanted to make it as easy as possible to extend
289 The idea behind decorators is that we wanted to make it as easy as possible to extend
291 wrapped objects. Since we already have an implementation for invoking any Qt Slot from
290 wrapped objects. Since we already have an implementation for invoking any Qt Slot from
292 Python, it looked promising to use this approach for the extension of wrapped objects as well.
291 Python, it looked promising to use this approach for the extension of wrapped objects as well.
293 This avoids that the PythonQt user needs to care about how Python arguments are mapped from/to
292 This avoids that the PythonQt user needs to care about how Python arguments are mapped from/to
294 Qt when he wants to create static methods, constructors and additional member functions.
293 Qt when he wants to create static methods, constructors and additional member functions.
295
294
296 The basic idea about decorators is to create a QObject derived class that implements slots
295 The basic idea about decorators is to create a QObject derived class that implements slots
297 which take one of the above roles (e.g. constructor, destructor etc.) via a naming convention.
296 which take one of the above roles (e.g. constructor, destructor etc.) via a naming convention.
298 These slots are then assigned to other classes via the naming convention.
297 These slots are then assigned to other classes via the naming convention.
299
298
300 - 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)
299 - 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)
301 - void delete_SomeClassName(SomeClassName* o) - defines a destructor, which should delete the passed in object o
300 - void delete_SomeClassName(SomeClassName* o) - defines a destructor, which should delete the passed in object o
302 - anything static_SomeClassName_someMethodName(...) - defines a static method that is callable on instances and the meta class
301 - anything static_SomeClassName_someMethodName(...) - defines a static method that is callable on instances and the meta class
303 - 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.
302 - 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.
304
303
305 The below example shows all kinds of decorators in action:
304 The below example shows all kinds of decorators in action:
306
305
307 \code
306 \code
308
307
309 // an example CPP object
308 // an example CPP object
310 class YourCPPObject {
309 class YourCPPObject {
311 public:
310 public:
312 YourCPPObject(int arg1, float arg2) { a = arg1; b = arg2; }
311 YourCPPObject(int arg1, float arg2) { a = arg1; b = arg2; }
313
312
314 float doSomething(int arg1) { return arg1*a*b; };
313 float doSomething(int arg1) { return arg1*a*b; };
315
314
316 private:
315 private:
317
316
318 int a;
317 int a;
319 float b;
318 float b;
320 };
319 };
321
320
322 // an example decorator
321 // an example decorator
323 class ExampleDecorator : public QObject
322 class ExampleDecorator : public QObject
324 {
323 {
325 Q_OBJECT
324 Q_OBJECT
326
325
327 public slots:
326 public slots:
328 // add a constructor to QSize that takes a QPoint
327 // add a constructor to QSize that takes a QPoint
329 QSize* new_QSize(const QPoint& p) { return new QSize(p.x(), p.y()); }
328 QSize* new_QSize(const QPoint& p) { return new QSize(p.x(), p.y()); }
330
329
331 // add a constructor for QPushButton that takes a text and a parent widget
330 // add a constructor for QPushButton that takes a text and a parent widget
332 QPushButton* new_QPushButton(const QString& text, QWidget* parent=NULL) { return new QPushButton(text, parent); }
331 QPushButton* new_QPushButton(const QString& text, QWidget* parent=NULL) { return new QPushButton(text, parent); }
333
332
334 // add a constructor for a CPP object
333 // add a constructor for a CPP object
335 YourCPPObject* new_YourCPPObject(int arg1, float arg2) { return new YourCPPObject(arg1, arg2); }
334 YourCPPObject* new_YourCPPObject(int arg1, float arg2) { return new YourCPPObject(arg1, arg2); }
336
335
337 // add a destructor for a CPP object
336 // add a destructor for a CPP object
338 void delete_YourCPPObject(YourCPPObject* obj) { delete obj; }
337 void delete_YourCPPObject(YourCPPObject* obj) { delete obj; }
339
338
340 // add a static method to QWidget
339 // add a static method to QWidget
341 QWidget* static_QWidget_mouseGrabber() { return QWidget::mouseGrabber(); }
340 QWidget* static_QWidget_mouseGrabber() { return QWidget::mouseGrabber(); }
342
341
343 // add an additional slot to QWidget (make move() callable, which is not declared as a slot in QWidget)
342 // add an additional slot to QWidget (make move() callable, which is not declared as a slot in QWidget)
344 void move(QWidget* w, const QPoint& p) { w->move(p); }
343 void move(QWidget* w, const QPoint& p) { w->move(p); }
345
344
346 // add an additional slot to QWidget, overloading the above move method
345 // add an additional slot to QWidget, overloading the above move method
347 void move(QWidget* w, int x, int y) { w->move(x,y); }
346 void move(QWidget* w, int x, int y) { w->move(x,y); }
348
347
349 // add a method to your own CPP object
348 // add a method to your own CPP object
350 int doSomething(YourCPPObject* obj, int arg1) { return obj->doSomething(arg1); }
349 int doSomething(YourCPPObject* obj, int arg1) { return obj->doSomething(arg1); }
351 };
350 };
352
351
353 ...
352 ...
354
353
355 PythonQt::self()->addDecorators(new ExampleDecorator());
354 PythonQt::self()->addDecorators(new ExampleDecorator());
356 PythonQt::self()->registerCPPClass("YourCPPObject");
355 PythonQt::self()->registerCPPClass("YourCPPObject");
357
356
358 \endcode
357 \endcode
359
358
360 After you have registered an instance of the above ExampleDecorator, you can do the following from Python
359 After you have registered an instance of the above ExampleDecorator, you can do the following from Python
361 (all these calls are mapped to the above decorator slots):
360 (all these calls are mapped to the above decorator slots):
362
361
363 \code
362 \code
364 from PythonQt import QtCore, QtGui, YourCPPObject
363 from PythonQt import QtCore, QtGui, YourCPPObject
365
364
366 # call our new constructor of QSize
365 # call our new constructor of QSize
367 size = QtCore.QSize(QPoint(1,2));
366 size = QtCore.QSize(QPoint(1,2));
368
367
369 # call our new QPushButton constructor
368 # call our new QPushButton constructor
370 button = QtGui.QPushButton("sometext");
369 button = QtGui.QPushButton("sometext");
371
370
372 # call the move slot (overload1)
371 # call the move slot (overload1)
373 button.move(QPoint(0,0))
372 button.move(QPoint(0,0))
374
373
375 # call the move slot (overload2)
374 # call the move slot (overload2)
376 button.move(0,0)
375 button.move(0,0)
377
376
378 # call the static method
377 # call the static method
379 grabber = QtGui.QWidget.mouseWrapper();
378 grabber = QtGui.QWidget.mouseWrapper();
380
379
381 # create a CPP object via constructor
380 # create a CPP object via constructor
382 yourCpp = YourCPPObject(1,11.5)
381 yourCpp = YourCPPObject(1,11.5)
383
382
384 # call the wrapped method on CPP object
383 # call the wrapped method on CPP object
385 print yourCpp.doSomething(1);
384 print yourCpp.doSomething(1);
386
385
387 # destructor will be called:
386 # destructor will be called:
388 yourCpp = None
387 yourCpp = None
389
388
390 \endcode
389 \endcode
391
390
392 \section Building
391 \section Building
393
392
394 PythonQt requires at least Qt 4.2.2 (or higher) and Python 2.3, 2.4, 2.5 or 2.6 on Windows, Linux and MacOS X. It has not yet been tested with Python 3.x, but it should only require minor changes.
393 PythonQt requires at least Qt 4.2.2 (or higher) and Python 2.3, 2.4, 2.5 or 2.6 on Windows, Linux and MacOS X. It has not yet been tested with Python 3.x, but it should only require minor changes.
395 To compile PythonQt, you will need a python developer installation which includes Python's header files and
394 To compile PythonQt, you will need a python developer installation which includes Python's header files and
396 the python2x.[lib | dll | so | dynlib].
395 the python2x.[lib | dll | so | dynlib].
397 The build scripts a currently set to use Python 2.5.
396 The build scripts a currently set to use Python 2.5.
398 You may need to tweak the \b build/python.prf file to set the correct Python includes and libs on your system.
397 You may need to tweak the \b build/python.prf file to set the correct Python includes and libs on your system.
399
398
400 \subsection Windows
399 \subsection Windows
401
400
402 On Windows, the (non-source) Python Windows installer can be used.
401 On Windows, the (non-source) Python Windows installer can be used.
403 Make sure that you use the same compiler, the current Python distribution is built
402 Make sure that you use the same compiler, the current Python distribution is built
404 with Visual Studio 2003. If you want to use another compiler, you will need to build
403 with Visual Studio 2003. If you want to use another compiler, you will need to build
405 Python yourself, using your compiler.
404 Python yourself, using your compiler.
406
405
407 To build PythonQt, you need to set the environment variable \b PYTHON_PATH to point to the root
406 To build PythonQt, you need to set the environment variable \b PYTHON_PATH to point to the root
408 dir of the python installation and \b PYTHON_LIB to point to
407 dir of the python installation and \b PYTHON_LIB to point to
409 the directory where the python lib file is located.
408 the directory where the python lib file is located.
410
409
411 When using the prebuild Python installer, this will be:
410 When using the prebuild Python installer, this will be:
412
411
413 \code
412 \code
414 > set PYTHON_PATH = c:\Python25
413 > set PYTHON_PATH = c:\Python25
415 > set PYTHON_LIB = c:\Python25\libs
414 > set PYTHON_LIB = c:\Python25\libs
416 \endcode
415 \endcode
417
416
418 When using the python sources, this will be something like:
417 When using the python sources, this will be something like:
419
418
420 \code
419 \code
421 > set PYTHON_PATH = c:\yourDir\Python-2.5.1\
420 > set PYTHON_PATH = c:\yourDir\Python-2.5.1\
422 > set PYTHON_LIB = c:\yourDir\Python-2.5.1\PCbuild8\Win32
421 > set PYTHON_LIB = c:\yourDir\Python-2.5.1\PCbuild8\Win32
423 \endcode
422 \endcode
424
423
425 To build all, do the following (after setting the above variables):
424 To build all, do the following (after setting the above variables):
426
425
427 \code
426 \code
428 > cd PythonQtRoot
427 > cd PythonQtRoot
429 > vcvars32
428 > vcvars32
430 > qmake
429 > qmake
431 > nmake
430 > nmake
432 \endcode
431 \endcode
433
432
434 This should build everything. If Python can not be linked or include files can not be found,
433 This should build everything. If Python can not be linked or include files can not be found,
435 you probably need to tweak \b build/python.prf
434 you probably need to tweak \b build/python.prf
436
435
437 The tests and examples are located in PythonQt/lib.
436 The tests and examples are located in PythonQt/lib.
438
437
439 \subsection Linux
438 \subsection Linux
440
439
441 On Linux, you need to install a Python-dev package.
440 On Linux, you need to install a Python-dev package.
442 If Python can not be linked or include files can not be found,
441 If Python can not be linked or include files can not be found,
443 you probably need to tweak \b build/python.prf
442 you probably need to tweak \b build/python.prf
444
443
445 To build PythonQt, just do a:
444 To build PythonQt, just do a:
446
445
447 \code
446 \code
448 > cd PythonQtRoot
447 > cd PythonQtRoot
449 > qmake
448 > qmake
450 > make all
449 > make all
451 \endcode
450 \endcode
452
451
453 The tests and examples are located in PythonQt/lib.
452 The tests and examples are located in PythonQt/lib.
454 You should add PythonQt/lib to your LD_LIBRARY_PATH so that the runtime
453 You should add PythonQt/lib to your LD_LIBRARY_PATH so that the runtime
455 linker can find the *.so files.
454 linker can find the *.so files.
456
455
457 \subsection MacOsX
456 \subsection MacOsX
458
457
459 On Mac, Python is installed as a Framework, so you should not need to install it.
458 On Mac, Python is installed as a Framework, so you should not need to install it.
460 To build PythonQt, just do a:
459 To build PythonQt, just do a:
461
460
462 \code
461 \code
463 > cd PythonQtRoot
462 > cd PythonQtRoot
464 > qmake
463 > qmake
465 > make all
464 > make all
466 \endcode
465 \endcode
467
466
468 \section Tests
467 \section Tests
469
468
470 There is a unit test that tests most features of PythonQt, see the \b tests subdirectory for details.
469 There is a unit test that tests most features of PythonQt, see the \b tests subdirectory for details.
471
470
472 \section Examples
471 \section Examples
473
472
474 Examples are available in the \b examples directory. The PyScriptingConsole implements a simple
473 Examples are available in the \b examples directory. The PyScriptingConsole implements a simple
475 interactive scripting console that shows how to script a simple application.
474 interactive scripting console that shows how to script a simple application.
476
475
477 The following shows how to integrate PythonQt into you Qt application:
476 The following shows how to integrate PythonQt into you Qt application:
478
477
479 \code
478 \code
480 #include "PythonQt.h"
479 #include "PythonQt.h"
481 #include <QApplication>
480 #include <QApplication>
482 ...
481 ...
483
482
484 int main( int argc, char **argv )
483 int main( int argc, char **argv )
485 {
484 {
486
485
487 QApplication qapp(argc, argv);
486 QApplication qapp(argc, argv);
488
487
489 // init PythonQt and Python itself
488 // init PythonQt and Python itself
490 PythonQt::init(PythonQt::IgnoreSiteModule | PythonQt::RedirectStdOut);
489 PythonQt::init(PythonQt::IgnoreSiteModule | PythonQt::RedirectStdOut);
491
490
492
491
493 // get a smart pointer to the __main__ module of the Python interpreter
492 // get a smart pointer to the __main__ module of the Python interpreter
494 PythonQtObjectPtr mainContext = PythonQt::self()->getMainModule();
493 PythonQtObjectPtr mainContext = PythonQt::self()->getMainModule();
495
494
496 // add a QObject as variable of name "example" to the namespace of the __main__ module
495 // add a QObject as variable of name "example" to the namespace of the __main__ module
497 PyExampleObject example;
496 PyExampleObject example;
498 PythonQt::self()->addObject(mainContext, "example", &example);
497 PythonQt::self()->addObject(mainContext, "example", &example);
499
498
500 // do something
499 // do something
501 PythonQt::self()->runScript(mainContext, "print example\n");
500 PythonQt::self()->runScript(mainContext, "print example\n");
502 PythonQt::self()->runScript(mainContext, "def multiply(a,b):\n return a*b;\n");
501 PythonQt::self()->runScript(mainContext, "def multiply(a,b):\n return a*b;\n");
503 QVariantList args;
502 QVariantList args;
504 args << 42 << 47;
503 args << 42 << 47;
505 QVariant result = PythonQt::self()->call(mainContext,"multiply", args);
504 QVariant result = PythonQt::self()->call(mainContext,"multiply", args);
506 ...
505 ...
507 \endcode
506 \endcode
508
507
509
508
510 */
509 */
General Comments 0
You need to be logged in to leave comments. Login now