summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorAaron Kennedy <aaron.kennedy@nokia.com>2009-10-20 05:14:01 (GMT)
committerAaron Kennedy <aaron.kennedy@nokia.com>2009-10-20 05:14:01 (GMT)
commit61b287e14d75a86c44f99f1110848c9036f63ded (patch)
tree2c7a7f3aa353ef09d3f85b5d2da52915e0055f12 /doc
parent214285b246d8cd65900a21262585b55767b4b8b3 (diff)
downloadQt-61b287e14d75a86c44f99f1110848c9036f63ded.zip
Qt-61b287e14d75a86c44f99f1110848c9036f63ded.tar.gz
Qt-61b287e14d75a86c44f99f1110848c9036f63ded.tar.bz2
Doc
Diffstat (limited to 'doc')
-rw-r--r--doc/src/declarative/scope.qdoc108
1 files changed, 102 insertions, 6 deletions
diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc
index df7a215..7dbbefc 100644
--- a/doc/src/declarative/scope.qdoc
+++ b/doc/src/declarative/scope.qdoc
@@ -46,7 +46,7 @@
\l {Property Binding}s and \l {ECMAScript Blocks} are executed in a scope chain automatically
established by QML when constructing a component instance. QML is a \e {dynamically scoped}
language. Different object instances instantiated from the same component can exist in
-dramatically different scope chains.
+different scope chains.
\image qml-scope.png
@@ -262,15 +262,111 @@ Item {
\section1 QML Component chain
-\section2 IDs
-\section2 Script Methods
-\section2 Root Object
+When a QML component is instantiated it is given a parent component instance. The parent
+component instance is immutable - it is not effected, for example, by changes in the instance's
+visual parent (in the case of visual elements). Should name resolution fail within the
+\l {QML Local Scope}, this parent chain is searched.
+
+For each component instance in the chain, the following are examined:
+
+\list 1
+\o IDs
+\o Script Methods
+\o Root Object
+\endlist
+
+This list is a sub-set of that in the \l {QML Local Scope}.
+
+Sub-components used within a component have their parent component instance set to the component
+instance that created them. In the following example, the two \c Button instances have the
+\c main.qml instance as their parent component instance. If the \c Button type was used from
+within another QML file, it may have a difference parent component instance, and consequently
+the \c buttonClicked() method may resolve differently.
+
+\table
+\row
+\o
+\code
+// main.qml
+Item {
+ function buttonClicked(var data) {
+ print(data + " clicked");
+ }
+
+ Button { text: "Button1" }
+ Button { text: "Button2" }
+}
+\endcode
+\o
+\code
+// Button.qml
+Rectangle {
+ id: root
+ property string text
+ width: 80
+ height: 30
+ Text {
+ anchors.centerIn: parent
+ text: root.text
+ }
+ MouseRegion {
+ anchors.fill: parent
+ onClicked: buttonClicked(text)
+ }
+}
+\endcode
+\endtable
+
+The code above discourages the re-use of the \c Button component, as it has a hard dependency
+on the environment in which it is used. Tightly coupling two types together like this should
+only be used when the components are within the same module, and the author controls the
+implementations of both.
+
+In the following example, the \l ListView sets the parent component instance of each of its
+delegates to its own component instance. In this way, the main component can easily pass data
+into the \l ListView delegates.
+
+\code
+Item {
+ property color delegateColor: "red"
+
+ ListView {
+ delegate: Component {
+ Rectangle {
+ color: delegateColor
+ }
+ }
+ }
+}
+\endcode
\section1 QmlContext chain
-App provided data.
+The \l QmlContext chain allows C++ applications to pass data into QML applications.
+\l QmlComponent object instances created from C++ are passed a \l QmlContext in which they
+are created. Variables defined in this context appear in the scope chain. Each QmlContext
+also defines a parent context. Variables in child QmlContext's shadow those in its parent.
+
+Consider the following QmlContext tree.
+
+\image qml-context-tree.png
+
+The value of \c background in \c {Context 1} would be used if it was instantiated in
+\c {Context 1}, where as the value of the \c background in the root context would be used if
+the component instance was instantiated in \c {Context 2}.
+
+\code
+import Qt 4.6
+
+Rectangle {
+ id: myRect
+ width: 100; height: 100
+ color: background
+}
+\endcode
\section1 QML Global Object
-Contains all the properties ECMAScript defines, plus some QML ones. Documented \l {QML Global Object}.
+The \l {QML Global Object} contains all the properties of the ECMAScript global object, plus some
+QML specific extensions.
*/