improvements to docs and examples

6 files changed, 63 insertions, 47 deletions

diff --git a/src/declarative/graphicsitems/qdeclarativeimage.cpp b/src/declarative/graphicsitems/qdeclarativeimage.cpp
index 34d33f5..90738c8 100644
--- a/src/declarative/graphicsitems/qdeclarativeimage.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeimage.cpp
@@ -324,17 +324,34 @@ qreal QDeclarativeImage::paintedHeight() const
 /*!
     \qmlproperty QSize Image::sourceSize
 
-    This property holds the size of the loaded image, in pixels.
+    This property holds the actual width and height of the loaded image.
 
-    This is used to control the storage used by a loaded image. Unlike
-    the width and height properties, which scale the painting of the image, this property
-    affects the number of pixels stored.
+    Unlike the \l {Item::}{width} and \l {Item::}{height} properties, which scale
+    the painting of the image, this property sets the actual number of pixels
+    stored for the loaded image so that large images do not use more
+    memory than necessary. For example, this ensures the image is memory is no
+    larger than 1024x1024 pixels, regardless of the Image's \l {Item::}{width} and 
+    \l {Item::}{height} values:
+
+    \code
+    Rectangle {
+        width: ...
+        height: ...
+
+        Image {
+           anchors.fill: parent
+           source: "reallyBigImage.jpg"
+           sourceSize.width: 1024
+           sourceSize.height: 1024
+        }
+    }
+    \endcode
 
     If the image's actual size is larger than the sourceSize, the image is scaled down.
     If only one dimension of the size is set to greater than 0, the
     other dimension is set in proportion to preserve the source image's aspect ratio.
     (The \l fillMode is independent of this.)
-   
+
     If the source is an instrinsically scalable image (eg. SVG), this property
     determines the size of the loaded image regardless of intrinsic size.
     Avoid changing this property dynamically; rendering an SVG is \e slow compared
@@ -344,34 +361,8 @@ qreal QDeclarativeImage::paintedHeight() const
     be no greater than this property specifies. For some formats (currently only JPEG),
     the whole image will never actually be loaded into memory.
  
-    \note \e{Changing this property dynamically will lead to the image source being reloaded,
-    potentially even from the network if it is not in the disk cache.}
-
-    Here is an example that ensures the size of the image in memory is
-    no larger than 1024x1024 pixels, regardless of the size of the Image element.
-
-    \code
-    Image {
-       anchors.fill: parent
-       source: "images/reallyBigImage.jpg"
-       sourceSize.width: 1024
-       sourceSize.height: 1024
-    }
-    \endcode
-
-    The example below ensures the memory used by the image is no more than necessary 
-    to display the image at the size of the Image element.
-    Of course if the Image element is resized a costly reload will be required, so
-    use this technique \e only when the Image size is fixed.
-
-    \code
-    Image {
-       anchors.fill: parent
-       source: "images/reallyBigImage.jpg"
-       sourceSize.width: width
-       sourceSize.height: height
-    }
-    \endcode
+    \note \e {Changing this property dynamically causes the image source to be reloaded,
+    potentially even from the network, if it is not in the disk cache.}
 */
 
 void QDeclarativeImage::updatePaintedGeometry()
