image/qimageiohandler.cpp

Source codeSwitch to Preprocessed file
LineSource CodeCoverage
1/**************************************************************************** -
2** -
3** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). -
4** Contact: http://www.qt-project.org/legal -
5** -
6** This file is part of the QtGui module of the Qt Toolkit. -
7** -
8** $QT_BEGIN_LICENSE:LGPL$ -
9** Commercial License Usage -
10** Licensees holding valid commercial Qt licenses may use this file in -
11** accordance with the commercial license agreement provided with the -
12** Software or, alternatively, in accordance with the terms contained in -
13** a written agreement between you and Digia. For licensing terms and -
14** conditions see http://qt.digia.com/licensing. For further information -
15** use the contact form at http://qt.digia.com/contact-us. -
16** -
17** GNU Lesser General Public License Usage -
18** Alternatively, this file may be used under the terms of the GNU Lesser -
19** General Public License version 2.1 as published by the Free Software -
20** Foundation and appearing in the file LICENSE.LGPL included in the -
21** packaging of this file. Please review the following information to -
22** ensure the GNU Lesser General Public License version 2.1 requirements -
23** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -
24** -
25** In addition, as a special exception, Digia gives you certain additional -
26** rights. These rights are described in the Digia Qt LGPL Exception -
27** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -
28** -
29** GNU General Public License Usage -
30** Alternatively, this file may be used under the terms of the GNU -
31** General Public License version 3.0 as published by the Free Software -
32** Foundation and appearing in the file LICENSE.GPL included in the -
33** packaging of this file. Please review the following information to -
34** ensure the GNU General Public License version 3.0 requirements will be -
35** met: http://www.gnu.org/copyleft/gpl.html. -
36** -
37** -
38** $QT_END_LICENSE$ -
39** -
40****************************************************************************/ -
41 -
42/*! -
43 \class QImageIOHandler -
44 \brief The QImageIOHandler class defines the common image I/O -
45 interface for all image formats in Qt. -
46 \reentrant -
47 \inmodule QtGui -
48 -
49 Qt uses QImageIOHandler for reading and writing images through -
50 QImageReader and QImageWriter. You can also derive from this class -
51 to write your own image format handler using Qt's plugin mechanism. -
52 -
53 Call setDevice() to assign a device to the handler, and -
54 setFormat() to assign a format to it. One QImageIOHandler may -
55 support more than one image format. canRead() returns true if an -
56 image can be read from the device, and read() and write() return -
57 true if reading or writing an image was completed successfully. -
58 -
59 QImageIOHandler also has support for animations formats, through -
60 the functions loopCount(), imageCount(), nextImageDelay() and -
61 currentImageNumber(). -
62 -
63 In order to determine what options an image handler supports, Qt -
64 will call supportsOption() and setOption(). Make sure to -
65 reimplement these functions if you can provide support for any of -
66 the options in the ImageOption enum. -
67 -
68 To write your own image handler, you must at least reimplement -
69 canRead() and read(). Then create a QImageIOPlugin that -
70 can create the handler. Finally, install your plugin, and -
71 QImageReader and QImageWriter will then automatically load the -
72 plugin, and start using it. -
73 -
74 \sa QImageIOPlugin, QImageReader, QImageWriter -
75*/ -
76 -
77/*! \enum QImageIOHandler::ImageOption -
78 -
79 This enum describes the different options supported by -
80 QImageIOHandler. Some options are used to query an image for -
81 properties, and others are used to toggle the way in which an -
82 image should be written. -
83 -
84 \value Size The original size of an image. A handler that supports -
85 this option is expected to read the size of the image from the -
86 image metadata, and return this size from option() as a QSize. -
87 -
88 \value ClipRect The clip rect, or ROI (Region Of Interest). A -
89 handler that supports this option is expected to only read the -
90 provided QRect area from the original image in read(), before any -
91 other transformation is applied. -
92 -
93 \value ScaledSize The scaled size of the image. A handler that -
94 supports this option is expected to scale the image to the -
95 provided size (a QSize), after applying any clip rect -
96 transformation (ClipRect). If the handler does not support this -
97 option, QImageReader will perform the scaling after the image has -
98 been read. -
99 -
100 \value ScaledClipRect The scaled clip rect (or ROI, Region Of -
101 Interest) of the image. A handler that supports this option is -
102 expected to apply the provided clip rect (a QRect), after applying -
103 any scaling (ScaleSize) or regular clipping (ClipRect). If the -
104 handler does not support this option, QImageReader will apply the -
105 scaled clip rect after the image has been read. -
106 -
107 \value Description The image description. Some image formats, -
108 such as GIF and PNG, allow embedding of text -
109 or comments into the image data (e.g., for storing copyright -
110 information). It's common that the text is stored in key-value -
111 pairs, but some formats store all text in one continuous block. -
112 QImageIOHandler returns the text as one -
113 QString, where keys and values are separated by a ':', and -
114 keys-value pairs are separated by two newlines (\\n\\n). For example, -
115 "Title: Sunset\\n\\nAuthor: Jim Smith\\nSarah Jones\\n\\n". Formats that -
116 store text in a single block can use "Description" as the key. -
117 -
118 \value CompressionRatio The compression ratio of the image data. A -
119 handler that supports this option is expected to set its -
120 compression rate depending on the value of this option (an int) -
121 when writing. -
122 -
123 \value Gamma The gamma level of the image. A handler that supports -
124 this option is expected to set the image gamma level depending on -
125 the value of this option (a float) when writing. -
126 -
127 \value Quality The quality level of the image. A handler that -
128 supports this option is expected to set the image quality level -
129 depending on the value of this option (an int) when writing. -
130 -
131 \value Name The name of the image. A handler that supports this -
132 option is expected to read the name from the image metadata and -
133 return this as a QString, or when writing an image it is expected -
134 to store the name in the image metadata. -
135 -
136 \value SubType The subtype of the image. A handler that supports -
137 this option can use the subtype value to help when reading and -
138 writing images. For example, a PPM handler may have a subtype -
139 value of "ppm" or "ppmraw". -
140 -
141 \value IncrementalReading A handler that supports this option is -
142 expected to read the image in several passes, as if it was an -
143 animation. QImageReader will treat the image as an animation. -
144 -
145 \value Endianness The endianness of the image. Certain image -
146 formats can be stored as BigEndian or LittleEndian. A handler that -
147 supports Endianness uses the value of this option to determine how -
148 the image should be stored. -
149 -
150 \value Animation Image formats that support animation return -
151 true for this value in supportsOption(); otherwise, false is returned. -
152 -
153 \value BackgroundColor Certain image formats allow the -
154 background color to be specified. A handler that supports -
155 BackgroundColor initializes the background color to this option -
156 (a QColor) when reading an image. -
157 -
158 \value ImageFormat The image's data format returned by the handler. -
159 This can be any of the formats listed in QImage::Format. -
160*/ -
161 -
162/*! -
163 \class QImageIOPlugin -
164 \inmodule QtGui -
165 \brief The QImageIOPlugin class defines an interface for writing -
166 an image format plugin. -
167 \reentrant -
168 -
169 \ingroup plugins -
170 -
171 QImageIOPlugin is a factory for creating QImageIOHandler objects, -
172 which are used internally by QImageReader and QImageWriter to add -
173 support for different image formats to Qt. -
174 -
175 Writing an image I/O plugin is achieved by subclassing this -
176 base class, reimplementing the pure virtual functions capabilities() -
177 and create(), and exporting the class with the -
178 Q_PLUGIN_METADATA() macro. See \l{How to Create Qt Plugins} for details. -
179 -
180 An image format plugin can support three capabilities: reading (\l -
181 CanRead), writing (\l CanWrite) and \e incremental reading (\l -
182 CanReadIncremental). Reimplement capabilities() in you subclass to -
183 expose the capabilities of your image format. -
184 -
185 create() should create an instance of your QImageIOHandler -
186 subclass, with the provided device and format properly set, and -
187 return this handler. -
188 -
189 The json metadata file for the plugin needs to contain information -
190 about the image formats the plugins supports. For a jpeg plugin, this -
191 could e.g. look as follows: -
192 -
193 \code -
194 { "Keys": [ "jpg", "jpeg" ] } -
195 \endcode -
196 -
197 Different plugins can support different capabilities. For example, -
198 you may have one plugin that supports reading the GIF format, and -
199 another that supports writing. Qt will select the correct plugin -
200 for the job, depending on the return value of capabilities(). If -
201 several plugins support the same capability, Qt will select one -
202 arbitrarily. -
203 -
204 \sa QImageIOHandler, {How to Create Qt Plugins} -
205*/ -
206 -
207/*! -
208 \enum QImageIOPlugin::Capability -
209 -
210 This enum describes the capabilities of a QImageIOPlugin. -
211 -
212 \value CanRead The plugin can read images. -
213 \value CanWrite The plugin can write images. -
214 \value CanReadIncremental The plugin can read images incrementally. -
215*/ -
216 -
217#include "qimageiohandler.h" -
218 -
219#include <qbytearray.h> -
220#include <qimage.h> -
221#include <qvariant.h> -
222 -
223QT_BEGIN_NAMESPACE -
224 -
225class QIODevice; -
226 -
227class QImageIOHandlerPrivate -
228{ -
229 Q_DECLARE_PUBLIC(QImageIOHandler) -
230public: -
231 QImageIOHandlerPrivate(QImageIOHandler *q); -
232 virtual ~QImageIOHandlerPrivate(); -
233 -
234 QIODevice *device; -
235 mutable QByteArray format; -
236 -
237 QImageIOHandler *q_ptr; -
238}; -
239 -
240QImageIOHandlerPrivate::QImageIOHandlerPrivate(QImageIOHandler *q) -
241{ -
242 device = 0;
executed (the execution status of this line is deduced): device = 0;
-
243 q_ptr = q;
executed (the execution status of this line is deduced): q_ptr = q;
-
244}
executed: }
Execution Count:2219
2219
245 -
246QImageIOHandlerPrivate::~QImageIOHandlerPrivate() -
247{ -
248} -
249 -
250/*! -
251 Constructs a QImageIOHandler object. -
252*/ -
253QImageIOHandler::QImageIOHandler() -
254 : d_ptr(new QImageIOHandlerPrivate(this)) -
255{ -
256}
executed: }
Execution Count:2219
2219
257 -
258/*! \internal -
259 -
260 Constructs a QImageIOHandler object, using the private member \a -
261 dd. -
262*/ -
263QImageIOHandler::QImageIOHandler(QImageIOHandlerPrivate &dd) -
264 : d_ptr(&dd) -
265{ -
266}
never executed: }
0
267 -
268/*! -
269 Destructs the QImageIOHandler object. -
270*/ -
271QImageIOHandler::~QImageIOHandler() -
272{ -
273} -
274 -
275/*! -
276 Sets the device of the QImageIOHandler to \a device. The image -
277 handler will use this device when reading and writing images. -
278 -
279 The device can only be set once and must be set before calling -
280 canRead(), read(), write(), etc. If you need to read multiple -
281 files, construct multiple instances of the appropriate -
282 QImageIOHandler subclass. -
283 -
284 \sa device() -
285*/ -
286void QImageIOHandler::setDevice(QIODevice *device) -
287{ -
288 Q_D(QImageIOHandler);
executed (the execution status of this line is deduced): QImageIOHandlerPrivate * const d = d_func();
-
289 d->device = device;
executed (the execution status of this line is deduced): d->device = device;
-
290}
executed: }
Execution Count:2692
2692
291 -
292/*! -
293 Returns the device currently assigned to the QImageIOHandler. If -
294 not device has been assigned, 0 is returned. -
295*/ -
296QIODevice *QImageIOHandler::device() const -
297{ -
298 Q_D(const QImageIOHandler);
executed (the execution status of this line is deduced): const QImageIOHandlerPrivate * const d = d_func();
-
299 return d->device;
executed: return d->device;
Execution Count:20625
20625
300} -
301 -
302/*! -
303 Sets the format of the QImageIOHandler to \a format. The format is -
304 most useful for handlers that support multiple image formats. -
305 -
306 \sa format() -
307*/ -
308void QImageIOHandler::setFormat(const QByteArray &format) -
309{ -
310 Q_D(QImageIOHandler);
executed (the execution status of this line is deduced): QImageIOHandlerPrivate * const d = d_func();
-
311 d->format = format;
executed (the execution status of this line is deduced): d->format = format;
-
312}
executed: }
Execution Count:1547
1547
313 -
314/*! -
315 Sets the format of the QImageIOHandler to \a format. The format is -
316 most useful for handlers that support multiple image formats. -
317 -
318 This function is declared const so that it can be called from canRead(). -
319 -
320 \sa format() -
321*/ -
322void QImageIOHandler::setFormat(const QByteArray &format) const -
323{ -
324 Q_D(const QImageIOHandler);
executed (the execution status of this line is deduced): const QImageIOHandlerPrivate * const d = d_func();
-
325 d->format = format;
executed (the execution status of this line is deduced): d->format = format;
-
326}
executed: }
Execution Count:1335
1335
327 -
328/*! -
329 Returns the format that is currently assigned to -
330 QImageIOHandler. If no format has been assigned, an empty string -
331 is returned. -
332 -
333 \sa setFormat() -
334*/ -
335QByteArray QImageIOHandler::format() const -
336{ -
337 Q_D(const QImageIOHandler);
executed (the execution status of this line is deduced): const QImageIOHandlerPrivate * const d = d_func();
-
338 return d->format;
executed: return d->format;
Execution Count:177
177
339} -
340 -
341/*! -
342 \fn bool QImageIOHandler::read(QImage *image) -
343 -
344 Read an image from the device, and stores it in \a image. -
345 Returns true if the image is successfully read; otherwise returns -
346 false. -
347 -
348 For image formats that support incremental loading, and for animation -
349 formats, the image handler can assume that \a image points to the -
350 previous frame. -
351 -
352 \sa canRead() -
353*/ -
354 -
355/*! -
356 \fn bool QImageIOHandler::canRead() const -
357 -
358 Returns true if an image can be read from the device (i.e., the -
359 image format is supported, the device can be read from and the -
360 initial header information suggests that the image can be read); -
361 otherwise returns false. -
362 -
363 When reimplementing canRead(), make sure that the I/O device -
364 (device()) is left in its original state (e.g., by using peek() -
365 rather than read()). -
366 -
367 \sa read(), QIODevice::peek() -
368*/ -
369 -
370/*! -
371 \obsolete -
372 -
373 Use format() instead. -
374*/ -
375 -
376QByteArray QImageIOHandler::name() const -
377{ -
378 return format();
never executed: return format();
0
379} -
380 -
381/*! -
382 Writes the image \a image to the assigned device. Returns true on -
383 success; otherwise returns false. -
384 -
385 The default implementation does nothing, and simply returns false. -
386*/ -
387bool QImageIOHandler::write(const QImage &image) -
388{ -
389 Q_UNUSED(image);
never executed (the execution status of this line is deduced): (void)image;;
-
390 return false;
never executed: return false;
0
391} -
392 -
393/*! -
394 Sets the option \a option with the value \a value. -
395 -
396 \sa option(), ImageOption -
397*/ -
398void QImageIOHandler::setOption(ImageOption option, const QVariant &value) -
399{ -
400 Q_UNUSED(option);
never executed (the execution status of this line is deduced): (void)option;;
-
401 Q_UNUSED(value);
never executed (the execution status of this line is deduced): (void)value;;
-
402}
never executed: }
0
403 -
404/*! -
405 Returns the value assigned to \a option as a QVariant. The type of -
406 the value depends on the option. For example, option(Size) returns -
407 a QSize variant. -
408 -
409 \sa setOption(), supportsOption() -
410*/ -
411QVariant QImageIOHandler::option(ImageOption option) const -
412{ -
413 Q_UNUSED(option);
never executed (the execution status of this line is deduced): (void)option;;
-
414 return QVariant();
never executed: return QVariant();
0
415} -
416 -
417/*! -
418 Returns true if the QImageIOHandler supports the option \a option; -
419 otherwise returns false. For example, if the QImageIOHandler -
420 supports the \l Size option, supportsOption(Size) must return -
421 true. -
422 -
423 \sa setOption(), option() -
424*/ -
425bool QImageIOHandler::supportsOption(ImageOption option) const -
426{ -
427 Q_UNUSED(option);
never executed (the execution status of this line is deduced): (void)option;;
-
428 return false;
never executed: return false;
0
429} -
430 -
431/*! -
432 For image formats that support animation, this function returns -
433 the sequence number of the current image in the animation. If -
434 this function is called before any image is read(), -1 is -
435 returned. The number of the first image in the sequence is 0. -
436 -
437 If the image format does not support animation, 0 is returned. -
438 -
439 \sa read() -
440*/ -
441int QImageIOHandler::currentImageNumber() const -
442{ -
443 return 0;
never executed: return 0;
0
444} -
445 -
446/*! -
447 Returns the rect of the current image. If no rect is defined for the -
448 image, and empty QRect() is returned. -
449 -
450 This function is useful for animations, where only parts of the frame -
451 may be updated at a time. -
452*/ -
453QRect QImageIOHandler::currentImageRect() const -
454{ -
455 return QRect();
never executed: return QRect();
0
456} -
457 -
458/*! -
459 For image formats that support animation, this function returns -
460 the number of images in the animation. If the image format does -
461 not support animation, or if it is unable to determine the number -
462 of images, 0 is returned. -
463 -
464 The default implementation returns 1 if canRead() returns true; -
465 otherwise 0 is returned. -
466*/ -
467int QImageIOHandler::imageCount() const -
468{ -
469 return canRead() ? 1 : 0;
executed: return canRead() ? 1 : 0;
Execution Count:36
36
470} -
471 -
472/*! -
473 For image formats that support animation, this function jumps to the -
474 next image. -
475 -
476 The default implementation does nothing, and returns false. -
477*/ -
478bool QImageIOHandler::jumpToNextImage() -
479{ -
480 return false;
never executed: return false;
0
481} -
482 -
483/*! -
484 For image formats that support animation, this function jumps to the image -
485 whose sequence number is \a imageNumber. The next call to read() will -
486 attempt to read this image. -
487 -
488 The default implementation does nothing, and returns false. -
489*/ -
490bool QImageIOHandler::jumpToImage(int imageNumber) -
491{ -
492 Q_UNUSED(imageNumber);
executed (the execution status of this line is deduced): (void)imageNumber;;
-
493 return false;
executed: return false;
Execution Count:7
7
494} -
495 -
496/*! -
497 For image formats that support animation, this function returns -
498 the number of times the animation should loop. If the image format -
499 does not support animation, 0 is returned. -
500*/ -
501int QImageIOHandler::loopCount() const -
502{ -
503 return 0;
executed: return 0;
Execution Count:4
4
504} -
505 -
506/*! -
507 For image formats that support animation, this function returns -
508 the number of milliseconds to wait until reading the next -
509 image. If the image format does not support animation, 0 is -
510 returned. -
511*/ -
512int QImageIOHandler::nextImageDelay() const -
513{ -
514 return 0;
executed: return 0;
Execution Count:45
45
515} -
516 -
517#ifndef QT_NO_IMAGEFORMATPLUGIN -
518 -
519/*! -
520 Constructs an image plugin with the given \a parent. This is -
521 invoked automatically by the moc generated code that exports the plugin. -
522*/ -
523QImageIOPlugin::QImageIOPlugin(QObject *parent) -
524 : QObject(parent) -
525{ -
526}
executed: }
Execution Count:100
100
527 -
528/*! -
529 Destroys the picture format plugin. -
530 -
531 You never have to call this explicitly. Qt destroys a plugin -
532 automatically when it is no longer used. -
533*/ -
534QImageIOPlugin::~QImageIOPlugin() -
535{ -
536} -
537 -
538/*! \fn QImageIOPlugin::capabilities(QIODevice *device, const QByteArray &format) const -
539 -
540 Returns the capabilities on the plugin, based on the data in \a -
541 device and the format \a format. For example, if the -
542 QImageIOHandler supports the BMP format, and the data in the -
543 device starts with the characters "BM", this function should -
544 return \l CanRead. If \a format is "bmp" and the handler supports -
545 both reading and writing, this function should return \l CanRead | -
546 \l CanWrite. -
547*/ -
548 -
549/*! -
550 \fn QImageIOHandler *QImageIOPlugin::create(QIODevice *device, const QByteArray &format) const -
551 -
552 Creates and returns a QImageIOHandler subclass, with \a device -
553 and \a format set. The \a format must come from the list returned by keys(). -
554 Format names are case sensitive. -
555 -
556 \sa keys() -
557*/ -
558 -
559#endif // QT_NO_IMAGEFORMATPLUGIN -
560 -
561QT_END_NAMESPACE -
562 -
Source codeSwitch to Preprocessed file

Generated by Squish Coco Non-Commercial