1 files changed, 47 insertions, 0 deletions
diff --git a/examples/qml/tutorials/extending-qml/chapter5-listproperties/doc/chapter5-listproperties.rst b/examples/qml/tutorials/extending-qml/chapter5-listproperties/doc/chapter5-listproperties.rst
new file mode 100644
index 000000000..a98f18c81
--- /dev/null
+++ b/examples/qml/tutorials/extending-qml/chapter5-listproperties/doc/chapter5-listproperties.rst
@@ -0,0 +1,47 @@
+.. _qml-chapter5-listproperties:
+
+Extending QML - Using List Property Types
+=========================================
+
+This is the fifth of a series of 6 examples forming a tutorial about extending
+QML with Python.
+
+Right now, a ``PieChart`` can only have one ``PieSlice.`` Ideally a chart would
+have multiple slices, with different colors and sizes. To do this, we could
+have a ``slices`` property that accepts a list of ``PieSlice`` items:
+
+.. literalinclude:: app.qml
+   :lineno-start: 4
+   :lines: 4-32
+
+To do this, we replace the ``pieSlice`` property in ``PieChart`` with a
+``slices`` property, declared as a class variable of the
+:class:`~PySide6.QtQml.ListProperty` type.
+The ``ListProperty`` class enables the creation of list properties in
+QML extensions. We replace the ``pieSlice()`` function with a ``slices()``
+function that returns a list of slices, and add an internal ``appendSlice()``
+function (discussed below). We also use a list to store the internal list of
+slices as ``_slices``:
+
+.. literalinclude:: listproperties.py
+   :lineno-start: 62
+   :lines: 62-65
+
+.. literalinclude:: listproperties.py
+   :lineno-start: 75
+   :lines: 75-79
+
+Although the ``slices`` property does not have an associated setter, it is
+still modifiable because of the way ``ListProperty`` works. We indicate
+that the internal ``PieChart.appendSlice()`` function is to be called whenever
+a request is made from QML to add items to the list.
+
+The ``appendSlice()`` function simply sets the parent item as before, and adds
+the new item to the ``_slices`` list. As you can see, the append function for
+a ``ListProperty`` is called with two arguments: the list property, and the
+item that is to be appended.
+
+The ``PieSlice`` class has also been modified to include ``fromAngle`` and
+``angleSpan`` properties and to draw the slice according to these values. This
+is a straightforward modification if you have read the previous pages in this
+tutorial, so the code is not shown here.