10 files changed, 303 insertions, 53 deletions
diff --git a/src/quick/doc/snippets/qml/listview/ReusableDelegate.qml b/src/quick/doc/snippets/qml/listview/ReusableDelegate.qml
new file mode 100644
index 0000000000..050572d5f2
--- /dev/null
+++ b/src/quick/doc/snippets/qml/listview/ReusableDelegate.qml
@@ -0,0 +1,82 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** 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.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.15
+
+//![0]
+Component {
+    id: listViewDelegate
+    Rectangle {
+        width: 100
+        height: 50
+
+        ListView.onPooled: rotationAnimation.pause()
+        ListView.onReused: rotationAnimation.resume()
+
+        Rectangle {
+            id: rect
+            anchors.centerIn: parent
+            width: 40
+            height: 5
+            color: "green"
+
+            RotationAnimation {
+                id: rotationAnimation
+                target: rect
+                duration: (Math.random() * 2000) + 200
+                from: 0
+                to: 359
+                running: true
+                loops: Animation.Infinite
+            }
+        }
+    }
+}
+//![0]
diff --git a/src/quick/doc/snippets/qml/qml-data-models/listmodel-listview-required.qml b/src/quick/doc/snippets/qml/qml-data-models/listmodel-listview-required.qml
new file mode 100644
index 0000000000..e9a668ed8f
--- /dev/null
+++ b/src/quick/doc/snippets/qml/qml-data-models/listmodel-listview-required.qml
@@ -0,0 +1,81 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** 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.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [document]
+import QtQuick 2.0
+
+Item {
+    width: 200
+    height: 250
+
+    ListModel {
+        id: myModel
+        ListElement { type: "Dog"; age: 8; noise: "meow" }
+        ListElement { type: "Cat"; age: 5; noise: "woof" }
+    }
+
+    component MyDelegate : Text {
+        required property string type
+        required property int age
+        text: type + ", " + age
+        // WRONG: Component.onCompleted: () => console.log(noise)
+        // The above line would cause a ReferenceError
+        // as there is no required property noise,
+        // and the presence of the required properties prevents
+        // noise from being injected into the scope
+    }
+
+    ListView {
+        anchors.fill: parent
+        model: myModel
+        delegate: MyDelegate {}
+    }
+}
+//! [document]
diff --git a/src/quick/doc/snippets/qml/tableview/cpp-tablemodel.cpp b/src/quick/doc/snippets/qml/tableview/cpp-tablemodel.cpp
index ea9f76f131..a8a37f80af 100644
--- a/src/quick/doc/snippets/qml/tableview/cpp-tablemodel.cpp
+++ b/src/quick/doc/snippets/qml/tableview/cpp-tablemodel.cpp
@@ -48,56 +48,19 @@
  **
  ****************************************************************************/
 
-//![0]
+#include "cpp-tablemodel.h"
 #include <QGuiApplication>
-#include <QQmlApplicationEngine>
-#include <QAbstractTableModel>
-
-class TableModel : public QAbstractTableModel
-{
-    Q_OBJECT
-
-public:
-
-    int rowCount(const QModelIndex & = QModelIndex()) const override
-    {
-        return 200;
-    }
-
-    int columnCount(const QModelIndex & = QModelIndex()) const override
-    {
-        return 200;
-    }
-
-    QVariant data(const QModelIndex &index, int role) const override
-    {
-        switch (role) {
-            case Qt::DisplayRole:
-                return QString("%1, %2").arg(index.column()).arg(index.row());
-            default:
-                break;
-        }
-
-        return QVariant();
-    }
-
-    QHash<int, QByteArray> roleNames() const override
-    {
-        return { {Qt::DisplayRole, "display"} };
-    }
-};
+#include <QQuickView>
 
 int main(int argc, char *argv[])
 {
     QGuiApplication app(argc, argv);
 
-    qmlRegisterType<TableModel>("TableModel", 0, 1, "TableModel");
-
-    QQmlApplicationEngine engine;
-    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
+    QQuickView view;
+    view.setSource(QStringLiteral("qrc:/cpp-tablemodel.qml"));
+    view.show();
 
     return app.exec();
 }
 
