diff options
author | Qt Forward Merge Bot <qt_forward_merge_bot@qt-project.org> | 2020-02-17 01:01:00 +0100 |
---|---|---|
committer | Ulf Hermann <ulf.hermann@qt.io> | 2020-02-17 10:21:59 +0100 |
commit | 3e758800b4daf8fbc870a2ff5d54fce9d4402ce8 (patch) | |
tree | ba237b9da1c7dfd08bf13e71c5dbd6b3c2e77633 /src/quick/doc | |
parent | 925a0e499a5dbdb180fd9969a79abf96006ce4fd (diff) | |
parent | 55546991e24ca6799709cbe0171b9ab87216c35f (diff) |
Merge remote-tracking branch 'origin/5.15' into dev
Conflicts:
src/imports/qtqml/plugin.cpp
src/qml/qml/qqml.h
src/qml/qml/qqmlmetatype.cpp
src/qml/qml/qqmlmetatype_p.h
src/qml/qml/qqmltypeloader.cpp
src/qml/types/qqmlbind.cpp
src/quick/items/qquickitemsmodule.cpp
tests/auto/qml/qqmlecmascript/tst_qqmlecmascript.cpp
Change-Id: I52548938a582cb6510271ed4bc3a9aa0c3c11df6
Diffstat (limited to 'src/quick/doc')
3 files changed, 102 insertions, 0 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/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: |