Qt 4.8
Public Types | Public Functions | Properties | List of all members
QDeclarativeImageProvider Class Reference

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

#include <qdeclarativeimageprovider.h>

Public Types

enum  ImageType { Image, Pixmap }
 Defines the type of image supported by this image provider. More...
 

Public Functions

ImageType imageType () const
 Returns the image type supported by this provider. More...
 
 QDeclarativeImageProvider (ImageType type)
 Creates an image provider that will provide images of the given type. More...
 
virtual QImage requestImage (const QString &id, QSize *size, const QSize &requestedSize)
 Implement this method to return the image with id. More...
 
virtual QPixmap requestPixmap (const QString &id, QSize *size, const QSize &requestedSize)
 Implement this method to return the pixmap with id. More...
 
virtual ~QDeclarativeImageProvider ()
 Destroys the QDeclarativeImageProvider. More...
 

Properties

QDeclarativeImageProviderPrivated
 

Detailed Description

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

Since
4.7

QDeclarativeImageProvider is used to provide advanced image loading features in QML applications. It allows images in QML to be:

To specify that an image should be loaded by an image provider, use the "image:" scheme for the URL source of the image, followed by the identifiers of the image provider and the requested image. For example:

Image { source: "image://myimageprovider/image.png" }

This specifies that the image should be loaded by the image provider named "myimageprovider", and the image to be loaded is named "image.png". The QML engine invokes the appropriate image provider according to the providers that have been registered through QDeclarativeEngine::addImageProvider().

Note that the identifiers are case-insensitive, but the rest of the URL will be passed on with preserved case. For example, the below snippet would still specify that the image is loaded by the image provider named "myimageprovider", but it would request a different image than the above snippet ("Image.png" instead of "image.png").

Image { source: "image://MyImageProvider/Image.png" }

If you want the rest of the URL to be case insensitive, you will have to take care of that yourself inside your image provider.

An example

Here are two images. Their source values indicate they should be loaded by an image provider named "colors", and the images to be loaded are "yellow" and "red", respectively:

Column {
Image { source: "image://colors/yellow" }
Image { source: "image://colors/red" }
}

When these images are loaded by QML, it looks for a matching image provider and calls its requestImage() or requestPixmap() method (depending on its imageType()) to load the image. The method is called with the id parameter set to "yellow" for the first image, and "red" for the second.

Here is an image provider implementation that can load the images requested by the above QML. This implementation dynamically generates QPixmap images that are filled with the requested color:

class ColorImageProvider : public QDeclarativeImageProvider
{
public:
ColorImageProvider()
{
}
QPixmap requestPixmap(const QString &id, QSize *size, const QSize &requestedSize)
{
int width = 100;
int height = 50;
if (size)
*size = QSize(width, height);
QPixmap pixmap(requestedSize.width() > 0 ? requestedSize.width() : width,
requestedSize.height() > 0 ? requestedSize.height() : height);
pixmap.fill(QColor(id).rgba());
return pixmap;
}
};

To make this provider accessible to QML, it is registered with the QML engine with a "colors" identifier:

int main(int argc, char *argv[])
{
...
engine->addImageProvider(QLatin1String("colors"), new ColorPixmapProvider);
...
}

Now the images can be successfully loaded in QML:

imageprovider.png

A complete example is available in Qt's declarative/cppextensions/imageprovider{examples/declarative/cppextensions/imageprovider} directory. Note the example registers the provider via a plugin instead of registering it in the application main() function as shown above.

Asynchronous image loading

Image providers that support QImage loading automatically include support for asychronous loading of images. To enable asynchronous loading for an image source, set the asynchronous property to true for the relevant Image , BorderImage or 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.

Asynchronous loading is not supported for image providers that provide QPixmap rather than QImage values, as pixmaps can only be created in the main thread. In this case, if Image::asynchronous is set to true, the value is ignored and the image is loaded synchronously.

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 cache property to false for the relevant Image , BorderImage or AnimatedImage object.

See also
QDeclarativeEngine::addImageProvider()

Definition at line 56 of file qdeclarativeimageprovider.h.

Enumerations

◆ ImageType

Defines the type of image supported by this image provider.

Enumerator
Image 
Pixmap 

Definition at line 59 of file qdeclarativeimageprovider.h.

Constructors and Destructors

◆ QDeclarativeImageProvider()

