From 022891bcd8ae4e8de02cdef9ed281e9a31eedbc4 Mon Sep 17 00:00:00 2001
From: Sona Kurazyan <sona.kurazyan@qt.io>
Date: Fri, 26 Nov 2021 15:49:18 +0100
Subject: [PATCH] Document the example showing the benefits of using bindable
 properties

And mention the example in the bindable properties docs.

Pick-to: 6.2
Task-number: QTBUG-97655
Change-Id: I676e90dbda66c2e718c7f6c2240fac608a8653df
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
---
 .../bindablesubscription.cpp                  |   8 +
 .../bindablesubscription.h                    |   4 +
 .../bindablesubscription/bindableuser.cpp     |   4 +
 .../bindablesubscription/bindableuser.h       |   5 +
 .../bindablesubscription/main.cpp             |   2 +
 .../images/bindable_properties_example.png    | Bin 0 -> 18831 bytes
 .../doc/src/bindableproperties.qdoc           | 202 ++++++++++++++++++
 .../bindableproperties/subscription/main.cpp  |  10 +
 .../subscription/subscription.cpp             |  20 ++
 .../subscription/subscription.h               |   4 +
 .../bindableproperties/subscription/user.cpp  |   4 +
 .../bindableproperties/subscription/user.h    |   4 +
 .../src/objectmodel/bindableproperties.qdoc   |  14 ++
 13 files changed, 281 insertions(+)
 create mode 100644 examples/corelib/bindableproperties/doc/images/bindable_properties_example.png
 create mode 100644 examples/corelib/bindableproperties/doc/src/bindableproperties.qdoc

diff --git a/examples/corelib/bindableproperties/bindablesubscription/bindablesubscription.cpp b/examples/corelib/bindableproperties/bindablesubscription/bindablesubscription.cpp
index d962216cd99..14b28b3fae7 100644
--- a/examples/corelib/bindableproperties/bindablesubscription/bindablesubscription.cpp
+++ b/examples/corelib/bindableproperties/bindablesubscription/bindablesubscription.cpp
@@ -51,6 +51,8 @@
 #include "bindablesubscription.h"
 #include "bindableuser.h"
 
+//! [binding-expressions]
+
 BindableSubscription::BindableSubscription(BindableUser *user) : m_user(user)
 {
     Q_ASSERT(user);
@@ -62,11 +64,17 @@ BindableSubscription::BindableSubscription(BindableUser *user) : m_user(user)
     });
 }
 
+//! [binding-expressions]
+
+//! [set-duration]
+
 void BindableSubscription::setDuration(Duration newDuration)
 {
     m_duration = newDuration;
 }
 
