From 127147feb0428227a5598a6d053501d984a26d51 Mon Sep 17 00:00:00 2001 From: Andreas Buhr Date: Tue, 19 Jan 2021 12:53:28 +0100 Subject: Create bindable property overview documentation So far, all documentation about bindable properties was in the corresponding classes QProperty and QObjectBindableProperty. This patch creates one documentation page for a general introduction to bindable properties and information concerning all of those classes. Change-Id: Ib718dbeb385c3899fb34cc2ce03bec7a8d43a034 Reviewed-by: Fabian Kosmale --- .../doc/src/objectmodel/bindableproperties.qdoc | 102 +++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 src/corelib/doc/src/objectmodel/bindableproperties.qdoc (limited to 'src/corelib/doc') diff --git a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc new file mode 100644 index 0000000000..cae55f73b5 --- /dev/null +++ b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \page bindableproperties.html + \title Qt Bindable Properties + \brief Qt's bindable properties. + + \ingroup qt-basic-concepts + \keyword Qt's Bindable Properties + + Qt provides bindable properties. Bindable properties are properties + which either have a value or are specified using any C++ function, + typically a C++ lambda expression. + In case they are specified using a C++ function, they are + updated automatically whenever their dependencies change. + + Bindable properties are implemented in the class QProperty, which + consists the data object and a pointer to a management data structure, and + in class QObjectBindableProperty, which consists only of the data object and + uses the encapsulating QObject to store the pointer to the + management data structure. + + \section1 Introductory Example + + The binding expression computes the value by reading other QProperty values. + Behind the scenes this dependency is tracked. Whenever a change in any property's + dependency is detected, the binding expression is re-evaluated and the new + result is applied to the property. This happens lazily, by marking the binding + as dirty and evaluating it only when the property's value is requested. For example: + + \code + QProperty firstname("John"); + QProperty lastname("Smith"); + QProperty age(41); + + QProperty fullname; + fullname.setBinding([&]() { return firstname.value() + " " + lastname.value() + " age: " + QString::number(age.value()); }); + + qDebug() << fullname.value(); // Prints "John Smith age: 41" + + firstname = "Emma"; // Marks binding expression as dirty + + qDebug() << fullname.value(); // Re-evaluates the binding expression and prints "Emma Smith age: 41" + + // Birthday is coming up + age.setValue(age.value() + 1); + + qDebug() << fullname.value(); // Re-evaluates the binding expression and prints "Emma Smith age: 42" + \endcode + + When a new value is assigned to the \c firstname property, the binding + expression for \c fullname is marked as dirty. So when the last \c qDebug() statement + tries to read the name value of the \c fullname property, the expression is + evaluated again, \c firstname() will be called again and return the new value. + + Since bindings are C++ functions, they may do anything that's possible + in C++. This includes calling other functions. If those functions access values + held by QProperty, they automatically become dependencies to the binding. + + Binding expressions may use properties of any type, so in the above example the age + is an integer and folded into the string value using conversion to integer, but + the dependency is fully tracked. + + \section1 Tracking Bindable Properties + + Sometimes the relationships between properties cannot be expressed using + bindings. Instead you may need to run custom code whenever the value of a property + changes and instead of assigning the value to another property, pass it to + other parts of your application. For example writing data into a network socket + or printing debug output. QProperty provides two mechanisms for tracking. + + You can register for a callback function to be called whenever the value of + a property changes, by using onValueChanged(). If you want the callback to also + be called for the current value of the property, register your callback using + subscribe() instead. + +*/ -- cgit v1.2.3