6 files changed, 75 insertions, 175 deletions
diff --git a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc
index 391ce4baf7..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
@@ -56,7 +32,7 @@
     different objects.
 
     The \l {Introductory Example} below demonstrates the usage of bindable
-    properties in C++ code. You can also check \l {Bindable Properties Example}
+    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
@@ -271,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.
+
 */
diff --git a/src/corelib/doc/src/objectmodel/metaobjects.qdoc b/src/corelib/doc/src/objectmodel/metaobjects.qdoc
index ada6a6dea1..3d7685447f 100644
--- a/src/corelib/doc/src/objectmodel/metaobjects.qdoc
+++ b/src/corelib/doc/src/objectmodel/metaobjects.qdoc
@@ -1,35 +1,11 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \page metaobjects.html
     \title The Meta-Object System
     \brief An overview of Qt's meta-object system and introspection capabilities.
-
+    \ingroup explanations-basics
     \ingroup qt-basic-concepts
     \keyword meta-object
     \keyword Meta-Object System
diff --git a/src/corelib/doc/src/objectmodel/object.qdoc b/src/corelib/doc/src/objectmodel/object.qdoc
index 2dd2594ae4..7b6b840df0 100644
--- a/src/corelib/doc/src/objectmodel/object.qdoc
+++ b/src/corelib/doc/src/objectmodel/object.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \page object.html
diff --git a/src/corelib/doc/src/objectmodel/objecttrees.qdoc b/src/corelib/doc/src/objectmodel/objecttrees.qdoc
index 29e2393e57..8939a534d4 100644
--- a/src/corelib/doc/src/objectmodel/objecttrees.qdoc
+++ b/src/corelib/doc/src/objectmodel/objecttrees.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \page objecttrees.html
diff --git a/src/corelib/doc/src/objectmodel/properties.qdoc b/src/corelib/doc/src/objectmodel/properties.qdoc
index e73bf0cebc..99a3e60d88 100644
--- a/src/corelib/doc/src/objectmodel/properties.qdoc
+++ b/src/corelib/doc/src/objectmodel/properties.qdoc
@@ -1,35 +1,11 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \page properties.html
     \title The Property System
     \brief An overview of Qt's property system.
-
+    \ingroup explanations-basics
     \ingroup qt-basic-concepts
     \keyword Qt's Property System
 
@@ -68,14 +44,21 @@
     specified. It is for reading the property value. Ideally, a const function
     is used for this purpose, and it must return either the property's type or a
     const reference to that type. e.g., QWidget::focus is a read-only
-    property with \c READ function, QWidget::hasFocus().
+    property with \c READ function, QWidget::hasFocus(). If a \c BINDABLE is
+    specified, you can write \c{READ default} to have the \c READ accessor
+    generated from the \c BINDABLE.
 
     \li A \c WRITE accessor function is optional. It is for setting the
     property value. It must return void and must take exactly one
     argument, either of the property's type or a pointer or reference
     to that type. e.g., QWidget::enabled has the \c WRITE function
     QWidget::setEnabled().  Read-only properties do not need \c WRITE
-    functions. e.g., QWidget::focus has no \c WRITE function.
+    functions. e.g., QWidget::focus has no \c WRITE function. If you specify
+    both a \c BINDABLE and \c{WRITE default}, a \c WRITE accessor will be
+    generated from the \c BINDABLE. The generated \c WRITE accessor will \e not
+    explicitly emit any signal declared with \c NOTIFY. You should register
+    the signal as change handler to the \c BINDABLE, for example using
+    \l{Q_OBJECT_BINDABLE_PROPERTY}.
 
     \li A \c MEMBER variable association is required if no \c READ accessor
     function is specified. This makes the given member variable
@@ -99,8 +82,9 @@
     which must be of the same type as the property. The parameter will take the
     new value of the property. The \c NOTIFY signal should only be emitted when
     the property has really been changed, to avoid bindings being unnecessarily
-    re-evaluated in QML, for example. Qt emits automatically that signal when
-    needed for MEMBER properties that do not have an explicit setter.
+    re-evaluated in QML, for example. The signal is emitted automatically when
+    the property is changed via the Qt API (QObject::setProperty,
+    QMetaProperty, etc.), but not when the MEMBER is changed directly.
 
     \li A \c REVISION number or \c REVISION() macro is optional. If included,
     it defines the property and its notifier signal to be used in a particular
