diff options
Diffstat (limited to 'examples/qml/tutorials/extending-qml/chapter4-customPropertyTypes/doc/chapter4-customPropertyTypes.rst')
-rw-r--r-- | examples/qml/tutorials/extending-qml/chapter4-customPropertyTypes/doc/chapter4-customPropertyTypes.rst | 73 |
1 files changed, 73 insertions, 0 deletions
diff --git a/examples/qml/tutorials/extending-qml/chapter4-customPropertyTypes/doc/chapter4-customPropertyTypes.rst b/examples/qml/tutorials/extending-qml/chapter4-customPropertyTypes/doc/chapter4-customPropertyTypes.rst new file mode 100644 index 000000000..f7c3efb11 --- /dev/null +++ b/examples/qml/tutorials/extending-qml/chapter4-customPropertyTypes/doc/chapter4-customPropertyTypes.rst @@ -0,0 +1,73 @@ +.. _qml-chapter4-custompropertytypes: + +Extending QML - Using Custom Property Types +=========================================== + +This is the fourth of a series of 6 examples forming a tutorial about extending +QML with Python. + +The ``PieChart`` type currently has a string-type property and a color-type property. +It could have many other types of properties. For example, it could have an +int-type property to store an identifier for each chart: + +.. code-block:: python + + class PieChart(QQuickPaintedItem): + chartIdChanged = Signal() + + @Property(int, notify=chartIdChanged) + def chartId(self): + pass + + @chartId.setter + def setChartId(self, chartId): + pass + +.. code-block:: javascript + + // QML + PieChart { + ... + chartId: 100 + } + +Aside from ``int``, we could use various other property types. Many of the Qt +data types such as ``QColor``, ``QSize`` and ``QRect`` are automatically +supported from QML. + +If we want to create a property whose type is not supported by QML by default, +we need to register the type with the QML engine. + +For example, let's replace the use of the ``property`` with a type called +``PieSlice`` that has a ``color`` property. Instead of assigning a color, +we assign an ``PieSlice`` value which itself contains a ``color``: + +.. literalinclude:: app.qml + :lineno-start: 4 + :lines: 4-22 + +Like ``PieChart``, this new ``PieSlice`` type inherits from +``QQuickPaintedItem``, is exposed via the ``QmlElement`` decorator and declares +its properties with the ``Property`` decorator: + +.. literalinclude:: customPropertyTypes.py + :lineno-start: 21 + :lines: 21-40 + +To use it in ``PieChart``, we modify the ``color`` property declaration +and associated method signatures: + +.. literalinclude:: customPropertyTypes.py + :lineno-start: 58 + :lines: 58-65 + +There is one thing to be aware of when implementing ``setPieSlice()``. The +``PieSlice`` is a visual item, so it must be set as a child of the ``PieChart`` +using ``QQuickItem.setParentItem()`` so that the ``PieChart`` knows to paint +this child item when its contents are drawn. + +As with ``PieChart``, we add the ``Charts`` type namespace, version 1.0: + +.. literalinclude:: customPropertyTypes.py + :lineno-start: 15 + :lines: 15-18 |