src/declarative/qml/qdeclarativeimageprovider.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtDeclarative module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qdeclarativeimageprovider.h"
  43
  44 QT_BEGIN_NAMESPACE
  45
  46 class QDeclarativeImageProviderPrivate
  47 {
  48 public:
  49     QDeclarativeImageProvider::ImageType type;
  50 };
  51
  52 /*!
  53     \class QDeclarativeImageProvider
  54     \since 4.7
  55     \brief The QDeclarativeImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML.
  56
  57     QDeclarativeImageProvider is used to provide advanced image loading features
  58     in QML applications. It allows images in QML to be:
  59
  60     \list
  61     \o Loaded using QPixmaps rather than actual image files
  62     \o Loaded asynchronously in a separate thread, if imageType() is \l{QDeclarativeImageProvider::ImageType}{ImageType::Image}
  63     \endlist
  64
  65     To specify that an image should be loaded by an image provider, use the
  66     \bold {"image:"} scheme for the URL source of the image, followed by the
  67     identifiers of the image provider and the requested image. For example:
  68
  69     \qml
  70     Image { source: "image://myimageprovider/image.png" }
  71     \endqml
  72
  73     This specifies that the image should be loaded by the image provider named
  74     "myimageprovider", and the image to be loaded is named "image.png". The QML engine
  75     invokes the appropriate image provider according to the providers that have
  76     been registered through QDeclarativeEngine::addImageProvider().
  77
  78     Note that the identifiers are case-insensitive, but the rest of the URL will be passed on with
  79     preserved case. For example, the below snippet would still specify that the image is loaded by the
  80     image provider named "myimageprovider", but it would request a different image than the above snippet
  81     ("Image.png" instead of "image.png").
  82     \qml
  83     Image { source: "image://MyImageProvider/Image.png" }
  84     \endqml
  85
  86     If you want the rest of the URL to be case insensitive, you will have to take care
  87     of that yourself inside your image provider.
  88
  89     \section2 An example
  90
  91     Here are two images. Their \c source values indicate they should be loaded by
  92     an image provider named "colors", and the images to be loaded are "yellow"
  93     and "red", respectively:
  94
  95     \snippet examples/declarative/cppextensions/imageprovider/imageprovider-example.qml 0
  96
  97     When these images are loaded by QML, it looks for a matching image provider
  98     and calls its requestImage() or requestPixmap() method (depending on its
  99     imageType()) to load the image. The method is called with the \c id
 100     parameter set to "yellow" for the first image, and "red" for the second.
 101
 102     Here is an image provider implementation that can load the images
 103     requested by the above QML. This implementation dynamically
 104     generates QPixmap images that are filled with the requested color:
 105
 106     \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 0
 107     \codeline
 108     \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 1
 109
 110     To make this provider accessible to QML, it is registered with the QML engine
 111     with a "colors" identifier:
 112
 113     \code
 114     int main(int argc, char *argv[])
 115     {
 116         ...
 117
 118         QDeclarativeEngine engine;
 119         engine->addImageProvider(QLatin1String("colors"), new ColorPixmapProvider);
 120
 121         ...
 122     }
 123     \endcode
 124
 125     Now the images can be successfully loaded in QML:
 126
 127     \image imageprovider.png
 128
 129     A complete example is available in Qt's
 130     \l {declarative/cppextensions/imageprovider}{examples/declarative/cppextensions/imageprovider}
 131     directory. Note the example registers the provider via a \l{QDeclarativeExtensionPlugin}{plugin}
 132     instead of registering it in the application \c main() function as shown above.
 133
 134
 135     \section2 Asynchronous image loading
 136
 137     Image providers that support QImage loading automatically include support
 138     for asychronous loading of images. To enable asynchronous loading for an
 139     image source, set the \c asynchronous property to \c true for the relevant
 140     \l Image, \l BorderImage or \l AnimatedImage object. When this is enabled,
 141     the image request to the provider is run in a low priority thread,
 142     allowing image loading to be executed in the background, and reducing the
 143     performance impact on the user interface.
 144
 145     Asynchronous loading is not supported for image providers that provide
 146     QPixmap rather than QImage values, as pixmaps can only be created in the
 147     main thread. In this case, if \l {Image::}{asynchronous} is set to
 148     \c true, the value is ignored and the image is loaded
 149     synchronously.
 150
 151
 152     \section2 Image caching
 153
 154     Images returned by a QDeclarativeImageProvider are automatically cached,
 155     similar to any image loaded by the QML engine. When an image with a
 156     "image://" prefix is loaded from cache, requestImage() and requestPixmap()
 157     will not be called for the relevant image provider. If an image should always
 158     be fetched from the image provider, and should not be cached at all, set the
 159     \c cache property to \c false for the relevant \l Image, \l BorderImage or
 160     \l AnimatedImage object.
 161
 162     \sa QDeclarativeEngine::addImageProvider()
 163 */
 164
 165 /*!
 166     \enum QDeclarativeImageProvider::ImageType
 167
 168     Defines the type of image supported by this image provider.
 169
 170     \value Image The Image Provider provides QImage images. The
 171         requestImage() method will be called for all image requests.
 172     \value Pixmap The Image Provider provides QPixmap images. The
 173         requestPixmap() method will be called for all image requests.
 174     \value Texture The Image Provider provides QSGTextureProvider based images.
 175         The requestTexture() method will be called for all image requests. \omitvalue
 176 */
 177
 178 /*!
 179     Creates an image provider that will provide images of the given \a type.
 180 */
 181 QDeclarativeImageProvider::QDeclarativeImageProvider(ImageType type)
 182     : d(new QDeclarativeImageProviderPrivate)
 183 {
 184     d->type = type;
 185 }
 186
 187 /*!
 188     Destroys the QDeclarativeImageProvider
 189
 190     \note The destructor of your derived class need to be thread safe.
 191 */
 192 QDeclarativeImageProvider::~QDeclarativeImageProvider()
 193 {
 194     delete d;
 195 }
 196
 197 /*!
 198     Returns the image type supported by this provider.
 199 */
 200 QDeclarativeImageProvider::ImageType QDeclarativeImageProvider::imageType() const
 201 {
 202     return d->type;
 203 }
 204
 205 /*!
 206     Implement this method to return the image with \a id. The default
 207     implementation returns an empty image.
 208
 209     The \a id is the requested image source, with the "image:" scheme and
 210     provider identifier removed. For example, if the image \l{Image::}{source}
 211     was "image://myprovider/icons/home", the given \a id would be "icons/home".
 212
 213     The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
 214     an Image element. If \a requestedSize is a valid size, the image
 215     returned should be of that size.
 216
 217     In all cases, \a size must be set to the original size of the image. This
 218     is used to set the \l {Item::}{width} and \l {Item::}{height} of the
 219     relevant \l Image if these values have not been set explicitly.
 220
 221     \note this method may be called by multiple threads, so ensure the
 222     implementation of this method is reentrant.
 223 */
 224 QImage QDeclarativeImageProvider::requestImage(const QString &id, QSize *size, const QSize& requestedSize)
 225 {
 226     Q_UNUSED(id);
 227     Q_UNUSED(size);
 228     Q_UNUSED(requestedSize);
 229     if (d->type == Image)
 230         qWarning("ImageProvider supports Image type but has not implemented requestImage()");
 231     return QImage();
 232 }
 233
 234 /*!
 235     Implement this method to return the pixmap with \a id. The default
 236     implementation returns an empty pixmap.
 237
 238     The \a id is the requested image source, with the "image:" scheme and
 239     provider identifier removed. For example, if the image \l{Image::}{source}
 240     was "image://myprovider/icons/home", the given \a id would be "icons/home".
 241
 242     The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
 243     an Image element. If \a requestedSize is a valid size, the image
 244     returned should be of that size.
 245
 246     In all cases, \a size must be set to the original size of the image. This
 247     is used to set the \l {Item::}{width} and \l {Item::}{height} of the
 248     relevant \l Image if these values have not been set explicitly.
 249 */
 250 QPixmap QDeclarativeImageProvider::requestPixmap(const QString &id, QSize *size, const QSize& requestedSize)
 251 {
 252     Q_UNUSED(id);
 253     Q_UNUSED(size);
 254     Q_UNUSED(requestedSize);
 255     if (d->type == Pixmap)
 256         qWarning("ImageProvider supports Pixmap type but has not implemented requestPixmap()");
 257     return QPixmap();
 258 }
 259
 260
 261 /*!
 262     Implement this method to return the texture with \a id. The default
 263     implementation returns 0.
 264
 265     The \a id is the requested image source, with the "image:" scheme and
 266     provider identifier removed. For example, if the image \l{Image::}{source}
 267     was "image://myprovider/icons/home", the given \a id would be "icons/home".
 268
 269     The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
 270     an Image element. If \a requestedSize is a valid size, the image
 271     returned should be of that size.
 272
 273     In all cases, \a size must be set to the original size of the image. This
 274     is used to set the \l {Item::}{width} and \l {Item::}{height} of the
 275     relevant \l Image if these values have not been set explicitly.
 276
 277     \note this method may be called by multiple threads, so ensure the
 278     implementation of this method is reentrant.
 279 */
 280
 281 QSGTexture *QDeclarativeImageProvider::requestTexture(const QString &id, QSize *size, const QSize &requestedSize)
 282 {
 283     Q_UNUSED(id);
 284     Q_UNUSED(size);
 285     Q_UNUSED(requestedSize);
 286     if (d->type == Texture)
 287         qWarning("ImageProvider supports Texture type but has not implemented requestTexture()");
 288     return 0;
 289 }
 290
 291 QT_END_NAMESPACE
 292