@@ -109,7 +93,7 @@
 
     \li The \c DESIGNABLE attribute indicates whether the property
     should be visible in the property editor of GUI design tool (e.g.,
-    \l {Qt Designer Manual}{Qt Designer}). Most properties are \c DESIGNABLE
+    \l {Qt Widgets Designer Manual}{\QD}). Most properties are \c DESIGNABLE
     (default true). Valid values are true and false.
 
     \li The \c SCRIPTABLE attribute indicates whether this property
@@ -224,7 +208,10 @@
     The \c READ function is const and returns the property type. The
     \c WRITE function returns void and has exactly one parameter of
     the property type. The meta-object compiler enforces these
-    requirements.
+    requirements. The equality check in the \c WRITE function, while not
+    mandatory, is good practice as there is no point in notifying and
+    potentially forcing re-evaluation in other places if nothing has
+    changed.
 
     Given a pointer to an instance of MyClass or a pointer to a
     QObject that is an instance of MyClass, we have two ways to set
@@ -290,7 +277,9 @@
 
     Connected to the property system is an additional macro,
     Q_CLASSINFO(), that can be used to attach additional
-    \e{name}--\e{value} pairs to a class's meta-object, for example:
+    \e{name}--\e{value} pairs to a class's meta-object. This is
+    used for instance to mark a property as the \e default one
+    in the context of \l{QML Object Types}:
 
     \snippet code/doc_src_properties.cpp 7
 
@@ -312,5 +301,5 @@
     and the general tips on implementing and using
     \l {Qt Bindable Properties}{bindable properties}.
 
-    \sa {Qt Bindable Properties}
+    \sa {Qt Bindable Properties}, {Defining QML Types from C++}
 */
diff --git a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc
index 85fe4df2ce..f0eeb20048 100644
--- a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc
+++ b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc
@@ -1,29 +1,5 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \page signalsandslots.html
@@ -32,7 +8,7 @@
     \ingroup qt-basic-concepts
     \brief An overview of Qt's signals and slots inter-object
     communication mechanism.
-
+    \ingroup explanations-basics
     Signals and slots are used for communication between objects. The
     signals and slots mechanism is a central feature of Qt and
     probably the part that differs most from the features provided by
@@ -133,8 +109,7 @@
     when the signal is emitted.
 
     Signals are automatically generated by the \l moc and must not be
-    implemented in the \c .cpp file. They can never have return types
-    (i.e. use \c void).
+    implemented in the \c .cpp file.
 
     A note about arguments: Our experience shows that signals and slots
     are more reusable if they do not use special types. If
@@ -321,8 +296,7 @@
     callbacks, you'd have to find five different names and keep track
     of the types yourself.
 
-    \sa QLCDNumber, QObject::connect(), {Digital Clock Example},
-    {Tetrix Example}
+    \sa QLCDNumber, QObject::connect()
 
     \section1 Signals And Slots With Default Arguments
 
@@ -412,8 +386,12 @@
     \section2 Using Qt with 3rd Party Signals and Slots
 
     It is possible to use Qt with a 3rd party signal/slot mechanism.
-    You can even use both mechanisms in the same project. Just add the
-    following line to your qmake project (.pro) file.
+    You can even use both mechanisms in the same project. To do that,
+    write the following into your CMake project file:
+
+    \snippet code/doc_src_containers.cpp cmake_no_keywords
+
+    In a qmake project (.pro) file, you need to write:
 
     \snippet code/doc_src_containers.cpp 22
 
@@ -423,4 +401,19 @@
     with the \c{no_keywords} flag, simply replace all uses of the Qt
     moc keywords in your sources with the corresponding Qt macros
     Q_SIGNALS (or Q_SIGNAL), Q_SLOTS (or Q_SLOT), and Q_EMIT.
-*/
+
+    \section2 Signals and slots in Qt-based libraries
+
+    The public API of Qt-based libraries should use the keywords
+    \c{Q_SIGNALS} and \c{Q_SLOTS} instead of \c{signals} and
+    \c{slots}. Otherwise it is hard to use such a library in a project
+    that defines \c{QT_NO_KEYWORDS}.
+
+    To enforce this restriction, the library creator may set the
+    preprocessor define \c{QT_NO_SIGNALS_SLOTS_KEYWORDS} when building
+    the library.
+
+    This define excludes signals and slots without affecting whether
+    other Qt-specific keywords can be used in the library
+    implementation.
+ */