From 83dbab1052e177ed694fed061e7692262992daee Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Wed, 3 May 2023 14:52:06 +0200 Subject: 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 (cherry picked from commit 7c5721fe74183e37bac46b42929c35c293f1ad54) Reviewed-by: Qt Cherry-pick Bot --- .../doc/advanced2-Inheritance-and-coercion.rst | 77 +++++++++++++++------- .../doc/advanced3-Default-properties.rst | 70 +++++++++++--------- .../doc/advanced4-Grouped-properties.rst | 46 +++++++++---- .../doc/advanced5-Attached-properties.rst | 57 +++++++++++++--- .../doc/advanced6-Property-value-source.rst | 53 ++++++++++----- 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 `_ -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! -- cgit v1.2.3