QML reference examples: Adapt tutorial texts

Take over the texts from C++ with adaptions for Python.

Task-number: PYSIDE-2206
Task-number: QTBUG-111033
Change-Id: I0e4f1ec39b10bc1440389219604194b2ee001450
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
(cherry picked from commit 7c5721fe74183e37bac46b42929c35c293f1ad54)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

5 files changed, 212 insertions, 91 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
diff --git a/examples/qml/tutorials/extending-qml-advanced/advanced3-Default-properties/doc/advanced3-Default-properties.rst b/examples/qml/tutorials/extending-qml-advanced/advanced3-Default-properties/doc/advanced3-Default-properties.rst
index 1b28519a7..0857f9d0a 100644
--- a/examples/qml/tutorials/extending-qml-advanced/advanced3-Default-properties/doc/advanced3-Default-properties.rst
+++ b/examples/qml/tutorials/extending-qml-advanced/advanced3-Default-properties/doc/advanced3-Default-properties.rst
@@ -1,30 +1,40 @@
-.. _qml-default-property-example:
-
-Extending QML - Default Property Example
-========================================
-
-This example builds on the :ref:`qml-adding-types-example`,
-the :ref:`qml-object-and-list-property-types-example` and
-the :ref:`qml-inheritance-and-coercion-example`.
-
-The Default Property Example is a minor modification of the
-:ref:`qml-inheritance-and-coercion-example` that simplifies the
-specification of a BirthdayParty through the use of a default property.
-
-Declaring the BirthdayParty Class
----------------------------------
-
-The only difference between this example and the last, is the addition of a
-``DefaultProperty`` class info annotation.
-
-The default property specifies the property to assign to whenever an explicit
-property is not specified, in the case of the BirthdayParty type the guest
-property.  It is purely a syntactic simplification, the behavior is identical
-to specifying the property by name, but it can add a more natural feel in many
-situations.  The default property must be either an object or list property.
-
-Running the Example
--------------------
-
-The main.py file in the example includes a simple shell application that
-loads and runs the QML snippet shown below.
+.. _qml-advanced3-default-properties:
+
+Extending QML (advanced) - Default Properties
+=============================================
+
+This is the third 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.
+
+Currently, in the QML file, each property is assigned explicitly. For example,
+the ``host`` property is assigned a ``Boy`` and the ``guests`` property is
+assigned a list of ``Boy`` or ``Girl``. This is easy but it can be made a bit
+simpler for this specific use case. Instead of assigning the ``guests``
+property explicitly, we can add ``Boy`` and ``Girl`` objects inside the party
+directly and have them assigned to ``guests`` implicitly. It makes sense that
+all the attendees that we specify, and that are not the host, are guests. This
+change is purely syntactical but it can add a more natural feel in many
+situations.
+
+The ``guests`` property can be designated as the default property of
+``BirthdayParty``. Meaning that each object created inside of a
+``BirthdayParty`` is implicitly appended to the default property ``guests``.
+The resulting QML looks like this.
+
+.. literalinclude:: People/Main.qml
+    :lineno-start: 6
+    :lines: 6-15
+
+The only change required to enable this behavior is to add the ``DefaultProperty``
+class info annotation to ``BirthdayParty`` to designate ``guests`` as its default
+property.
+
+.. literalinclude:: birthdayparty.py
+    :lineno-start: 16
+    :lines: 16-18
+
+You may already be familiar with this mechanism. The default property for all
+descendants of ``Item`` in QML is the ``data`` property. All elements not
+explicitly added to a property of an ``Item`` will be added to ``data``. This
+makes the structure clear and reduces unnecessary noise in the code.
diff --git a/examples/qml/tutorials/extending-qml-advanced/advanced4-Grouped-properties/doc/advanced4-Grouped-properties.rst b/examples/qml/tutorials/extending-qml-advanced/advanced4-Grouped-properties/doc/advanced4-Grouped-properties.rst
index 691c1d393..7748d3189 100644
--- a/examples/qml/tutorials/extending-qml-advanced/advanced4-Grouped-properties/doc/advanced4-Grouped-properties.rst
+++ b/examples/qml/tutorials/extending-qml-advanced/advanced4-Grouped-properties/doc/advanced4-Grouped-properties.rst
@@ -1,17 +1,39 @@
-.. _qml-grouped-example:
+.. _qml-advanced-advanced4-grouped-properties:
 
-Extending QML - Grouped Properties Example
-==========================================
+Extending QML (advanced) - Grouped Properties
+=============================================
 
-Grouped Properties.
+This is the fourth 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.
 
-This example builds on the the :ref:`qml-default-property-example`,
-the :ref:`qml-inheritance-and-coercion-example`
-the :ref:`qml-object-and-list-property-types-example`
-and the :ref:`qml-adding-types-example`.
+More information is needed about the shoes of the guests. Aside from their
+size, we also want to store the shoes' color, brand, and price. This
+information is stored in a ``ShoeDescription`` class.
 
-Running the Example
--------------------
+.. literalinclude:: person.py
+    :lineno-start: 14
+    :lines: 14-66
 
