Document the concept of creation context for QML Components.

Task-number: QTBUG-18011
Change-Id: I78d13df70a20fd9286a20fad4cc09f21591d3f9a
Reviewed-by: Bea Lam <bea.lam@nokia.com>

9 files changed, 450 insertions, 0 deletions

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 0000000000..8933e3cd2b
--- /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 0000000000..98c22741fc
--- /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 42dbb2baa4..00d42d7057 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 0000000000..b0aadfce3c
--- /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 0000000000..1c738420fb
--- /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 0000000000..3b873a1725
--- /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 0000000000..e686701c72
--- /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 0000000000..5a7da4000c
--- /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 7945a359cc..bd927a115e 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}
 */