@@ -415,6 +406,8 @@ void QDeclarativeImage::geometryChanged(const QRectF &newGeometry, const QRectF
     Image can handle any image format supported by Qt, loaded from any URL scheme supported by Qt.
 
     The URL may be absolute, or relative to the URL of the component.
+
+    \sa QDeclarativeImageProvider
 */
 
 /*!
diff --git a/src/declarative/graphicsitems/qdeclarativeitem.cpp b/src/declarative/graphicsitems/qdeclarativeitem.cpp
index 7022fac..190b22c 100644
--- a/src/declarative/graphicsitems/qdeclarativeitem.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeitem.cpp
@@ -2097,7 +2097,7 @@ QDeclarativeAnchorLine QDeclarativeItemPrivate::baseline() const
   relationship with other items.
 
   Margins apply to top, bottom, left, right, and fill anchors.
-  The margins property can be used to set all of the various margins at once, to the same value.
+  The \c anchors.margins property can be used to set all of the various margins at once, to the same value.
 
   Offsets apply for horizontal center, vertical center, and baseline anchors.
 
@@ -2132,10 +2132,12 @@ QDeclarativeAnchorLine QDeclarativeItemPrivate::baseline() const
   \endqml
   \endtable
 
-  anchors.fill provides a convenient way for one item to have the
+  \c anchors.fill provides a convenient way for one item to have the
   same geometry as another item, and is equivalent to connecting all
   four directional anchors.
 
+  To clear an anchor value, set it to \c undefined.
+
   \note You can only anchor an item to siblings or a parent.
 
   For more information see \l {anchor-layout}{Anchor Layouts}.
diff --git a/src/declarative/graphicsitems/qdeclarativemousearea.cpp b/src/declarative/graphicsitems/qdeclarativemousearea.cpp
index 7b65ca7..b7b0c9e 100644
--- a/src/declarative/graphicsitems/qdeclarativemousearea.cpp
+++ b/src/declarative/graphicsitems/qdeclarativemousearea.cpp
@@ -767,10 +767,16 @@ QDeclarativeDrag *QDeclarativeMouseArea::drag()
     \i \c drag.minimum and \c drag.maximum limit how far the target can be dragged along the corresponding axes.
     \endlist
 
-    The following example displays an image that can be dragged along the X-axis. The opacity
-    of the image is reduced when it is dragged to the right.
+    The following example displays a \l Rectangle that can be dragged along the X-axis. The opacity
+    of the rectangle is reduced when it is dragged to the right.
 
     \snippet doc/src/snippets/declarative/mousearea.qml drag
+
+    \note Items cannot be dragged if they are anchored for the requested 
+    \c drag.axis. For example, if \c anchors.left or \c anchors.right was set
+    for \c rect in the above example, it cannot be dragged along the X-axis.
+    This can be avoided by settng the anchor value to \c undefined in 
+    an \l onPressed handler.
 */
 
 QT_END_NAMESPACE
diff --git a/src/declarative/qml/qdeclarativeimageprovider.cpp b/src/declarative/qml/qdeclarativeimageprovider.cpp
index f38da4e..a294c38 100644
--- a/src/declarative/qml/qdeclarativeimageprovider.cpp
+++ b/src/declarative/qml/qdeclarativeimageprovider.cpp
@@ -180,9 +180,13 @@ QDeclarativeImageProvider::ImageType QDeclarativeImageProvider::imageType() cons
     Implement this method to return the image with \a id. The default 
     implementation returns an empty image.
 
-    If \a requestedSize is a valid size, the image returned should be of that size.
+    The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
+    an Image element. If \a requestedSize is a valid size, the image
+    returned should be of that size.
 
-    In all cases, \a size must be set to the original size of the image.
+    In all cases, \a size must be set to the original size of the image. This
+    is used to set the \l {Item::}{width} and \l {Item::}{height} of image
+    elements that should be automatically sized to the loaded image.
 
     \note this method may be called by multiple threads, so ensure the
     implementation of this method is reentrant.
@@ -201,9 +205,13 @@ QImage QDeclarativeImageProvider::requestImage(const QString &id, QSize *size, c
     Implement this method to return the pixmap with \a id. The default
     implementation returns an empty pixmap.
 
-    If \a requestedSize is a valid size, the image returned should be of that size.
+    The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
+    an Image element. If \a requestedSize is a valid size, the image
+    returned should be of that size.
 
-    In all cases, \a size must be set to the original size of the image.
+    In all cases, \a size must be set to the original size of the image. This
+    is used to set the \l {Item::}{width} and \l {Item::}{height} of image
+    elements that should be automatically sized to the loaded image.
 
     \note this method may be called by multiple threads, so ensure the
     implementation of this method is reentrant.
diff --git a/src/declarative/util/qdeclarativestateoperations.cpp b/src/declarative/util/qdeclarativestateoperations.cpp
index 51e6f99..5590449 100644
--- a/src/declarative/util/qdeclarativestateoperations.cpp
+++ b/src/declarative/util/qdeclarativestateoperations.cpp
@@ -1039,7 +1039,7 @@ public:
 
 /*!
     \qmlproperty Item AnchorChanges::target
-    This property holds the Item whose anchors will change
+    This property holds the \l Item for which the anchor changes will be applied.
 */
 
 QDeclarativeAnchorChanges::QDeclarativeAnchorChanges(QObject *parent)
diff --git a/src/declarative/util/qdeclarativexmllistmodel.cpp b/src/declarative/util/qdeclarativexmllistmodel.cpp
index 00169db..9895ff2 100644
--- a/src/declarative/util/qdeclarativexmllistmodel.cpp
+++ b/src/declarative/util/qdeclarativexmllistmodel.cpp
@@ -508,8 +508,8 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla
   \since 4.7
     \brief The XmlListModel element is used to specify a model using XPath expressions.
 
-    XmlListModel is used to create a model from XML data. XmlListModel can be used as a data source
-    for the view classes (such as ListView, PathView, GridView) and other classes that interact with model
+    XmlListModel is used to create a model from XML data. It can be used as a data source
+    for view elements (such as ListView, PathView, GridView) and other elements that interact with model
     data (such as \l Repeater).
 
     For example, if there is a XML document at http://www.mysite.com/feed.xml like this:
@@ -520,11 +520,11 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla
         ...
         <channel>
             <item>
-                <title>Item A</title>
+                <title>A blog post</title>
                 <pubDate>Sat, 07 Sep 2010 10:00:01 GMT</pubDate>
             </item>
             <item>
-                <title>Item B</title>
+                <title>Another blog post</title>
                 <pubDate>Sat, 07 Sep 2010 15:35:01 GMT</pubDate>
             </item>
         </channel>
@@ -560,10 +560,17 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla
     ListView {
         width: 180; height: 300
         model: xmlModel
-        delegate: Text { title + " (" + pubDate + ")" }
+        delegate: Text { text: title + " (" + pubDate + ")" }
     }
     \endqml
 
+    \image qml-xmllistmodel-example.png
+
+    The XmlListModel data is loaded asynchronously, and \l status
+    is set to \l XmlListModel::Ready when loading is complete.
+    Note this means when XmlListModel is used for a view, the view is not
+    populated until the model is loaded.
+
 
     \section2 Using key XML roles