1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the QtDeclarative module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
#include "qdeclarativeimageprovider.h"
QT_BEGIN_NAMESPACE
class QDeclarativeImageProviderPrivate
{
public:
QDeclarativeImageProvider::ImageType type;
};
/*!
\class QDeclarativeImageProvider
\since 4.7
\brief The QDeclarativeImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML.
QDeclarativeImageProvider is used to provide advanced image loading features
in QML applications. It allows images in QML to be:
\list
\o Loaded using QPixmaps rather than actual image files
\o Loaded asynchronously in a separate thread, if imageType() is \l{QDeclarativeImageProvider::ImageType}{ImageType::Image}
\endlist
To specify that an image should be loaded by an image provider, use the
\bold {"image:"} scheme for the URL source of the image, followed by the
identifiers of the image provider and the requested image. For example:
\qml
Image { source: "image://myimageprovider/image.png" }
\endqml
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().
\section2 An example
Here are two images. Their \c source values indicate they should be loaded by
an image provider named "colors", and the images to be loaded are "yellow"
and "red", respectively:
\snippet examples/declarative/cppextensions/imageprovider/imageprovider-example.qml 0
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 \c 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:
\snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 0
\codeline
\snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 1
To make this provider accessible to QML, it is registered with the QML engine
with a "colors" identifier:
\code
int main(int argc, char *argv[])
{
...
QDeclarativeEngine engine;
engine->addImageProvider(QLatin1String("colors"), new ColorPixmapProvider);
...
}
\endcode
Now the images can be successfully loaded in QML:
\image imageprovider.png
A complete example is available in Qt's
\l {declarative/cppextensions/imageprovider}{examples/declarative/cppextensions/imageprovider}
directory. Note the example registers the provider via a \l{QDeclarativeExtensionPlugin}{plugin}
instead of registering it in the application \c main() function as shown above.
\section2 Asynchronous image loading
Image providers that support QImage loading automatically include support
for asychronous loading of images. To enable asynchronous loading for an
\l Image source, set \l Image::asynchronous to \c true. 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 \l {Image::}{asynchronous} is set to
\c true, the value is ignored and the image is loaded
synchronously.
\sa QDeclarativeEngine::addImageProvider()
*/
/*!
\enum QDeclarativeImageProvider::ImageType
Defines the type of image supported by this image provider.
\value Image The Image Provider provides QImage images. The
requestImage() method will be called for all image requests.
\value Pixmap The Image Provider provides QPixmap images. The
requestPixmap() method will be called for all image requests.
*/
/*!
Creates an image provider that will provide images of the given \a type.
*/
QDeclarativeImageProvider::QDeclarativeImageProvider(ImageType type)
: d(new QDeclarativeImageProviderPrivate)
{
d->type = type;
}
/*!
Destroys the QDeclarativeImageProvider
\note The destructor of your derived class need to be thread safe.
*/
QDeclarativeImageProvider::~QDeclarativeImageProvider()
{
delete d;
}
/*!
Returns the image type supported by this provider.
*/
QDeclarativeImageProvider::ImageType QDeclarativeImageProvider::imageType() const
{
return d->type;
}
/*!
Implement this method to return the image with \a id. The default
implementation returns an empty image.
The \a id is the requested image source, with the "image:" scheme and
provider identifier removed. For example, if the image \l{Image::}{source}
was "image://myprovider/icons/home", the given \a id would be "icons/home".
The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
an Image element. If \a requestedSize is a valid size, the image
returned should be of that size.
In all cases, \a size must be set to the original size of the image. This
is used to set the \l {Item::}{width} and \l {Item::}{height} of the
relevant \l 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.
*/
QImage QDeclarativeImageProvider::requestImage(const QString &id, QSize *size, const QSize& requestedSize)
{
Q_UNUSED(id);
Q_UNUSED(size);
Q_UNUSED(requestedSize);
if (d->type == Image)
qWarning("ImageProvider supports Image type but has not implemented requestImage()");
return QImage();
}
/*!
Implement this method to return the pixmap with \a id. The default
implementation returns an empty pixmap.
The \a id is the requested image source, with the "image:" scheme and
provider identifier removed. For example, if the image \l{Image::}{source}
was "image://myprovider/icons/home", the given \a id would be "icons/home".
The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
an Image element. If \a requestedSize is a valid size, the image
returned should be of that size.
In all cases, \a size must be set to the original size of the image. This
is used to set the \l {Item::}{width} and \l {Item::}{height} of the
relevant \l Image if these values have not been set explicitly.
*/
QPixmap QDeclarativeImageProvider::requestPixmap(const QString &id, QSize *size, const QSize& requestedSize)
{
Q_UNUSED(id);
Q_UNUSED(size);
Q_UNUSED(requestedSize);
if (d->type == Pixmap)
qWarning("ImageProvider supports Pixmap type but has not implemented requestPixmap()");
return QPixmap();
}
QT_END_NAMESPACE
|
