#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
*/
//----------------------------------------------------------------------------------
/*!
\mainpage
\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!
\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 and \b properties of any QObject derived class from Python
- Connecting Qt Signals to Python functions
- Wrapping of C++ objects (which are not derived from QObject) via PythonQtCPPWrapperFactory
- 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 many QVariant types to and from Python
- 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 access normal member functions of QObjects, only slots and properties, because the \b moc does not store normal member functions in the MetaObject system
- you can only script QObject derived classes, for normal C++ classes you need to create a PythonQtCPPWrapperFactory and adequate wrapper classes
- you can not derive from QObjects inside of Python, this would require wrapper generation like PyQt does
\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().
\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>char*</td><td>str</td></tr>
<tr><td>QStringList</td><td>tuple of unicode strings</td></tr>
<tr><td>QSize</td><td>QSize wrapper</td></tr>
<tr><td>QRect</td><td>QRect wrapper</td></tr>
<tr><td>QPoint</td><td>QPoint wrapper</td></tr>
<tr><td>QImage</td><td>QImage wrapper</td></tr>
<tr><td>QPixmap</td><td>QPixmap wrapper</td></tr>
<tr><td>QVariant</td><td>depends on type, see below</td></tr>
<tr><td>QVariantList</td><td>tuple of objects</td></tr>
<tr><td>QVariantMap</td><td>dict of objects</td></tr>
<tr><td>QDate</td><td>string</td></tr>
<tr><td>QTime</td><td>string</td></tr>
<tr><td>QDateTime</td><td>string</td></tr>
<tr><td>QObject (and derived classes)</td><td>QObject wrapper</td></tr>
</table>
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.
Not all Qt QVariant types are implemented, the support for all QVariant types
is on the TODO list.
\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 and slots of the object
\section Building
PythonQt has been tested with Qt 4.1 and 4.2 and Python 2.3, 2.4 and 2.5 on Windows, Linux and MacOS X.
To complile PythonQt, you will need a python developer installation which includes Python's header files and
the python2x.[lib | dll | so | dynlib].
For building PythonQt, you will need to set some environment variables:
\b PYTHON_ROOT should point to the Python sources/headers.
\b PYTHON_LIB should point to where the Python library files are located.
\b PYTHONQT_ROOT should point to the root directory of PythonQt.
Run qmake on PythonQt.pro to generate a project file for your system and then build it.
\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): return a*b;\n");
QVariantList args;
args << 42 << 47;
QVariant result = PythonQt::self()->call(mainContext,"multiply", args);
...
\endcode
\section TODOs
- add verbose/diagnosis mode
- add missing Qt variant types
- improve qmake profiles for non mevis users
- add more information on how to distribute an application that uses PythonQt, including the Python distribution
*/
