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

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

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