Revision control
++ // Copyright (C) 2021 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example bindableproperties
++ \examplecategory {Data Processing & I/O}
++ \ingroup corelib_examples
++ \title Bindable Properties
++ \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 {Subscription form with Age,
++ Interval, country flags, and Price/month}
++
++ \section1 Modeling 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 Subscription:
++
++ \snippet bindableproperties/subscription/main.cpp init
++
++ And do the proper signal-slot connections to update the \c user and
++ \c subscription 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 subscription 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
++ in order to properly track changes to both \c user and \c subscription.
++ If any of the dependencies of the price changes, we need to remember to emit the
++ corresponding notifier signals, recalculate the price, and update it in
++ the UI.
++ \li If more dependencies for price calculation are added in the 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
++ 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 difference is in the implementation of these classes. 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 BindableSubscription 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 the 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
++ */