pybind11-qt

pybind11-qt

This library contains code to interface pybind11 with Qt and PyQt.

Type casters

The main part of this library is a set of (templated) type casters for Qt types that can be used by simply importing pybind11_qt/pybind11_qt.h. This provides type casters for:

• Standard Qt types, such as QString or QVariant.
  • QString is equivalent to Python str (unicode or not).
  • QVariant is not exposed but the object is directly converted, similarly to std::variant default type caster.
• Qt containers (QList, QSet, QMap, QStringList).
  • The QList type-caster is more flexible than the standard container type-casters from pybind11 as it accepts any iterable.
• QFlags - Delegates the cast to the underlying type, basically.
• Qt enumerations: a lot of enumerations are provided in pybind11_qt_enums.h and new ones can be easily added using the PYQT_ENUM macro (inside the header file).
• Qt objects: very few are provided in pybind11_qt_objects.h and new ones can be added using the PYQT_OBJECT macro (inside the header file).
  • Copy-constructible Qt objects are copied when passing from C++ to Python or vice-versa.
  • Non copy-constructible Qt objects, e.g., QObject or QWidget should always be exposed as pointer, and their ownership is transferred to C++ when coming from Python.

Qt holder

The library also provides a pybind11::qt::qobject_holder holder for pybind11 that transfer ownerships of the Python object to the underlying QObject.

This holder is useful when exposing classes inheriting QObject (or a child class of QObject) that can be extended to Python.

The library also provides two set_qt_owner functions that can be used to transfer ownership manually.

Qt delegates

The library provides a add_qt_delegate function that can be used to delegate Python call to Qt functions to C++:

py::class_<
    // the C++ class extending QObject to expose
    ISaveGameInfoWidget,

    // the trampoline class
    PySaveGameInfoWidget,

    // the Qt holder to keep the Python object alive alongside the C++ one
    py::qt::qobject_holder<ISaveGameInfoWidget>

> iSaveGameInfoWidget(m, "ISaveGameInfoWidget");

// allow to access most of the class attributes through Python via an overload of
// __getattr__ and add a _widget() method to access the widget itself if needed
//
py::qt::add_qt_delegate<QWidget>(iSaveGameInfoWidget, "_widget");