1 files changed, 64 insertions, 0 deletions
diff --git a/libs/plugin_python/src/pybind11-qt/README.md b/libs/plugin_python/src/pybind11-qt/README.md
new file mode 100644
index 0000000..784f9a8
--- /dev/null
+++ b/libs/plugin_python/src/pybind11-qt/README.md
@@ -0,0 +1,64 @@
+# 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`](include/pybind11_qt/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`](include/pybind11_qt/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++:
+
+```cpp
+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");
+```