QQuickImageProvider Class
The QQuickImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML. More...
Header: | #include <QQuickImageProvider> |
qmake: | QT += quick |
Since: | Qt 5.0 |
Inherits: | QQmlImageProviderBase |
Inherited By: |
Public Functions
QQuickImageProvider(ImageType type, Flags flags = 0) | |
virtual | ~QQuickImageProvider() |
virtual QImage | requestImage(const QString & id, QSize * size, const QSize & requestedSize, bool requestedAutoTransform) |
virtual QPixmap | requestPixmap(const QString & id, QSize * size, const QSize & requestedSize, bool requestedAutoTransform) |
virtual QQuickTextureFactory * | requestTexture(const QString & id, QSize * size, const QSize & requestedSize, bool requestedAutoTransform) |
Reimplemented Public Functions
- 2 public functions inherited from QQmlImageProviderBase
Detailed Description
The QQuickImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML.
QQuickImageProvider is used to provide advanced image loading features in QML applications. It allows images in QML to be:
- Loaded using QPixmaps rather than actual image files
- Loaded asynchronously in a separate thread
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 QQmlEngine::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 QQuickImageProvider { public: ColorImageProvider() : QQuickImageProvider(QQuickImageProvider::Pixmap) { } 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[]) { ... QQuickView view; QQmlEngine *engine = view.engine(); engine->addImageProvider(QLatin1String("colors"), new ColorPixmapProvider); ... }
Now the images can be successfully loaded in QML:
See the Image Provider Example for the complete implementation. Note that 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 or Texture 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.
To force asynchronous image loading, even for image sources that do not have the asynchronous
property set to true
, you may pass the QQuickImageProvider::ForceAsynchronousImageLoading
flag to the image provider constructor. This ensures that all image requests for the provider are handled in a separate thread.
Asynchronous loading for image providers that provide QPixmap is only supported in platforms that have the ThreadedPixmaps feature, in platforms where pixmaps can only be created in the main thread (i.e. ThreadedPixmaps is not supported) if asynchronous is set to true
, the value is ignored and the image is loaded synchronously.
Image caching
Images returned by a QQuickImageProvider 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.
The Qt Quick 1 version of this class is named QDeclarativeImageProvider.
See also QQmlEngine::addImageProvider().
Member Function Documentation
QQuickImageProvider::QQuickImageProvider(ImageType type, Flags flags = 0)
Creates an image provider that will provide images of the given type and behave according to the given flags.
[virtual]
QQuickImageProvider::~QQuickImageProvider()
Destroys the QQuickImageProvider
Note: The destructor of your derived class need to be thread safe.
[virtual]
Flags QQuickImageProvider::flags() const
Reimplemented from QQmlImageProviderBase::flags().
Returns the flags set for this provider.
[virtual]
ImageType QQuickImageProvider::imageType() const
Reimplemented from QQmlImageProviderBase::imageType().
Returns the image type supported by this provider.
[virtual]
QImage QQuickImageProvider::requestImage(const QString & id, QSize * size, const QSize & requestedSize, bool requestedAutoTransform)
[virtual]
QPixmap QQuickImageProvider::requestPixmap(const QString & id, QSize * size, const QSize & requestedSize, bool requestedAutoTransform)
[virtual]
QQuickTextureFactory * QQuickImageProvider::requestTexture(const QString & id, QSize * size, const QSize & requestedSize, bool requestedAutoTransform)
© 2016 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.