diff options
Diffstat (limited to 'examples/corelib/bindableproperties/doc')
-rw-r--r-- | examples/corelib/bindableproperties/doc/images/bindable_properties_example.png | bin | 0 -> 18831 bytes | |||
-rw-r--r-- | examples/corelib/bindableproperties/doc/src/bindableproperties.qdoc | 179 |
2 files changed, 179 insertions, 0 deletions
diff --git a/examples/corelib/bindableproperties/doc/images/bindable_properties_example.png b/examples/corelib/bindableproperties/doc/images/bindable_properties_example.png Binary files differnew file mode 100644 index 0000000000..f38261a217 --- /dev/null +++ b/examples/corelib/bindableproperties/doc/images/bindable_properties_example.png diff --git a/examples/corelib/bindableproperties/doc/src/bindableproperties.qdoc b/examples/corelib/bindableproperties/doc/src/bindableproperties.qdoc new file mode 100644 index 0000000000..476522b086 --- /dev/null +++ b/examples/corelib/bindableproperties/doc/src/bindableproperties.qdoc @@ -0,0 +1,179 @@ +// 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} + \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 + + \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 +*/ |