-#include "main.moc"
 //![0]
diff --git a/src/quick/doc/snippets/qml/tableview/cpp-tablemodel.h b/src/quick/doc/snippets/qml/tableview/cpp-tablemodel.h
new file mode 100644
index 0000000000..4a3c46b573
--- /dev/null
+++ b/src/quick/doc/snippets/qml/tableview/cpp-tablemodel.h
@@ -0,0 +1,94 @@
+/****************************************************************************
+ **
+ ** Copyright (C) 2020 The Qt Company Ltd.
+ ** Contact: https://www.qt.io/licensing/
+ **
+ ** This file is part of the documentation of the Qt Toolkit.
+ **
+ ** $QT_BEGIN_LICENSE:BSD$
+ ** 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.
+ **
+ ** BSD License Usage
+ ** Alternatively, you may use this file under the terms of the BSD license
+ ** as follows:
+ **
+ ** "Redistribution and use in source and binary forms, with or without
+ ** modification, are permitted provided that the following conditions are
+ ** met:
+ **   * Redistributions of source code must retain the above copyright
+ **     notice, this list of conditions and the following disclaimer.
+ **   * Redistributions in binary form must reproduce the above copyright
+ **     notice, this list of conditions and the following disclaimer in
+ **     the documentation and/or other materials provided with the
+ **     distribution.
+ **   * Neither the name of The Qt Company Ltd nor the names of its
+ **     contributors may be used to endorse or promote products derived
+ **     from this software without specific prior written permission.
+ **
+ **
+ ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+ **
+ ** $QT_END_LICENSE$
+ **
+ ****************************************************************************/
+
+#ifndef CPPTABLEMODEL_H
+#define CPPTABLEMODEL_H
+
+//![0]
+#include <qqml.h>
+#include <QAbstractTableModel>
+
+class TableModel : public QAbstractTableModel
+{
+    Q_OBJECT
+    QML_ELEMENT
+    QML_ADDED_IN_MINOR_VERSION(1)
+
+public:
+    int rowCount(const QModelIndex & = QModelIndex()) const override
+    {
+        return 200;
+    }
+
+    int columnCount(const QModelIndex & = QModelIndex()) const override
+    {
+        return 200;
+    }
+
+    QVariant data(const QModelIndex &index, int role) const override
+    {
+        switch (role) {
+            case Qt::DisplayRole:
+                return QString("%1, %2").arg(index.column()).arg(index.row());
+            default:
+                break;
+        }
+
+        return QVariant();
+    }
+
+    QHash<int, QByteArray> roleNames() const override
+    {
+        return { {Qt::DisplayRole, "display"} };
+    }
+};
+//![0]
+
+#endif // CPPTABLEMODEL_H
diff --git a/src/quick/doc/snippets/qml/tableview/tableview.pro b/src/quick/doc/snippets/qml/tableview/tableview.pro
new file mode 100644
index 0000000000..0821f1b5d3
--- /dev/null
+++ b/src/quick/doc/snippets/qml/tableview/tableview.pro
@@ -0,0 +1,20 @@
+TEMPLATE = app
+
+QT += qml quick
+
+CONFIG += qmltypes
+QML_IMPORT_NAME = TableModel
+QML_IMPORT_MAJOR_VERSION = 0
+
+SOURCES += \
+    cpp-tablemodel.cpp
+
+HEADERS += \
+    cpp-tablemodel.h
+
+RESOURCES += \
+    cpp-tablemodel.qml \
+    qml-tablemodel.qml \
+    reusabledelegate.qml \
+    tableviewwithheader.qml \
+    tableviewwithprovider.qml
diff --git a/src/quick/doc/src/advtutorial.qdoc b/src/quick/doc/src/advtutorial.qdoc
index a18d4493ea..63c70067fd 100644
--- a/src/quick/doc/src/advtutorial.qdoc
+++ b/src/quick/doc/src/advtutorial.qdoc
@@ -64,7 +64,6 @@ directory.
 
 /*!
 \title QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks
-\contentspage QML Advanced Tutorial
 \previouspage QML Advanced Tutorial
 \nextpage QML Advanced Tutorial 2 - Populating the Game Canvas
 
@@ -132,7 +131,6 @@ types to get started. Next, we will populate the game canvas with some blocks.
 
 /*!
 \title QML Advanced Tutorial 2 - Populating the Game Canvas
-\contentspage QML Advanced Tutorial
 \previouspage QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks
 \nextpage QML Advanced Tutorial 3 - Implementing the Game Logic
 
@@ -206,7 +204,6 @@ Now, we have a screen of blocks, and we can begin to add the game mechanics.
 
 /*!
 \title QML Advanced Tutorial 3 - Implementing the Game Logic
-\contentspage QML Advanced Tutorial
 \previouspage QML Advanced Tutorial 2 - Populating the Game Canvas
 \nextpage QML Advanced Tutorial 4 - Finishing Touches
 
@@ -293,7 +290,6 @@ until the next chapter - where your application becomes alive!
 
 /*!
 \title QML Advanced Tutorial 4 - Finishing Touches
-\contentspage QML Advanced Tutorial
 \previouspage QML Advanced Tutorial 3 - Implementing the Game Logic
 
 \example tutorials/samegame/samegame4
diff --git a/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc b/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
index 04dbf1cf20..555f730c9e 100644
--- a/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
+++ b/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
@@ -164,6 +164,16 @@ To visualize data, bind the view's \c model property to a model and the
 
     \snippet qml/qml-data-models/listmodel-listview.qml document
 
+    To get finer control over which roles are accessible, and to make delegates
+    more self-contained and usable outside of views,
+    \li{Required Properties}{required properties} can be used. If a delegate
+    contains required properties, the named roles are not provided. Instead,
+    the QML engine will check if the name of a required property matches that of
+    a model role. If so, that property will be bound to the corresponding value
+    from the model.
+
+    \snippet qml/qml-data-models/listmodel-listview-required.qml document
+
     If there is a naming clash between the model's properties and the delegate's
     properties, the roles can be accessed with the qualified \e model name
     instead. For example, if a \l Text type had \e type or \e age properties,
@@ -186,6 +196,10 @@ To visualize data, bind the view's \c model property to a model and the
     modelData role is also provided for models that have only one role. In this
     case the \e modelData role contains the same data as the named role.
 
+    \note \e model, \e index, and \e modelData roles are not accessible
+    if the delegate contains required properties, unless it has also required
+    properties with matching names.
+
     QML provides several types of data models among the built-in set of QML
     types. In addition, models can be created with Qt C++ and then made
     available to \l{QQmlEngine} for use by
@@ -417,6 +431,12 @@ ListView {
 \note The \c edit role is equal to \l Qt::EditRole. See \l{QAbstractItemModel::}{roleNames}()
 for the built-in role names. However, real life models would usually register custom roles.
 
+\node If a model role is bound to a \li{Required Property}{required property}, assigning to
+that property will not modify the model. It will instead break the binding to the model (just
+like assigning to any other property breaks existing bindings). If you want to use
+required properties and change the model data, make model also a required property and assign to
+\e model.propertyName.
+
 For more information, visit the \l{qtquick-modelviewsdata-cppmodels.html#changing-model-data}{Using C++ Models with Qt Quick Views}
 article.
 
diff --git a/src/quick/doc/src/dynamicview-tutorial.qdoc b/src/quick/doc/src/dynamicview-tutorial.qdoc
index 6f44ba1947..d221e2ae62 100644
--- a/src/quick/doc/src/dynamicview-tutorial.qdoc
+++ b/src/quick/doc/src/dynamicview-tutorial.qdoc
@@ -50,7 +50,6 @@ directory.
 
 /*!
 \title QML Dynamic View Ordering Tutorial 1 - A Simple ListView and Delegate
-\contentspage QML Dynamic View Ordering Tutorial
 \previouspage QML Dynamic View Ordering Tutorial
 \nextpage QML Dynamic View Ordering Tutorial 2 - Dragging View Items
 
@@ -85,7 +84,6 @@ The second part of the application is the ListView itself to which we bind the m
 
 /*!
 \title QML Dynamic View Ordering Tutorial 2 - Dragging View Items
-\contentspage QML Dynamic View Ordering Tutorial
 \previouspage QML Dynamic View Ordering Tutorial 1 - A Simple ListView and Delegate
 \nextpage QML Dynamic View Ordering Tutorial 3 - Moving Dragged Items
 
@@ -128,7 +126,6 @@ so that is above other items in the stacking order and isn't obscured as it is d
 
 /*!
 \title QML Dynamic View Ordering Tutorial 3 - Moving Dragged Items
-\contentspage QML Dynamic View Ordering Tutorial
 \previouspage QML Dynamic View Ordering Tutorial 2 - Dragging View Items
 \nextpage QML Dynamic View Ordering Tutorial 4 - Sorting Items
 
@@ -180,7 +177,6 @@ property of the view and bind the \l {DelegateModel::}{model} and
 
 /*!
 \title QML Dynamic View Ordering Tutorial 4 - Sorting Items
-\contentspage QML Dynamic View Ordering Tutorial
 \previouspage QML Dynamic View Ordering Tutorial 3 - Moving Dragged Items
 
 \example tutorials/dynamicview/dynamicview4
diff --git a/src/quick/doc/src/examples.qdoc b/src/quick/doc/src/examples.qdoc
index a913af47c1..9a1308440f 100644
--- a/src/quick/doc/src/examples.qdoc
+++ b/src/quick/doc/src/examples.qdoc
@@ -177,6 +177,7 @@ Creator.
         \li \l{Scene Graph - OpenGL Under QML}{OpenGL Under QML}
         \li \l{Scene Graph - Direct3D 11 Under QML}{Direct3D 11 Under QML}
         \li \l{Scene Graph - Vulkan Under QML}{Vulkan Under QML}
+        \li \l{Scene Graph - Vulkan Texture Import}{Vulkan Texture Import}
         \li \l{Scene Graph - Custom Rendering with QSGRenderNode}{Render Node}
         \li \l{Scene Graph - Painted Item}{Painted Item}
         \li \l{Scene Graph - Graph}{Graph}
diff --git a/src/quick/doc/src/tutorial.qdoc b/src/quick/doc/src/tutorial.qdoc
index 20021f2432..7cb5f655e8 100644
--- a/src/quick/doc/src/tutorial.qdoc
+++ b/src/quick/doc/src/tutorial.qdoc
@@ -54,7 +54,6 @@ Tutorial chapters:
 /*!
 \page qml-tutorial1.html
 \title QML Tutorial 1 - Basic Types
-\contentspage QML Tutorial
 \previouspage QML Tutorial
 \nextpage QML Tutorial 2 - QML Components
 
@@ -112,7 +111,6 @@ qmlscene tutorials/helloworld/tutorial1.qml
 /*!
 \page qml-tutorial2.html
 \title QML Tutorial 2 - QML Components
-\contentspage QML Tutorial
 \previouspage QML Tutorial 1 - Basic Types
 \nextpage QML Tutorial 3 - States and Transitions
 
@@ -184,7 +182,6 @@ We can react to any signal of our component through a property of the name \e 'o
 /*!
 \page qml-tutorial3.html
 \title QML Tutorial 3 - States and Transitions
-\contentspage QML Tutorial
 \previouspage QML Tutorial 2 - QML Components
 
 In this chapter, we make this example a little bit more dynamic by introducing states and transitions.