From 70910dfb354a0a12ae0e446982071e54051ca83d Mon Sep 17 00:00:00 2001
From: Bea Lam <bea.lam@nokia.com>
Date: Tue, 7 Jun 2011 11:34:57 +1000
Subject: Fix docs on caching for images loaded by image providers

Also add docs for 'source' and 'asynchronous' properties for
AnimatedImage.

Task-number: QTBUG-19504
Change-Id: Iec72dc7630308a94c37d00c6b008b5949c6fccd4
Reviewed-by: Martin Jones
(cherry picked from commit 7602be09663d37f01cfd640a7f1be959ce4317b7)
---
 .../graphicsitems/qdeclarativeanimatedimage.cpp    | 26 ++++++++++++++++++++++
 src/declarative/qml/qdeclarativeengine.cpp         |  3 ---
 src/declarative/qml/qdeclarativeimageprovider.cpp  | 14 +++++++++++-
 3 files changed, 39 insertions(+), 4 deletions(-)

diff --git a/src/declarative/graphicsitems/qdeclarativeanimatedimage.cpp b/src/declarative/graphicsitems/qdeclarativeanimatedimage.cpp
index b7fcbb546e..8787a5ed68 100644
--- a/src/declarative/graphicsitems/qdeclarativeanimatedimage.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeanimatedimage.cpp
@@ -86,6 +86,32 @@ QT_BEGIN_NAMESPACE
     \sa BorderImage, Image
 */
 
+/*!
+    \qmlproperty url AnimatedImage::source
+
+    This property holds the URL that refers to the source image.
+
+    AnimatedImage can handle any image format supported by Qt, loaded from any
+    URL scheme supported by Qt.
+
+    \sa QDeclarativeImageProvider
+*/
+
+/*!
+    \qmlproperty bool AnimatedImage::asynchronous
+
+    Specifies that images on the local filesystem should be loaded
+    asynchronously in a separate thread.  The default value is
+    false, causing the user interface thread to block while the
+    image is loaded.  Setting \a asynchronous to true is useful where
+    maintaining a responsive user interface is more desirable
+    than having images immediately visible.
+
+    Note that this property is only valid for images read from the
+    local filesystem.  Images loaded via a network resource (e.g. HTTP)
+    are always loaded asynchonously.
+*/
+
 /*!
     \qmlproperty bool AnimatedImage::cache
     \since Quick 1.1
diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp
index ecd6a2bd7a..4f9e6e3af8 100644
--- a/src/declarative/qml/qdeclarativeengine.cpp
+++ b/src/declarative/qml/qdeclarativeengine.cpp
@@ -796,9 +796,6 @@ QNetworkAccessManager *QDeclarativeEngine::networkAccessManager() const
   All required image providers should be added to the engine before any
   QML sources files are loaded.
 
-  Note that images loaded from a QDeclarativeImageProvider are cached
-  by QPixmapCache, similar to any image loaded by QML.
-
   \sa removeImageProvider()
 */
 void QDeclarativeEngine::addImageProvider(const QString &providerId, QDeclarativeImageProvider *provider)
diff --git a/src/declarative/qml/qdeclarativeimageprovider.cpp b/src/declarative/qml/qdeclarativeimageprovider.cpp
index 50a3aad733..56e04c963f 100644
--- a/src/declarative/qml/qdeclarativeimageprovider.cpp
+++ b/src/declarative/qml/qdeclarativeimageprovider.cpp
@@ -136,7 +136,8 @@ public:
 
     Image providers that support QImage loading automatically include support
     for asychronous loading of images. To enable asynchronous loading for an
-    \l Image source, set \l Image::asynchronous to \c true. When this is enabled, 
+    image source, set the \c asynchronous property to \c true for the relevant
+    \l Image, \l BorderImage or \l AnimatedImage object. When this is enabled, 
     the image request to the provider is run in a low priority thread,
     allowing image loading to be executed in the background, and reducing the
     performance impact on the user interface.
@@ -147,6 +148,17 @@ public:
     \c true, the value is ignored and the image is loaded
     synchronously.
 
+
+    \section2 Image caching
+
+    Images returned by a QDeclarativeImageProvider are automatically cached,
+    similar to any image loaded by the QML engine. When an image with a
+    "image://" prefix is loaded from cache, requestImage() and requestPixmap()
+    will not be called for the relevant image provider. If an image should always
+    be fetched from the image provider, and should not be cached at all, set the
+    \c cache property to \c false for the relevant \l Image, \l BorderImage or
+    \l AnimatedImage object.
+
     \sa QDeclarativeEngine::addImageProvider()
 */
 
-- 
cgit v1.2.3