@@ -55,9 +55,9 | |||
|
55 | 55 | It offers an easy way to embed the Python scripting language into |
|
56 | 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 | |
|
59 | Python wrapper around the complete Qt functionality. So if you are looking for a way to | |
|
60 | write complete applications in Python using the Qt GUI, you should use PyQt. | |
|
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, | |
|
60 | you should use <a href="http://www.riverbankcomputing.co.uk/pyqt/">PyQt</a> instead. | |
|
61 | 61 | |
|
62 | 62 | If you are looking for a simple way to embed Python objects into your C++/Qt Application |
|
63 | 63 |
and to script parts of your application via Python, PythonQt is the way to go! |
@@ -66,21 +66,41 | |||
|
66 | 66 | Image Processing and Visualization platform MeVisLab (http://www.mevislab.de) |
|
67 | 67 | scriptable from Python. |
|
68 | 68 | |
|
69 | \section Licensing | |
|
70 | ||
|
71 | PythonQt is distributed under the LGPL license. | |
|
72 | ||
|
73 | 69 | \section Download |
|
74 | 70 | |
|
75 | 71 | PythonQt is hosted on SourceForge at http://sourceforge.net/projects/pythonqt , you can access it via SVN |
|
76 | 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 | 96 | \section Features |
|
79 | 97 | |
|
80 | - Easy wrapping of Python objects from C++ with smart, reference-counting PythonQtObjectPtr. | |
|
81 | - Convenient conversions to/from QVariant for PythonQtObjectPtr. | |
|
98 | The following are the built-in features of the PythonQt library: | |
|
99 | ||
|
82 | 100 | - Access all \b slots, \b properties, children and registered enums of any QObject derived class from Python |
|
83 | 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 | 104 | - Wrapping of C++ objects (which are not derived from QObject) via PythonQtCppWrapperFactory |
|
85 | 105 | - Extending C++ and QObject derived classes with additional slots, static methods and constructors (see Decorators) |
|
86 | 106 | - StdOut/Err redirection to Qt signals instead of cout |
@@ -90,22 +110,50 | |||
|
90 | 110 | - Support for Qt namespace (with all enumerators) |
|
91 | 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 | 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 | 150 | \section Interface |
|
103 | 151 | |
|
104 | 152 | The main interface to PythonQt is the PythonQt singleton. |
|
105 | 153 | PythonQt needs to be initialized via PythonQt::init() once. |
|
106 | 154 | Afterwards you communicate with the singleton via PythonQt::self(). |
|
107 |
PythonQt offers a |
|
|
108 |
needs to be enabled via PythonQt |
|
|
155 | PythonQt offers a complete Qt binding, which | |
|
156 | needs to be enabled via PythonQt_QtAll::init(). | |
|
109 | 157 | |
|
110 | 158 | |
|
111 | 159 | \section Datatype Datatype Mapping |
@@ -127,7 +175,8 | |||
|
127 | 175 | <tr><td>QVariantMap</td><td>dict of objects</td></tr> |
|
128 | 176 | <tr><td>QVariant</td><td>depends on type, see below</td></tr> |
|
129 | 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 | 180 | <tr><td>EnumType</td><td>integer (all enums that are known via the moc and the Qt namespace are supported)</td></tr> |
|
132 | 181 | <tr><td>QObject (and derived classes)</td><td>QObject wrapper</td></tr> |
|
133 | 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 | 211 | In addition to this, the wrapped objects support |
|
163 | 212 | - className() - returns a string that reprents the classname of the QObject |
|
164 | 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 | 215 | - connect(signal, function) - connect the signal of the given object to a python function |
|
166 | 216 | - connect(signal, qobject, slot) - connect the signal of the given object to a slot of another QObject |
|
167 | 217 | - disconnect(signal, function) - disconnect the signal of the given object from a python function |
@@ -185,7 +235,7 | |||
|
185 | 235 | |
|
186 | 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 | 239 |
and adding your factory via addWrapperFactory(). |
|
190 | 240 | Whenever PythonQt encounters a CPP pointer (e.g. on a slot or signal) |
|
191 | 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 | 245 | \section MetaObject Meta Object/Class access |
|
196 | 246 | |
|
197 |
For each known C |
|
|
198 | inside of the "PythonQt" python module. | |
|
247 | For each known C++ class, PythonQt provides a Python class. These classes are visible | |
|
248 | inside of the "PythonQt" python module or in subpackages if a package is given when the class is registered. | |
|
199 | 249 | |
|
200 | 250 | A Meta class supports: |
|
201 | 251 | |
|
202 | 252 | - access to all declared enum values |
|
203 | 253 | - constructors |
|
204 | - static decorator slots | |
|
254 | - static methods | |
|
255 | - unbound non-static methods | |
|
205 | 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 | 260 | \code |
|
210 |
from PythonQt import |
|
|
261 | from PythonQt import QtCore | |
|
211 | 262 | |
|
212 | 263 | # namespace access: |
|
213 | print Qt.AlignLeft | |
|
264 | print QtCore.Qt.AlignLeft | |
|
214 | 265 | |
|
215 | 266 | # constructors |
|
216 | a = QSize(12,13) | |
|
217 | b = QFont() | |
|
267 | a = QtCore.QSize(12,13) | |
|
268 | b = QtCore.QFont() | |
|
218 | 269 | |
|
219 | 270 | # static method |
|
220 | QDate.currentDate() | |
|
271 | QtCore.QDate.currentDate() | |
|
221 | 272 | |
|
222 | 273 | # enum value |
|
223 | QFont.UltraCondensed | |
|
274 | QtCore.QFont.UltraCondensed | |
|
224 | 275 | |
|
225 | 276 | \endcode |
|
226 | 277 | |
@@ -243,7 +294,6 The basic idea about decorators is to create a QObject derived class that implem | |||
|
243 | 294 | which take one of the above roles (e.g. constructor, destructor etc.) via a naming convention. |
|
244 | 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 | 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 | 298 | - void delete_SomeClassName(SomeClassName* o) - defines a destructor, which should delete the passed in object o |
|
249 | 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 | 322 | Q_OBJECT |
|
273 | 323 | |
|
274 | 324 | public slots: |
|
275 |
// add a constructor to QSize |
|
|
276 |
Q |
|
|
325 | // add a constructor to QSize that takes a QPoint | |
|
326 | QSize* new_QSize(const QPoint& p) { return new QSize(p.x(), p.y()); } | |
|
277 | 327 | |
|
278 | 328 | // add a constructor for QPushButton that takes a text and a parent widget |
|
279 | 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 | 352 | PythonQt::self()->addDecorators(new ExampleDecorator()); |
|
303 |
PythonQt::self()->registerC |
|
|
304 | PythonQt::self()->registerCPPClassNames(QStringList() << "YourCPPObject"); | |
|
353 | PythonQt::self()->registerCPPClass("YourCPPObject"); | |
|
305 | 354 | |
|
306 | 355 | \endcode |
|
307 | 356 | |
@@ -309,13 +358,13 After you have registered an instance of the above ExampleDecorator, you can do | |||
|
309 | 358 | (all these calls are mapped to the above decorator slots): |
|
310 | 359 | |
|
311 | 360 | \code |
|
312 | from PythonQt import * | |
|
361 | from PythonQt import QtCore, QtGui, YourCPPObject | |
|
313 | 362 | |
|
314 | 363 | # call our new constructor of QSize |
|
315 | size = QSize(QPoint(1,2)); | |
|
364 | size = QtCore.QSize(QPoint(1,2)); | |
|
316 | 365 | |
|
317 | 366 | # call our new QPushButton constructor |
|
318 | button = QPushButton("sometext"); | |
|
367 | button = QtGui.QPushButton("sometext"); | |
|
319 | 368 | |
|
320 | 369 | # call the move slot (overload1) |
|
321 | 370 | button.move(QPoint(0,0)) |
@@ -324,7 +373,7 button.move(QPoint(0,0)) | |||
|
324 | 373 | button.move(0,0) |
|
325 | 374 | |
|
326 | 375 | # call the static method |
|
327 | grabber = QWidget.mouseWrapper(); | |
|
376 | grabber = QtGui.QWidget.mouseWrapper(); | |
|
328 | 377 | |
|
329 | 378 | # create a CPP object via constructor |
|
330 | 379 | yourCpp = YourCPPObject(1,11.5) |
@@ -437,6 +486,7 the python2x.[lib | dll | so | dynlib]. | |||
|
437 | 486 | // init PythonQt and Python itself |
|
438 | 487 | PythonQt::init(PythonQt::IgnoreSiteModule | PythonQt::RedirectStdOut); |
|
439 | 488 | |
|
489 | ||
|
440 | 490 | // get a smart pointer to the __main__ module of the Python interpreter |
|
441 | 491 | PythonQtObjectPtr mainContext = PythonQt::self()->getMainModule(); |
|
442 | 492 | |
@@ -444,11 +494,6 the python2x.[lib | dll | so | dynlib]. | |||
|
444 | 494 | PyExampleObject example; |
|
445 | 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 | 497 | // do something |
|
453 | 498 | PythonQt::self()->runScript(mainContext, "print example\n"); |
|
454 | 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