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

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

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