diff options
| author | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2023-05-03 14:52:06 +0200 |
|---|---|---|
| committer | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2023-05-10 21:29:59 +0200 |
| commit | 7c5721fe74183e37bac46b42929c35c293f1ad54 (patch) | |
| tree | 2ec34232eecce69bfb8e8d228286076708529d0c /examples/qml/tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/doc | |
| parent | 3e40f27cb539e0106511790a40327f5a03e48fab (diff) | |
QML reference examples: Adapt tutorial texts
Take over the texts from C++ with adaptions for Python.
Task-number: PYSIDE-2206
Task-number: QTBUG-111033
Pick-to: 6.5
Change-Id: I0e4f1ec39b10bc1440389219604194b2ee001450
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Diffstat (limited to 'examples/qml/tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/doc')
| -rw-r--r-- | examples/qml/tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/doc/advanced2-Inheritance-and-coercion.rst | 77 |
1 files changed, 52 insertions, 25 deletions
diff --git a/examples/qml/tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/doc/advanced2-Inheritance-and-coercion.rst b/examples/qml/tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/doc/advanced2-Inheritance-and-coercion.rst index 2ccdaeb4f..16c0dbc9a 100644 --- a/examples/qml/tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/doc/advanced2-Inheritance-and-coercion.rst +++ b/examples/qml/tutorials/extending-qml-advanced/advanced2-Inheritance-and-coercion/doc/advanced2-Inheritance-and-coercion.rst @@ -1,35 +1,62 @@ -.. _qml-inheritance-and-coercion-example: +.. _qml-advanced2-inheritance-and-coercion: -Extending QML - Inheritance and Coercion Example -================================================ +Extending QML (advanced) - Inheritance and Coercion +=================================================== -This example builds on the :ref:`qml-adding-types-example` and the -:ref:`qml-object-and-list-property-types-example` . +This is the second of a series of 6 examples forming a tutorial using the +example of a birthday party to demonstrate some of the advanced features of +QML. -The Inheritance and Coercion Example shows how to use base classes to assign -types of more than one type to a property. It specializes the Person type -developed in the previous examples into two types - a ``Boy`` and a ``Girl``. +Right now, each attendant is being modelled as a person. This is a bit too +generic and it would be nice to be able to know more about the attendees. By +specializing them as boys and girls, we can already get a better idea of who's +coming. -Declare Boy and Girl --------------------- +To do this, the ``Boy`` and ``Girl`` classes are introduced, both inheriting from +``Person``. -The Person class remains unaltered in this example and the Boy and Girl C++ -classes are trivial extensions of it. The types and their QML name are -registered with the QML engine. +.. literalinclude:: person.py + :lineno-start: 43 + :lines: 43-46 -As an example, the inheritance used here is a little contrived, but in real -applications it is likely that the two extensions would add additional -properties or modify the Person classes behavior. +.. literalinclude:: person.py + :lineno-start: 49 + :lines: 49-52 -Running the Example -------------------- +The ``Person`` class remains unaltered and the ``Boy`` and ``Girl`` classes are +trivial extensions of it. The types and their QML name are registered with the +QML engine with ``@QmlElement``. -The BirthdayParty type has not changed since the previous example. The -celebrant and guests property still use the People type. +Notice that the ``host`` and ``guests`` properties in ``BirthdayParty`` still +take instances of ``Person``. -However, as all three types, Person, Boy and Girl, have been registered with the -QML system, on assignment QML automatically (and type-safely) converts the Boy -and Girl objects into a Person. +.. literalinclude:: birthdayparty.py + :lineno-start: 26 + :lines: 26-26 -The main.py file in the example includes a simple shell application that -loads and runs the QML snippet shown below. +.. literalinclude:: birthdayparty.py + :lineno-start: 46 + :lines: 46-46 + +The implementation of the ``Person`` class itself has not been changed. +However, as the ``Person`` class was repurposed as a common base for ``Boy`` +and ``Girl``, ``Person`` should no longer be instantiable from QML directly. An +explicit ``Boy`` or ``Girl`` should be instantiated instead. + +.. literalinclude:: person.py + :lineno-start: 13 + :lines: 13-15 + +While we want to disallow instantiating ``Person`` from within QML, it still +needs to be registered with the QML engine so that it can be used as a property +type and other types can be coerced to it. This is what the ``@QmlUncreatable`` +macro does. As all three types, ``Person``, ``Boy`` and ``Girl``, have been +registered with the QML system, on assignment, QML automatically (and +type-safely) converts the ``Boy`` and ``Girl`` objects into a ``Person``. + +With these changes in place, we can now specify the birthday party with the +extra information about the attendees as follows. + +.. literalinclude:: People/Main.qml + :lineno-start: 6 + :lines: 6-16 |