-The ``main.py`` file in the example includes a simple shell application that
-loads and runs the QML snippet shown below.
+Each person now has two properties, a ``name`` and a shoe description ``shoe``.
+
+.. literalinclude:: person.py
+    :lineno-start: 69
+    :lines: 69-90
+
+Specifying the values for each element of the shoe description works but is a
+bit repetitive.
+
+.. literalinclude:: People/Main.qml
+    :lineno-start: 26
+    :lines: 26-32
+
+Grouped properties provide a more elegant way of assigning these properties.
+Instead of assigning the values to each property one-by-one, the individual
+values can be passed as a group to the ``shoe`` property making the code more
+readable. No changes are required to enable this feature as it is available by
+default for all of QML.
+
+.. literalinclude:: People/Main.qml
+    :lineno-start: 9
+    :lines: 9-12
diff --git a/examples/qml/tutorials/extending-qml-advanced/advanced5-Attached-properties/doc/advanced5-Attached-properties.rst b/examples/qml/tutorials/extending-qml-advanced/advanced5-Attached-properties/doc/advanced5-Attached-properties.rst
index 95fb5c43c..14b4bddb0 100644
--- a/examples/qml/tutorials/extending-qml-advanced/advanced5-Attached-properties/doc/advanced5-Attached-properties.rst
+++ b/examples/qml/tutorials/extending-qml-advanced/advanced5-Attached-properties/doc/advanced5-Attached-properties.rst
@@ -1,12 +1,51 @@
-.. _qml-attached-properties-example:
+.. _qml-advanced-advanced5-attached-properties:
 
-Extending QML - Attached Properties Example
-===========================================
+Extending QML (advanced) - Attached Properties
+==============================================
 
-This example builds on the :ref:`qml-default-property-example`,
-:ref:`qml-inheritance-and-coercion-example`,
-:ref:`qml-object-and-list-property-types-example`
-and the :ref:`qml-adding-types-example`.
+This is the fifth 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 Attached Properties Example example shows how to inject
-properties to child objects.
+The time has come for the host to send out invitations. To keep track of which
+guests have responded to the invitation and when, we need somewhere to store
+that information. Storing it in the ``BirthdayParty`` object iself would not
+really fit. A better way would be to store the responses as attached objects to
+the party object.
+
+First, we declare the ``BirthdayPartyAttached`` class which holds the guest reponses.
+
+.. literalinclude:: birthdayparty.py
+    :lineno-start: 16
+    :lines: 16-32
+
+And we attach it to the ``BirthdayParty`` class and define
+``qmlAttachedProperties()`` to return the attached object.
+
+.. literalinclude:: birthdayparty.py
+    :lineno-start: 34
+    :lines: 34-38
+
+.. literalinclude:: birthdayparty.py
+    :lineno-start: 67
+    :lines: 67-69
+
+Now, attached objects can be used in the QML to hold the rsvp information of
+the invited guests.
+
+.. literalinclude:: People/Main.qml
+    :lineno-start: 6
+    :lines: 6-22
+
+Finally, the information can be accessed in the following way.
+
+.. literalinclude:: main.py
+    :lineno-start: 36
+    :lines: 36-39
+
+The program outputs the following summary of the party to come::
+
+    "Jack Smith" is having a birthday!
+    He is inviting:
+        "Robert Campbell" RSVP date: "Wed Mar 1 2023"
+        "Leo Hodges" RSVP date: "Mon Mar 6 2023"
diff --git a/examples/qml/tutorials/extending-qml-advanced/advanced6-Property-value-source/doc/advanced6-Property-value-source.rst b/examples/qml/tutorials/extending-qml-advanced/advanced6-Property-value-source/doc/advanced6-Property-value-source.rst
index 81fbc827f..4e1dc393a 100644
--- a/examples/qml/tutorials/extending-qml-advanced/advanced6-Property-value-source/doc/advanced6-Property-value-source.rst
+++ b/examples/qml/tutorials/extending-qml-advanced/advanced6-Property-value-source/doc/advanced6-Property-value-source.rst
@@ -1,20 +1,43 @@
-.. _qml-valuesource-example:
+.. _qml-advanced/advanced6-property-value-source:
 
-Extending QML - Value Source Example
-====================================
+Extending QML (advanced) - Property Value Source
+================================================
 
-This example builds on the :ref:`qml-adding-types-example`,
-the :ref:`qml-attached-properties-example`,
-the :ref:`qml-default-property-example`,
-the :ref:`qml-inheritance-and-coercion-example` and
-the :ref:`qml-object-and-list-property-types-example`.
+This is the last 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.
 
-It demonstrates implementing a
-`property value source <https://doc.qt.io/qt-6/qtqml-cppintegration-definetypes.html#property-value-sources>`_
-in Python.
+During the party the guests have to sing for the host. It would be handy if the
+program could display the lyrics customized for the occasion to help the
+guests. To this end, a property value source is used to generate the verses of
+the song over time.
 
-Running the Example
--------------------
+.. literalinclude:: happybirthdaysong.py
+    :lineno-start: 13
+    :lines: 13-49
 
-The main.py file in the example includes a simple shell application that
-loads and runs the QML snippet shown below.
+The class ``HappyBirthdaySong`` is added as a value source. It must inherit
+from ``QQmlPropertyValueSource`` and implement its interface. The
+``setTarget()`` function is used to define which property this source acts
+upon. In this case, the value source writes to the ``announcement`` property of
+the ``BirthdayParty`` to display the lyrics over time. It has an internal timer
+that causes the ``announcement`` property of the party to be set to the next
+line of the lyrics repeatedly.
+
+In QML, a ``HappyBirthdaySong`` is instantiated inside the ``BirthdayParty``.
+The ``on`` keyword in its signature is used to specify the property that the
+value source targets, in this case ``announcement``. The ``name`` property of
+the ``HappyBirthdaySong`` object is also bound to the name of the host of the
+party.
+
+.. literalinclude:: People/Main.qml
+    :lineno-start: 6
+    :lines: 6-7
+
+The program displays the time at which the party started using the
+``partyStarted`` signal and then prints the following happy birthday verses
+over and over::
+
+    Happy birthday to you,
+    Happy birthday to you,
+    Happy birthday dear Bob Jones,
+    Happy birthday to you!