49     \brief The QDeclarativeImageProvider class provides an interface for threaded image requests in QML.

    55     \brief The QDeclarativeImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML.

    50 

    56 

    51     QDeclarativeImageProvider can be used by a QDeclarativeEngine to provide images to QML asynchronously.

    57     QDeclarativeImageProvider is used to provide advanced image loading features

    52     The image request will be run in a low priority thread, allowing potentially costly image

    58     in QML applications. It allows images in QML to be:

    53     loading to be done in the background, without affecting the performance of the UI.

    59 

    54 

    60     \list

    55     See the QDeclarativeEngine::addImageProvider() documentation for an

    61     \o Loaded using QPixmaps rather than actual image files

    56     example of how a custom QDeclarativeImageProvider can be constructed and used.

    62     \o Loaded asynchronously in a separate thread, if imageType() is \l ImageType::Image

    57 

    63     \endlist

    58     \note the request() method may be called by multiple threads, so ensure the

    64 

    59     implementation of this method is reentrant.

    65     To specify that an image should be loaded by an image provider, use the

    60 

    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 

    79     \section2 An example

    80 

    81     Here are two images. Their \c source values indicate they should be loaded by

    82     an image provider named "colors", and the images to be loaded are "yellow"

    83     and "red", respectively:

    84 

    85     \snippet examples/declarative/cppextensions/imageprovider/imageprovider-example.qml 0

    86  

    87     When these images are loaded by QML, it looks for a matching image provider

    88     and calls its requestImage() or requestPixmap() method (depending on its

    89     imageType()) to load the image. The method is called with the \c id 

    90     parameter set to "yellow" for the first image, and "red" for the second.

    91 

    92     Here is an image provider implementation that can load the images 

    93     requested by the above QML. This implementation dynamically 

    94     generates QPixmap images that are filled with the requested color:

    95 

    96     \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 0

    97     \codeline

    98     \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 1

    99 

   100     To make this provider accessible to QML, it is registered with the QML engine

   101     with a "colors" identifier:

   102 

   103     \code

   104     int main(int argc, char *argv[]) 

   105     {

   106         ...

   107 

   108         QDeclarativeEngine engine;

   109         engine->addImageProvider(QLatin1String("colors"), new ColorPixmapProvider);

   110 

   111         ...

   112     }

   113     \endcode

   114 

   115     Now the images can be succesfully loaded in QML:

   116 

   117     \image imageprovider.png

   118 

   119     A complete example is available in Qt's 

   120     \l {declarative/cppextensions/imageprovider}{examples/declarative/cppextensions/imageprovider}

   121     directory. Note the example registers the provider via a \l{QDeclarativeExtensionPlugin}{plugin}

   122     instead of registering it in the application \c main() function as shown above.

   123 

   124 

   125     \section2 Asynchronous image loading

   126 

   127     Image providers that support QImage loading automatically include support

   128     for asychronous loading of images. To enable asynchronous loading for an

   129     \l Image source, set \l Image::asynchronous to \c true. When this is enabled, 

   130     the image request to the provider is run in a low priority thread,

   131     allowing image loading to be executed in the background, and reducing the

   132     performance impact on the user interface.

   133 

   134     Asynchronous loading is not supported for image providers that provide

   135     QPixmap rather than QImage values, as pixmaps can only be created in the

   136     main thread. In this case, if \l {Image::}{asynchronous} is set to 

   137     \c true, the value is ignored and the image is loaded

   138     synchronously.

   139    

    65   Destroys the image provider.

   144     \enum QDeclarativeImageProvider::ImageType

    66  */

   145 

   146     Defines the type of image supported by this image provider.

   147 

   148     \value Image The Image Provider provides QImage images. The 

   149         requestImage() method will be called for all image requests.

   150     \value Pixmap The Image Provider provides QPixmap images. The 

   151         requestPixmap() method will be called for all image requests.

   152 */

   153 

   154 /*!

   155     Creates an image provider that will provide images of the given \a type.

   156 */

   157 QDeclarativeImageProvider::QDeclarativeImageProvider(ImageType type)

   158     : d(new QDeclarativeImageProviderPrivate)

   159 {

   160     d->type = type;

   161 }

   162 

   163 /*!

   164    \internal

   165 */

    69 }

   168     delete d;

    70 

   169 }

    71 /*!

   170 

    72     \fn QImage QDeclarativeImageProvider::request(const QString &id, QSize *size, const QSize& requestedSize)

   171 /*!

    73 

   172     Returns the image type supported by this provider.

    74     Implement this method to return the image with \a id.

   173 */

    75 

   174 QDeclarativeImageProvider::ImageType QDeclarativeImageProvider::imageType() const

    76     If \a requestedSize is a valid size, the image returned should be of that size.

   175 {

    77 

   176     return d->type;

    78     In all cases, \a size must be set to the original size of the image.

   177 }

   178 

   179 /*!

   180     Implement this method to return the image with \a id. The default 

   181     implementation returns an empty image.

   182 

   183     The \a requestedSize corresponds to the \l {Image::sourceSize} requested by

   184     an Image element. If \a requestedSize is a valid size, the image

   185     returned should be of that size.

   186 

   187     In all cases, \a size must be set to the original size of the image. This

   188     is used to set the \l {Item::}{width} and \l {Item::}{height} of image

   189     elements that should be automatically sized to the loaded image.