1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    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 painting

    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 

   145 QT_BEGIN_NAMESPACE

   146 

   147 #if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

   148 Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,

   149                           (QImageIOHandlerFactoryInterface_iid, QLatin1String("/imageformats")))

   150 #endif

   151 

   152 enum _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 

   172 struct _qt_BuiltInFormatStruct

   173 {

   174     _qt_BuiltInFormatType type;

   175     const char *extension;

   176 };

   177 

   178 static 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 

   197 static QImageIOHandler *createReadHandlerHelper(QIODevice *device,

   198                                                 const QByteArray &format,

   199                                                 bool autoDetectImageFormat,

   200                                                 bool ignoresFormatAndExtension)

   201 {

   202     if (!autoDetectImageFormat && format.isEmpty())

   203         return 0;

   204 

   205     QByteArray form = format.toLower();

   206     QImageIOHandler *handler = 0;

   207 

   208 #if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

   209     // check if we have plugins that support the image format

   210     QFactoryLoader *l = loader();

   211     QStringList keys = l->keys();

   212 #endif

   213     QByteArray suffix;

   214 

   215 #ifdef QIMAGEREADER_DEBUG

   216     qDebug() << "QImageReader::createReadHandler( device =" << (void *)device << ", format =" << format << "),"

   217              << keys.size() << "plugins available: " << keys;

   218 #endif

   219 

   220 #if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

   221     int suffixPluginIndex = -1;

   222     if (device && format.isEmpty() && autoDetectImageFormat && !ignoresFormatAndExtension) {

   223         // if there's no format, see if \a device is a file, and if so, find

   224         // the file suffix and find support for that format among our plugins.

   225         // this allows plugins to override our built-in handlers.

   226         if (QFile *file = qobject_cast<QFile *>(device)) {

   227 #ifdef QIMAGEREADER_DEBUG

   228             qDebug() << "QImageReader::createReadHandler: device is a file:" << file->fileName();

   229 #endif

   230             if (!(suffix = QFileInfo(file->fileName()).suffix().toLower().toLatin1()).isEmpty()) {

   231                 int index = keys.indexOf(QString::fromLatin1(suffix));

   232                 if (index != -1) {

   233 #ifdef QIMAGEREADER_DEBUG

   234                     qDebug() << "QImageReader::createReadHandler: suffix recognized; the"

   235                              << suffix << "plugin might be able to read this";

   236 #endif

   237                     suffixPluginIndex = index;

   238                 }

   239             }

   240         }

   241     }

   242 #endif // QT_NO_LIBRARY

   243 

   244     QByteArray testFormat = !form.isEmpty() ? form : suffix;

   245 

   246     if (ignoresFormatAndExtension)

   247         testFormat = QByteArray();

   248 

   249 #if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

   250     if (suffixPluginIndex != -1) {

   251         // check if the plugin that claims support for this format can load

   252         // from this device with this format.

   253         const qint64 pos = device ? device->pos() : 0;

   254         QImageIOPlugin *plugin = qobject_cast<QImageIOPlugin *>(l->instance(QString::fromLatin1(suffix)));

   255         if (plugin && plugin->capabilities(device, testFormat) & QImageIOPlugin::CanRead) {

   256             handler = plugin->create(device, testFormat);

   257 #ifdef QIMAGEREADER_DEBUG

   258             qDebug() << "QImageReader::createReadHandler: using the" << suffix

   259                      << "plugin";

   260 #endif

   261         }

   262         if (device && !device->isSequential())

   263             device->seek(pos);

   264     }

   265 

   266     if (!handler && !testFormat.isEmpty() && autoDetectImageFormat && !ignoresFormatAndExtension) {

   267         // check if any plugin supports the format (they are not allowed to

   268         // read from the device yet).

   269         const qint64 pos = device ? device->pos() : 0;

   270         for (int i = 0; i < keys.size(); ++i) {

   271             if (i != suffixPluginIndex) {

   272                 QImageIOPlugin *plugin = qobject_cast<QImageIOPlugin *>(l->instance(keys.at(i)));

   273                 if (plugin && plugin->capabilities(device, testFormat) & QImageIOPlugin::CanRead) {

   274 #ifdef QIMAGEREADER_DEBUG

   275                     qDebug() << "QImageReader::createReadHandler: the" << keys.at(i) << "plugin can read this format";

   276 #endif

   277                     handler = plugin->create(device, testFormat);

   278                     break;

   279                 }

   280             }

   281         }

   282         if (device && !device->isSequential())

   283             device->seek(pos);

   284     }

   285 #endif // QT_NO_LIBRARY

   286 

   287     // if we don't have a handler yet, check if we have built-in support for

   288     // the format

   289     if (!handler && !testFormat.isEmpty()) {

   290         if (false) {

   291 #ifndef QT_NO_IMAGEFORMAT_PNG

   292 	} else if (testFormat == "png") {

   293             handler = new QPngHandler;

   294 #endif

   295 #ifndef QT_NO_IMAGEFORMAT_BMP

   296         } else if (testFormat == "bmp") {

   297             handler = new QBmpHandler;

   298 #endif

   299 #ifndef QT_NO_IMAGEFORMAT_XPM

   300         } else if (testFormat == "xpm") {

   301             handler = new QXpmHandler;

   302 #endif

   303 #ifndef QT_NO_IMAGEFORMAT_XBM

   304         } else if (testFormat == "xbm") {

   305             handler = new QXbmHandler;

   306             handler->setOption(QImageIOHandler::SubType, testFormat);

   307 #endif

   308 #ifndef QT_NO_IMAGEFORMAT_PPM

   309         } else if (testFormat == "pbm" || testFormat == "pbmraw" || testFormat == "pgm"

   310                    || testFormat == "pgmraw" || testFormat == "ppm" || testFormat == "ppmraw") {

   311             handler = new QPpmHandler;

   312             handler->setOption(QImageIOHandler::SubType, testFormat);

   313 #endif

   314         }

   315 

   316 #ifdef QIMAGEREADER_DEBUG

   317         if (handler)

   318             qDebug() << "QImageReader::createReadHandler: using the built-in handler for" << testFormat;

   319 #endif

   320     }

   321 

   322 #if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

   323     if (!handler && (autoDetectImageFormat || ignoresFormatAndExtension)) {

   324         // check if any of our plugins recognize the file from its contents.

   325         const qint64 pos = device ? device->pos() : 0;

   326         for (int i = 0; i < keys.size(); ++i) {

   327             if (i != suffixPluginIndex) {

   328                 QImageIOPlugin *plugin = qobject_cast<QImageIOPlugin *>(l->instance(keys.at(i)));

   329                 if (plugin && plugin->capabilities(device, QByteArray()) & QImageIOPlugin::CanRead) {

   330                     handler = plugin->create(device, testFormat);

   331 #ifdef QIMAGEREADER_DEBUG

   332                     qDebug() << "QImageReader::createReadHandler: the" << keys.at(i) << "plugin can read this data";

   333 #endif

   334                     break;

   335                 }

   336             }

   337         }

   338         if (device && !device->isSequential())

   339             device->seek(pos);

   340     }

   341 #endif

   342 

   343     if (!handler && (autoDetectImageFormat || ignoresFormatAndExtension)) {

   344         // check if any of our built-in handlers recognize the file from its

   345         // contents.

   346         int currentFormat = 0;

   347         if (!suffix.isEmpty()) {

   348             // If reading from a file with a suffix, start testing our

   349             // built-in handler for that suffix first.

   350             for (int i = 0; i < _qt_NumFormats; ++i) {

   351                 if (_qt_BuiltInFormats[i].extension == suffix) {

   352                     currentFormat = i;

   353                     break;

   354                 }

   355             }

   356         }

   357 

   358         QByteArray subType;

   359         int numFormats = _qt_NumFormats;

   360         while (device && numFormats >= 0) {

   361             const _qt_BuiltInFormatStruct *formatStruct = &_qt_BuiltInFormats[currentFormat];

   362 

   363             const qint64 pos = device->pos();

   364             switch (formatStruct->type) {

   365 #ifndef QT_NO_IMAGEFORMAT_PNG

   366             case _qt_PngFormat:

   367                 if (QPngHandler::canRead(device))

   368                     handler = new QPngHandler;

   369                 break;

   370 #endif

   371 #ifndef QT_NO_IMAGEFORMAT_BMP

   372             case _qt_BmpFormat:

   373                 if (QBmpHandler::canRead(device))

   374                     handler = new QBmpHandler;

   375                 break;

   376 #endif

   377 #ifndef QT_NO_IMAGEFORMAT_XPM

   378             case _qt_XpmFormat:

   379                 if (QXpmHandler::canRead(device))

   380                     handler = new QXpmHandler;

   381                 break;

   382 #endif

   383 #ifndef QT_NO_IMAGEFORMAT_PPM

   384             case _qt_PbmFormat:

   385             case _qt_PgmFormat:

   386             case _qt_PpmFormat:

   387                 if (QPpmHandler::canRead(device, &subType)) {

   388                     handler = new QPpmHandler;

   389                     handler->setOption(QImageIOHandler::SubType, subType);

   390                 }

   391                 break;

   392 #endif

   393 #ifndef QT_NO_IMAGEFORMAT_XBM

   394             case _qt_XbmFormat:

   395                 if (QXbmHandler::canRead(device))

   396                     handler = new QXbmHandler;

   397                 break;

   398 #endif

   399             default:

   400                 break;

   401             }

   402             if (!device->isSequential())

   403                 device->seek(pos);

   404 

   405             if (handler) {

   406 #ifdef QIMAGEREADER_DEBUG

   407                 qDebug() << "QImageReader::createReadHandler: the" << formatStruct->extension

   408                          << "built-in handler can read this data";

   409 #endif

   410                 break;

   411             }

   412 

   413             --numFormats;

   414             ++currentFormat;

   415             currentFormat %= _qt_NumFormats;

   416         }

   417     }

   418 

   419     if (!handler) {

   420 #ifdef QIMAGEREADER_DEBUG

   421         qDebug() << "QImageReader::createReadHandler: no handlers found. giving up.";

   422 #endif

   423         // no handler: give up.

   424         return 0;

   425     }

   426 

   427     handler->setDevice(device);

   428     if (!form.isEmpty())

   429         handler->setFormat(form);

   430     return handler;

   431 }

   432 

   433 class QImageReaderPrivate

   434 {

   435 public:

   436     QImageReaderPrivate(QImageReader *qq);

   437     ~QImageReaderPrivate();

   438 

   439     // device

   440     QByteArray format;

   441     bool autoDetectImageFormat;

   442     bool ignoresFormatAndExtension;

   443     QIODevice *device;

   444     bool deleteDevice;

   445     QImageIOHandler *handler;

   446     bool initHandler();

   447 

   448     // image options

   449     QRect clipRect;

   450     QSize scaledSize;

   451     QRect scaledClipRect;

   452     int quality;

   453     QMap<QString, QString> text;

   454     void getText();

   455 

   456     // error

   457     QImageReader::ImageReaderError imageReaderError;

   458     QString errorString;

   459 

   460     QImageReader *q;

   461 };

   462 

   463 /*!

   464     \internal

   465 */

   466 QImageReaderPrivate::QImageReaderPrivate(QImageReader *qq)

   467     : autoDetectImageFormat(true), ignoresFormatAndExtension(false)

   468 {

   469     device = 0;

   470     deleteDevice = false;

   471     handler = 0;

   472     quality = -1;

   473     imageReaderError = QImageReader::UnknownError;

   474     errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "Unknown error"));

   475 

   476     q = qq;

   477 }

   478 

   479 /*!

   480     \internal

   481 */

   482 QImageReaderPrivate::~QImageReaderPrivate()

   483 {

   484     if (deleteDevice)

   485         delete device;

   486     delete handler;

   487 }

   488 

   489 /*!

   490     \internal

   491 */

   492 bool QImageReaderPrivate::initHandler()

   493 {

   494     // check some preconditions

   495     if (!device || (!deleteDevice && !device->isOpen())) {

   496         imageReaderError = QImageReader::DeviceError;

   497         errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "Invalid device"));

   498         return false;

   499     }

   500 

   501     // probe the file extension

   502     if (deleteDevice && !device->isOpen() && !device->open(QIODevice::ReadOnly) && autoDetectImageFormat) {

   503         QList<QByteArray> extensions = QImageReader::supportedImageFormats();

   504         if (!format.isEmpty()) {

   505             // Try the most probable extension first

   506             int currentFormatIndex = extensions.indexOf(format.toLower());

   507             if (currentFormatIndex > 0)

   508                 extensions.swap(0, currentFormatIndex);

   509         }

   510 

   511         int currentExtension = 0;

   512 

   513         QFile *file = static_cast<QFile *>(device);

   514         QString fileName = file->fileName();

   515 

   516         do {

   517             file->setFileName(fileName + QLatin1Char('.')

   518                     + QString::fromLatin1(extensions.at(currentExtension++).constData()));

   519             file->open(QIODevice::ReadOnly);

   520         } while (!file->isOpen() && currentExtension < extensions.size());

   521 

   522         if (!device->isOpen()) {

   523             imageReaderError = QImageReader::FileNotFoundError;

   524             errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "File not found"));

   525             file->setFileName(fileName); // restore the old file name

   526             return false;

   527         }

   528     }

   529 

   530     // assign a handler

   531     if (!handler && (handler = createReadHandlerHelper(device, format, autoDetectImageFormat, ignoresFormatAndExtension)) == 0) {

   532         imageReaderError = QImageReader::UnsupportedFormatError;

   533         errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "Unsupported image format"));

   534         return false;

   535     }

   536     return true;

   537 }

   538 

   539 /*!

   540     \internal

   541 */

   542 void QImageReaderPrivate::getText()

   543 {

   544     if (!text.isEmpty() || (!handler && !initHandler()) || !handler->supportsOption(QImageIOHandler::Description))

   545         return;

   546     foreach (QString pair, handler->option(QImageIOHandler::Description).toString().split(

   547                 QLatin1String("\n\n"))) {

   548         int index = pair.indexOf(QLatin1Char(':'));

   549         if (index >= 0 && pair.indexOf(QLatin1Char(' ')) < index) {

   550             text.insert(QLatin1String("Description"), pair.simplified());

   551         } else {

   552             QString key = pair.left(index);

   553             text.insert(key, pair.mid(index + 2).simplified());

   554         }

   555     }

   556 }

   557 

   558 /*!

   559     Constructs an empty QImageReader object. Before reading an image,

   560     call setDevice() or setFileName().

   561 */

   562 QImageReader::QImageReader()

   563     : d(new QImageReaderPrivate(this))

   564 {

   565 }

   566 

   567 /*!

   568     Constructs a QImageReader object with the device \a device and the

   569     image format \a format.

   570 */

   571 QImageReader::QImageReader(QIODevice *device, const QByteArray &format)

   572     : d(new QImageReaderPrivate(this))

   573 {

   574     d->device = device;

   575     d->format = format;

   576 }

   577 

   578 /*!

   579     Constructs a QImageReader object with the file name \a fileName

   580     and the image format \a format.

   581 

   582     \sa setFileName()

   583 */

   584 QImageReader::QImageReader(const QString &fileName, const QByteArray &format)

   585     : d(new QImageReaderPrivate(this))

   586 {

   587     QFile *file = new QFile(fileName);

   588     d->device = file;

   589     d->deleteDevice = true;

   590     d->format = format;

   591 }

   592 

   593 /*!

   594     Destructs the QImageReader object.

   595 */

   596 QImageReader::~QImageReader()

   597 {

   598     delete d;

   599 }

   600 

   601 /*!

   602     Sets the format QImageReader will use when reading images, to \a

   603     format. \a format is a case insensitive text string. Example:

   604 

   605     \snippet doc/src/snippets/code/src_gui_image_qimagereader.cpp 0

   606 

   607     You can call supportedImageFormats() for the full list of formats

   608     QImageReader supports.

   609 

   610     \sa format()

   611 */

   612 void QImageReader::setFormat(const QByteArray &format)

   613 {

   614     d->format = format;

   615 }

   616 

   617 /*!

   618     Returns the format QImageReader uses for reading images.

   619 

   620     You can call this function after assigning a device to the

   621     reader to determine the format of the device. For example:

   622 

   623     \snippet doc/src/snippets/code/src_gui_image_qimagereader.cpp 1

   624 

   625     If the reader cannot read any image from the device (e.g., there is no

   626     image there, or the image has already been read), or if the format is

   627     unsupported, this function returns an empty QByteArray().

   628 

   629     \sa setFormat(), supportedImageFormats()

   630 */

   631 QByteArray QImageReader::format() const

   632 {

   633     if (d->format.isEmpty()) {

   634         if (!d->initHandler())

   635             return QByteArray();

   636         return d->handler->canRead() ? d->handler->format() : QByteArray();

   637     }

   638 

   639     return d->format;

   640 }

   641 

   642 /*!

   643     If \a enabled is true, image format autodetection is enabled; otherwise,

   644     it is disabled. By default, autodetection is enabled.

   645 

   646     QImageReader uses an extensive approach to detecting the image format;

   647     firstly, if you pass a file name to QImageReader, it will attempt to

   648     detect the file extension if the given file name does not point to an

   649     existing file, by appending supported default extensions to the given file

   650     name, one at a time. It then uses the following approach to detect the

   651     image format:

   652 

   653     \list

   654 

   655     \o Image plugins are queried first, based on either the optional format

   656     string, or the file name suffix (if the source device is a file). No

   657     content detection is done at this stage. QImageReader will choose the

   658     first plugin that supports reading for this format.

   659 

   660     \o If no plugin supports the image format, Qt's built-in handlers are

   661     checked based on either the optional format string, or the file name

   662     suffix.

   663 

   664     \o If no capable plugins or built-in handlers are found, each plugin is

   665     tested by inspecting the content of the data stream.

   666 

   667     \o If no plugins could detect the image format based on data contents,

   668     each built-in image handler is tested by inspecting the contents.

   669 

   670     \o Finally, if all above approaches fail, QImageReader will report failure

   671     when trying to read the image.

   672 

   673     \endlist

   674 

   675     By disabling image format autodetection, QImageReader will only query the

   676     plugins and built-in handlers based on the format string (i.e., no file

   677     name extensions are tested).

   678 

   679     \sa QImageIOHandler::canRead(), QImageIOPlugin::capabilities()

   680 */

   681 void QImageReader::setAutoDetectImageFormat(bool enabled)

   682 {

   683     d->autoDetectImageFormat = enabled;

   684 }

   685 

   686 /*!

   687     Returns true if image format autodetection is enabled on this image

   688     reader; otherwise returns false. By default, autodetection is enabled.

   689 

   690     \sa setAutoDetectImageFormat()

   691 */

   692 bool QImageReader::autoDetectImageFormat() const

   693 {

   694     return d->autoDetectImageFormat;

   695 }

   696 

   697 

   698 /*!

   699     If \a ignored is set to true, then the image reader will ignore

   700     specified formats or file extensions and decide which plugin to

   701     use only based on the contents in the datastream.

   702 

   703     Setting this flag means that all image plugins gets loaded. Each

   704     plugin will read the first bytes in the image data and decide if

   705     the plugin is compatible or not.

   706 

   707     This also disables auto detecting the image format.

   708 

   709     \sa decideFormatFromContent()

   710 */

   711 

   712 void QImageReader::setDecideFormatFromContent(bool ignored)

   713 {

   714     d->ignoresFormatAndExtension = ignored;

   715 }

   716 

   717 

   718 /*!

   719     Returns whether the image reader should decide which plugin to use

   720     only based on the contents of the datastream rather than on the file

   721     extension.

   722 

   723     \sa setDecideFormatFromContent()

   724 */

   725 

   726 bool QImageReader::decideFormatFromContent() const

   727 {

   728     return d->ignoresFormatAndExtension;

   729 }

   730 

   731 

   732 /*!

   733     Sets QImageReader's device to \a device. If a device has already

   734     been set, the old device is removed from QImageReader and is

   735     otherwise left unchanged.

   736 

   737     If the device is not already open, QImageReader will attempt to

   738     open the device in \l QIODevice::ReadOnly mode by calling

   739     open(). Note that this does not work for certain devices, such as

   740     QProcess, QTcpSocket and QUdpSocket, where more logic is required

   741     to open the device.

   742 

   743     \sa device(), setFileName()

   744 */

   745 void QImageReader::setDevice(QIODevice *device)

   746 {

   747     if (d->device && d->deleteDevice)

   748         delete d->device;

   749     d->device = device;

   750     d->deleteDevice = false;

   751     delete d->handler;

   752     d->handler = 0;

   753     d->text.clear();

   754 }

   755 

   756 /*!

   757     Returns the device currently assigned to QImageReader, or 0 if no

   758     device has been assigned.

   759 */

   760 QIODevice *QImageReader::device() const

   761 {

   762     return d->device;

   763 }

   764 

   765 /*!

   766     Sets the file name of QImageReader to \a fileName. Internally,

   767     QImageReader will create a QFile object and open it in \l

   768     QIODevice::ReadOnly mode, and use this when reading images.

   769 

   770     If \a fileName does not include a file extension (e.g., .png or .bmp),

   771     QImageReader will cycle through all supported extensions until it finds

   772     a matching file.

   773 

   774     \sa fileName(), setDevice(), supportedImageFormats()

   775 */

   776 void QImageReader::setFileName(const QString &fileName)

   777 {

   778     setDevice(new QFile(fileName));

   779     d->deleteDevice = true;

   780 }

   781 

   782 /*!

   783     If the currently assigned device is a QFile, or if setFileName()

   784     has been called, this function returns the name of the file

   785     QImageReader reads from. Otherwise (i.e., if no device has been

   786     assigned or the device is not a QFile), an empty QString is

   787     returned.

   788 

   789     \sa setFileName(), setDevice()

   790 */

   791 QString QImageReader::fileName() const

   792 {

   793     QFile *file = qobject_cast<QFile *>(d->device);

   794     return file ? file->fileName() : QString();

   795 }

   796 

   797 /*!

   798     \since 4.2

   799 

   800     This is an image format specific function that sets the quality

   801     level of the image to \a quality. For image formats that do not

   802     support setting the quality, this value is ignored.

   803 

   804     The value range of \a quality depends on the image format. For

   805     example, the "jpeg" format supports a quality range from 0 (low

   806     quality, high compression) to 100 (high quality, low compression).

   807 

   808     \sa quality()

   809 */

   810 void QImageReader::setQuality(int quality)

   811 {

   812     d->quality = quality;

   813 }

   814 

   815 /*!

   816     \since 4.2

   817 

   818     Returns the quality level of the image.

   819 

   820     \sa setQuality()

   821 */

   822 int QImageReader::quality() const

   823 {

   824     return d->quality;

   825 }

   826 

   827 

   828 /*!

   829     Returns the size of the image, without actually reading the image

   830     contents.

   831 

   832     If the image format does not support this feature, this function returns

   833     an invalid size. Qt's built-in image handlers all support this feature,

   834     but custom image format plugins are not required to do so.

   835 

   836     \sa QImageIOHandler::ImageOption, QImageIOHandler::option(), QImageIOHandler::supportsOption()

   837 */

   838 QSize QImageReader::size() const

   839 {

   840     if (!d->initHandler())

   841         return QSize();

   842 

   843     if (d->handler->supportsOption(QImageIOHandler::Size))

   844         return d->handler->option(QImageIOHandler::Size).toSize();

   845 

   846     return QSize();

   847 }

   848 

   849 /*!

   850     \since 4.5

   851 

   852     Returns the format of the image, without actually reading the image

   853     contents. The format describes the image format \l QImageReader::read()

   854     returns, not the format of the actual image.

   855 

   856     If the image format does not support this feature, this function returns

   857     an invalid format.

   858 

   859     \sa QImageIOHandler::ImageOption, QImageIOHandler::option(), QImageIOHandler::supportsOption()

   860 */

   861 QImage::Format QImageReader::imageFormat() const

   862 {

   863     if (!d->initHandler())

   864         return QImage::Format_Invalid;

   865 

   866     if (d->handler->supportsOption(QImageIOHandler::ImageFormat))

   867         return (QImage::Format)d->handler->option(QImageIOHandler::ImageFormat).toInt();

   868 

   869     return QImage::Format_Invalid;

   870 }

   871 

   872 /*!

   873     \since 4.1

   874 

   875     Returns the text keys for this image. You can use

   876     these keys with text() to list the image text for

   877     a certain key.

   878 

   879     Support for this option is implemented through

   880     QImageIOHandler::Description.

   881 

   882     \sa text(), QImageWriter::setText(), QImage::textKeys()

   883 */

   884 QStringList QImageReader::textKeys() const

   885 {

   886     d->getText();

   887     return d->text.keys();

   888 }

   889 

   890 /*!

   891     \since 4.1

   892 

   893     Returns the image text associated with \a key.

   894 

   895     Support for this option is implemented through

   896     QImageIOHandler::Description.

   897 

   898     \sa textKeys(), QImageWriter::setText()

   899 */

   900 QString QImageReader::text(const QString &key) const

   901 {

   902     d->getText();

   903     return d->text.value(key);

   904 }

   905 

   906 /*!

   907     Sets the image clip rect (also known as the ROI, or Region Of

   908     Interest) to \a rect. The coordinates of \a rect are relative to

   909     the untransformed image size, as returned by size().

   910 

   911     \sa clipRect(), setScaledSize(), setScaledClipRect()

   912 */

   913 void QImageReader::setClipRect(const QRect &rect)

   914 {

   915     d->clipRect = rect;

   916 }

   917 

   918 /*!

   919     Returns the clip rect (also known as the ROI, or Region Of

   920     Interest) of the image. If no clip rect has been set, an invalid

   921     QRect is returned.

   922 

   923     \sa setClipRect()

   924 */

   925 QRect QImageReader::clipRect() const

   926 {

   927     return d->clipRect;

   928 }

   929 

   930 /*!

   931     Sets the scaled size of the image to \a size. The scaling is

   932     performed after the initial clip rect, but before the scaled clip

   933     rect is applied. The algorithm used for scaling depends on the

   934     image format. By default (i.e., if the image format does not

   935     support scaling), QImageReader will use QImage::scale() with

   936     Qt::SmoothScaling.

   937 

   938     \sa scaledSize(), setClipRect(), setScaledClipRect()

   939 */

   940 void QImageReader::setScaledSize(const QSize &size)

   941 {

   942     d->scaledSize = size;

   943 }

   944 

   945 /*!

   946     Returns the scaled size of the image.

   947 

   948     \sa setScaledSize()

   949 */

   950 QSize QImageReader::scaledSize() const

   951 {

   952     return d->scaledSize;

   953 }

   954 

   955 /*!

   956     Sets the scaled clip rect to \a rect. The scaled clip rect is the

   957     clip rect (also known as ROI, or Region Of Interest) that is

   958     applied after the image has been scaled.

   959 

   960     \sa scaledClipRect(), setScaledSize()

   961 */

   962 void QImageReader::setScaledClipRect(const QRect &rect)

   963 {

   964     d->scaledClipRect = rect;

   965 }

   966 

   967 /*!

   968     Returns the scaled clip rect of the image.

   969 

   970     \sa setScaledClipRect()

   971 */

   972 QRect QImageReader::scaledClipRect() const

   973 {

   974     return d->scaledClipRect;

   975 }

   976 

   977 /*!

   978     \since 4.1

   979 

   980     Sets the background color to \a color.

   981     Image formats that support this operation are expected to

   982     initialize the background to \a color before reading an image.

   983 

   984     \sa backgroundColor(), read()

   985 */

   986 void QImageReader::setBackgroundColor(const QColor &color)

   987 {

   988     if (!d->initHandler())

   989         return;

   990     if (d->handler->supportsOption(QImageIOHandler::BackgroundColor))

   991         d->handler->setOption(QImageIOHandler::BackgroundColor, color);

   992 }

   993 

   994 /*!

   995     \since 4.1

   996 

   997     Returns the background color that's used when reading an image.

   998     If the image format does not support setting the background color

   999     an invalid color is returned.

  1000 

  1001     \sa setBackgroundColor(), read()

  1002 */

  1003 QColor QImageReader::backgroundColor() const

  1004 {

  1005     if (!d->initHandler())

  1006         return QColor();

  1007     if (d->handler->supportsOption(QImageIOHandler::BackgroundColor))

  1008         return qVariantValue<QColor>(d->handler->option(QImageIOHandler::BackgroundColor));

  1009     return QColor();

  1010 }

  1011 

  1012 /*!

  1013     \since 4.1

  1014 

  1015     Returns true if the image format supports animation;

  1016     otherwise, false is returned.

  1017 

  1018     \sa QMovie::supportedFormats()

  1019 */

  1020 bool QImageReader::supportsAnimation() const

  1021 {

  1022     if (!d->initHandler())

  1023         return false;

  1024     if (d->handler->supportsOption(QImageIOHandler::Animation))

  1025         return d->handler->option(QImageIOHandler::Animation).toBool();

  1026     return false;

  1027 }

  1028 

  1029 /*!

  1030     Returns true if an image can be read for the device (i.e., the

  1031     image format is supported, and the device seems to contain valid

  1032     data); otherwise returns false.

  1033 

  1034     canRead() is a lightweight function that only does a quick test to

  1035     see if the image data is valid. read() may still return false

  1036     after canRead() returns true, if the image data is corrupt.

  1037 

  1038     For images that support animation, canRead() returns false when

  1039     all frames have been read.

  1040 

  1041     \sa read(), supportedImageFormats()

  1042 */

  1043 bool QImageReader::canRead() const

  1044 {

  1045     if (!d->initHandler())

  1046         return false;

  1047 

  1048     return d->handler->canRead();

  1049 }

  1050 

  1051 /*!

  1052     Reads an image from the device. On success, the image that was

  1053     read is returned; otherwise, a null QImage is returned. You can

  1054     then call error() to find the type of error that occurred, or

  1055     errorString() to get a human readable description of the error.

  1056 

  1057     For image formats that support animation, calling read()

  1058     repeatedly will return the next frame. When all frames have been

  1059     read, a null image will be returned.

  1060 

  1061     \sa canRead(), supportedImageFormats(), supportsAnimation(), QMovie

  1062 */

  1063 QImage QImageReader::read()

  1064 {

  1065     // Because failed image reading might have side effects, we explicitly

  1066     // return a null image instead of the image we've just created.

  1067     QImage image;

  1068     return read(&image) ? image : QImage();

  1069 }

  1070 

  1071 /*!

  1072     \overload

  1073 

  1074     Reads an image from the device into \a image, which must point to a

  1075     QImage. Returns true on success; otherwise, returns false.

  1076 

  1077     If \a image has same format and size as the image data that is about to be

  1078     read, this function may not need to allocate a new image before

  1079     reading. Because of this, it can be faster than the other read() overload,

  1080     which always constructs a new image; especially when reading several

  1081     images with the same format and size.

  1082 

  1083     \snippet doc/src/snippets/code/src_gui_image_qimagereader.cpp 2

  1084 

  1085     For image formats that support animation, calling read() repeatedly will

  1086     return the next frame. When all frames have been read, a null image will

  1087     be returned.

  1088 

  1089     \sa canRead(), supportedImageFormats(), supportsAnimation(), QMovie

  1090 */

  1091 bool QImageReader::read(QImage *image)

  1092 {

  1093     if (!image) {

  1094         qWarning("QImageReader::read: cannot read into null pointer");

  1095         return false;

  1096     }

  1097 

  1098     if (!d->handler && !d->initHandler())

  1099         return false;

  1100 

  1101     // set the handler specific options.

  1102     if (d->handler->supportsOption(QImageIOHandler::ScaledSize) && d->scaledSize.isValid()) {

  1103         if ((d->handler->supportsOption(QImageIOHandler::ClipRect) && !d->clipRect.isNull())

  1104             || d->clipRect.isNull()) {

  1105             // Only enable the ScaledSize option if there is no clip rect, or

  1106             // if the handler also supports ClipRect.

  1107             d->handler->setOption(QImageIOHandler::ScaledSize, d->scaledSize);

  1108         }

  1109     }

  1110     if (d->handler->supportsOption(QImageIOHandler::ClipRect) && !d->clipRect.isNull())

  1111         d->handler->setOption(QImageIOHandler::ClipRect, d->clipRect);

  1112     if (d->handler->supportsOption(QImageIOHandler::ScaledClipRect) && !d->scaledClipRect.isNull())

  1113         d->handler->setOption(QImageIOHandler::ScaledClipRect, d->scaledClipRect);

  1114     if (d->handler->supportsOption(QImageIOHandler::Quality))

  1115         d->handler->setOption(QImageIOHandler::Quality, d->quality);

  1116 

  1117     // read the image

  1118     if (!d->handler->read(image)) {

  1119         d->imageReaderError = InvalidDataError;

  1120         d->errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "Unable to read image data"));

  1121         return false;

  1122     }

  1123 

  1124     // provide default implementations for any unsupported image

  1125     // options

  1126     if (d->handler->supportsOption(QImageIOHandler::ClipRect) && !d->clipRect.isNull()) {

  1127         if (d->handler->supportsOption(QImageIOHandler::ScaledSize) && d->scaledSize.isValid()) {

  1128             if (d->handler->supportsOption(QImageIOHandler::ScaledClipRect) && !d->scaledClipRect.isNull()) {

  1129                 // all features are supported by the handler; nothing to do.

  1130             } else {

  1131                 // the image is already scaled, so apply scaled clipping.

  1132                 if (!d->scaledClipRect.isNull())

  1133                     *image = image->copy(d->scaledClipRect);

  1134             }