TableView pixelator example

Example of a QML TableView with custom table model.
Inspired from the original pixelator example from the widget world.

Change-Id: Ic33e6d2e9320fe135d56dde92326dd8a606fe109
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>

8 files changed, 488 insertions, 0 deletions

diff --git a/examples/quick/tableview/doc/images/qt-pixelator.png b/examples/quick/tableview/doc/images/qt-pixelator.png
new file mode 100644
index 0000000000..a6c4a3b40b
--- /dev/null
+++ b/examples/quick/tableview/doc/images/qt-pixelator.png
diff --git a/examples/quick/tableview/doc/src/tableview.qdoc b/examples/quick/tableview/doc/src/tableview.qdoc
new file mode 100644
index 0000000000..e0d9200730
--- /dev/null
+++ b/examples/quick/tableview/doc/src/tableview.qdoc
@@ -0,0 +1,95 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 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$
+**
+****************************************************************************/
+/*!
+    \title Qt Quick TableViews examples - Pixelator
+    \example tableview
+    \brief The Pixelator example shows how a QML TableView and a delegate
+    can be used for custom table models.
+
+    \image qt-pixelator.png
+    \ingroup qtquickexamples
+
+    \include examples-run.qdocinc
+
+    \snippet tableview/imagemodel.h model
+
+    We only require a simple, read-only table model. Thus, we need to implement
+    functions to indicate the dimensions of the image and supply data to the
+    TableView.
+    We use the \l{Qt property system}{Qt Property System} and a source property
+    as \c QString to set the path of the image.
+
+    \snippet tableview/imagemodel.cpp setsource
+
+    Here we load the image when the source path is set.
+    When the source path has changed, we need to call \c beginResetModel() before.
+    After the image has been loaded, we need to call \c endResetModel().
+
+    \snippet tableview/imagemodel.cpp rowcolcount
+
+    The row and column count is set to image height and width, respectively.
+
+    \snippet tableview/imagemodel.cpp data
+
+    This overloaded function allows us to access the pixel data from the image.
+    When we call this function with the display role, we return the pixel's
+    gray value.
+
+    \snippet tableview/main.cpp registertype
+
+    We need to register our model in the QML type system to be able to use it
+    from the QML side.
+
+    \snippet tableview/main.qml pixelcomponent
+
+    Each pixel in the \c TableView is displayed via a delegate component.
+    It contains an item that has an implicit height and width defining the
+    cell size of the table.
+    It also has a property for the gray value of the pixel that is retrieved
+    from the model.
+
+    \snippet tableview/main.qml rectshape
+
+    Inside the \c Item, there is a rounded \c Rectangle with the size and
+    radius according to the pixel's gray value.
+
+    \snippet tableview/main.qml interaction
+
+    For a little bit of interaction, we place a \c MouseArea inside the \c Item
+    and change the Rectangle's color on mouse over.
+
+    \snippet tableview/main.qml animation
+
+    The \c Rectangle also has a short color animation to fade between the
+    colors when it is changed.
+
+    \snippet tableview/main.qml tableview
+
+    The \c TableView spans over the whole window and has an instance of our
+    custom \c ImageModel attached.
+
+*/
diff --git a/examples/quick/tableview/imagemodel.cpp b/examples/quick/tableview/imagemodel.cpp
new file mode 100644
index 0000000000..827204bc06
--- /dev/null
+++ b/examples/quick/tableview/imagemodel.cpp
@@ -0,0 +1,108 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples 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$
+**
+****************************************************************************/
+
+#include "imagemodel.h"
+
+ImageModel::ImageModel(QObject *parent)
+    : QAbstractTableModel(parent)
+{
+}
+
+QString ImageModel::source() const
+{
+    return m_source;
+}
+
+//! [setsource]
+void ImageModel::setSource(const QString &source)
+{
+    if (m_source == source)
+        return;
+
+    beginResetModel();
+    m_source = source;
+    m_image.load(m_source);
+    endResetModel();
+}
+//! [setsource]
+
+//! [rowcolcount]
+int ImageModel::rowCount(const QModelIndex &parent) const
+{
+    if (parent.isValid())
+        return 0;
+    return m_image.height();
+}
+
+int ImageModel::columnCount(const QModelIndex &parent) const
+{
+    if (parent.isValid())
+        return 0;
+    return m_image.width();
+}
+//! [rowcolcount]
+
+
+//! [data]
+QVariant ImageModel::data(const QModelIndex &index, int role) const
+{
+    if (!index.isValid() || role != Qt::DisplayRole)
+        return QVariant();
+    return qGray(m_image.pixel(index.column(), index.row()));
+}
+//! [data]
+
+QVariant ImageModel::headerData(int /* section */, Qt::Orientation /* orientation */,
+                                int role) const
+{
+    if (role == Qt::SizeHintRole)
+        return QSize(1, 1);
+    return QVariant();
+}
diff --git a/examples/quick/tableview/imagemodel.h b/examples/quick/tableview/imagemodel.h
new file mode 100644
index 0000000000..bf0ec90da4
--- /dev/null
+++ b/examples/quick/tableview/imagemodel.h
@@ -0,0 +1,85 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples 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 IMAGEMODEL_H
+#define IMAGEMODEL_H
+
+#include <QAbstractTableModel>
+#include <QImage>
+
+//! [model]
+class ImageModel : public QAbstractTableModel
+{
+    Q_OBJECT
+    Q_PROPERTY(QString source READ source WRITE setSource NOTIFY sourceChanged)
+public:
+    ImageModel(QObject *parent = nullptr);
+
+    QString source() const;
+    void setSource(const QString &source);
+
+    int rowCount(const QModelIndex &parent = QModelIndex()) const override;
+    int columnCount(const QModelIndex &parent = QModelIndex()) const override;
+
+    QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
+
+    QVariant headerData(int /* section */, Qt::Orientation /* orientation */,
+                        int role) const override;
+
+signals:
+    void sourceChanged();
+
+private:
+    QString m_source;
+    QImage m_image;
+};
+//! [model]
+
+#endif // IMAGEMODEL_H
diff --git a/examples/quick/tableview/main.cpp b/examples/quick/tableview/main.cpp
new file mode 100644
index 0000000000..c57039556a
--- /dev/null
+++ b/examples/quick/tableview/main.cpp
@@ -0,0 +1,71 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples 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$
+**
+****************************************************************************/
+
+#include <QGuiApplication>
+#include <QQmlApplicationEngine>
+
+#include "imagemodel.h"
+
+int main(int argc, char *argv[])
+{
+    QGuiApplication app(argc, argv);
+
+    QQmlApplicationEngine engine;
+
+    //! [registertype]
+    qmlRegisterType<ImageModel>("ImageModel", 1, 0, "ImageModel");
+    //! [registertype]
+
+    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
+    if (engine.rootObjects().isEmpty())
+        return -1;
+
+    return app.exec();
+}
diff --git a/examples/quick/tableview/main.qml b/examples/quick/tableview/main.qml
new file mode 100644
index 0000000000..f471fc5c6b
--- /dev/null
+++ b/examples/quick/tableview/main.qml
@@ -0,0 +1,118 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the examples 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.12
+
+import QtQuick.Window 2.12
+import Qt.labs.tableview 1.0
+
+import ImageModel 1.0
+
+Window {
+    visible: true
+    width: 900
+    height: 900
+    title: qsTr("TableView Pixelator")
+
+    //! [pixelcomponent]
+    Component {
+        id: pixelDelegate
+
+        Item {
+            readonly property real gray: model.display / 255.0
+            readonly property real size: 16
+
+            implicitWidth: size
+            implicitHeight: size
+            //! [pixelcomponent]
+
+            //! [rectshape]
+            Rectangle {
+                id: rect
+                anchors.centerIn: parent
+                color: "#09102b"
+                radius: size - gray * size
+                implicitWidth: radius
+                implicitHeight: radius
+                //! [rectshape]
+
+                //! [animation]
+                ColorAnimation on color {
+                    id: colorAnimation
+                    running: false
+                    to: "#41cd52"
+                    duration: 1500
+                }
+                //! [animation]
+            }
+
+            //! [interaction]
+            MouseArea {
+                anchors.fill: parent
+                hoverEnabled: true
+                onEntered: rect.color = "#cecfd5"
+                onExited: colorAnimation.start()
+            }
+            //! [interaction]
+        }
+    }
+
+    //! [tableview]
+    TableView {
+        id: tableView
+        anchors.fill: parent
+        model: ImageModel {
+            source: ":/qt.png"
+        }
+
+        delegate: pixelDelegate
+    }
+    //! [tableview]
+}
diff --git a/examples/quick/tableview/qt.png b/examples/quick/tableview/qt.png
new file mode 100644
index 0000000000..e3301c4a02
--- /dev/null
+++ b/examples/quick/tableview/qt.png
diff --git a/examples/quick/tableview/tableview.pro b/examples/quick/tableview/tableview.pro
new file mode 100644
index 0000000000..ea8e3bd12b
--- /dev/null
+++ b/examples/quick/tableview/tableview.pro
@@ -0,0 +1,11 @@
+TEMPLATE = app
+
+QT += quick qml
+HEADERS += imagemodel.h
+SOURCES += main.cpp \
+        imagemodel.cpp
+
+RESOURCES += qt.png main.qml
+
+target.path = $$[QT_INSTALL_EXAMPLES]/quick/tableview
+INSTALLS += target