+//! [set-duration]
+
 double BindableSubscription::calculateDiscount() const
 {
     switch (m_duration) {
diff --git a/examples/corelib/bindableproperties/bindablesubscription/bindablesubscription.h b/examples/corelib/bindableproperties/bindablesubscription/bindablesubscription.h
index 86dd0bdf26e..763864d6279 100644
--- a/examples/corelib/bindableproperties/bindablesubscription/bindablesubscription.h
+++ b/examples/corelib/bindableproperties/bindablesubscription/bindablesubscription.h
@@ -56,6 +56,8 @@
 
 class BindableUser;
 
+//! [bindable-subscription-class]
+
 class BindableSubscription
 {
 public:
@@ -84,4 +86,6 @@ private:
     QProperty<bool> m_isValid { false };
 };
 
+//! [bindable-subscription-class]
+
 #endif // BNDABLESUBSCRIPTION_H
diff --git a/examples/corelib/bindableproperties/bindablesubscription/bindableuser.cpp b/examples/corelib/bindableproperties/bindablesubscription/bindableuser.cpp
index fc651c25796..d30e203b612 100644
--- a/examples/corelib/bindableproperties/bindablesubscription/bindableuser.cpp
+++ b/examples/corelib/bindableproperties/bindablesubscription/bindableuser.cpp
@@ -50,6 +50,8 @@
 
 #include "bindableuser.h"
 
+//! [bindable-user-setters]
+
 void BindableUser::setCountry(Country country)
 {
     m_country = country;
@@ -59,3 +61,5 @@ void BindableUser::setAge(int age)
 {
     m_age = age;
 }
+
+//! [bindable-user-setters]
diff --git a/examples/corelib/bindableproperties/bindablesubscription/bindableuser.h b/examples/corelib/bindableproperties/bindablesubscription/bindableuser.h
index 1c370780768..65541e6ac1e 100644
--- a/examples/corelib/bindableproperties/bindablesubscription/bindableuser.h
+++ b/examples/corelib/bindableproperties/bindablesubscription/bindableuser.h
@@ -53,6 +53,8 @@
 
 #include <QProperty>
 
+//! [bindable-user-class]
+
 class BindableUser
 {
 public:
@@ -78,4 +80,7 @@ private:
     QProperty<Country> m_country { None };
     QProperty<int> m_age { 0 };
 };
+
+//! [bindable-user-class]
+
 #endif // BINDABLEUSER_H
diff --git a/examples/corelib/bindableproperties/bindablesubscription/main.cpp b/examples/corelib/bindableproperties/bindablesubscription/main.cpp
index 2ee39c5bb56..df935679ade 100644
--- a/examples/corelib/bindableproperties/bindablesubscription/main.cpp
+++ b/examples/corelib/bindableproperties/bindablesubscription/main.cpp
@@ -103,6 +103,7 @@ int main(int argc, char *argv[])
     QLabel *priceDisplay = w.findChild<QLabel *>("priceDisplay");
 
     // Track price changes
+//! [update-ui]
     auto priceChangeHandler = subscription.bindablePrice().subscribe([&] {
         priceDisplay->setText(QString::number(subscription.price()));
     });
@@ -110,6 +111,7 @@ int main(int argc, char *argv[])
     auto priceValidHandler = subscription.bindableIsValid().subscribe([&] {
         priceDisplay->setEnabled(subscription.isValid());
     });
+//! [update-ui]
 
     w.show();
     return a.exec();
diff --git a/examples/corelib/bindableproperties/doc/images/bindable_properties_example.png b/examples/corelib/bindableproperties/doc/images/bindable_properties_example.png
new file mode 100644
index 0000000000000000000000000000000000000000..f38261a217ff3f3d26c0beb0ffca4be7ee23286a
GIT binary patch
literal 18831
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
XGXgo1U}SIL%Oi<TvZ7_e`hNcdS_jFd

literal 0
HcmV?d00001

diff --git a/examples/corelib/bindableproperties/doc/src/bindableproperties.qdoc b/examples/corelib/bindableproperties/doc/src/bindableproperties.qdoc
new file mode 100644
index 00000000000..8c36921ff8b
--- /dev/null
+++ b/examples/corelib/bindableproperties/doc/src/bindableproperties.qdoc
@@ -0,0 +1,202 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example bindableproperties
+    \title Bindable Properties Example
+    \brief Demonstrates how the usage of bindable properties can simplify
+    your C++ code.
+
+    In this example we will demonstrate two approaches for expressing the
+    relationships between different objects depending on each other:
+    signal/slot connection-based and bindable property-based. For this
+    purpose we will consider a subscription service model to calculate the
+    cost of the subscription.
+
+    \image bindable_properties_example.png
+
+    \section1 Modelling Subscription System with Signal/Slot Approach
+
+    Let's first consider the usual pre-Qt 6 implementation.
+    To model the subscription service the \c Subscription class is used:
+
+    \snippet bindableproperties/subscription/subscription.h subscription-class
+
+    It stores the information about the subscription and provides corresponding
+    getters, setters, and notifier signals for informing the listeners about the
+    subscription information changes. It also keeps a pointer to an instance of
+    the \c User class.
+
+    The price of the subscription is calculated based on the duration of the
+    subscription:
+
+    \snippet bindableproperties/subscription/subscription.cpp calculate-discount
+
+    And user's location:
+
+    \snippet bindableproperties/subscription/subscription.cpp calculate-base-price
+
+    When the price changes, the \c priceChanged() signal is emitted, to notify the
+    listeners about the change:
+
+    \snippet bindableproperties/subscription/subscription.cpp calculate-price
+
+    Similarly, when the duration of the subscription changes, the \c durationChanged()
+    signal is emitted.
+
+    \snippet bindableproperties/subscription/subscription.cpp set-duration
+
+    \note Both methods need to check if the data is actually changed and
+    only then emit the signals. \c setDuration() also needs to recalculate
+    the price, when the duration has changed.
+
+    The \c Subscription is not valid unless the user has a valid country and
+    age, so the validity is updated in the following way:
+
+    \snippet bindableproperties/subscription/subscription.cpp update-validity
+
+    The \c User class is simple: it stores country and age of the user and
+    provides the corresponding getters, setters, and notifier signals:
+
+    \snippet bindableproperties/subscription/user.h user-class
+
+    \snippet bindableproperties/subscription/user.cpp user-setters
+
+    In the \c main() function we initialize instances of \c User and
+    \c Subsrcription:
+
+    \snippet bindableproperties/subscription/main.cpp init
+
+    And do the proper signal-slot connections, to update the \c user and
+    \c subsrcription data when UI elements change. That is straightforward,
+    so we will skip this part.
+
+    Next, we connect to \c Subscription::priceChanged(), to update the price
+    in the UI when the price changes.
+
+    \snippet bindableproperties/subscription/main.cpp connect-price-changed
+
+    We also connect to \c Subscription::isValidChanged(), to disable the price
+    display if the subscription isn't valid.
+
+    \snippet bindableproperties/subscription/main.cpp connect-validity-changed
+
+    Because the subsrcription price and validity also depend on the user's
+    country and age, we also need to connect to the \c User::countryChanged()
+    and \c User::ageChanged() signals and update \c subscription accordingly.
+
+    \snippet bindableproperties/subscription/main.cpp connect-user
+
+    This works, but there are some problems:
+
+    \list
+    \li There's a lot of boilerplate code for the signal-slot connections,
+    to be able to react to changes to \c user or \c subscription. If any of
+    the dependencies of the price changes, we need to remember to emit the
+    corresponding notifier signals, to recalculate the price and update it in
+    the UI.
+    \li If more dependencies for price calculation are added in future, we'll
+    need to add more signal-slot connections and make sure all the dependencies
+    are properly updated whenever any of them changes. The overall complexity
+    will grow, and the code will become harder to maintain.
+    \li The \c Subscription and \c User classes depend on the metaobject system
+    to be able to use the signal/slot mechanism.
+    \endlist
+
+    Can we do better?
+
+    \section1 Modeling Subscription System with Bindbable Properties
+
+    Now let's see how the \l {Qt Bindable Properties} can help to solve the
+    same problem. First, let's have a look at the \c BindableSubscription class,
+    which is similar to the \c Subscription class, but is implemented using the
+    bindable properties:
+
+    \snippet bindableproperties/bindablesubscription/bindablesubscription.h bindable-subscription-class
+
+    The first difference we can notice, is that the data fields are now wrapped
+    inside \l QProperty classes, and the notifier signals (and as a consequence the
+    dependency from the metaobject system) are gone, and new methods returning a
+    \l QBindable for each \l QProperty are added instead. The \c calculatePrice()
+    and \c updateValidty() methods are also removed. We'll see below why they aren't
+    needed anymore.
+
+    The \c BindableUser class differs from the \c User class in a similar way:
+
+    \snippet bindableproperties/bindablesubscription/bindableuser.h bindable-user-class
+
+    The second differenece is in the implementation of these calsses. First of
+    all, the dependencies between \c subscription and \c user are now tracked via
+    binding expressions:
+
+    \snippet bindableproperties/bindablesubscription/bindablesubscription.cpp binding-expressions
+
+    Behind the scenes the bindable properties track the dependency changes and
+    update the property's value whenever a change is detected. So if, for example,
+    user's country or age is changed, subscription's price and validity will be
+    updated automatically.
+
+    Another difference is that the setters are now trivial:
+
+    \snippet bindableproperties/bindablesubscription/bindablesubscription.cpp set-duration
+
+    \snippet bindableproperties/bindablesubscription/bindableuser.cpp bindable-user-setters
+
+    There's no need to check inside the setters if the property's value has
+    actually changed, \l QProperty already does that. The dependent properties
+    will be notified about the change only if the value has actually changed.
+
+    The code for updating the information about the price in the UI is also
+    simplified:
+
+    \snippet bindableproperties/bindablesubscription/main.cpp update-ui
+
+    We subscribe to changes via \c bindablePrice() and \c bindableIsValid()
+    and update the price display accordingly when any of these properties
+    changes the value. The subscriptions will stay alive as long as the
+    corresponding handlers are alive.
+
+    Also note that the copy constructors of both \c BindableSubsrciption and
+    \c BindableUser are disabled, since it's not defined what should happen
+    with their bindings when copying.
+
+    As you can see, the code became much simpler, and the problems mentioned
+    above are solved:
+
+    \list
+    \li The boilerplate code for the signal-slot connections is removed, the
+    dependencies are now tracked automatically.
+    \li The code is easier to maintain. Adding more dependencies in future
+    will only require adding the corresponding bindable properties and setting
+    the binding expressions that reflect the relationships between each other.
+    \li The \c Subscription and \c User classes don't depend on the metaobject
+    system anymore. Of course, you can still expose them to the metaobject
+    system and add \l {Q_PROPERTY}s if you need, and have the advantages of
+    bindable properties both in \c C++ and \c QML code. You can use the
+    \l QObjectBindableProperty class for that.
+    \endlist
+*/
diff --git a/examples/corelib/bindableproperties/subscription/main.cpp b/examples/corelib/bindableproperties/subscription/main.cpp
index c9874486115..6ff0c960f15 100644
--- a/examples/corelib/bindableproperties/subscription/main.cpp
+++ b/examples/corelib/bindableproperties/subscription/main.cpp
@@ -62,8 +62,11 @@
 int main(int argc, char *argv[])
 {
     QApplication a(argc, argv);
+
+//! [init]
     User user;
     Subscription subscription(&user);
+//! [init]
 
     SubscriptionWindow w;
 
@@ -106,14 +109,20 @@ int main(int argc, char *argv[])
     priceDisplay->setEnabled(subscription.isValid());
 
     // Track the price changes
+
+//! [connect-price-changed]
     QObject::connect(&subscription, &Subscription::priceChanged, [&] {
         priceDisplay->setText(QString::number(subscription.price()));
     });
+//! [connect-price-changed]
 
+//! [connect-validity-changed]
     QObject::connect(&subscription, &Subscription::isValidChanged, [&] {
         priceDisplay->setEnabled(subscription.isValid());
     });
+//! [connect-validity-changed]
 
+//! [connect-user]
     QObject::connect(&user, &User::countryChanged, [&] {
         subscription.calculatePrice();
         subscription.updateValidity();
@@ -122,6 +131,7 @@ int main(int argc, char *argv[])
     QObject::connect(&user, &User::ageChanged, [&] {
         subscription.updateValidity();
     });
+//! [connect-user]
 
     w.show();
     return a.exec();
diff --git a/examples/corelib/bindableproperties/subscription/subscription.cpp b/examples/corelib/bindableproperties/subscription/subscription.cpp
index 7f6da358625..20efe825f32 100644
--- a/examples/corelib/bindableproperties/subscription/subscription.cpp
+++ b/examples/corelib/bindableproperties/subscription/subscription.cpp
@@ -56,6 +56,8 @@ Subscription::Subscription(User *user) : m_user(user)
     Q_ASSERT(user);
 }
 
+//! [calculate-price]
+
 void Subscription::calculatePrice()
 {
     const auto oldPrice = m_price;
@@ -65,6 +67,10 @@ void Subscription::calculatePrice()
         emit priceChanged();
 }
 
+//! [calculate-price]
+
+//! [set-duration]
+
 void Subscription::setDuration(Duration newDuration)
 {
     if (newDuration != m_duration) {
@@ -74,6 +80,10 @@ void Subscription::setDuration(Duration newDuration)
     }
 }
 
+//! [set-duration]
+
+//! [calculate-discount]
+
 double Subscription::calculateDiscount() const
 {
     switch (m_duration) {
@@ -88,6 +98,10 @@ double Subscription::calculateDiscount() const
     return -1;
 }
 
+//! [calculate-discount]
+
+//! [calculate-base-price]
+
 int Subscription::basePrice() const
 {
     if (m_user->country() == User::None)
@@ -96,6 +110,10 @@ int Subscription::basePrice() const
     return (m_user->country() == User::Norway) ? 100 : 80;
 }
 
+//! [calculate-base-price]
+
+//! [update-validity]
+
 void Subscription::updateValidity()
 {
     bool isValid = m_isValid;
@@ -104,3 +122,5 @@ void Subscription::updateValidity()
     if (m_isValid != isValid)
         emit isValidChanged();
 }
+
+//! [update-validity]
diff --git a/examples/corelib/bindableproperties/subscription/subscription.h b/examples/corelib/bindableproperties/subscription/subscription.h
index 95b840bbe53..41d052e86ff 100644
--- a/examples/corelib/bindableproperties/subscription/subscription.h
+++ b/examples/corelib/bindableproperties/subscription/subscription.h
@@ -56,6 +56,8 @@
 
 class User;
 
+//! [subscription-class]
+
 class Subscription : public QObject
 {
     Q_OBJECT
@@ -88,4 +90,6 @@ private:
     bool m_isValid = false;
 };
 
+//! [subscription-class]
+
 #endif // SUBSCRIPTION_H
diff --git a/examples/corelib/bindableproperties/subscription/user.cpp b/examples/corelib/bindableproperties/subscription/user.cpp
index af97576cc73..c2b08353304 100644
--- a/examples/corelib/bindableproperties/subscription/user.cpp
+++ b/examples/corelib/bindableproperties/subscription/user.cpp
@@ -50,6 +50,8 @@
 
 #include "user.h"
 
+//! [user-setters]
+
 void User::setCountry(Country country)
 {
     if (m_country != country) {
@@ -65,3 +67,5 @@ void User::setAge(int age)
         emit ageChanged();
     }
 }
+
+//! [user-setters]
diff --git a/examples/corelib/bindableproperties/subscription/user.h b/examples/corelib/bindableproperties/subscription/user.h
index a872ecf8c88..8c9ebb10095 100644
--- a/examples/corelib/bindableproperties/subscription/user.h
+++ b/examples/corelib/bindableproperties/subscription/user.h
@@ -53,6 +53,8 @@
 
 #include <QObject>
 
+//! [user-class]
+
 class User : public QObject
 {
     Q_OBJECT
@@ -79,4 +81,6 @@ private:
     Country m_country = Country::None;
     int m_age = 0;
 };
+
+//! [user-class]
 #endif // USER_H
diff --git a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
index dc83c01e3db..391ce4baf7e 100644
--- a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
+++ b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
@@ -45,6 +45,20 @@
     uses the encapsulating QObject to store the pointer to the
     management data structure.
 
+    \section1 Why Use Bindable Properties?
+
+    Property bindings are one of the core features of QML. They allow to specify
+    relationships between different object properties and automatically update
+    properties' values whenever their dependencies change. Bindable properties
+    allow to achieve the same not only in QML code, but also in C++. Using
+    bindable properties can help to simplify your program, by eliminating a lot
+    of boilerplate code for tracking and reacting to dependency updates of
+    different objects.
+
+    The \l {Introductory Example} below demonstrates the usage of bindable
+    properties in C++ code. You can also check \l {Bindable Properties Example}
+    to see how the bindable properties can help to improve your code.
+
     \section1 Introductory Example
 
     The binding expression computes the value by reading other QProperty values.