Expand documention of status property with examples

Task-number: QTBUG-8542

4 files changed, 40 insertions, 1 deletions

diff --git a/src/declarative/graphicsitems/qdeclarativeimage.cpp b/src/declarative/graphicsitems/qdeclarativeimage.cpp
index 99ab053..2739ab8 100644
--- a/src/declarative/graphicsitems/qdeclarativeimage.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeimage.cpp
@@ -232,6 +232,16 @@ qreal QDeclarativeImage::paintedHeight() const
     \o Error - an error occurred while loading the image
     \endlist
 
+    Note that a change in the status property does not cause anything to happen
+    (although it reflects what has happened with the image internally). If you wish
+    to react to the change in status you need to do it yourself, for example in one
+    of the following ways:
+    \list
+    \o Create a state, so that a state change occurs, e.g. State{name: 'loaded'; when: image.status = Image.Ready;}
+    \o Do something inside the onStatusChanged signal handler, e.g. Image{id: image; onStatusChanged: if(image.status == Image.Ready) console.log('Loaded');}
+    \o Bind to the status variable somewhere, e.g. Text{text: if(image.status!=Image.Ready){'Not Loaded';}else{'Loaded';}}
+    \endlist
+
     \sa progress
 */
 
diff --git a/src/declarative/graphicsitems/qdeclarativeloader.cpp b/src/declarative/graphicsitems/qdeclarativeloader.cpp
index bd89321..b0499d7 100644
--- a/src/declarative/graphicsitems/qdeclarativeloader.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeloader.cpp
@@ -320,6 +320,15 @@ void QDeclarativeLoaderPrivate::_q_sourceLoaded()
     \o Error - an error occurred while loading the QML source
     \endlist
 
+    Note that a change in the status property does not cause anything to happen
+    (although it reflects what has happened to the loader internally). If you wish
+    to react to the change in status you need to do it yourself, for example in one
+    of the following ways:
+    \list
+    \o Create a state, so that a state change occurs, e.g. State{name: 'loaded'; when: loader.status = Loader.Ready;}
+    \o Do something inside the onStatusChanged signal handler, e.g. Loader{id: loader; onStatusChanged: if(loader.status == Loader.Ready) console.log('Loaded');}
+    \o Bind to the status variable somewhere, e.g. Text{text: if(loader.status!=Loader.Ready){'Not Loaded';}else{'Loaded';}}
+    \endlist
     \sa progress
 */
 
diff --git a/src/declarative/util/qdeclarativefontloader.cpp b/src/declarative/util/qdeclarativefontloader.cpp
index 4d12ae1..8f5f537 100644
--- a/src/declarative/util/qdeclarativefontloader.cpp
+++ b/src/declarative/util/qdeclarativefontloader.cpp
@@ -189,6 +189,16 @@ void QDeclarativeFontLoader::setName(const QString &name)
     \o Loading - the font is currently being loaded
     \o Error - an error occurred while loading the font
     \endlist
+
+    Note that a change in the status property does not cause anything to happen
+    (although it reflects what has happened to the font loader internally). If you wish
+    to react to the change in status you need to do it yourself, for example in one
+    of the following ways:
+    \list
+    \o Create a state, so that a state change occurs, e.g. State{name: 'loaded'; when: loader.status = FontLoader.Ready;}
+    \o Do something inside the onStatusChanged signal handler, e.g. FontLoader{id: loader; onStatusChanged: if(loader.status == FontLoader.Ready) console.log('Loaded');}
+    \o Bind to the status variable somewhere, e.g. Text{text: if(loader.status!=FontLoader.Ready){'Not Loaded';}else{'Loaded';}}
+    \endlist
 */
 QDeclarativeFontLoader::Status QDeclarativeFontLoader::status() const
 {
diff --git a/src/declarative/util/qdeclarativexmllistmodel.cpp b/src/declarative/util/qdeclarativexmllistmodel.cpp
index 162a669..d260ada 100644
--- a/src/declarative/util/qdeclarativexmllistmodel.cpp
+++ b/src/declarative/util/qdeclarativexmllistmodel.cpp
@@ -647,11 +647,21 @@ void QDeclarativeXmlListModel::setNamespaceDeclarations(const QString &declarati
     This property holds the status of data source loading.  It can be one of:
     \list
     \o Null - no data source has been set
-    \o Ready - nthe data source has been loaded
+    \o Ready - the data source has been loaded
     \o Loading - the data source is currently being loaded
     \o Error - an error occurred while loading the data source
     \endlist
 
+    Note that a change in the status property does not cause anything to happen
+    (although it reflects what has happened to the XmlListModel internally). If you wish
+    to react to the change in status you need to do it yourself, for example in one
+    of the following ways:
+    \list
+    \o Create a state, so that a state change occurs, e.g. State{name: 'loaded'; when: xmlListModel.status = XmlListModel.Ready;}
+    \o Do something inside the onStatusChanged signal handler, e.g. XmlListModel{id: xmlListModel; onStatusChanged: if(xmlListModel.status == XmlListModel.Ready) console.log('Loaded');}
+    \o Bind to the status variable somewhere, e.g. Text{text: if(xmlListModel.status!=XmlListModel.Ready){'Not Loaded';}else{'Loaded';}}
+    \endlist
+
     \sa progress
 
 */