QDeclarativeImageProvider::QDeclarativeImageProvider ( ImageType  type)

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

Definition at line 185 of file qdeclarativeimageprovider.cpp.

187 {
188  d->type = type;
189 }
QDeclarativeImageProvider::ImageType type
int type
Definition: qmetatype.cpp:239
QDeclarativeImageProviderPrivate * d

◆ ~QDeclarativeImageProvider()

QDeclarativeImageProvider::~QDeclarativeImageProvider ( )
virtual

Destroys the QDeclarativeImageProvider.

Note
The destructor of your derived class need to be thread safe.

Definition at line 196 of file qdeclarativeimageprovider.cpp.

197 {
198  delete d;
199 }
QDeclarativeImageProviderPrivate * d

Functions

◆ imageType()

QDeclarativeImageProvider::ImageType QDeclarativeImageProvider::imageType ( ) const

Returns the image type supported by this provider.

Definition at line 204 of file qdeclarativeimageprovider.cpp.

Referenced by QDeclarativeEnginePrivate::getImageProviderType().

205 {
206  return d->type;
207 }
QDeclarativeImageProvider::ImageType type
QDeclarativeImageProviderPrivate * d

◆ requestImage()

QImage QDeclarativeImageProvider::requestImage ( const QString id,
QSize size,
const QSize requestedSize 
)
virtual

Implement this method to return the image with id.

The default implementation returns an empty image.

The id is the requested image source, with the "image:" scheme and provider identifier removed. For example, if the image Image::source was "image://myprovider/icons/home", the given id would be "icons/home".

The requestedSize corresponds to the Image::sourceSize requested by an Image element. If requestedSize is a valid size, the image returned should be of that size.

In all cases, size must be set to the original size of the image. This is used to set the Item::width and Item::height of the relevant Image if these values have not been set explicitly.

Note
this method may be called by multiple threads, so ensure the implementation of this method is reentrant.

Definition at line 228 of file qdeclarativeimageprovider.cpp.

Referenced by QDeclarativeEnginePrivate::getImageFromProvider().

229 {
230  Q_UNUSED(id);
231  Q_UNUSED(size);
232  Q_UNUSED(requestedSize);
233  if (d->type == Image)
234  qWarning("ImageProvider supports Image type but has not implemented requestImage()");
235  return QImage();
236 }
QDeclarativeImageProvider::ImageType type
Q_CORE_EXPORT void qWarning(const char *,...)
The QImage class provides a hardware-independent image representation that allows direct access to th...
Definition: qimage.h:87
QDeclarativeImageProviderPrivate * d
The Image element displays an image in a declarative user interface.
#define Q_UNUSED(x)
Indicates to the compiler that the parameter with the specified name is not used in the body of a fun...
Definition: qglobal.h:1729

◆ requestPixmap()

QPixmap QDeclarativeImageProvider::requestPixmap ( const QString id,
QSize size,
const QSize requestedSize 
)
virtual

Implement this method to return the pixmap with id.

The default implementation returns an empty pixmap.

The id is the requested image source, with the "image:" scheme and provider identifier removed. For example, if the image Image::source was "image://myprovider/icons/home", the given id would be "icons/home".

The requestedSize corresponds to the Image::sourceSize requested by an Image element. If requestedSize is a valid size, the image returned should be of that size.

In all cases, size must be set to the original size of the image. This is used to set the Item::width and Item::height of the relevant Image if these values have not been set explicitly.

Definition at line 254 of file qdeclarativeimageprovider.cpp.

Referenced by QDeclarativeEnginePrivate::getPixmapFromProvider().

255 {
256  Q_UNUSED(id);
257  Q_UNUSED(size);
258  Q_UNUSED(requestedSize);
259  if (d->type == Pixmap)
260  qWarning("ImageProvider supports Pixmap type but has not implemented requestPixmap()");
261  return QPixmap();
262 }
QDeclarativeImageProvider::ImageType type
Q_CORE_EXPORT void qWarning(const char *,...)
QDeclarativeImageProviderPrivate * d
The QPixmap class is an off-screen image representation that can be used as a paint device...
Definition: qpixmap.h:71
#define Q_UNUSED(x)
Indicates to the compiler that the parameter with the specified name is not used in the body of a fun...
Definition: qglobal.h:1729

Properties

◆ d

QDeclarativeImageProviderPrivate* QDeclarativeImageProvider::d
private

The documentation for this class was generated from the following files: