From: Michael Brasser Date: Tue, 26 Jun 2012 03:45:35 +0000 (+1000) Subject: Document the concept of creation context for QML Components. X-Git-Tag: 071012131707~78 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=73736a5f2e9668e4f38f5466df5df2ddf93e064f;p=profile%2Fivi%2Fqtdeclarative.git Document the concept of creation context for QML Components. Task-number: QTBUG-18011 Change-Id: I78d13df70a20fd9286a20fad4cc09f21591d3f9a Reviewed-by: Bea Lam --- diff --git a/src/qml/doc/snippets/qml/component/MyItem.qml b/src/qml/doc/snippets/qml/component/MyItem.qml new file mode 100644 index 0000000..8933e3c --- /dev/null +++ b/src/qml/doc/snippets/qml/component/MyItem.qml @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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 Nokia Corporation and its Subsidiary(-ies) 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.0 + +//![0] +Item { + property Component mycomponent: comp1 + + QtObject { + id: internalSettings + property color color: "green" + } + + Component { + id: comp1 + Rectangle { color: internalSettings.color; width: 400; height: 50 } + } +} +//![0] diff --git a/src/qml/doc/snippets/qml/component/main.qml b/src/qml/doc/snippets/qml/component/main.qml new file mode 100644 index 0000000..98c2274 --- /dev/null +++ b/src/qml/doc/snippets/qml/component/main.qml @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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 Nokia Corporation and its Subsidiary(-ies) 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.0 + +//![0] +ListView { + width: 400; height: 400 + model: 5 + delegate: myItem.mycomponent //will create green Rectangles + + MyItem { id: myItem } +} +//![0] diff --git a/src/qml/qml/qqmlcomponent.cpp b/src/qml/qml/qqmlcomponent.cpp index 42dbb2b..00d42d7 100644 --- a/src/qml/qml/qqmlcomponent.cpp +++ b/src/qml/qml/qqmlcomponent.cpp @@ -225,6 +225,27 @@ static inline QString buildTypeNameForDebug(const QMetaObject *metaObject) \c Component objects can also be created dynamically using \l{QML:Qt::createComponent()}{Qt.createComponent()}. + + \section2 Creation Context + + The creation context of a Component corresponds to the context where the Component was declared. + This context is used as the parent context (creating a \l{qtqml-documents-scope.html#component-instance-hierarchy}{context hierarchy}) + when the component is instantiated by an object such as a ListView or a Loader. + + In the following example, \c comp1 is created within the root context of MyItem.qml, and any objects + instantiated from this component will have access to the ids and properties within that context, + such as \c internalSettings.color. When \c comp1 is used as a ListView delegate in another context + (as in main.qml below), it will continue to have access to the properties of its creation context + (which would otherwise be private to external users). + + \table + \row + \li MyItem.qml + \li main.qml + \row + \li \snippet qml/component/MyItem.qml 0 + \li \snippet qml/component/main.qml 0 + \endtable */ /*! diff --git a/src/quick/doc/snippets/qml/loader/MyComponent.qml b/src/quick/doc/snippets/qml/loader/MyComponent.qml new file mode 100644 index 0000000..b0aadfc --- /dev/null +++ b/src/quick/doc/snippets/qml/loader/MyComponent.qml @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms and +** conditions contained in a signed written agreement between you and Nokia. +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Text { text: index } diff --git a/src/quick/doc/snippets/qml/loader/creationContext1.qml b/src/quick/doc/snippets/qml/loader/creationContext1.qml new file mode 100644 index 0000000..1c73842 --- /dev/null +++ b/src/quick/doc/snippets/qml/loader/creationContext1.qml @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms and +** conditions contained in a signed written agreement between you and Nokia. +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import QtQuick 2.0 + +//![0] +Item { + width: 400 + height: 400 + + Component { + id: myComponent + Text { text: index } //fails + } + + ListView { + anchors.fill: parent + model: 5 + delegate: Component { + id: delegateComponent + Loader { + sourceComponent: myComponent + } + } + } +} +//![0] diff --git a/src/quick/doc/snippets/qml/loader/creationContext2.qml b/src/quick/doc/snippets/qml/loader/creationContext2.qml new file mode 100644 index 0000000..3b873a1 --- /dev/null +++ b/src/quick/doc/snippets/qml/loader/creationContext2.qml @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms and +** conditions contained in a signed written agreement between you and Nokia. +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Item { + width: 400 + height: 400 + + ListView { + anchors.fill: parent + model: 5 +//![0] + delegate: Component { + Loader { + sourceComponent: Component { + Text { text: index } //okay + } + } + } +//![0] + } +} + diff --git a/src/quick/doc/snippets/qml/loader/creationContext3.qml b/src/quick/doc/snippets/qml/loader/creationContext3.qml new file mode 100644 index 0000000..e686701 --- /dev/null +++ b/src/quick/doc/snippets/qml/loader/creationContext3.qml @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms and +** conditions contained in a signed written agreement between you and Nokia. +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import QtQuick 2.0 + +Item { + width: 400 + height: 400 + + ListView { + anchors.fill: parent + model: 5 +//![0] + delegate: Component { + Loader { + source: "MyComponent.qml" //okay + } + } +//![0] + } +} + diff --git a/src/quick/doc/snippets/qml/loader/creationContext4.qml b/src/quick/doc/snippets/qml/loader/creationContext4.qml new file mode 100644 index 0000000..5a7da40 --- /dev/null +++ b/src/quick/doc/snippets/qml/loader/creationContext4.qml @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms and +** conditions contained in a signed written agreement between you and Nokia. +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import QtQuick 2.0 + +//![0] +Item { + width: 400 + height: 400 + + Component { + id: myComponent + Text { text: modelIndex } //okay + } + + ListView { + anchors.fill: parent + model: 5 + delegate: Component { + Loader { + property int modelIndex: index + sourceComponent: myComponent + } + } + } +} +//![0] diff --git a/src/quick/items/qquickloader.cpp b/src/quick/items/qquickloader.cpp index 7945a35..bd927a1 100644 --- a/src/quick/items/qquickloader.cpp +++ b/src/quick/items/qquickloader.cpp @@ -267,6 +267,31 @@ qreal QQuickLoaderPrivate::getImplicitHeight() const Since QtQuick 2.0 Loader can also load non-visual components. + \section2 Using a Loader within a view delegate + + In some cases you may wish to use a Loader within a view delegate to improve delegate + loading performance. This works well in most cases, but there is one important issue to + be aware of related to the \l{QtQuick2::Component#creation-context}{creation context} of a Component. + + In the following example, the \c index context property inserted by the ListView into \c delegateComponent's + context will be inaccessible to Text, as the Loader will use the creation context of \c myComponent as the parent + context when instantiating it, and \c index does not refer to anything within that context chain. + + \snippet qml/loader/creationContext1.qml 0 + + In this situation we can either move the component inline, + + \snippet qml/loader/creationContext2.qml 0 + + into a separate file, + + \snippet qml/loader/creationContext3.qml 0 + + or explicitly set the required information as a property of the Loader (this works because the + Loader sets itself as the context object for the component it is loading). + + \snippet qml/loader/creationContext4.qml 0 + \sa {dynamic-object-creation}{Dynamic Object Creation} */