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

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

started to update/improve docs...
florianlink -
r32:ae159b178ea0
parent child
Show More
Show file before | Show file after | Hide comments
@@ -55,32 +55,52
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!
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 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 default binding for the complete QWidget set, which
155 PythonQt offers a complete Qt binding, which
108 needs to be enabled via PythonQtGui::init().
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>variant wrapper, optionally with a wrapper provided by addVariantWrapper()</td></tr>
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,8 +235,8
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
192 can be passed through Python. If the wrapper factory supports the CPP class, a QObject wrapper will be created for each
242 can be passed through Python. If the wrapper factory supports the CPP class, a QObject wrapper will be created for each
@@ -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 CPP class, QObject derived class and QVariant type, PythonQt provides a Meta class. These meta classes are visible
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 meta objects and the Qt namespace.
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 variant that takes a QPoint
325 // add a constructor to QSize that takes a QPoint
276 QVariant new_QSize(const QPoint& p) { return QSize(p.x(), p.y()); }
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()->registerClass(&QPushButton::staticMetaObject);
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