source: trunk/src/gui/image/qimagereader.cpp@ 67

Last change on this file since 67 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.

File size: 42.8 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the QtGui module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42//#define QIMAGEREADER_DEBUG
43
44/*!
45 \class QImageReader
46 \brief The QImageReader class provides a format independent interface
47 for reading images from files or other devices.
48
49 \reentrant
50 \ingroup multimedia
51 \ingroup io
52
53 The most common way to read images is through QImage and QPixmap's
54 constructors, or by calling QImage::load() and
55 QPixmap::load(). QImageReader is a specialized class which gives
56 you more control when reading images. For example, you can read an
57 image into a specific size by calling setScaledSize(), and you can
58 select a clip rect, effectively loading only parts of an image, by
59 calling setClipRect(). Depending on the underlying support in the
60 image format, this can save memory and speed up loading of images.
61
62 To read an image, you start by constructing a QImageReader object.
63 Pass either a file name or a device pointer, and the image format
64 to QImageReader's constructor. You can then set several options,
65 such as the clip rect (by calling setClipRect()) and scaled size
66 (by calling setScaledSize()). canRead() returns the image if the
67 QImageReader can read the image (i.e., the image format is
68 supported and the device is open for reading). Call read() to read
69 the image.
70
71 If any error occurs when reading the image, read() will return a
72 null QImage. You can then call error() to find the type of error
73 that occurred, or errorString() to get a human readable
74 description of what went wrong.
75
76 Call supportedImageFormats() for a list of formats that
77 QImageReader can read. QImageReader supports all built-in image
78 formats, in addition to any image format plugins that support
79 reading.
80
81 QImageReader autodetects the image format by default, by looking at the
82 provided (optional) format string, the file name suffix, and the data
83 stream contents. You can enable or disable this feature, by calling
84 setAutoDetectImageFormat().
85
86 \sa QImageWriter, QImageIOHandler, QImageIOPlugin
87*/
88
89/*!
90 \enum QImageReader::ImageReaderError
91
92 This enum describes the different types of errors that can occur
93 when reading images with QImageReader.
94
95 \value FileNotFoundError QImageReader was used with a file name,
96 but not file was found with that name. This can also happen if the
97 file name contained no extension, and the file with the correct
98 extension is not supported by Qt.
99
100 \value DeviceError QImageReader encountered a device error when
101 reading the image. You can consult your particular device for more
102 details on what went wrong.
103
104 \value UnsupportedFormatError Qt does not support the requested
105 image format.
106
107 \value InvalidDataError The image data was invalid, and
108 QImageReader was unable to read an image from it. The can happen
109 if the image file is damaged.
110
111 \value UnknownError An unknown error occurred. If you get this
112 value after calling read(), it is most likely caused by a bug in
113 QImageReader.
114*/
115#include "qimagereader.h"
116
117#include <qbytearray.h>
118#ifdef QIMAGEREADER_DEBUG
119#include <qdebug.h>
120#endif
121#include <qfile.h>
122#include <qfileinfo.h>
123#include <qimage.h>
124#include <qimageiohandler.h>
125#include <qlist.h>
126#include <qrect.h>
127#include <qset.h>
128#include <qsize.h>
129#include <qcolor.h>
130#include <qvariant.h>
131
132// factory loader
133#include <qcoreapplication.h>
134#include <private/qfactoryloader_p.h>
135
136// image handlers
137#include <private/qbmphandler_p.h>
138#include <private/qppmhandler_p.h>
139#include <private/qxbmhandler_p.h>
140#include <private/qxpmhandler_p.h>
141#ifndef QT_NO_IMAGEFORMAT_PNG
142#include <private/qpnghandler_p.h>
143#endif
144
145QT_BEGIN_NAMESPACE
146
147#if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)
148Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,
149 (QImageIOHandlerFactoryInterface_iid, QLatin1String("/imageformats")))
150#endif
151
152enum _qt_BuiltInFormatType {
153#ifndef QT_NO_IMAGEFORMAT_PNG
154 _qt_PngFormat,
155#endif
156 _qt_BmpFormat,
157#ifndef QT_NO_IMAGEFORMAT_PPM
158 _qt_PpmFormat,
159 _qt_PgmFormat,
160 _qt_PbmFormat,
161#endif
162#ifndef QT_NO_IMAGEFORMAT_XBM
163 _qt_XbmFormat,
164#endif
165#ifndef QT_NO_IMAGEFORMAT_XPM
166 _qt_XpmFormat,
167#endif
168 _qt_NumFormats,
169 _qt_NoFormat = -1
170};
171
172struct _qt_BuiltInFormatStruct
173{
174 _qt_BuiltInFormatType type;
175 const char *extension;
176};
177
178static const _qt_BuiltInFormatStruct _qt_BuiltInFormats[] = {
179#ifndef QT_NO_IMAGEFORMAT_PNG
180 {_qt_PngFormat, "png"},
181#endif
182 {_qt_BmpFormat, "bmp"},
183#ifndef QT_NO_IMAGEFORMAT_PPM
184 {_qt_PpmFormat, "ppm"},
185 {_qt_PgmFormat, "pgm"},
186 {_qt_PbmFormat, "pbm"},
187#endif
188#ifndef QT_NO_IMAGEFORMAT_XBM
189 {_qt_XbmFormat, "xbm"},
190#endif
191#ifndef QT_NO_IMAGEFORMAT_XPM
192 {_qt_XpmFormat, "xpm"},
193#endif
194 {_qt_NoFormat, ""}
195};
196
197static QImageIOHandler *createReadHandlerHelper(QIODevice *device,
198 const QByteArray &format, bool autoDetectImageFormat)
199{
200 if (!autoDetectImageFormat && format.isEmpty())
201 return 0;
202
203 QByteArray form = format.toLower();
204 QImageIOHandler *handler = 0;
205
206#if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)
207 // check if we have plugins that support the image format
208 QFactoryLoader *l = loader();
209 QStringList keys = l->keys();
210#endif
211 QByteArray suffix;
212
213#ifdef QIMAGEREADER_DEBUG
214 qDebug() << "QImageReader::createReadHandler( device =" << (void *)device << ", format =" << format << "),"
215 << keys.size() << "plugins available: " << keys;
216#endif
217
218#if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)
219 int suffixPluginIndex = -1;
220 if (device && format.isEmpty() && autoDetectImageFormat) {
221 // if there's no format, see if \a device is a file, and if so, find
222 // the file suffix and find support for that format among our plugins.
223 // this allows plugins to override our built-in handlers.
224 if (QFile *file = qobject_cast<QFile *>(device)) {
225#ifdef QIMAGEREADER_DEBUG
226 qDebug() << "QImageReader::createReadHandler: device is a file:" << file->fileName();
227#endif
228 if (!(suffix = QFileInfo(file->fileName()).suffix().toLower().toLatin1()).isEmpty()) {
229 int index = keys.indexOf(QString::fromLatin1(suffix));
230 if (index != -1) {
231#ifdef QIMAGEREADER_DEBUG
232 qDebug() << "QImageReader::createReadHandler: suffix recognized; the"
233 << suffix << "plugin might be able to read this";
234#endif
235 suffixPluginIndex = index;
236 }
237 }
238 }
239 }
240#endif // QT_NO_LIBRARY
241
242 QByteArray testFormat = !form.isEmpty() ? form : suffix;
243
244#if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)
245 if (suffixPluginIndex != -1) {
246 // check if the plugin that claims support for this format can load
247 // from this device with this format.
248 const qint64 pos = device ? device->pos() : 0;
249 QImageIOPlugin *plugin = qobject_cast<QImageIOPlugin *>(l->instance(QString::fromLatin1(suffix)));
250 if (plugin && plugin->capabilities(device, testFormat) & QImageIOPlugin::CanRead) {
251 handler = plugin->create(device, testFormat);
252#ifdef QIMAGEREADER_DEBUG
253 qDebug() << "QImageReader::createReadHandler: using the" << suffix
254 << "plugin";
255#endif
256 }
257 if (device && !device->isSequential())
258 device->seek(pos);
259 }
260
261 if (!handler && !testFormat.isEmpty() && autoDetectImageFormat) {
262 // check if any plugin supports the format (they are not allowed to
263 // read from the device yet).
264 const qint64 pos = device ? device->pos() : 0;
265 for (int i = 0; i < keys.size(); ++i) {
266 if (i != suffixPluginIndex) {
267 QImageIOPlugin *plugin = qobject_cast<QImageIOPlugin *>(l->instance(keys.at(i)));
268 if (plugin && plugin->capabilities(device, testFormat) & QImageIOPlugin::CanRead) {
269#ifdef QIMAGEREADER_DEBUG
270 qDebug() << "QImageReader::createReadHandler: the" << keys.at(i) << "plugin can read this format";
271#endif
272 handler = plugin->create(device, testFormat);
273 break;
274 }
275 }
276 }
277 if (device && !device->isSequential())
278 device->seek(pos);
279 }
280#endif // QT_NO_LIBRARY
281
282 // if we don't have a handler yet, check if we have built-in support for
283 // the format
284 if (!handler && !testFormat.isEmpty()) {
285 if (false) {
286#ifndef QT_NO_IMAGEFORMAT_PNG
287 } else if (testFormat == "png") {
288 handler = new QPngHandler;
289#endif
290#ifndef QT_NO_IMAGEFORMAT_BMP
291 } else if (testFormat == "bmp") {
292 handler = new QBmpHandler;
293#endif
294#ifndef QT_NO_IMAGEFORMAT_XPM
295 } else if (testFormat == "xpm") {
296 handler = new QXpmHandler;
297#endif
298#ifndef QT_NO_IMAGEFORMAT_XBM
299 } else if (testFormat == "xbm") {
300 handler = new QXbmHandler;
301 handler->setOption(QImageIOHandler::SubType, testFormat);
302#endif
303#ifndef QT_NO_IMAGEFORMAT_PPM
304 } else if (testFormat == "pbm" || testFormat == "pbmraw" || testFormat == "pgm"
305 || testFormat == "pgmraw" || testFormat == "ppm" || testFormat == "ppmraw") {
306 handler = new QPpmHandler;
307 handler->setOption(QImageIOHandler::SubType, testFormat);
308#endif
309 }
310
311#ifdef QIMAGEREADER_DEBUG
312 if (handler)
313 qDebug() << "QImageReader::createReadHandler: using the built-in handler for" << testFormat;
314#endif
315 }
316
317#if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)
318 if (!handler && autoDetectImageFormat) {
319 // check if any of our plugins recognize the file from its contents.
320 const qint64 pos = device ? device->pos() : 0;
321 for (int i = 0; i < keys.size(); ++i) {
322 if (i != suffixPluginIndex) {
323 QImageIOPlugin *plugin = qobject_cast<QImageIOPlugin *>(l->instance(keys.at(i)));
324 if (plugin && plugin->capabilities(device, QByteArray()) & QImageIOPlugin::CanRead) {
325 handler = plugin->create(device, testFormat);
326#ifdef QIMAGEREADER_DEBUG
327 qDebug() << "QImageReader::createReadHandler: the" << keys.at(i) << "plugin can read this data";
328#endif
329 break;
330 }
331 }
332 }
333 if (device && !device->isSequential())
334 device->seek(pos);
335 }
336#endif
337
338 if (!handler && autoDetectImageFormat) {
339 // check if any of our built-in handlers recognize the file from its
340 // contents.
341 int currentFormat = 0;
342 if (!suffix.isEmpty()) {
343 // If reading from a file with a suffix, start testing our
344 // built-in handler for that suffix first.
345 for (int i = 0; i < _qt_NumFormats; ++i) {
346 if (_qt_BuiltInFormats[i].extension == suffix) {
347 currentFormat = i;
348 break;
349 }
350 }
351 }
352
353 QByteArray subType;
354 int numFormats = _qt_NumFormats;
355 while (device && numFormats >= 0) {
356 const _qt_BuiltInFormatStruct *formatStruct = &_qt_BuiltInFormats[currentFormat];
357
358 const qint64 pos = device->pos();
359 switch (formatStruct->type) {
360#ifndef QT_NO_IMAGEFORMAT_PNG
361 case _qt_PngFormat:
362 if (QPngHandler::canRead(device))
363 handler = new QPngHandler;
364 break;
365#endif
366#ifndef QT_NO_IMAGEFORMAT_BMP
367 case _qt_BmpFormat:
368 if (QBmpHandler::canRead(device))
369 handler = new QBmpHandler;
370 break;
371#endif
372#ifndef QT_NO_IMAGEFORMAT_XPM
373 case _qt_XpmFormat:
374 if (QXpmHandler::canRead(device))
375 handler = new QXpmHandler;
376 break;
377#endif
378#ifndef QT_NO_IMAGEFORMAT_PPM
379 case _qt_PbmFormat:
380 case _qt_PgmFormat:
381 case _qt_PpmFormat:
382 if (QPpmHandler::canRead(device, &subType)) {
383 handler = new QPpmHandler;
384 handler->setOption(QImageIOHandler::SubType, subType);
385 }
386 break;
387#endif
388#ifndef QT_NO_IMAGEFORMAT_XBM
389 case _qt_XbmFormat:
390 if (QXbmHandler::canRead(device))
391 handler = new QXbmHandler;
392 break;
393#endif
394 default:
395 break;
396 }
397 if (!device->isSequential())
398 device->seek(pos);
399
400 if (handler) {
401#ifdef QIMAGEREADER_DEBUG
402 qDebug() << "QImageReader::createReadHandler: the" << formatStruct->extension
403 << "built-in handler can read this data";
404#endif
405 break;
406 }
407
408 --numFormats;
409 ++currentFormat;
410 currentFormat %= _qt_NumFormats;
411 }
412 }
413
414 if (!handler) {
415#ifdef QIMAGEREADER_DEBUG
416 qDebug() << "QImageReader::createReadHandler: no handlers found. giving up.";
417#endif
418 // no handler: give up.
419 return 0;
420 }
421
422 handler->setDevice(device);
423 if (!form.isEmpty())
424 handler->setFormat(form);
425 return handler;
426}
427
428class QImageReaderPrivate
429{
430public:
431 QImageReaderPrivate(QImageReader *qq);
432 ~QImageReaderPrivate();
433
434 // device
435 QByteArray format;
436 bool autoDetectImageFormat;
437 QIODevice *device;
438 bool deleteDevice;
439 QImageIOHandler *handler;
440 bool initHandler();
441
442 // image options
443 QRect clipRect;
444 QSize scaledSize;
445 QRect scaledClipRect;
446 int quality;
447 QMap<QString, QString> text;
448 void getText();
449
450 // error
451 QImageReader::ImageReaderError imageReaderError;
452 QString errorString;
453
454 QImageReader *q;
455};
456
457/*!
458 \internal
459*/
460QImageReaderPrivate::QImageReaderPrivate(QImageReader *qq)
461 : autoDetectImageFormat(true)
462{
463 device = 0;
464 deleteDevice = false;
465 handler = 0;
466 quality = -1;
467 imageReaderError = QImageReader::UnknownError;
468 errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "Unknown error"));
469
470 q = qq;
471}
472
473/*!
474 \internal
475*/
476QImageReaderPrivate::~QImageReaderPrivate()
477{
478 if (deleteDevice)
479 delete device;
480 delete handler;
481}
482
483/*!
484 \internal
485*/
486bool QImageReaderPrivate::initHandler()
487{
488 // check some preconditions
489 if (!device || (!deleteDevice && !device->isOpen())) {
490 imageReaderError = QImageReader::DeviceError;
491 errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "Invalid device"));
492 return false;
493 }
494
495 // probe the file extension
496 if (deleteDevice && !device->isOpen() && !device->open(QIODevice::ReadOnly) && autoDetectImageFormat) {
497 QList<QByteArray> extensions = QImageReader::supportedImageFormats();
498 if (!format.isEmpty()) {
499 // Try the most probable extension first
500 int currentFormatIndex = extensions.indexOf(format.toLower());
501 if (currentFormatIndex > 0)
502 extensions.swap(0, currentFormatIndex);
503 }
504
505 int currentExtension = 0;
506
507 QFile *file = static_cast<QFile *>(device);
508 QString fileName = file->fileName();
509
510 do {
511 file->setFileName(fileName + QLatin1Char('.')
512 + QString::fromLatin1(extensions.at(currentExtension++).constData()));
513 file->open(QIODevice::ReadOnly);
514 } while (!file->isOpen() && currentExtension < extensions.size());
515
516 if (!device->isOpen()) {
517 imageReaderError = QImageReader::FileNotFoundError;
518 errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "File not found"));
519 file->setFileName(fileName); // restore the old file name
520 return false;
521 }
522 }
523
524 // assign a handler
525 if (!handler && (handler = createReadHandlerHelper(device, format, autoDetectImageFormat)) == 0) {
526 imageReaderError = QImageReader::UnsupportedFormatError;
527 errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "Unsupported image format"));
528 return false;
529 }
530 return true;
531}
532
533/*!
534 \internal
535*/
536void QImageReaderPrivate::getText()
537{
538 if (!text.isEmpty() || (!handler && !initHandler()) || !handler->supportsOption(QImageIOHandler::Description))
539 return;
540 foreach (QString pair, handler->option(QImageIOHandler::Description).toString().split(
541 QLatin1String("\n\n"))) {
542 int index = pair.indexOf(QLatin1Char(':'));
543 if (index >= 0 && pair.indexOf(QLatin1Char(' ')) < index) {
544 text.insert(QLatin1String("Description"), pair.simplified());
545 } else {
546 QString key = pair.left(index);
547 text.insert(key, pair.mid(index + 2).simplified());
548 }
549 }
550}
551
552/*!
553 Constructs an empty QImageReader object. Before reading an image,
554 call setDevice() or setFileName().
555*/
556QImageReader::QImageReader()
557 : d(new QImageReaderPrivate(this))
558{
559}
560
561/*!
562 Constructs a QImageReader object with the device \a device and the
563 image format \a format.
564*/
565QImageReader::QImageReader(QIODevice *device, const QByteArray &format)
566 : d(new QImageReaderPrivate(this))
567{
568 d->device = device;
569 d->format = format;
570}
571
572/*!
573 Constructs a QImageReader object with the file name \a fileName
574 and the image format \a format.
575
576 \sa setFileName()
577*/
578QImageReader::QImageReader(const QString &fileName, const QByteArray &format)
579 : d(new QImageReaderPrivate(this))
580{
581 QFile *file = new QFile(fileName);
582 d->device = file;
583 d->deleteDevice = true;
584 d->format = format;
585}
586
587/*!
588 Destructs the QImageReader object.
589*/
590QImageReader::~QImageReader()
591{
592 delete d;
593}
594
595/*!
596 Sets the format QImageReader will use when reading images, to \a
597 format. \a format is a case insensitive text string. Example:
598
599 \snippet doc/src/snippets/code/src_gui_image_qimagereader.cpp 0
600
601 You can call supportedImageFormats() for the full list of formats
602 QImageReader supports.
603
604 \sa format()
605*/
606void QImageReader::setFormat(const QByteArray &format)
607{
608 d->format = format;
609}
610
611/*!
612 Returns the format QImageReader uses for reading images.
613
614 You can call this function after assigning a device to the
615 reader to determine the format of the device. For example:
616
617 \snippet doc/src/snippets/code/src_gui_image_qimagereader.cpp 1
618
619 If the reader cannot read any image from the device (e.g., there is no
620 image there, or the image has already been read), or if the format is
621 unsupported, this function returns an empty QByteArray().
622
623 \sa setFormat(), supportedImageFormats()
624*/
625QByteArray QImageReader::format() const
626{
627 if (d->format.isEmpty()) {
628 if (!d->initHandler())
629 return QByteArray();
630 return d->handler->canRead() ? d->handler->format() : QByteArray();
631 }
632
633 return d->format;
634}
635
636/*!
637 If \a enabled is true, image format autodetection is enabled; otherwise,
638 it is disabled. By default, autodetection is enabled.
639
640 QImageReader uses an extensive approach to detecting the image format;
641 firstly, if you pass a file name to QImageReader, it will attempt to
642 detect the file extension if the given file name does not point to an
643 existing file, by appending supported default extensions to the given file
644 name, one at a time. It then uses the following approach to detect the
645 image format:
646
647 \list
648
649 \o Image plugins are queried first, based on either the optional format
650 string, or the file name suffix (if the source device is a file). No
651 content detection is done at this stage. QImageReader will choose the
652 first plugin that supports reading for this format.
653
654 \o If no plugin supports the image format, Qt's built-in handlers are
655 checked based on either the optional format string, or the file name
656 suffix.
657
658 \o If no capable plugins or built-in handlers are found, each plugin is
659 tested by inspecting the content of the data stream.
660
661 \o If no plugins could detect the image format based on data contents,
662 each built-in image handler is tested by inspecting the contents.
663
664 \o Finally, if all above approaches fail, QImageReader will report failure
665 when trying to read the image.
666
667 \endlist
668
669 By disabling image format autodetection, QImageReader will only query the
670 plugins and built-in handlers based on the format string (i.e., no file
671 name extensions are tested).
672
673 \sa QImageIOHandler::canRead(), QImageIOPlugin::capabilities()
674*/
675void QImageReader::setAutoDetectImageFormat(bool enabled)
676{
677 d->autoDetectImageFormat = enabled;
678}
679
680/*!
681 Returns true if image format autodetection is enabled on this image
682 reader; otherwise returns false. By default, autodetection is enabled.
683
684 \sa setAutoDetectImageFormat()
685*/
686bool QImageReader::autoDetectImageFormat() const
687{
688 return d->autoDetectImageFormat;
689}
690
691/*!
692 Sets QImageReader's device to \a device. If a device has already
693 been set, the old device is removed from QImageReader and is
694 otherwise left unchanged.
695
696 If the device is not already open, QImageReader will attempt to
697 open the device in \l QIODevice::ReadOnly mode by calling
698 open(). Note that this does not work for certain devices, such as
699 QProcess, QTcpSocket and QUdpSocket, where more logic is required
700 to open the device.
701
702 \sa device(), setFileName()
703*/
704void QImageReader::setDevice(QIODevice *device)
705{
706 if (d->device && d->deleteDevice)
707 delete d->device;
708 d->device = device;
709 d->deleteDevice = false;
710 delete d->handler;
711 d->handler = 0;
712 d->text.clear();
713}
714
715/*!
716 Returns the device currently assigned to QImageReader, or 0 if no
717 device has been assigned.
718*/
719QIODevice *QImageReader::device() const
720{
721 return d->device;
722}
723
724/*!
725 Sets the file name of QImageReader to \a fileName. Internally,
726 QImageReader will create a QFile object and open it in \l
727 QIODevice::ReadOnly mode, and use this when reading images.
728
729 If \a fileName does not include a file extension (e.g., .png or .bmp),
730 QImageReader will cycle through all supported extensions until it finds
731 a matching file.
732
733 \sa fileName(), setDevice(), supportedImageFormats()
734*/
735void QImageReader::setFileName(const QString &fileName)
736{
737 setDevice(new QFile(fileName));
738 d->deleteDevice = true;
739}
740
741/*!
742 If the currently assigned device is a QFile, or if setFileName()
743 has been called, this function returns the name of the file
744 QImageReader reads from. Otherwise (i.e., if no device has been
745 assigned or the device is not a QFile), an empty QString is
746 returned.
747
748 \sa setFileName(), setDevice()
749*/
750QString QImageReader::fileName() const
751{
752 QFile *file = qobject_cast<QFile *>(d->device);
753 return file ? file->fileName() : QString();
754}
755
756/*!
757 \since 4.2
758
759 This is an image format specific function that sets the quality
760 level of the image to \a quality. For image formats that do not
761 support setting the quality, this value is ignored.
762
763 The value range of \a quality depends on the image format. For
764 example, the "jpeg" format supports a quality range from 0 (low
765 quality, high compression) to 100 (high quality, low compression).
766
767 \sa quality()
768*/
769void QImageReader::setQuality(int quality)
770{
771 d->quality = quality;
772}
773
774/*!
775 \since 4.2
776
777 Returns the quality level of the image.
778
779 \sa setQuality()
780*/
781int QImageReader::quality() const
782{
783 return d->quality;
784}
785
786
787/*!
788 Returns the size of the image, without actually reading the image
789 contents.
790
791 If the image format does not support this feature, this function returns
792 an invalid size. Qt's built-in image handlers all support this feature,
793 but custom image format plugins are not required to do so.
794
795 \sa QImageIOHandler::ImageOption, QImageIOHandler::option(), QImageIOHandler::supportsOption()
796*/
797QSize QImageReader::size() const
798{
799 if (!d->initHandler())
800 return QSize();
801
802 if (d->handler->supportsOption(QImageIOHandler::Size))
803 return d->handler->option(QImageIOHandler::Size).toSize();
804
805 return QSize();
806}
807
808/*!
809 \since 4.5
810
811 Returns the format of the image, without actually reading the image
812 contents. The format describes the image format \l QImageReader::read()
813 returns, not the format of the actual image.
814
815 If the image format does not support this feature, this function returns
816 an invalid format.
817
818 \sa QImageIOHandler::ImageOption, QImageIOHandler::option(), QImageIOHandler::supportsOption()
819*/
820QImage::Format QImageReader::imageFormat() const
821{
822 if (!d->initHandler())
823 return QImage::Format_Invalid;
824
825 if (d->handler->supportsOption(QImageIOHandler::ImageFormat))
826 return (QImage::Format)d->handler->option(QImageIOHandler::ImageFormat).toInt();
827
828 return QImage::Format_Invalid;
829}
830
831/*!
832 \since 4.1
833
834 Returns the text keys for this image. You can use
835 these keys with text() to list the image text for
836 a certain key.
837
838 Support for this option is implemented through
839 QImageIOHandler::Description.
840
841 \sa text(), QImageWriter::setText(), QImage::textKeys()
842*/
843QStringList QImageReader::textKeys() const
844{
845 d->getText();
846 return d->text.keys();
847}
848
849/*!
850 \since 4.1
851
852 Returns the image text associated with \a key.
853
854 Support for this option is implemented through
855 QImageIOHandler::Description.
856
857 \sa textKeys(), QImageWriter::setText()
858*/
859QString QImageReader::text(const QString &key) const
860{
861 d->getText();
862 return d->text.value(key);
863}
864
865/*!
866 Sets the image clip rect (also known as the ROI, or Region Of
867 Interest) to \a rect. The coordinates of \a rect are relative to
868 the untransformed image size, as returned by size().
869
870 \sa clipRect(), setScaledSize(), setScaledClipRect()
871*/
872void QImageReader::setClipRect(const QRect &rect)
873{
874 d->clipRect = rect;
875}
876
877/*!
878 Returns the clip rect (also known as the ROI, or Region Of
879 Interest) of the image. If no clip rect has been set, an invalid
880 QRect is returned.
881
882 \sa setClipRect()
883*/
884QRect QImageReader::clipRect() const
885{
886 return d->clipRect;
887}
888
889/*!
890 Sets the scaled size of the image to \a size. The scaling is
891 performed after the initial clip rect, but before the scaled clip
892 rect is applied. The algorithm used for scaling depends on the
893 image format. By default (i.e., if the image format does not
894 support scaling), QImageReader will use QImage::scale() with
895 Qt::SmoothScaling.
896
897 \sa scaledSize(), setClipRect(), setScaledClipRect()
898*/
899void QImageReader::setScaledSize(const QSize &size)
900{
901 d->scaledSize = size;
902}
903
904/*!
905 Returns the scaled size of the image.
906
907 \sa setScaledSize()
908*/
909QSize QImageReader::scaledSize() const
910{
911 return d->scaledSize;
912}
913
914/*!
915 Sets the scaled clip rect to \a rect. The scaled clip rect is the
916 clip rect (also known as ROI, or Region Of Interest) that is
917 applied after the image has been scaled.
918
919 \sa scaledClipRect(), setScaledSize()
920*/
921void QImageReader::setScaledClipRect(const QRect &rect)
922{
923 d->scaledClipRect = rect;
924}
925
926/*!
927 Returns the scaled clip rect of the image.
928
929 \sa setScaledClipRect()
930*/
931QRect QImageReader::scaledClipRect() const
932{
933 return d->scaledClipRect;
934}
935
936/*!
937 \since 4.1
938
939 Sets the background color to \a color.
940 Image formats that support this operation are expected to
941 initialize the background to \a color before reading an image.
942
943 \sa backgroundColor(), read()
944*/
945void QImageReader::setBackgroundColor(const QColor &color)
946{
947 if (!d->initHandler())
948 return;
949 if (d->handler->supportsOption(QImageIOHandler::BackgroundColor))
950 d->handler->setOption(QImageIOHandler::BackgroundColor, color);
951}
952
953/*!
954 \since 4.1
955
956 Returns the background color that's used when reading an image.
957 If the image format does not support setting the background color
958 an invalid color is returned.
959
960 \sa setBackgroundColor(), read()
961*/
962QColor QImageReader::backgroundColor() const
963{
964 if (!d->initHandler())
965 return QColor();
966 if (d->handler->supportsOption(QImageIOHandler::BackgroundColor))
967 return qVariantValue<QColor>(d->handler->option(QImageIOHandler::BackgroundColor));
968 return QColor();
969}
970
971/*!
972 \since 4.1
973
974 Returns true if the image format supports animation;
975 otherwise, false is returned.
976
977 \sa QMovie::supportedFormats()
978*/
979bool QImageReader::supportsAnimation() const
980{
981 if (!d->initHandler())
982 return false;
983 if (d->handler->supportsOption(QImageIOHandler::Animation))
984 return d->handler->option(QImageIOHandler::Animation).toBool();
985 return false;
986}
987
988/*!
989 Returns true if an image can be read for the device (i.e., the
990 image format is supported, and the device seems to contain valid
991 data); otherwise returns false.
992
993 canRead() is a lightweight function that only does a quick test to
994 see if the image data is valid. read() may still return false
995 after canRead() returns true, if the image data is corrupt.
996
997 For images that support animation, canRead() returns false when
998 all frames have been read.
999
1000 \sa read(), supportedImageFormats()
1001*/
1002bool QImageReader::canRead() const
1003{
1004 if (!d->initHandler())
1005 return false;
1006
1007 return d->handler->canRead();
1008}
1009
1010/*!
1011 Reads an image from the device. On success, the image that was
1012 read is returned; otherwise, a null QImage is returned. You can
1013 then call error() to find the type of error that occurred, or
1014 errorString() to get a human readable description of the error.
1015
1016 For image formats that support animation, calling read()
1017 repeatedly will return the next frame. When all frames have been
1018 read, a null image will be returned.
1019
1020 \sa canRead(), supportedImageFormats(), supportsAnimation(), QMovie
1021*/
1022QImage QImageReader::read()
1023{
1024 // Because failed image reading might have side effects, we explicitly
1025 // return a null image instead of the image we've just created.
1026 QImage image;
1027 return read(&image) ? image : QImage();
1028}
1029
1030/*!
1031 \overload
1032
1033 Reads an image from the device into \a image, which must point to a
1034 QImage. Returns true on success; otherwise, returns false.
1035
1036 If \a image has same format and size as the image data that is about to be
1037 read, this function may not need to allocate a new image before
1038 reading. Because of this, it can be faster than the other read() overload,
1039 which always constructs a new image; especially when reading several
1040 images with the same format and size.
1041
1042 \snippet doc/src/snippets/code/src_gui_image_qimagereader.cpp 2
1043
1044 For image formats that support animation, calling read() repeatedly will
1045 return the next frame. When all frames have been read, a null image will
1046 be returned.
1047
1048 \sa canRead(), supportedImageFormats(), supportsAnimation(), QMovie
1049*/
1050bool QImageReader::read(QImage *image)
1051{
1052 if (!image) {
1053 qWarning("QImageReader::read: cannot read into null pointer");
1054 return false;
1055 }
1056
1057 if (!d->handler && !d->initHandler())
1058 return false;
1059
1060 // set the handler specific options.
1061 if (d->handler->supportsOption(QImageIOHandler::ScaledSize) && d->scaledSize.isValid()) {
1062 if ((d->handler->supportsOption(QImageIOHandler::ClipRect) && !d->clipRect.isNull())
1063 || d->clipRect.isNull()) {
1064 // Only enable the ScaledSize option if there is no clip rect, or
1065 // if the handler also supports ClipRect.
1066 d->handler->setOption(QImageIOHandler::ScaledSize, d->scaledSize);
1067 }
1068 }
1069 if (d->handler->supportsOption(QImageIOHandler::ClipRect) && !d->clipRect.isNull())
1070 d->handler->setOption(QImageIOHandler::ClipRect, d->clipRect);
1071 if (d->handler->supportsOption(QImageIOHandler::ScaledClipRect) && !d->scaledClipRect.isNull())
1072 d->handler->setOption(QImageIOHandler::ScaledClipRect, d->scaledClipRect);
1073 if (d->handler->supportsOption(QImageIOHandler::Quality))
1074 d->handler->setOption(QImageIOHandler::Quality, d->quality);
1075
1076 // read the image
1077 if (!d->handler->read(image)) {
1078 d->imageReaderError = InvalidDataError;
1079 d->errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "Unable to read image data"));
1080 return false;
1081 }
1082
1083 // provide default implementations for any unsupported image
1084 // options
1085 if (d->handler->supportsOption(QImageIOHandler::ClipRect) && !d->clipRect.isNull()) {
1086 if (d->handler->supportsOption(QImageIOHandler::ScaledSize) && d->scaledSize.isValid()) {
1087 if (d->handler->supportsOption(QImageIOHandler::ScaledClipRect) && !d->scaledClipRect.isNull()) {
1088 // all features are supported by the handler; nothing to do.
1089 } else {
1090 // the image is already scaled, so apply scaled clipping.
1091 if (!d->scaledClipRect.isNull())
1092 *image = image->copy(d->scaledClipRect);
1093 }
1094 } else {
1095 if (d->handler->supportsOption(QImageIOHandler::ScaledClipRect) && !d->scaledClipRect.isNull()) {
1096 // supports scaled clipping but not scaling, most
1097 // likely a broken handler.
1098 } else {
1099 if (d->scaledSize.isValid()) {
1100 *image = image->scaled(d->scaledSize, Qt::IgnoreAspectRatio, Qt::SmoothTransformation);
1101 }
1102 if (d->scaledClipRect.isValid()) {
1103 *image = image->copy(d->scaledClipRect);
1104 }
1105 }
1106 }
1107 } else {
1108 if (d->handler->supportsOption(QImageIOHandler::ScaledSize) && d->scaledSize.isValid()) {
1109 // in this case, there's nothing we can do. if the
1110 // plugin supports scaled size but not ClipRect, then
1111 // we have to ignore ClipRect."
1112
1113 if (d->handler->supportsOption(QImageIOHandler::ScaledClipRect) && !d->scaledClipRect.isNull()) {
1114 // nothing to do (ClipRect is ignored!)
1115 } else {
1116 // provide all workarounds.
1117 if (d->scaledClipRect.isValid()) {
1118 *image = image->copy(d->scaledClipRect);
1119 }
1120 }
1121 } else {
1122 if (d->handler->supportsOption(QImageIOHandler::ScaledClipRect) && !d->scaledClipRect.isNull()) {
1123 // this makes no sense; a handler that supports
1124 // ScaledClipRect but not ScaledSize is broken, and we
1125 // can't work around it.
1126 } else {
1127 // provide all workarounds.
1128 if (d->clipRect.isValid())
1129 *image = image->copy(d->clipRect);
1130 if (d->scaledSize.isValid())
1131 *image = image->scaled(d->scaledSize, Qt::IgnoreAspectRatio, Qt::SmoothTransformation);
1132 if (d->scaledClipRect.isValid())
1133 *image = image->copy(d->scaledClipRect);
1134 }
1135 }
1136 }
1137
1138 return true;
1139}
1140
1141/*!
1142 For image formats that support animation, this function steps over the
1143 current image, returning true if successful or false if there is no
1144 following image in the animation.
1145
1146 The default implementation calls read(), then discards the resulting
1147 image, but the image handler may have a more efficient way of implementing
1148 this operation.
1149
1150 \sa jumpToImage(), QImageIOHandler::jumpToNextImage()
1151*/
1152bool QImageReader::jumpToNextImage()
1153{
1154 if (!d->initHandler())
1155 return false;
1156 return d->handler->jumpToNextImage();
1157}
1158
1159/*!
1160 For image formats that support animation, this function skips to the image
1161 whose sequence number is \a imageNumber, returning true if successful
1162 or false if the corresponding image cannot be found.
1163
1164 The next call to read() will attempt to read this image.
1165
1166 \sa jumpToNextImage(), QImageIOHandler::jumpToImage()
1167*/
1168bool QImageReader::jumpToImage(int imageNumber)
1169{
1170 if (!d->initHandler())
1171 return false;
1172 return d->handler->jumpToImage(imageNumber);
1173}
1174
1175/*!
1176 For image formats that support animation, this function returns
1177 the number of times the animation should loop. Otherwise, it
1178 returns -1.
1179
1180 \sa supportsAnimation(), QImageIOHandler::loopCount()
1181*/
1182int QImageReader::loopCount() const
1183{
1184 if (!d->initHandler())
1185 return -1;
1186 return d->handler->loopCount();
1187}
1188
1189/*!
1190 For image formats that support animation, this function returns
1191 the total number of images in the animation.
1192
1193 Certain animation formats do not support this feature, in which
1194 case 0 is returned.
1195
1196 \sa supportsAnimation(), QImageIOHandler::imageCount()
1197*/
1198int QImageReader::imageCount() const
1199{
1200 if (!d->initHandler())
1201 return -1;
1202 return d->handler->imageCount();
1203}
1204
1205/*!
1206 For image formats that support animation, this function returns
1207 the number of milliseconds to wait until displaying the next frame
1208 in the animation. Otherwise, 0 is returned.
1209
1210 \sa supportsAnimation(), QImageIOHandler::nextImageDelay()
1211*/
1212int QImageReader::nextImageDelay() const
1213{
1214 if (!d->initHandler())
1215 return -1;
1216 return d->handler->nextImageDelay();
1217}
1218
1219/*!
1220 For image formats that support animation, this function returns
1221 the sequence number of the current frame. Otherwise, -1 is
1222 returned.
1223
1224 \sa supportsAnimation(), QImageIOHandler::currentImageNumber()
1225*/
1226int QImageReader::currentImageNumber() const
1227{
1228 if (!d->initHandler())
1229 return -1;
1230 return d->handler->currentImageNumber();
1231}
1232
1233/*!
1234 For image formats that support animation, this function returns
1235 the rect for the current frame. Otherwise, a null rect is returned.
1236
1237 \sa supportsAnimation(), QImageIOHandler::currentImageRect()
1238*/
1239QRect QImageReader::currentImageRect() const
1240{
1241 if (!d->initHandler())
1242 return QRect();
1243 return d->handler->currentImageRect();
1244}
1245
1246/*!
1247 Returns the type of error that occurred last.
1248
1249 \sa ImageReaderError, errorString()
1250*/
1251QImageReader::ImageReaderError QImageReader::error() const
1252{
1253 return d->imageReaderError;
1254}
1255
1256/*!
1257 Returns a human readable description of the last error that
1258 occurred.
1259
1260 \sa error()
1261*/
1262QString QImageReader::errorString() const
1263{
1264 return d->errorString;
1265}
1266
1267/*!
1268 \since 4.2
1269
1270 Returns true if the reader supports \a option; otherwise returns
1271 false.
1272
1273 Different image formats support different options. Call this function to
1274 determine whether a certain option is supported by the current format. For
1275 example, the PNG format allows you to embed text into the image's metadata
1276 (see text()), and the BMP format allows you to determine the image's size
1277 without loading the whole image into memory (see size()).
1278
1279 \snippet doc/src/snippets/code/src_gui_image_qimagereader.cpp 3
1280
1281 \sa QImageWriter::supportsOption()
1282*/
1283bool QImageReader::supportsOption(QImageIOHandler::ImageOption option) const
1284{
1285 if (!d->initHandler())
1286 return false;
1287 return d->handler->supportsOption(option);
1288}
1289
1290/*!
1291 If supported, this function returns the image format of the file
1292 \a fileName. Otherwise, an empty string is returned.
1293*/
1294QByteArray QImageReader::imageFormat(const QString &fileName)
1295{
1296 QFile file(fileName);
1297 if (!file.open(QFile::ReadOnly))
1298 return QByteArray();
1299
1300 return imageFormat(&file);
1301}
1302
1303/*!
1304 If supported, this function returns the image format of the device
1305 \a device. Otherwise, an empty string is returned.
1306
1307 \sa QImageReader::autoDetectImageFormat()
1308*/
1309QByteArray QImageReader::imageFormat(QIODevice *device)
1310{
1311 QByteArray format;
1312 QImageIOHandler *handler = createReadHandlerHelper(device, format, /* autoDetectImageFormat = */ true);
1313 if (handler) {
1314 if (handler->canRead())
1315 format = handler->format();
1316 delete handler;
1317 }
1318 return format;
1319}
1320
1321/*!
1322 Returns the list of image formats supported by QImageReader.
1323
1324 By default, Qt can read the following formats:
1325
1326 \table
1327 \header \o Format \o Description
1328 \row \o BMP \o Windows Bitmap
1329 \row \o GIF \o Graphic Interchange Format (optional)
1330 \row \o JPG \o Joint Photographic Experts Group
1331 \row \o JPEG \o Joint Photographic Experts Group
1332 \row \o MNG \o Multiple-image Network Graphics
1333 \row \o PNG \o Portable Network Graphics
1334 \row \o PBM \o Portable Bitmap
1335 \row \o PGM \o Portable Graymap
1336 \row \o PPM \o Portable Pixmap
1337 \row \o TIFF \o Tagged Image File Format
1338 \row \o XBM \o X11 Bitmap
1339 \row \o XPM \o X11 Pixmap
1340 \endtable
1341
1342 Reading and writing SVG files is supported through Qt's
1343 \l{QtSvg Module}{SVG Module}.
1344
1345 To configure Qt with GIF support, pass \c -qt-gif to the \c
1346 configure script or check the appropriate option in the graphical
1347 installer.
1348
1349 \sa setFormat(), QImageWriter::supportedImageFormats(), QImageIOPlugin
1350*/
1351QList<QByteArray> QImageReader::supportedImageFormats()
1352{
1353 QSet<QByteArray> formats;
1354 for (int i = 0; i < _qt_NumFormats; ++i)
1355 formats << _qt_BuiltInFormats[i].extension;
1356
1357#if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)
1358 QFactoryLoader *l = loader();
1359 QStringList keys = l->keys();
1360
1361 for (int i = 0; i < keys.count(); ++i) {
1362 QImageIOPlugin *plugin = qobject_cast<QImageIOPlugin *>(l->instance(keys.at(i)));
1363 if (plugin && plugin->capabilities(0, keys.at(i).toLatin1()) & QImageIOPlugin::CanRead)
1364 formats << keys.at(i).toLatin1();
1365 }
1366#endif // QT_NO_LIBRARY
1367
1368 QList<QByteArray> sortedFormats;
1369 for (QSet<QByteArray>::ConstIterator it = formats.constBegin(); it != formats.constEnd(); ++it)
1370 sortedFormats << *it;
1371
1372 qSort(sortedFormats);
1373 return sortedFormats;
1374}
1375
1376QT_END_NAMESPACE
Note: See TracBrowser for help on using the repository browser.