Add some guidelines for declaring objects as properties of Components.

Task-number: QTBUG-20198
Change-Id: Id8ba8901be6c4f06974d1afd32f1932f867e2544
Reviewed-on: http://codereview.qt.nokia.com/2540
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Bea Lam <bea.lam@nokia.com>

3 files changed, 26 insertions, 3 deletions

diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc
index 850aaecfc4..9860dd4aa2 100644
--- a/doc/src/declarative/qmlreusablecomponents.qdoc
+++ b/doc/src/declarative/qmlreusablecomponents.qdoc
@@ -139,5 +139,22 @@ children which is beneficial for certain types of interfaces. However, since
 to be exposed.
 
 \snippet doc/src/snippets/declarative/reusablecomponents/focusbutton.qml document
-*/
 
+\section2 Child Components
+
+Objects or Items declared within a component can be made accessible by binding their id to a
+property alias.
+
+\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent begin
+\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml object alias
+\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml text
+\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent end
+
+The advantage of using an alias instead a property of type of the object is that the value of
+the alias cannot be overridden, and members of the object can be used in property bindings when
+declaring an instance of the component.
+\snippet doc/src/snippets/declarative/reusablecomponents/application.qml grouped property
+If a property of type \c Text was used instead of an alias in this instance there would be no
+guarantee that \c label would be initialized before the binding was attempted which would cause
+the binding to fail.
+*/
diff --git a/doc/src/snippets/declarative/reusablecomponents/Button.qml b/doc/src/snippets/declarative/reusablecomponents/Button.qml
index 3b97e00952..6a0567ec99 100644
--- a/doc/src/snippets/declarative/reusablecomponents/Button.qml
+++ b/doc/src/snippets/declarative/reusablecomponents/Button.qml
@@ -51,6 +51,9 @@ Rectangle {
     smooth: true; radius: 9
     property alias text: label.text
 //! [properties]
+//! [object alias]
+    property alias label: label
+//! [object alias]
     border {color: "#B9C5D0"; width: 1}
 
     gradient: Gradient {
@@ -58,7 +61,7 @@ Rectangle {
         GradientStop {color: "#99C0E5"; position: 0.57}
         GradientStop {color: "#719FCB"; position: 0.9}
     }
-
+//![text]
     Text {
         id: label
         anchors.centerIn: parent
@@ -66,7 +69,7 @@ Rectangle {
         font.pointSize: 12
         color: "blue"
     }
-
+//![text]
     MouseArea {
         anchors.fill: parent
         onClicked: console.log(text + " clicked")
diff --git a/doc/src/snippets/declarative/reusablecomponents/application.qml b/doc/src/snippets/declarative/reusablecomponents/application.qml
index a09b276b73..4fd8ed2bf6 100644
--- a/doc/src/snippets/declarative/reusablecomponents/application.qml
+++ b/doc/src/snippets/declarative/reusablecomponents/application.qml
@@ -50,6 +50,9 @@ Rectangle {
         Button {}
         Button {text: "Me Too!"}
         Button {text: "Me Three!"}
+//! [grouped property]
+        Button {label.color: "green"}
+//! [grouped property]
     }
 }
 //! [document]