summaryrefslogtreecommitdiffstats
path: root/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'src/corelib/doc/src/objectmodel/bindableproperties.qdoc')
-rw-r--r--src/corelib/doc/src/objectmodel/bindableproperties.qdoc56
1 files changed, 30 insertions, 26 deletions
diff --git a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
index dc83c01e3d..9b3ea6ae66 100644
--- a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
+++ b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** 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$
-**
-****************************************************************************/
+// Copyright (C) 2021 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page bindableproperties.html
@@ -45,6 +21,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.
@@ -257,4 +247,18 @@
be called for the current value of the property, register your callback using
subscribe() instead.
+ \section1 Interaction with Q_PROPERTYs
+
+ A \l {The Property System}{Q_PROPERTY} that defines \c BINDABLE can be bound and
+ used in binding expressions. You can implement such properties using \l {QProperty},
+ \l {QObjectBindableProperty}, or \l {QObjectComputedProperty}.
+
+ Q_PROPERTYs without \c BINDABLE can also be bound and be used in binding expressions,
+ as long as they define a \c NOTIFY signal. You must wrap the property in a \l QBindable
+ using the \c {QBindable(QObject* obj, const char* property)} constructor. Then, the
+ property can be bound using \l QBindable::setBinding() or used in a binding
+ expression via \l QBindable::value(). You must use \c QBindable::value() in binding
+ expressions instead of the normal property \c READ function (or \c MEMBER) to enable
+ dependency tracking if the property is not \c BINDABLE.
+
*/