<?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="index.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="qml">
<span class="type"><a href="qdeclarativeimageprovider.html#ImageType-enum">Image</a></span> { <span class="name">source</span>: <span class="string">"image://myimageprovider/image.png"</span> }
</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>
<p>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").</p>
<pre class="qml">
<span class="type"><a href="qdeclarativeimageprovider.html#ImageType-enum">Image</a></span> { <span class="name">source</span>: <span class="string">"image://MyImageProvider/Image.png"</span> }
</pre>
<p>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.</p>
<a id="an-example" name="an-example" />
<h4>An example</h4>
<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="qml">
<span class="type"><a href="qml-column.html">Column</a></span> {
<span class="type"><a href="qdeclarativeimageprovider.html#ImageType-enum">Image</a></span> { <span class="name">source</span>: <span class="string">"image://colors/yellow"</span> }
<span class="type"><a href="qdeclarativeimageprovider.html#ImageType-enum">Image</a></span> { <span class="name">source</span>: <span class="string">"image://colors/red"</span> }
}
</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="cpp">
<span class="keyword">class</span> ColorImageProvider : <span class="keyword">public</span> <span class="type">QDeclarativeImageProvider</span>
{
<span class="keyword">public</span>:
ColorImageProvider()
: <span class="type">QDeclarativeImageProvider</span>(<span class="type">QDeclarativeImageProvider</span><span class="operator">.</span>Pixmap)
{
}
<span class="type"><a href="qpixmap.html">QPixmap</a></span> requestPixmap(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>id<span class="operator">,</span> <span class="type"><a href="qsize.html">QSize</a></span> <span class="operator">*</span>size<span class="operator">,</span> <span class="keyword">const</span> <span class="type"><a href="qsize.html">QSize</a></span> <span class="operator">&</span>requestedSize)
{
<span class="type">int</span> width <span class="operator">=</span> <span class="number">100</span>;
<span class="type">int</span> height <span class="operator">=</span> <span class="number">50</span>;
<span class="keyword">if</span> (size)
<span class="operator">*</span>size <span class="operator">=</span> <span class="type"><a href="qsize.html">QSize</a></span>(width<span class="operator">,</span> height);
<span class="type"><a href="qpixmap.html">QPixmap</a></span> pixmap(requestedSize<span class="operator">.</span>width() <span class="operator">></span> <span class="number">0</span> <span class="operator">?</span> requestedSize<span class="operator">.</span>width() : width<span class="operator">,</span>
requestedSize<span class="operator">.</span>height() <span class="operator">></span> <span class="number">0</span> <span class="operator">?</span> requestedSize<span class="operator">.</span>height() : height);
pixmap<span class="operator">.</span>fill(<span class="type"><a href="qcolor.html">QColor</a></span>(id)<span class="operator">.</span>rgba());
<span class="keyword">return</span> pixmap;
}
};
</pre>
<p>To make this provider accessible to QML, it is registered with
the QML engine with a "colors" identifier:</p>
<pre class="cpp">
<span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span>argv<span class="operator">[</span><span class="operator">]</span>)
{
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="type"><a href="qdeclarativeengine.html">QDeclarativeEngine</a></span> engine;
engine<span class="operator">-</span><span class="operator">></span>addImageProvider(QLatin1String(<span class="string">"colors"</span>)<span class="operator">,</span> <span class="keyword">new</span> ColorPixmapProvider);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
}
</pre>
<p>Now the images can be successfully loaded in QML:</p>
<p class="centerAlign"><img alt="" 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" />
<h4>Asynchronous image loading</h4>
<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 image source, set the
<tt>asynchronous</tt> property to <tt>true</tt> for the relevant
<a href="qdeclarativeimageprovider.html#ImageType-enum">Image</a>,
<a href="qml-borderimage.html">BorderImage</a> or <a href="qml-animatedimage.html">AnimatedImage</a> 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.</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>
<a id="image-caching" name="image-caching" />
<h4>Image caching</h4>
<p>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, <a href="qdeclarativeimageprovider.html#requestImage">requestImage</a>()
and <a href="qdeclarativeimageprovider.html#requestPixmap">requestPixmap</a>()
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 <tt>cache</tt> property to <tt>false</tt>
for the relevant <a href="qdeclarativeimageprovider.html#ImageType-enum">Image</a>, <a href="qml-borderimage.html">BorderImage</a> or <a href="qml-animatedimage.html">AnimatedImage</a> object.</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" valign="top">
<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>id</i> is the requested image source, with the "image:"
scheme and provider identifier removed. For example, if the image
<a href="qml-image.html#source-prop">source</a> was
"image://myprovider/icons/home", the given <i>id</i> would be
"icons/home".</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 the relevant <a href="qdeclarativeimageprovider.html#ImageType-enum">Image</a> if these
values have not been set explicitly.</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>id</i> is the requested image source, with the "image:"
scheme and provider identifier removed. For example, if the image
<a href="qml-image.html#source-prop">source</a> was
"image://myprovider/icons/home", the given <i>id</i> would be
"icons/home".</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 the relevant <a href="qdeclarativeimageprovider.html#ImageType-enum">Image</a> if these
values have not been set explicitly.</p>
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.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> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
