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

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

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