From 15b232bf694fedf553abac09af077a58ce571f9d Mon Sep 17 00:00:00 2001
From: Gunnar Sletta <gunnar.sletta@digia.com>
Date: Wed, 30 Jan 2013 10:43:59 +0100
Subject: [PATCH] Document QQuickItem::itemChange and QQuickItem::window() properly

Change-Id: Ic0e50ae8760c0c3050db3a095b0fa86679a0c010
Reviewed-by: Alan Alpert <aalpert@rim.com>
---
 src/quick/items/qquickitem.cpp |   90 ++++++++++++++++++++++++++++++++++++++-
 1 files changed, 87 insertions(+), 3 deletions(-)

diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index 08f60ae..d72a7b1 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -1686,15 +1686,91 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus)
 
 /*!
     \enum QQuickItem::ItemChange
-    \internal
+    \brief Used in conjunction with QQuickItem::itemChange() to notify
+    the item about certain types of changes.
+
+    \value ItemChildAddedChange A child was added. ItemChangeData::item contains
+    the added child.
+
+    \value ItemChildRemovedChange A child was removed. ItemChangeData::item
+    contains the removed child.
+
+    \value ItemSceneChange The item was added to or removed from a scene. The
+    QQuickWindow rendering the scene is specified in using ItemChangeData::window.
+    The window parameter is null when the item is removed from a scene.
+
+    \value ItemVisibleHasChanged The item's visibility has changed.
+    ItemChangeData::boolValue contains the new visibility.
+
+    \value ItemParentHasChanged The item's parent has changed.
+    ItemChangeData::item contains the new parent.
+
+    \value ItemOpacityHasChanged The item's opacity has changed.
+    ItemChangeData::realValue contains the new opacity.
+
+    \value ItemActiveFocusHasChanged The item's focus has changed.
+    ItemChangeData::boolValue contains whether the item has focus or not.
+
+    \value ItemRotationHasChanged The item's rotation has changed.
+    ItemChangeData::realValue contains the new rotation.
 */
 
 /*!
     \class QQuickItem::ItemChangeData
-    \internal
+    \inmodule QtQuick
+    \brief Adds supplimentary information to the QQuickItem::itemChange()
+    function.
+
+    The meaning of each member of this class is defined by the change type.
+
+    \sa QQuickItem::ItemChange
 */
 
 /*!
+    \fn QQuickItem::ItemChangeData::ItemChangeData(QQuickItem *)
+    \internal
+ */
+
+/*!
+    \fn QQuickItem::ItemChangeData::ItemChangeData(QQuickWindow *)
+    \internal
+ */
+
+/*!
+    \fn QQuickItem::ItemChangeData::ItemChangeData(qreal)
+    \internal
+ */
+
+/*!
+    \fn QQuickItem::ItemChangeData::ItemChangeData(bool)
+    \internal
+ */
+
+/*!
+    \variable QQuickItem::ItemChangeData::realValue
+    Contains supplimentary information to the QQuickItem::itemChange() function.
+    \sa QQuickItem::ItemChange
+ */
+
+/*!
+    \variable QQuickItem::ItemChangeData::boolValue
+    Contains supplimentary information to the QQuickItem::itemChange() function.
+    \sa QQuickItem::ItemChange
+ */
+
+/*!
+    \variable QQuickItem::ItemChangeData::item
+    Contains supplimentary information to the QQuickItem::itemChange() function.
+    \sa QQuickItem::ItemChange
+ */
+
+/*!
+    \variable QQuickItem::ItemChangeData::window
+    Contains supplimentary information to the QQuickItem::itemChange() function.
+    \sa QQuickItem::ItemChange
+ */
+
+/*!
     \enum QQuickItem::TransformOrigin
 
     Controls the point about which simple transforms like scale apply.
@@ -2141,6 +2217,11 @@ void QQuickItem::stackAfter(const QQuickItem *sibling)
 
 /*!
   Returns the window in which this item is rendered.
+
+  The item does not have a window until it has been assigned into a scene. To
+  get notification about this, reimplement the itemChange() function and
+  listen for the ItemSceneChange change. The itemChange() function is called
+  both when the item is entered into a scene and when it is removed from a scene.
   */
 QQuickWindow *QQuickItem::window() const
 {
@@ -4170,7 +4251,10 @@ void QQuickItemPrivate::deliverDragEvent(QEvent *e)
 #endif // QT_NO_DRAGANDDROP
 
 /*!
-  \internal
+    Called when \a change occurs for this item.
+
+    \a value contains extra information relating to the change, when
+    applicable.
   */
 void QQuickItem::itemChange(ItemChange change, const ItemChangeData &value)
 {
-- 
1.7.2.5