PythonQtDoc.h
462 lines
| 17.9 KiB
| text/x-c
|
CLexer
/ src / PythonQtDoc.h
ezust
|
r0 | #ifndef _PYTHONQTDOC_H | ||
#define _PYTHONQTDOC_H | ||||
/* | ||||
* | ||||
* Copyright (C) 2006 MeVis Research GmbH All Rights Reserved. | ||||
* | ||||
* This library is free software; you can redistribute it and/or | ||||
* modify it under the terms of the GNU Lesser General Public | ||||
* License as published by the Free Software Foundation; either | ||||
* version 2.1 of the License, or (at your option) any later version. | ||||
* | ||||
* This library is distributed in the hope that it will be useful, | ||||
* but WITHOUT ANY WARRANTY; without even the implied warranty of | ||||
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||||
* Lesser General Public License for more details. | ||||
* | ||||
* Further, this software is distributed without any warranty that it is | ||||
* free of the rightful claim of any third person regarding infringement | ||||
* or the like. Any license provided herein, whether implied or | ||||
* otherwise, applies only to this software file. Patent licenses, if | ||||
* any, provided herein do not apply to combinations of this program with | ||||
* other software, or any other product whatsoever. | ||||
* | ||||
* You should have received a copy of the GNU Lesser General Public | ||||
* License along with this library; if not, write to the Free Software | ||||
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | ||||
* | ||||
* Contact information: MeVis Research GmbH, Universitaetsallee 29, | ||||
* 28359 Bremen, Germany or: | ||||
* | ||||
* http://www.mevis.de | ||||
* | ||||
*/ | ||||
//---------------------------------------------------------------------------------- | ||||
/*! | ||||
// \file PythonQtDoc.h | ||||
// \author Florian Link | ||||
// \author Last changed by $Author: florian $ | ||||
// \date 2006-10 | ||||
*/ | ||||
//---------------------------------------------------------------------------------- | ||||
/*! | ||||
\if USE_GLOBAL_DOXYGEN_DOC | ||||
\page PythonQtPage PythonQt Overview | ||||
\else | ||||
\mainpage PythonQt Overview | ||||
\endif | ||||
\section Introduction | ||||
\b PythonQt is a dynamic Python (http://www.python.org) binding for Qt (http://www.trolltech.com). | ||||
It offers an easy way to embedd the Python scripting language into | ||||
your Qt applications. It makes heavy use of the QMetaObject system and thus requires Qt4.x. | ||||
In contrast to <a href="http://www.riverbankcomputing.co.uk/pyqt/">PyQt</a> , PythonQt is \b not a complete | ||||
Python wrapper around the complete Qt functionality. So if you are looking for a way to | ||||
write complete applications in Python using the Qt GUI, you should use PyQt. | ||||
If you are looking for a simple way to embed the Python language into your Qt Application | ||||
and to script parts of your application via Python, PythonQt is the way to go! | ||||
PythonQt is a stable library that was developed to make the Image Processing and Visualization platform MeVisLab (http://www.mevislab.de) | ||||
scriptable from Python. | ||||
\section Licensing | ||||
PythonQt is distributed under the LGPL license. | ||||
\section Download | ||||
PythonQt is hosted on SourceForge at http://sourceforge.net/projects/pythonqt , you can access it via SVN | ||||
or download a tarball. | ||||
\section Features | ||||
- Access all \b slots, \b properties, children and registered enums of any QObject derived class from Python | ||||
- Connecting Qt Signals to Python functions (both from within Python and from C++) | ||||
- Wrapping of C++ objects (which are not derived from QObject) via PythonQtCPPWrapperFactory | ||||
- Extending C++ and QObject derived classes with additional slots, static methods and constructors (see Decorators) | ||||
- StdOut/Err redirection to Qt signals instead of cout | ||||
- Interface for creating your own \c import replacement, so that Python scripts can be e.g. signed/verified before they are executed (PythonQtImportInterface) | ||||
- Mapping of plain-old-datatypes and ALL QVariant types to and from Python | ||||
- Support for wrapping of user QVariant types which are registerd via QMetaType | ||||
- Support for Qt namespace (with all enumerators) | ||||
- All PythonQt wrapped objects support the dir() statement, so that you can see easily which attributes a QObject, CPP object or QVariant has | ||||
- 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) | ||||
\section Non-Features | ||||
Features that PythonQt does NOT support (and will not support): | ||||
- you can not derive from QObjects inside of Python, this would require wrapper generation like PyQt does | ||||
- you can only script QObject derived classes, for normal C++ classes you need to create a PythonQtCPPWrapperFactory and adequate wrapper classes or add decorator slots | ||||
- you can not access normal member functions of QObjects, only slots and properties, because the \b moc does not store normal member functions in the MetaObject system | ||||
\section Interface | ||||
The main interface to PythonQt is the PythonQt singleton. | ||||
PythonQt needs to be initialized via PythonQt::init() once. | ||||
Afterwards you communicate with the singleton via PythonQt::self(). | ||||
PythonQt offers a default binding for the complete QWidget set, which | ||||
needs to be enabled via PythonQtGui::init(). | ||||
\section Datatype Datatype Mapping | ||||
The following table shows the mapping between Python and Qt objects: | ||||
<table> | ||||
<tr><th>Qt/C++</th><th>Python</th></tr> | ||||
<tr><td>bool</td><td>bool</td></tr> | ||||
<tr><td>double</td><td>float</td></tr> | ||||
<tr><td>float</td><td>float</td></tr> | ||||
<tr><td>char/uchar,int/uint,short,ushort,QChar</td><td>integer</td></tr> | ||||
<tr><td>long</td><td>integer</td></tr> | ||||
<tr><td>ulong,longlong,ulonglong</td><td>long</td></tr> | ||||
<tr><td>QString</td><td>unicode string</td></tr> | ||||
<tr><td>QByteArray</td><td>str</td></tr> | ||||
<tr><td>char*</td><td>str</td></tr> | ||||
<tr><td>QStringList</td><td>tuple of unicode strings</td></tr> | ||||
<tr><td>QVariantList</td><td>tuple of objects</td></tr> | ||||
<tr><td>QVariantMap</td><td>dict of objects</td></tr> | ||||
<tr><td>QVariant</td><td>depends on type, see below</td></tr> | ||||
<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> | ||||
<tr><td>OwnRegisteredMetaType</td><td>variant wrapper, optionally with a wrapper provided by addVariantWrapper()</td></tr> | ||||
<tr><td>EnumType</td><td>integer (all enums that are known via the moc and the Qt namespace are supported)</td></tr> | ||||
<tr><td>QObject (and derived classes)</td><td>QObject wrapper</td></tr> | ||||
<tr><td>C++ object</td><td>CPP wrapper, either wrapped via PythonQtCPPWrapperFactory or just decorated with decorators</td></tr> | ||||
<tr><td>PyObject</td><td>PyObject</td></tr> | ||||
</table> | ||||
PyObject is passed as simple pointer, which allows to pass/return any Python Object directly to/from | ||||
a Qt slot. | ||||
QVariants are mapped recursively as given above, e.g. a dictionary can | ||||
contain lists of dictionaries of doubles. | ||||
For example a QVariant of type "String" is mapped to a python unicode string. | ||||
All Qt QVariant types are implemented, PythonQt supports the complete Qt API for these object. | ||||
\section QObject QObject Wrapping | ||||
All classes derived from QObject are automatically wrapped with a python wrapper class | ||||
when they become visible to the Python interpreter. This can happen via | ||||
- the PythonQt::addObject() method | ||||
- when a Qt \b slot returns a QObject derived object to python | ||||
- when a Qt \b signal contains a QObject and is connected to a python function | ||||
It is important that you call PythonQt::registerClass() for any QObject derived class | ||||
that may become visible to Python, except when you add it via PythonQt::addObject(). | ||||
This will register the complete parent hierachy of the registered class, so that | ||||
when you register e.g. a QPushButton, QWidget will be registered as well (and all intermediate | ||||
parents). | ||||
From Python, you can talk to the returned QObjects in a natural way by calling | ||||
their slots and receiving the return values. You can also read/write all | ||||
properties of the objects as if they where normal python properties. | ||||
In addition to this, the wrapped objects support | ||||
- className() - returns a string that reprents the classname of the QObject | ||||
- help() - shows all properties, slots, enums, decorator slots and constructors of the object, in a printable form | ||||
- connect(signal, function) - connect the signal of the given object to a python function | ||||
- connect(signal, qobject, slot) - connect the signal of the given object to a slot of another QObject | ||||
- disconnect(signal, function) - disconnect the signal of the given object from a python function | ||||
- disconnect(signal, qobject, slot) - disconnect the signal of the given object from a slot of another QObject | ||||
- children() - returns the children of the object | ||||
- setParent(QObject) - set the parent | ||||
- QObject* parent() - get the parent | ||||
The below example shows how to connect signals in Python: | ||||
\code | ||||
# define a signal handler function | ||||
def someFunction(flag): | ||||
print flag | ||||
# button1 is a QPushButton that has been added to Python via addObject() | ||||
# connect the clicked signal to a python function: | ||||
button1.connect("clicked(bool)", someFunction) | ||||
\endcode | ||||
\section CPP CPP Wrapping | ||||
You can create dedicated wrapper QObject for any C++ class. This is done by deriving from PythonQtCPPWrapperFactory | ||||
and adding your factory via addWrapperFactory(). Whenever PythonQt encounters a CPP pointer (e.g. on a slot or signal) | ||||
and it does not known it as a QObject derived class, it will create a generic CPP wrapper. So even unknown C++ objects | ||||
can be passed through Python. If the wrapper factory supports the CPP class, a QObject wrapper will be created for each | ||||
instance that enters Python. An alternative to a complete wrapper via the wrapper factory are decorators, see \ref Decorators | ||||
\section MetaObject Meta Object/Class access | ||||
For each known CPP class, QObject derived class and QVariant type, PythonQt provides a Meta class. These meta classes are visible | ||||
inside of the "PythonQt" python module. | ||||
A Meta class supports: | ||||
- access to all declared enum values | ||||
- constructors | ||||
- static decorator slots | ||||
- help() and className() | ||||
From within Python, you can import the module "PythonQt" to access these meta objects and the Qt namespace. | ||||
\code | ||||
from PythonQt import * | ||||
# namespace access: | ||||
print Qt.AlignLeft | ||||
# constructors | ||||
a = QSize(12,13) | ||||
b = QFont() | ||||
# static method | ||||
QDate.currentDate() | ||||
# enum value | ||||
QFont.UltraCondensed | ||||
\endcode | ||||
\section Decorators Decorator slots | ||||
PythonQt introduces a new generic approach to extend any wrapped QObject or CPP object with | ||||
- constructors | ||||
- destructors (for CPP objects) | ||||
- additional slots | ||||
- static slots (callable on both the Meta object and the instances) | ||||
The idea behind decorators is that we wanted to make it as easy as possible to extend | ||||
wrapped objects. Since we already have an implementation for invoking any Qt Slot from | ||||
Python, it looked promising to use this approach for the extension of wrapped objects as well. | ||||
This avoids that the PythonQt user needs to care about how Python arguments are mapped from/to | ||||
Qt when he wants to create static methods, constructors and additional member functions. | ||||
The basic idea about decorators is to create a QObject derived class that implements slots | ||||
which take one of the above roles (e.g. constructor, destructor etc.) via a naming convention. | ||||
These slots are then assigned to other classes via the naming convention. | ||||
- QVariant new_SomeClassName(...) - defines a constructor for "SomeClassName" that returns a QVariant | ||||
- 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) | ||||
- void delete_SomeClassName(SomeClassName* o) - defines a destructor, which should delete the passed in object o | ||||
- anything static_SomeClassName_someMethodName(...) - defines a static method that is callable on instances and the meta class | ||||
- 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. | ||||
The below example shows all kinds of decorators in action: | ||||
\code | ||||
// an example CPP object | ||||
class YourCPPObject { | ||||
public: | ||||
YourCPPObject(int arg1, float arg2) { a = arg1; b = arg2; } | ||||
float doSomething(int arg1) { return arg1*a*b; }; | ||||
private: | ||||
int a; | ||||
float b; | ||||
}; | ||||
// an example decorator | ||||
class ExampleDecorator : public QObject | ||||
{ | ||||
Q_OBJECT | ||||
public slots: | ||||
// add a constructor to QSize variant that takes a QPoint | ||||
QVariant new_QSize(const QPoint& p) { return QSize(p.x(), p.y()); } | ||||
// add a constructor for QPushButton that takes a text and a parent widget | ||||
QPushButton* new_QPushButton(const QString& text, QWidget* parent=NULL) { return new QPushButton(text, parent); } | ||||
// add a constructor for a CPP object | ||||
YourCPPObject* new_YourCPPObject(int arg1, float arg2) { return new YourCPPObject(arg1, arg2); } | ||||
// add a destructor for a CPP object | ||||
void delete_YourCPPObject(YourCPPObject* obj) { delete obj; } | ||||
// add a static method to QWidget | ||||
QWidget* static_QWidget_mouseGrabber() { return QWidget::mouseGrabber(); } | ||||
// add an additional slot to QWidget (make move() callable, which is not declared as a slot in QWidget) | ||||
void move(QWidget* w, const QPoint& p) { w->move(p); } | ||||
// add an additional slot to QWidget, overloading the above move method | ||||
void move(QWidget* w, int x, int y) { w->move(x,y); } | ||||
// add a method to your own CPP object | ||||
int doSomething(YourCPPObject* obj, int arg1) { return obj->doSomething(arg1); } | ||||
}; | ||||
... | ||||
PythonQt::self()->addDecorators(new ExampleDecorator()); | ||||
PythonQt::self()->registerClass(&QPushButton::staticMetaObject); | ||||
PythonQt::self()->registerCPPClassNames(QStringList() << "YourCPPObject"); | ||||
\endcode | ||||
After you have registered an instance of the above ExampleDecorator, you can do the following from Python | ||||
(all these calls are mapped to the above decorator slots): | ||||
\code | ||||
from PythonQt import * | ||||
# call our new constructor of QSize | ||||
size = QSize(QPoint(1,2)); | ||||
# call our new QPushButton constructor | ||||
button = QPushButton("sometext"); | ||||
# call the move slot (overload1) | ||||
button.move(QPoint(0,0)) | ||||
# call the move slot (overload2) | ||||
button.move(0,0) | ||||
# call the static method | ||||
grabber = QWidget.mouseWrapper(); | ||||
# create a CPP object via constructor | ||||
yourCpp = YourCPPObject(1,11.5) | ||||
# call the wrapped method on CPP object | ||||
print yourCpp.doSomething(1); | ||||
# destructor will be called: | ||||
yourCpp = None | ||||
\endcode | ||||
\section Building | ||||
PythonQt requires at least Qt 4.2.2 (or higher) and Python 2.3, 2.4 or 2.5 on Windows, Linux and MacOS X. | ||||
To compile PythonQt, you will need a python developer installation which includes Python's header files and | ||||
the python2x.[lib | dll | so | dynlib]. | ||||
The build scripts a currently set to use Python 2.5. | ||||
You may need to tweak the \b build/python.prf file to set the correct Python includes and libs on your system. | ||||
\subsection Windows | ||||
On Windows, the (non-source) Python Windows installer can be used. | ||||
Make sure that you use the same compiler, the current Python distribution is built | ||||
with Visual Studio 2003. If you want to use another compiler, you will need to build | ||||
Python yourself, using your compiler. | ||||
To build PythonQt, you need to set the environment variable \b PYTHON_PATH to point to the root | ||||
dir of the python installation and \b PYTHON_LIB to point to | ||||
the directory where the python lib file is located. | ||||
When using the prebuild Python installer, this will be: | ||||
\code | ||||
> set PYTHON_PATH = c:\Python25 | ||||
> set PYTHON_LIB = c:\Python25\libs | ||||
\endcode | ||||
When using the python sources, this will be something like: | ||||
\code | ||||
> set PYTHON_PATH = c:\yourDir\Python-2.5.1\ | ||||
> set PYTHON_LIB = c:\yourDir\Python-2.5.1\PCbuild8\Win32 | ||||
\endcode | ||||
To build all, do the following (after setting the above variables): | ||||
\code | ||||
> cd PythonQtRoot | ||||
> vcvars32 | ||||
> qmake | ||||
> nmake | ||||
\endcode | ||||
This should build everything. If Python can not be linked or include files can not be found, | ||||
you probably need to tweak \b build/python.prf | ||||
The tests and examples are located in PythonQt/lib. | ||||
\subsection Linux | ||||
On Linux, you need to install a Python-dev package. | ||||
If Python can not be linked or include files can not be found, | ||||
you probably need to tweak \b build/python.prf | ||||
To build PythonQt, just do a: | ||||
\code | ||||
> cd PythonQtRoot | ||||
> qmake | ||||
> make all | ||||
\endcode | ||||
The tests and examples are located in PythonQt/lib. | ||||
You should add PythonQt/lib to your LD_LIBRARY_PATH so that the runtime | ||||
linker can find the *.so files. | ||||
\subsection MacOsX | ||||
On Mac, Python is installed as a Framework, so you should not need to install it. | ||||
To build PythonQt, just do a: | ||||
\code | ||||
> cd PythonQtRoot | ||||
> qmake | ||||
> make all | ||||
\endcode | ||||
\section Tests | ||||
There is a unit test that tests most features of PythonQt, see the \b tests subdirectory for details. | ||||
\section Examples | ||||
Examples are available in the \b examples directory. The PyScriptingConsole implements a simple | ||||
interactive scripting console that shows how to script a simple application. | ||||
The following shows how to integrate PythonQt into you Qt application: | ||||
\code | ||||
#include "PythonQt.h" | ||||
#include <QApplication> | ||||
... | ||||
int main( int argc, char **argv ) | ||||
{ | ||||
QApplication qapp(argc, argv); | ||||
// init PythonQt and Python itself | ||||
PythonQt::init(PythonQt::IgnoreSiteModule | PythonQt::RedirectStdOut); | ||||
// get a smart pointer to the __main__ module of the Python interpreter | ||||
PythonQtObjectPtr mainContext = PythonQt::self()->getMainModule(); | ||||
// add a QObject as variable of name "example" to the namespace of the __main__ module | ||||
PyExampleObject example; | ||||
PythonQt::self()->addObject(mainContext, "example", &example); | ||||
// register all other QObjects that you want to script and that are returned by your API | ||||
PythonQt::self()->registerClass(&QMainWindow::staticMetaObject); | ||||
PythonQt::self()->registerClass(&QPushButton::staticMetaObject); | ||||
... | ||||
// do something | ||||
PythonQt::self()->runScript(mainContext, "print example\n"); | ||||
PythonQt::self()->runScript(mainContext, "def multiply(a,b):\n return a*b;\n"); | ||||
QVariantList args; | ||||
args << 42 << 47; | ||||
QVariant result = PythonQt::self()->call(mainContext,"multiply", args); | ||||
... | ||||
\endcode | ||||
\section TODOs | ||||
- add more information on how to distribute an application that uses PythonQt, including the Python distribution | ||||
*/ | ||||