diff options
Diffstat (limited to 'src/quick/doc')
7 files changed, 221 insertions, 62 deletions
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/snippets/qml/xmlrole.xml b/src/quick/doc/snippets/qml/xmlrole.xml deleted file mode 100644 index 70280e067d..0000000000 --- a/src/quick/doc/snippets/qml/xmlrole.xml +++ /dev/null @@ -1,20 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1" ?> -<catalog> - <book type="Online" wanted="true"> - <title>Qt 5 Cadaques</title> - <year>2014</year> - <author>Juergen Bocklage-Ryannel</author> - <author>Johan Thelin</author> - </book> - <book type="Hardcover"> - <title>C++ GUI Programming with Qt 4</title> - <year>2006</year> - <author>Jasmin Blanchette</author> - <author>Mark Summerfield</author> - </book> - <book type="Paperback"> - <title>Programming with Qt</title> - <year>2002</year> - <author>Matthias Kalle Dalheimer</author> - </book> - </catalog> 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/qmltypereference.qdoc b/src/quick/doc/src/qmltypereference.qdoc index 418475f100..528444cad3 100644 --- a/src/quick/doc/src/qmltypereference.qdoc +++ b/src/quick/doc/src/qmltypereference.qdoc @@ -179,6 +179,7 @@ available when you import \c QtQuick. \li \l bool \c font.kerning \li \l bool \c font.preferShaping \li \l enumeration \c font.hintingPreference + \li \l string \c font.styleName \endlist Example: |