GIT_REPOSITORIES/LPP/PythonQt Commit - r32:ae159b178ea0

started to update/improve docs...

florianlink -

r32:ae159b178ea0

parent child

Context file:

r32:ae159b178ea0

Collapse all files

src/PythonQtDoc.h +92 -47

               It offers an easy way to embed 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.
+              The focus of PythonQt is on embedding Python into an existing C++ application, not on writing the whole
+              application completely in Python. If you want to write your whole application in Python,
+              you should use <a href="http://www.riverbankcomputing.co.uk/pyqt/">PyQt</a> instead.
               If you are looking for a simple way to embed Python objects into your C++/Qt Application
-              and to script parts of your application via Python, PythonQt is the way to go!
+              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
+              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 Licensing
+              PythonQt is distributed under the LGPL license, so it pairs well with the LGPL of the Qt 4.5 release and allows
+              to be used in commercial applications when following the LGPL 2.1 obligations.
+              \section LicensingWrapper Licensing of Wrapper Generator
+              The build system of PythonQt makes use of a modified version of the GPL'ed QtScript generator,
+              located in the "generator" directory.
+              See http://labs.trolltech.com/page/Projects/QtScript/Generator for details on the original project.
+              Thanks a lot to the QtJambi guys and the QtScript Generator project for the C++ parser and
+              Qt typesystem files!
+              The PythonQt wrappers generated by the generator located in the "generated_cpp" directory are distributed under the LGPL,
+              they are not restriced by the GPL.
+              The generated wrappers are pre-generated and checked-in for Qt 4.4.3, so you only need to build and run the
+              generator when you want to build additional wrappers or you want to upgrade/downgrade to an newer Qt version.
+              You may use the generator to generate C++ bindings for your own C++ classes (e.g. to make them deriveable in Python),
+              , but this is currently not documented and involves creating your own typesystem files.
               \section Features
-              - Easy wrapping of Python objects from C++ with smart, reference-counting PythonQtObjectPtr.
-              - Convenient conversions to/from QVariant for PythonQtObjectPtr.
+              The following are the built-in features of the PythonQt library:
               - 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++)
+              - Easy wrapping of Python objects from C++ with smart, reference-counting PythonQtObjectPtr.
+              - Convenient conversions to/from QVariant for PythonQtObjectPtr.
               - 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
               - 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)
+              - 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)
+              - 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)
+              - Deriving C++ objects from Python and overwriting virtual method with a Python implementation (requires usage of wrapper generator or manual work!)
+              - Extensible handler for Python/C++ conversion of complex types, e.g. mapping of QVector<SomeObject> to/from a Python array
+              \section FeaturesQtAll Features (with PythonQt_QtAll linked in)
+              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.
+              This offers the following features:
+              - Complete Qt API wrapped and accessible
+              - The following modules are available as submodule of the PythonQt module:
+               - QtCore
+               - QtGui
+               - QtNetwork
+               - QtOpenGL
+               - QtSql
+               - QtSvg
+               - QtUiTools
+               - QtWebKit
+               - QtXml
+               - QtXmlPatterns
+               - (phonon, QtHelp, assistant, designer are currently not supported, this would require some additional effort on the code generator)
+              - 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
+              - Any Qt class that has virtual methods can be easily derived from Python and the virtual methods can be reimplemented in Python
+              - Polymorphic downcasting on QEvent, QGraphicsItem, QStyleOption, ...
+              - Multiple inheritance support (e.g. QGraphicsTextItem is a QObject AND a QGraphicsItem, PythonQt will handle this well)
+              \section Comparision Comparision with PyQt
+              - PythonQt is not as Pythonic as PyQt in many details (e.g. operator mapping, pickling, translation support, ...) and it is maily thought for embedding and intercommunication between Qt/Cpp and Python
+              - 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
+              - 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)
+              - PythonQt does not auto-convert objects, e.g. when a QPainter expects a QBrush and you pass a QColor, it is rejected, you will need to write QBrush(QColor(1,2,3)) instead
+              - Probably there are lots of details that differ, I do not know PyQt that well to list them all.
-              \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().
+              PythonQt offers a complete Qt binding, which
+              needs to be enabled via PythonQt_QtAll::init().
               \section Datatype Datatype Mapping
                <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>OwnRegisteredMetaType</td><td>C++ wrapper, optionally with additional information/wrapping provided by registerCPPClass()</td></tr>
+               <tr><td>QList<AnyObject*></td><td>converts to a list of CPP wrappers</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>
               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
+              - delete() - deletes the object (use with care, especially if you passed the ownership to C++)
               - 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
              \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().
+             You can create dedicated wrapper QObjects 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
              \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.
+             For each known C++ class, PythonQt provides a Python class. These classes are visible
+             inside of the "PythonQt" python module or in subpackages if a package is given when the class is registered.
              A Meta class supports:
              - access to all declared enum values
              - constructors
-             - static decorator slots
+             - static methods
+             - unbound non-static methods
              - help() and className()
-             From within Python, you can import the module "PythonQt" to access these meta objects and the Qt namespace.
+             From within Python, you can import the module "PythonQt" to access these classes and the Qt namespace.
              \code
-             from PythonQt import *
+             from PythonQt import QtCore
              # namespace access:
-             print Qt.AlignLeft
+             print QtCore.Qt.AlignLeft
              # constructors
-             a = QSize(12,13)
-             b = QFont()
+             a = QtCore.QSize(12,13)
+             b = QtCore.QFont()
              # static method
-             QDate.currentDate()
+             QtCore.QDate.currentDate()
              # enum value
-             QFont.UltraCondensed
+             QtCore.QFont.UltraCondensed
              \endcode
              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
                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 to QSize that takes a QPoint
+               QSize* new_QSize(const QPoint& p) { return new 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); }
              ...
              PythonQt::self()->addDecorators(new ExampleDecorator());
-             PythonQt::self()->registerClass(&QPushButton::staticMetaObject);
-             PythonQt::self()->registerCPPClassNames(QStringList() << "YourCPPObject");
+             PythonQt::self()->registerCPPClass("YourCPPObject");
              \endcode
              (all these calls are mapped to the above decorator slots):
              \code
-             from PythonQt import *
+             from PythonQt import QtCore, QtGui, YourCPPObject
              # call our new constructor of QSize
-             size = QSize(QPoint(1,2));
+             size = QtCore.QSize(QPoint(1,2));
              # call our new QPushButton constructor
-             button = QPushButton("sometext");
+             button = QtGui.QPushButton("sometext");
              # call the move slot (overload1)
              button.move(QPoint(0,0))
              button.move(0,0)
              # call the static method
-             grabber = QWidget.mouseWrapper();
+             grabber = QtGui.QWidget.mouseWrapper();
              # create a CPP object via constructor
              yourCpp = YourCPPObject(1,11.5)
                // 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();
                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");

General Comments 0

Write
Preview

You need to be logged in to leave comments. Login now

No TODOs yet

	Site-wide shortcuts
/	Use quick search box
g h	Goto home page
g g	Goto my private gists page
g G	Goto my public gists page
g 0-9	Goto bookmarked items from 0-9
n r	New repository page
n g	New gist page

	Repositories
g s	Goto summary page
g c	Goto changelog page
g f	Goto files page
g F	Goto files page with file search activated
g p	Goto pull requests page
g o	Goto repository settings
g O	Goto repository access permissions settings
t s	Toggle sidebar on some pages