@@ -55,9 +55,9 | |||||
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 | In contrast to <a href="http://www.riverbankcomputing.co.uk/pyqt/">PyQt</a> , PythonQt is \b not a complete |
|
58 | The focus of PythonQt is on embedding Python into an existing C++ application, not on writing the whole | |
59 | Python wrapper around the complete Qt functionality. So if you are looking for a way to |
|
59 | application completely in Python. If you want to write your whole application in Python, | |
60 | write complete applications in Python using the Qt GUI, you should use PyQt. |
|
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! | |
@@ -66,21 +66,41 | |||||
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 Licensing |
|
|||
70 |
|
||||
71 | PythonQt is distributed under the LGPL license. |
|
|||
72 |
|
||||
73 | \section Download |
|
69 | \section Download | |
74 |
|
70 | |||
75 | 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 | |
76 | or download a tarball. |
|
72 | or download a tarball. | |
77 |
|
73 | |||
|
74 | \section Licensing | |||
|
75 | ||||
|
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. | |||
|
78 | ||||
|
79 | \section LicensingWrapper Licensing of Wrapper Generator | |||
|
80 | ||||
|
81 | The build system of PythonQt makes use of a modified version of the GPL'ed QtScript generator, | |||
|
82 | located in the "generator" directory. | |||
|
83 | ||||
|
84 | See http://labs.trolltech.com/page/Projects/QtScript/Generator for details on the original project. | |||
|
85 | Thanks a lot to the QtJambi guys and the QtScript Generator project for the C++ parser and | |||
|
86 | Qt typesystem files! | |||
|
87 | ||||
|
88 | The PythonQt wrappers generated by the generator located in the "generated_cpp" directory are distributed under the LGPL, | |||
|
89 | they are not restriced by the GPL. | |||
|
90 | ||||
|
91 | 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. | |||
|
93 | 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. | |||
|
95 | ||||
78 | \section Features |
|
96 | \section Features | |
79 |
|
97 | |||
80 | - Easy wrapping of Python objects from C++ with smart, reference-counting PythonQtObjectPtr. |
|
98 | The following are the built-in features of the PythonQt library: | |
81 | - Convenient conversions to/from QVariant for PythonQtObjectPtr. |
|
99 | ||
82 | - Access all \b slots, \b properties, children and registered enums of any QObject derived class from Python |
|
100 | - Access all \b slots, \b properties, children and registered enums of any QObject derived class from Python | |
83 | - Connecting Qt Signals to Python functions (both from within Python and from C++) |
|
101 | - 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. | |||
|
103 | - Convenient conversions to/from QVariant for PythonQtObjectPtr. | |||
84 | - Wrapping of C++ objects (which are not derived from QObject) via PythonQtCppWrapperFactory |
|
104 | - Wrapping of C++ objects (which are not derived from QObject) via PythonQtCppWrapperFactory | |
85 | - Extending C++ and QObject derived classes with additional slots, static methods and constructors (see Decorators) |
|
105 | - Extending C++ and QObject derived classes with additional slots, static methods and constructors (see Decorators) | |
86 | - StdOut/Err redirection to Qt signals instead of cout |
|
106 | - StdOut/Err redirection to Qt signals instead of cout | |
@@ -90,22 +110,50 | |||||
90 | - Support for Qt namespace (with all enumerators) |
|
110 | - Support for Qt namespace (with all enumerators) | |
91 | - All PythonQt wrapped objects support the dir() statement, so that you can see easily which attributes a QObject, CPP object or QVariant has |
|
111 | - All PythonQt wrapped objects support the dir() statement, so that you can see easily which attributes a QObject, CPP object or QVariant has | |
92 | - 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) |
|
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) | |
|
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) | |||
|
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) | |||
|
115 | - 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 | |||
|
117 | ||||
|
118 | \section FeaturesQtAll Features (with PythonQt_QtAll linked in) | |||
|
119 | ||||
|
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. | |||
|
121 | This offers the following features: | |||
|
122 | ||||
|
123 | - Complete Qt API wrapped and accessible | |||
|
124 | - The following modules are available as submodule of the PythonQt module: | |||
|
125 | - QtCore | |||
|
126 | - QtGui | |||
|
127 | - QtNetwork | |||
|
128 | - QtOpenGL | |||
|
129 | - QtSql | |||
|
130 | - QtSvg | |||
|
131 | - QtUiTools | |||
|
132 | - QtWebKit | |||
|
133 | - QtXml | |||
|
134 | - QtXmlPatterns | |||
|
135 | - (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 | |||
|
137 | - 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, ... | |||
|
139 | - Multiple inheritance support (e.g. QGraphicsTextItem is a QObject AND a QGraphicsItem, PythonQt will handle this well) | |||
|
140 | ||||
|
141 | \section Comparision Comparision with PyQt | |||
|
142 | ||||
|
143 | - PythonQt is not as Pythonic as PyQt in many details (e.g. operator mapping, pickling, translation support, ...) and it is maily 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 | |||
|
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) | |||
|
146 | - PythonQt does not auto-convert objects, e.g. when a QPainter expects a QBrush and you pass a QColor, it is rejected, you will need to write QBrush(QColor(1,2,3)) instead | |||
|
147 | - Probably there are lots of details that differ, I do not know PyQt that well to list them all. | |||
93 |
|
148 | |||
94 | \section Non-Features |
|
|||
95 |
|
||||
96 | Features that PythonQt does NOT support (and will not support): |
|
|||
97 |
|
||||
98 | - you can not derive from QObjects inside of Python, this would require wrapper generation like PyQt does |
|
|||
99 | - you can only script QObject derived classes, for normal C++ classes you need to create a PythonQtCppWrapperFactory and adequate wrapper classes or add decorator slots |
|
|||
100 | - you can not access normal member functions of QObjects, only slots and properties, because the \b moc does not store normal member functions in the MetaObject system |
|
|||
101 |
|
149 | |||
102 | \section Interface |
|
150 | \section Interface | |
103 |
|
151 | |||
104 | The main interface to PythonQt is the PythonQt singleton. |
|
152 | The main interface to PythonQt is the PythonQt singleton. | |
105 | PythonQt needs to be initialized via PythonQt::init() once. |
|
153 | PythonQt needs to be initialized via PythonQt::init() once. | |
106 | Afterwards you communicate with the singleton via PythonQt::self(). |
|
154 | Afterwards you communicate with the singleton via PythonQt::self(). | |
107 |
PythonQt offers a |
|
155 | PythonQt offers a complete Qt binding, which | |
108 |
needs to be enabled via PythonQt |
|
156 | needs to be enabled via PythonQt_QtAll::init(). | |
109 |
|
157 | |||
110 |
|
158 | |||
111 | \section Datatype Datatype Mapping |
|
159 | \section Datatype Datatype Mapping | |
@@ -127,7 +175,8 | |||||
127 | <tr><td>QVariantMap</td><td>dict of objects</td></tr> |
|
175 | <tr><td>QVariantMap</td><td>dict of objects</td></tr> | |
128 | <tr><td>QVariant</td><td>depends on type, see below</td></tr> |
|
176 | <tr><td>QVariant</td><td>depends on type, see below</td></tr> | |
129 | <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> |
|
177 | <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> | |
130 |
<tr><td>OwnRegisteredMetaType</td><td> |
|
178 | <tr><td>OwnRegisteredMetaType</td><td>C++ wrapper, optionally with additional information/wrapping provided by registerCPPClass()</td></tr> | |
|
179 | <tr><td>QList<AnyObject*></td><td>converts to a list of CPP wrappers</td></tr> | |||
131 | <tr><td>EnumType</td><td>integer (all enums that are known via the moc and the Qt namespace are supported)</td></tr> |
|
180 | <tr><td>EnumType</td><td>integer (all enums that are known via the moc and the Qt namespace are supported)</td></tr> | |
132 | <tr><td>QObject (and derived classes)</td><td>QObject wrapper</td></tr> |
|
181 | <tr><td>QObject (and derived classes)</td><td>QObject wrapper</td></tr> | |
133 | <tr><td>C++ object</td><td>CPP wrapper, either wrapped via PythonQtCppWrapperFactory or just decorated with decorators</td></tr> |
|
182 | <tr><td>C++ object</td><td>CPP wrapper, either wrapped via PythonQtCppWrapperFactory or just decorated with decorators</td></tr> | |
@@ -162,6 +211,7 | |||||
162 | In addition to this, the wrapped objects support |
|
211 | In addition to this, the wrapped objects support | |
163 | - className() - returns a string that reprents the classname of the QObject |
|
212 | - className() - returns a string that reprents the classname of the QObject | |
164 | - help() - shows all properties, slots, enums, decorator slots and constructors of the object, in a printable form |
|
213 | - help() - shows all properties, slots, enums, decorator slots and constructors of the object, in a printable form | |
|
214 | - delete() - deletes the object (use with care, especially if you passed the ownership to C++) | |||
165 | - connect(signal, function) - connect the signal of the given object to a python function |
|
215 | - connect(signal, function) - connect the signal of the given object to a python function | |
166 | - connect(signal, qobject, slot) - connect the signal of the given object to a slot of another QObject |
|
216 | - connect(signal, qobject, slot) - connect the signal of the given object to a slot of another QObject | |
167 | - disconnect(signal, function) - disconnect the signal of the given object from a python function |
|
217 | - disconnect(signal, function) - disconnect the signal of the given object from a python function | |
@@ -185,7 +235,7 | |||||
185 |
|
235 | |||
186 | \section CPP CPP Wrapping |
|
236 | \section CPP CPP Wrapping | |
187 |
|
237 | |||
188 | You can create dedicated wrapper QObject for any C++ class. This is done by deriving from PythonQtCppWrapperFactory |
|
238 | You can create dedicated wrapper QObjects for any C++ class. This is done by deriving from PythonQtCppWrapperFactory | |
189 |
and adding your factory via addWrapperFactory(). |
|
239 | and adding your factory via addWrapperFactory(). | |
190 | Whenever PythonQt encounters a CPP pointer (e.g. on a slot or signal) |
|
240 | Whenever PythonQt encounters a CPP pointer (e.g. on a slot or signal) | |
191 | and it does not known it as a QObject derived class, it will create a generic CPP wrapper. So even unknown C++ objects |
|
241 | and it does not known it as a QObject derived class, it will create a generic CPP wrapper. So even unknown C++ objects | |
@@ -194,33 +244,34 instance that enters Python. An alternative to a complete wrapper via the wrappe | |||||
194 |
|
244 | |||
195 | \section MetaObject Meta Object/Class access |
|
245 | \section MetaObject Meta Object/Class access | |
196 |
|
246 | |||
197 |
For each known C |
|
247 | For each known C++ class, PythonQt provides a Python class. These classes are visible | |
198 | inside of the "PythonQt" python module. |
|
248 | inside of the "PythonQt" python module or in subpackages if a package is given when the class is registered. | |
199 |
|
249 | |||
200 | A Meta class supports: |
|
250 | A Meta class supports: | |
201 |
|
251 | |||
202 | - access to all declared enum values |
|
252 | - access to all declared enum values | |
203 | - constructors |
|
253 | - constructors | |
204 | - static decorator slots |
|
254 | - static methods | |
|
255 | - unbound non-static methods | |||
205 | - help() and className() |
|
256 | - help() and className() | |
206 |
|
257 | |||
207 |
From within Python, you can import the module "PythonQt" to access these |
|
258 | From within Python, you can import the module "PythonQt" to access these classes and the Qt namespace. | |
208 |
|
259 | |||
209 | \code |
|
260 | \code | |
210 |
from PythonQt import |
|
261 | from PythonQt import QtCore | |
211 |
|
262 | |||
212 | # namespace access: |
|
263 | # namespace access: | |
213 | print Qt.AlignLeft |
|
264 | print QtCore.Qt.AlignLeft | |
214 |
|
265 | |||
215 | # constructors |
|
266 | # constructors | |
216 | a = QSize(12,13) |
|
267 | a = QtCore.QSize(12,13) | |
217 | b = QFont() |
|
268 | b = QtCore.QFont() | |
218 |
|
269 | |||
219 | # static method |
|
270 | # static method | |
220 | QDate.currentDate() |
|
271 | QtCore.QDate.currentDate() | |
221 |
|
272 | |||
222 | # enum value |
|
273 | # enum value | |
223 | QFont.UltraCondensed |
|
274 | QtCore.QFont.UltraCondensed | |
224 |
|
275 | |||
225 | \endcode |
|
276 | \endcode | |
226 |
|
277 | |||
@@ -243,7 +294,6 The basic idea about decorators is to create a QObject derived class that implem | |||||
243 | which take one of the above roles (e.g. constructor, destructor etc.) via a naming convention. |
|
294 | which take one of the above roles (e.g. constructor, destructor etc.) via a naming convention. | |
244 | These slots are then assigned to other classes via the naming convention. |
|
295 | These slots are then assigned to other classes via the naming convention. | |
245 |
|
296 | |||
246 | - QVariant new_SomeClassName(...) - defines a constructor for "SomeClassName" that returns a QVariant |
|
|||
247 | - 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) |
|
297 | - 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) | |
248 | - void delete_SomeClassName(SomeClassName* o) - defines a destructor, which should delete the passed in object o |
|
298 | - void delete_SomeClassName(SomeClassName* o) - defines a destructor, which should delete the passed in object o | |
249 | - anything static_SomeClassName_someMethodName(...) - defines a static method that is callable on instances and the meta class |
|
299 | - anything static_SomeClassName_someMethodName(...) - defines a static method that is callable on instances and the meta class | |
@@ -272,8 +322,8 class ExampleDecorator : public QObject | |||||
272 | Q_OBJECT |
|
322 | Q_OBJECT | |
273 |
|
323 | |||
274 | public slots: |
|
324 | public slots: | |
275 |
// add a constructor to QSize |
|
325 | // add a constructor to QSize that takes a QPoint | |
276 |
Q |
|
326 | QSize* new_QSize(const QPoint& p) { return new QSize(p.x(), p.y()); } | |
277 |
|
327 | |||
278 | // add a constructor for QPushButton that takes a text and a parent widget |
|
328 | // add a constructor for QPushButton that takes a text and a parent widget | |
279 | QPushButton* new_QPushButton(const QString& text, QWidget* parent=NULL) { return new QPushButton(text, parent); } |
|
329 | QPushButton* new_QPushButton(const QString& text, QWidget* parent=NULL) { return new QPushButton(text, parent); } | |
@@ -300,8 +350,7 public slots: | |||||
300 | ... |
|
350 | ... | |
301 |
|
351 | |||
302 | PythonQt::self()->addDecorators(new ExampleDecorator()); |
|
352 | PythonQt::self()->addDecorators(new ExampleDecorator()); | |
303 |
PythonQt::self()->registerC |
|
353 | PythonQt::self()->registerCPPClass("YourCPPObject"); | |
304 | PythonQt::self()->registerCPPClassNames(QStringList() << "YourCPPObject"); |
|
|||
305 |
|
354 | |||
306 | \endcode |
|
355 | \endcode | |
307 |
|
356 | |||
@@ -309,13 +358,13 After you have registered an instance of the above ExampleDecorator, you can do | |||||
309 | (all these calls are mapped to the above decorator slots): |
|
358 | (all these calls are mapped to the above decorator slots): | |
310 |
|
359 | |||
311 | \code |
|
360 | \code | |
312 | from PythonQt import * |
|
361 | from PythonQt import QtCore, QtGui, YourCPPObject | |
313 |
|
362 | |||
314 | # call our new constructor of QSize |
|
363 | # call our new constructor of QSize | |
315 | size = QSize(QPoint(1,2)); |
|
364 | size = QtCore.QSize(QPoint(1,2)); | |
316 |
|
365 | |||
317 | # call our new QPushButton constructor |
|
366 | # call our new QPushButton constructor | |
318 | button = QPushButton("sometext"); |
|
367 | button = QtGui.QPushButton("sometext"); | |
319 |
|
368 | |||
320 | # call the move slot (overload1) |
|
369 | # call the move slot (overload1) | |
321 | button.move(QPoint(0,0)) |
|
370 | button.move(QPoint(0,0)) | |
@@ -324,7 +373,7 button.move(QPoint(0,0)) | |||||
324 | button.move(0,0) |
|
373 | button.move(0,0) | |
325 |
|
374 | |||
326 | # call the static method |
|
375 | # call the static method | |
327 | grabber = QWidget.mouseWrapper(); |
|
376 | grabber = QtGui.QWidget.mouseWrapper(); | |
328 |
|
377 | |||
329 | # create a CPP object via constructor |
|
378 | # create a CPP object via constructor | |
330 | yourCpp = YourCPPObject(1,11.5) |
|
379 | yourCpp = YourCPPObject(1,11.5) | |
@@ -437,6 +486,7 the python2x.[lib | dll | so | dynlib]. | |||||
437 | // init PythonQt and Python itself |
|
486 | // init PythonQt and Python itself | |
438 | PythonQt::init(PythonQt::IgnoreSiteModule | PythonQt::RedirectStdOut); |
|
487 | PythonQt::init(PythonQt::IgnoreSiteModule | PythonQt::RedirectStdOut); | |
439 |
|
488 | |||
|
489 | ||||
440 | // get a smart pointer to the __main__ module of the Python interpreter |
|
490 | // get a smart pointer to the __main__ module of the Python interpreter | |
441 | PythonQtObjectPtr mainContext = PythonQt::self()->getMainModule(); |
|
491 | PythonQtObjectPtr mainContext = PythonQt::self()->getMainModule(); | |
442 |
|
492 | |||
@@ -444,11 +494,6 the python2x.[lib | dll | so | dynlib]. | |||||
444 | PyExampleObject example; |
|
494 | PyExampleObject example; | |
445 | PythonQt::self()->addObject(mainContext, "example", &example); |
|
495 | PythonQt::self()->addObject(mainContext, "example", &example); | |
446 |
|
496 | |||
447 | // register all other QObjects that you want to script and that are returned by your API |
|
|||
448 | PythonQt::self()->registerClass(&QMainWindow::staticMetaObject); |
|
|||
449 | PythonQt::self()->registerClass(&QPushButton::staticMetaObject); |
|
|||
450 | ... |
|
|||
451 |
|
||||
452 | // do something |
|
497 | // do something | |
453 | PythonQt::self()->runScript(mainContext, "print example\n"); |
|
498 | PythonQt::self()->runScript(mainContext, "print example\n"); | |
454 | PythonQt::self()->runScript(mainContext, "def multiply(a,b):\n return a*b;\n"); |
|
499 | PythonQt::self()->runScript(mainContext, "def multiply(a,b):\n return a*b;\n"); |
General Comments 0
You need to be logged in to leave comments.
Login now