<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd"> <html><head><title>QDeclarativeImageProvider Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm } a:link { color: #004faf; text-decoration: none } a:visited { color: #672967; text-decoration: none } td.postheader { font-family: sans-serif } tr.address { font-family: sans-serif } body { background: #ffffff; color: black; } </style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="../pyqt4ref.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QDeclarativeImageProvider Class Reference<br /><sup><sup>[<a href="qtdeclarative.html">QtDeclarative</a> module]</sup></sup></h1><p>The QDeclarativeImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML. <a href="#details">More...</a></p> <h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qdeclarativeimageprovider.html#ImageType-enum">ImageType</a></b> { Image, Pixmap }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qdeclarativeimageprovider.html#QDeclarativeImageProvider">__init__</a></b> (<i>self</i>, ImageType <i>type</i>)</li><li><div class="fn" /><b><a href="qdeclarativeimageprovider.html#QDeclarativeImageProvider-2">__init__</a></b> (<i>self</i>, QDeclarativeImageProvider)</li><li><div class="fn" />ImageType <b><a href="qdeclarativeimageprovider.html#imageType">imageType</a></b> (<i>self</i>)</li><li><div class="fn" />QImage <b><a href="qdeclarativeimageprovider.html#requestImage">requestImage</a></b> (<i>self</i>, QString <i>id</i>, QSize <i>size</i>, QSize <i>requestedSize</i>)</li><li><div class="fn" />QPixmap <b><a href="qdeclarativeimageprovider.html#requestPixmap">requestPixmap</a></b> (<i>self</i>, QString <i>id</i>, QSize <i>size</i>, QSize <i>requestedSize</i>)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QDeclarativeImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML.</p> <p>QDeclarativeImageProvider is used to provide advanced image loading features in QML applications. It allows images in QML to be:</p> <ul> <li>Loaded using QPixmaps rather than actual image files</li> <li>Loaded asynchronously in a separate thread, if <a href="qdeclarativeimageprovider.html#imageType">imageType</a>() is <a href="qdeclarativeimageprovider.html#ImageType-enum">ImageType.Image</a></li> </ul> <p>To specify that an image should be loaded by an image provider, use the <b>"image:"</b> scheme for the URL source of the image, followed by the identifiers of the image provider and the requested image. For example:</p> <pre class="highlightedCode brush: cpp"> Image { source: "image://myimageprovider/image.png" } </pre> <p>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 <a href="qdeclarativeengine.html#addImageProvider">QDeclarativeEngine.addImageProvider</a>().</p> <a id="an-example" name="an-example" /> <h3>An example</h3> <p>Here are two images. Their <tt>source</tt> values indicate they should be loaded by an image provider named "colors", and the images to be loaded are "yellow" and "red", respectively:</p> <pre class="highlightedCode brush: cpp"> Column { Image { source: "image://colors/yellow" } Image { source: "image://colors/red" } } </pre> <p>When these images are loaded by QML, it looks for a matching image provider and calls its <a href="qdeclarativeimageprovider.html#requestImage">requestImage</a>() or <a href="qdeclarativeimageprovider.html#requestPixmap">requestPixmap</a>() method (depending on its <a href="qdeclarativeimageprovider.html#imageType">imageType</a>()) to load the image. The method is called with the <tt>id</tt> parameter set to "yellow" for the first image, and "red" for the second.</p> <p>Here is an image provider implementation that can load the images requested by the above QML. This implementation dynamically generates <a href="qpixmap.html">QPixmap</a> images that are filled with the requested color:</p> <pre class="highlightedCode brush: cpp"> class ColorImageProvider : public QDeclarativeImageProvider { public: ColorImageProvider() : QDeclarativeImageProvider(QDeclarativeImageProvider.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; } }; </pre> <p>To make this provider accessible to QML, it is registered with the QML engine with a "colors" identifier:</p> <pre class="highlightedCode brush: cpp"> int main(int argc, char *argv[]) { ... QDeclarativeEngine engine; engine->addImageProvider(QLatin1String("colors"), new ColorPixmapProvider); ... } </pre> <p>Now the images can be successfully loaded in QML:</p> <p class="centerAlign"><img src="images/imageprovider.png" /></p> <p>A complete example is available in Qt's <a href="declarative-cppextensions-imageprovider.html">examples/declarative/cppextensions/imageprovider</a> directory. Note the example registers the provider via a <a href="qdeclarativeextensionplugin.html">plugin</a> instead of registering it in the application <tt>main()</tt> function as shown above.</p> <a id="asynchronous-image-loading" name="asynchronous-image-loading" /> <h3>Asynchronous image loading</h3> <p>Image providers that support <a href="qimage.html">QImage</a> loading automatically include support for asychronous loading of images. To enable asynchronous loading for an <a href="qdeclarativeimageprovider.html#ImageType-enum">Image</a> source, set <a href="qml-image.html#asynchronous-prop">Image.asynchronous</a> to <tt>true</tt>. 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.</p> <p>Asynchronous loading is not supported for image providers that provide <a href="qpixmap.html">QPixmap</a> rather than <a href="qimage.html">QImage</a> values, as pixmaps can only be created in the main thread. In this case, if <a href="qml-image.html#asynchronous-prop">asynchronous</a> is set to <tt>true</tt>, the value is ignored and the image is loaded synchronously.</p> <hr /><h2>Type Documentation</h2><h3 class="fn"><a name="ImageType-enum" />QDeclarativeImageProvider.ImageType</h3><p>Defines the type of image supported by this image provider.</p> <table class="valuelist"> <tr class="odd"> <td /> </tr> <tr> <th class="tblConst">Constant</th> <th class="tblval">Value</th> <th class="tbldscr">Description</th> </tr> <tr> <td class="topAlign"><tt>QDeclarativeImageProvider.Image</tt></td> <td class=" topAlign"><tt>0</tt></td> <td class="topAlign">The Image Provider provides <a href="qimage.html">QImage</a> images. The <a href="qdeclarativeimageprovider.html#requestImage">requestImage</a>() method will be called for all image requests.</td> </tr> <tr> <td class="topAlign"> <tt>QDeclarativeImageProvider.Pixmap</tt></td> <td class=" topAlign"><tt>1</tt></td> <td class="topAlign">The Image Provider provides <a href="qpixmap.html">QPixmap</a> images. The <a href="qdeclarativeimageprovider.html#requestPixmap">requestPixmap</a>() method will be called for all image requests.</td> </tr> </table> <hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QDeclarativeImageProvider" />QDeclarativeImageProvider.__init__ (<i>self</i>, <a href="qdeclarativeimageprovider.html#ImageType-enum">ImageType</a> <i>type</i>)</h3><p>Creates an image provider that will provide images of the given <i>type</i>.</p> <h3 class="fn"><a name="QDeclarativeImageProvider-2" />QDeclarativeImageProvider.__init__ (<i>self</i>, <a href="qdeclarativeimageprovider.html">QDeclarativeImageProvider</a>)</h3><h3 class="fn"><a name="imageType" /><a href="qdeclarativeimageprovider.html#ImageType-enum">ImageType</a> QDeclarativeImageProvider.imageType (<i>self</i>)</h3><p>Returns the image type supported by this provider.</p> <h3 class="fn"><a name="requestImage" /><a href="qimage.html">QImage</a> QDeclarativeImageProvider.requestImage (<i>self</i>, QString <i>id</i>, <a href="qsize.html">QSize</a> <i>size</i>, <a href="qsize.html">QSize</a> <i>requestedSize</i>)</h3><p>Implement this method to return the image with <i>id</i>. The default implementation returns an empty image.</p> <p>The <i>requestedSize</i> corresponds to the <a href="qml-image.html#sourceSize-prop">Image.sourceSize</a> requested by an Image element. If <i>requestedSize</i> is a valid size, the image returned should be of that size.</p> <p>In all cases, <i>size</i> must be set to the original size of the image. This is used to set the <a href="qml-item.html#width-prop">width</a> and <a href="qml-item.html#height-prop">height</a> of image elements that should be automatically sized to the loaded image.</p> <p><b>Note:</b> this method may be called by multiple threads, so ensure the implementation of this method is reentrant.</p> <h3 class="fn"><a name="requestPixmap" /><a href="qpixmap.html">QPixmap</a> QDeclarativeImageProvider.requestPixmap (<i>self</i>, QString <i>id</i>, <a href="qsize.html">QSize</a> <i>size</i>, <a href="qsize.html">QSize</a> <i>requestedSize</i>)</h3><p>Implement this method to return the pixmap with <i>id</i>. The default implementation returns an empty pixmap.</p> <p>The <i>requestedSize</i> corresponds to the <a href="qml-image.html#sourceSize-prop">Image.sourceSize</a> requested by an Image element. If <i>requestedSize</i> is a valid size, the image returned should be of that size.</p> <p>In all cases, <i>size</i> must be set to the original size of the image. This is used to set the <a href="qml-item.html#width-prop">width</a> and <a href="qml-item.html#height-prop">height</a> of image elements that should be automatically sized to the loaded image.</p> <address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.8.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2011</td><td align="right" width="25%">Qt 4.7.1</td></tr></table></div></address></body></html>