Qt 4.8
Public Types | Public Functions | Static Public Functions | Properties | List of all members
QImageReader Class Reference

The QImageReader class provides a format independent interface for reading images from files or other devices. More...

#include <qimagereader.h>

Public Types

enum  ImageReaderError {
  UnknownError, FileNotFoundError, DeviceError, UnsupportedFormatError,
  InvalidDataError
}
 This enum describes the different types of errors that can occur when reading images with QImageReader. More...
 

Public Functions

bool autoDetectImageFormat () const
 Returns true if image format autodetection is enabled on this image reader; otherwise returns false. More...
 
QColor backgroundColor () const
 Returns the background color that's used when reading an image. More...
 
bool canRead () const
 Returns true if an image can be read for the device (i.e., the image format is supported, and the device seems to contain valid data); otherwise returns false. More...
 
QRect clipRect () const
 Returns the clip rect (also known as the ROI, or Region Of Interest) of the image. More...
 
int currentImageNumber () const
 For image formats that support animation, this function returns the sequence number of the current frame. More...
 
QRect currentImageRect () const
 For image formats that support animation, this function returns the rect for the current frame. More...
 
bool decideFormatFromContent () const
 Returns whether the image reader should decide which plugin to use only based on the contents of the datastream rather than on the file extension. More...
 
QIODevicedevice () const
 Returns the device currently assigned to QImageReader, or 0 if no device has been assigned. More...
 
ImageReaderError error () const
 Returns the type of error that occurred last. More...
 
QString errorString () const
 Returns a human readable description of the last error that occurred. More...
 
QString fileName () const
 If the currently assigned device is a QFile, or if setFileName() has been called, this function returns the name of the file QImageReader reads from. More...
 
QByteArray format () const
 Returns the format QImageReader uses for reading images. More...
 
int imageCount () const
 For image formats that support animation, this function returns the total number of images in the animation. More...
 
QImage::Format imageFormat () const
 Returns the format of the image, without actually reading the image contents. More...
 
bool jumpToImage (int imageNumber)
 For image formats that support animation, this function skips to the image whose sequence number is imageNumber, returning true if successful or false if the corresponding image cannot be found. More...
 
bool jumpToNextImage ()
 For image formats that support animation, this function steps over the current image, returning true if successful or false if there is no following image in the animation. More...
 
int loopCount () const
 For image formats that support animation, this function returns the number of times the animation should loop. More...
 
int nextImageDelay () const
 For image formats that support animation, this function returns the number of milliseconds to wait until displaying the next frame in the animation. More...
 
 QImageReader ()
 Constructs an empty QImageReader object. More...
 
 QImageReader (QIODevice *device, const QByteArray &format=QByteArray())
 Constructs a QImageReader object with the device device and the image format format. More...
 
 QImageReader (const QString &fileName, const QByteArray &format=QByteArray())
 Constructs a QImageReader object with the file name fileName and the image format format. More...
 
int quality () const
 Returns the quality level of the image. More...
 
QImage read ()
 Reads an image from the device. More...
 
bool read (QImage *image)
 Reads an image from the device into image, which must point to a QImage. More...
 
QRect scaledClipRect () const
 Returns the scaled clip rect of the image. More...
 
QSize scaledSize () const
 Returns the scaled size of the image. More...
 
void setAutoDetectImageFormat (bool enabled)
 If enabled is true, image format autodetection is enabled; otherwise, it is disabled. More...
 
void setBackgroundColor (const QColor &color)
 Sets the background color to color. More...
 
void setClipRect (const QRect &rect)
 Sets the image clip rect (also known as the ROI, or Region Of Interest) to rect. More...
 
void setDecideFormatFromContent (bool ignored)
 If ignored is set to true, then the image reader will ignore specified formats or file extensions and decide which plugin to use only based on the contents in the datastream. More...
 
void setDevice (QIODevice *device)
 Sets QImageReader's device to device. More...
 
void setFileName (const QString &fileName)
 Sets the file name of QImageReader to fileName. More...
 
void setFormat (const QByteArray &format)
 Sets the format QImageReader will use when reading images, to format. More...
 
void setQuality (int quality)
 This is an image format specific function that sets the quality level of the image to quality. More...
 
void setScaledClipRect (const QRect &rect)
 Sets the scaled clip rect to rect. More...
 
void setScaledSize (const QSize &size)
 Sets the scaled size of the image to size. More...
 
QSize size () const
 Returns the size of the image, without actually reading the image contents. More...
 
bool supportsAnimation () const
 Returns true if the image format supports animation; otherwise, false is returned. More...
 
bool supportsOption (QImageIOHandler::ImageOption option) const
 Returns true if the reader supports option; otherwise returns false. More...
 
QString text (const QString &key) const
 Returns the image text associated with key. More...
 
QStringList textKeys () const
 Returns the text keys for this image. More...
 
 ~QImageReader ()
 Destructs the QImageReader object. More...
 

Static Public Functions

static QByteArray imageFormat (const QString &fileName)
 If supported, this function returns the image format of the file fileName. More...
 
static QByteArray imageFormat (QIODevice *device)
 If supported, this function returns the image format of the device device. More...
 
static QList< QByteArraysupportedImageFormats ()
 Returns the list of image formats supported by QImageReader. More...
 

Properties

QImageReaderPrivated
 

Detailed Description

The QImageReader class provides a format independent interface for reading images from files or other devices.

Note
This class or function is reentrant.

The most common way to read images is through QImage and QPixmap's constructors, or by calling QImage::load() and QPixmap::load(). QImageReader is a specialized class which gives you more control when reading images. For example, you can read an image into a specific size by calling setScaledSize(), and you can select a clip rect, effectively loading only parts of an image, by calling setClipRect(). Depending on the underlying support in the image format, this can save memory and speed up loading of images.

To read an image, you start by constructing a QImageReader object. Pass either a file name or a device pointer, and the image format to QImageReader's constructor. You can then set several options, such as the clip rect (by calling setClipRect()) and scaled size (by calling setScaledSize()). canRead() returns the image if the QImageReader can read the image (i.e., the image format is supported and the device is open for reading). Call read() to read the image.

If any error occurs when reading the image, read() will return a null QImage. You can then call error() to find the type of error that occurred, or errorString() to get a human readable description of what went wrong.

Call supportedImageFormats() for a list of formats that QImageReader can read. QImageReader supports all built-in image formats, in addition to any image format plugins that support reading.

QImageReader autodetects the image format by default, by looking at the provided (optional) format string, the file name suffix, and the data stream contents. You can enable or disable this feature, by calling setAutoDetectImageFormat().

See also
QImageWriter, QImageIOHandler, QImageIOPlugin

Definition at line 62 of file qimagereader.h.

Enumerations

◆ ImageReaderError

This enum describes the different types of errors that can occur when reading images with QImageReader.

  • FileNotFoundError QImageReader was used with a file name, but not file was found with that name. This can also happen if the file name contained no extension, and the file with the correct extension is not supported by Qt.
  • DeviceError QImageReader encountered a device error when reading the image. You can consult your particular device for more details on what went wrong.
  • UnsupportedFormatError Qt does not support the requested image format.
  • InvalidDataError The image data was invalid, and QImageReader was unable to read an image from it. The can happen if the image file is damaged.
  • UnknownError An unknown error occurred. If you get this value after calling read(), it is most likely caused by a bug in QImageReader.
Enumerator
UnknownError 
FileNotFoundError 
DeviceError 
UnsupportedFormatError 
InvalidDataError 

Definition at line 65 of file qimagereader.h.

Constructors and Destructors

◆ QImageReader() [1/3]

QImageReader::QImageReader ( )

Constructs an empty QImageReader object.

Before reading an image, call setDevice() or setFileName().

Definition at line 655 of file qimagereader.cpp.

656  : d(new QImageReaderPrivate(this))
657 {
658 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ QImageReader() [2/3]

QImageReader::QImageReader ( QIODevice device,
const QByteArray format = QByteArray() 
)
explicit

Constructs a QImageReader object with the device device and the image format format.

Definition at line 664 of file qimagereader.cpp.

665  : d(new QImageReaderPrivate(this))
666 {
667  d->device = device;
668  d->format = format;
669 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QByteArray format() const
Returns the format QImageReader uses for reading images.
QIODevice * device() const
Returns the device currently assigned to QImageReader, or 0 if no device has been assigned...

◆ QImageReader() [3/3]

QImageReader::QImageReader ( const QString fileName,
const QByteArray format = QByteArray() 
)
explicit

Constructs a QImageReader object with the file name fileName and the image format format.

See also
setFileName()

Definition at line 677 of file qimagereader.cpp.

678  : d(new QImageReaderPrivate(this))
679 {
680  QFile *file = new QFile(fileName);
681  d->device = file;
682  d->deleteDevice = true;
683  d->format = format;
684 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QByteArray format() const
Returns the format QImageReader uses for reading images.
The QFile class provides an interface for reading from and writing to files.
Definition: qfile.h:65

◆ ~QImageReader()

QImageReader::~QImageReader ( )

Destructs the QImageReader object.

Definition at line 689 of file qimagereader.cpp.

690 {
691  delete d;
692 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

Functions

◆ autoDetectImageFormat()

bool QImageReader::autoDetectImageFormat ( ) const

Returns true if image format autodetection is enabled on this image reader; otherwise returns false.

By default, autodetection is enabled.

See also
setAutoDetectImageFormat()

Definition at line 785 of file qimagereader.cpp.

786 {
787  return d->autoDetectImageFormat;
788 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ backgroundColor()

QColor QImageReader::backgroundColor ( ) const

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

Since
4.1

If the image format does not support setting the background color an invalid color is returned.

See also
setBackgroundColor(), read()

Definition at line 1116 of file qimagereader.cpp.

Referenced by QMoviePrivate::infoForFrame().

1117 {
1118  if (!d->initHandler())
1119  return QColor();
1121  return qvariant_cast<QColor>(d->handler->option(QImageIOHandler::BackgroundColor));
1122  return QColor();
1123 }
The QColor class provides colors based on RGB, HSV or CMYK values.
Definition: qcolor.h:67
QImageReaderPrivate * d
Definition: qimagereader.h:140
QImageIOHandler * handler
virtual QVariant option(ImageOption option) const
Returns the value assigned to option as a QVariant.
virtual bool supportsOption(ImageOption option) const
Returns true if the QImageIOHandler supports the option option; otherwise returns false...

◆ canRead()

bool QImageReader::canRead ( ) const

Returns true if an image can be read for the device (i.e., the image format is supported, and the device seems to contain valid data); otherwise returns false.

canRead() is a lightweight function that only does a quick test to see if the image data is valid. read() may still return false after canRead() returns true, if the image data is corrupt.

For images that support animation, canRead() returns false when all frames have been read.

See also
read(), supportedImageFormats()

Definition at line 1159 of file qimagereader.cpp.

Referenced by QMoviePrivate::isValid().

1160 {
1161  if (!d->initHandler())
1162  return false;
1163 
1164  return d->handler->canRead();
1165 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QImageIOHandler * handler
virtual bool canRead() const =0
Returns true if an image can be read from the device (i.

◆ clipRect()

QRect QImageReader::clipRect ( ) const

Returns the clip rect (also known as the ROI, or Region Of Interest) of the image.

If no clip rect has been set, an invalid QRect is returned.

See also
setClipRect()

Definition at line 1032 of file qimagereader.cpp.

1033 {
1034  return d->clipRect;
1035 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ currentImageNumber()

int QImageReader::currentImageNumber ( ) const

For image formats that support animation, this function returns the sequence number of the current frame.

If the image format doesn't support animation, 0 is returned.

This function returns -1 if an error occurred.

See also
supportsAnimation(), QImageIOHandler::currentImageNumber(), canRead()

Definition at line 1391 of file qimagereader.cpp.

1392 {
1393  if (!d->initHandler())
1394  return -1;
1395  return d->handler->currentImageNumber();
1396 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
virtual int currentImageNumber() const
For image formats that support animation, this function returns the sequence number of the current im...
QImageIOHandler * handler

◆ currentImageRect()

QRect QImageReader::currentImageRect ( ) const

For image formats that support animation, this function returns the rect for the current frame.

Otherwise, a null rect is returned.

See also
supportsAnimation(), QImageIOHandler::currentImageRect()

Definition at line 1404 of file qimagereader.cpp.

1405 {
1406  if (!d->initHandler())
1407  return QRect();
1408  return d->handler->currentImageRect();
1409 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
The QRect class defines a rectangle in the plane using integer precision.
Definition: qrect.h:58
QImageIOHandler * handler
virtual QRect currentImageRect() const
Returns the rect of the current image.

◆ decideFormatFromContent()

bool QImageReader::decideFormatFromContent ( ) const

Returns whether the image reader should decide which plugin to use only based on the contents of the datastream rather than on the file extension.

See also
setDecideFormatFromContent()

Definition at line 819 of file qimagereader.cpp.

820 {
822 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ device()

QIODevice * QImageReader::device ( ) const

Returns the device currently assigned to QImageReader, or 0 if no device has been assigned.

Definition at line 853 of file qimagereader.cpp.

Referenced by QMoviePrivate::infoForFrame(), QImageReader(), QMoviePrivate::reset(), and setDevice().

854 {
855  return d->device;
856 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ error()

QImageReader::ImageReaderError QImageReader::error ( ) const

Returns the type of error that occurred last.

See also
ImageReaderError, errorString()

Definition at line 1416 of file qimagereader.cpp.

Referenced by QMoviePrivate::_q_loadNextFrame().

1417 {
1418  return d->imageReaderError;
1419 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QImageReader::ImageReaderError imageReaderError

◆ errorString()

QString QImageReader::errorString ( ) const

Returns a human readable description of the last error that occurred.

See also
error()

Definition at line 1427 of file qimagereader.cpp.

Referenced by readImage().

1428 {
1429  if (d->errorString.isEmpty())
1430  return QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "Unknown error"));
1431  return d->errorString;
1432 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
#define QT_TRANSLATE_NOOP(scope, x)
Marks the string literal sourceText for dynamic translation in the given context; i...
Definition: qglobal.h:2487
QLatin1String(DBUS_INTERFACE_DBUS))) Q_GLOBAL_STATIC_WITH_ARGS(QString
bool isEmpty() const
Returns true if the string has no characters; otherwise returns false.
Definition: qstring.h:704
The QImageReader class provides a format independent interface for reading images from files or other...
Definition: qimagereader.h:62

◆ fileName()

QString QImageReader::fileName ( ) const

If the currently assigned device is a QFile, or if setFileName() has been called, this function returns the name of the file QImageReader reads from.

Otherwise (i.e., if no device has been assigned or the device is not a QFile), an empty QString is returned.

See also
setFileName(), setDevice()

Definition at line 883 of file qimagereader.cpp.

Referenced by QMoviePrivate::infoForFrame().

884 {
885  QFile *file = qobject_cast<QFile *>(d->device);
886  return file ? file->fileName() : QString();
887 }
T qobject_cast(QObject *object)
Definition: qobject.h:375
QString fileName() const
Returns the name set by setFileName() or to the QFile constructors.
Definition: qfile.cpp:470
QImageReaderPrivate * d
Definition: qimagereader.h:140
The QString class provides a Unicode character string.
Definition: qstring.h:83
The QFile class provides an interface for reading from and writing to files.
Definition: qfile.h:65

◆ format()

QByteArray QImageReader::format ( ) const

Returns the format QImageReader uses for reading images.

You can call this function after assigning a device to the reader to determine the format of the device. For example:

QImageReader reader("image.png");
// reader.format() == "png"

If the reader cannot read any image from the device (e.g., there is no image there, or the image has already been read), or if the format is unsupported, this function returns an empty QByteArray().

See also
setFormat(), supportedImageFormats()

Definition at line 724 of file qimagereader.cpp.

Referenced by imageFormat(), QMoviePrivate::infoForFrame(), QImageReader(), and setFormat().

725 {
726  if (d->format.isEmpty()) {
727  if (!d->initHandler())
728  return QByteArray();
729  return d->handler->canRead() ? d->handler->format() : QByteArray();
730  }
731 
732  return d->format;
733 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
The QByteArray class provides an array of bytes.
Definition: qbytearray.h:135
QByteArray format() const
Returns the format that is currently assigned to QImageIOHandler.
QImageIOHandler * handler
bool isEmpty() const
Returns true if the byte array has size 0; otherwise returns false.
Definition: qbytearray.h:421
virtual bool canRead() const =0
Returns true if an image can be read from the device (i.

◆ imageCount()

int QImageReader::imageCount ( ) const

For image formats that support animation, this function returns the total number of images in the animation.

If the format does not support animation, 0 is returned.

This function returns -1 if an error occurred.

See also
supportsAnimation(), QImageIOHandler::imageCount(), canRead()

Definition at line 1359 of file qimagereader.cpp.

Referenced by QMoviePrivate::frameCount().

1360 {
1361  if (!d->initHandler())
1362  return -1;
1363  return d->handler->imageCount();
1364 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
virtual int imageCount() const
For image formats that support animation, this function returns the number of images in the animation...
QImageIOHandler * handler

◆ imageFormat() [1/3]

QImage::Format QImageReader::imageFormat ( ) const

Returns the format of the image, without actually reading the image contents.

Since
4.5

The format describes the image format QImageReader::read() returns, not the format of the actual image.

If the image format does not support this feature, this function returns an invalid format.

See also
QImageIOHandler::ImageOption, QImageIOHandler::option(), QImageIOHandler::supportsOption()

Definition at line 962 of file qimagereader.cpp.

Referenced by imageFormat().

963 {
964  if (!d->initHandler())
965  return QImage::Format_Invalid;
966 
969 
970  return QImage::Format_Invalid;
971 }
Format
The following image formats are available in Qt.
Definition: qimage.h:91
QImageReaderPrivate * d
Definition: qimagereader.h:140
int toInt(bool *ok=0) const
Returns the variant as an int if the variant has type() Int , Bool , ByteArray , Char ...
Definition: qvariant.cpp:2625
QImageIOHandler * handler
virtual QVariant option(ImageOption option) const
Returns the value assigned to option as a QVariant.
virtual bool supportsOption(ImageOption option) const
Returns true if the QImageIOHandler supports the option option; otherwise returns false...

◆ imageFormat() [2/3]

QByteArray QImageReader::imageFormat ( const QString fileName)
static

If supported, this function returns the image format of the file fileName.

Otherwise, an empty string is returned.

Definition at line 1464 of file qimagereader.cpp.

1465 {
1466  QFile file(fileName);
1467  if (!file.open(QFile::ReadOnly))
1468  return QByteArray();
1469 
1470  return imageFormat(&file);
1471 }
QImage::Format imageFormat() const
Returns the format of the image, without actually reading the image contents.
The QByteArray class provides an array of bytes.
Definition: qbytearray.h:135
The QFile class provides an interface for reading from and writing to files.
Definition: qfile.h:65

◆ imageFormat() [3/3]

QByteArray QImageReader::imageFormat ( QIODevice device)
static

If supported, this function returns the image format of the device device.

Otherwise, an empty string is returned.

See also
QImageReader::autoDetectImageFormat()

Definition at line 1479 of file qimagereader.cpp.

1480 {
1482  QImageIOHandler *handler = createReadHandlerHelper(device, format, /* autoDetectImageFormat = */ true, false);
1483  if (handler) {
1484  if (handler->canRead())
1485  format = handler->format();
1486  delete handler;
1487  }
1488  return format;
1489 }
The QByteArray class provides an array of bytes.
Definition: qbytearray.h:135
QByteArray format() const
Returns the format that is currently assigned to QImageIOHandler.
QByteArray format() const
Returns the format QImageReader uses for reading images.
The QImageIOHandler class defines the common image I/O interface for all image formats in Qt...
static QImageIOHandler * createReadHandlerHelper(QIODevice *device, const QByteArray &format, bool autoDetectImageFormat, bool ignoresFormatAndExtension)
QImageIOHandler * handler
virtual bool canRead() const =0
Returns true if an image can be read from the device (i.

◆ jumpToImage()

bool QImageReader::jumpToImage ( int  imageNumber)

For image formats that support animation, this function skips to the image whose sequence number is imageNumber, returning true if successful or false if the corresponding image cannot be found.

The next call to read() will attempt to read this image.

See also
jumpToNextImage(), QImageIOHandler::jumpToImage()

Definition at line 1328 of file qimagereader.cpp.

Referenced by QMoviePrivate::infoForFrame().

1329 {
1330  if (!d->initHandler())
1331  return false;
1332  return d->handler->jumpToImage(imageNumber);
1333 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
virtual bool jumpToImage(int imageNumber)
For image formats that support animation, this function jumps to the image whose sequence number is i...
QImageIOHandler * handler

◆ jumpToNextImage()

bool QImageReader::jumpToNextImage ( )

For image formats that support animation, this function steps over the current image, returning true if successful or false if there is no following image in the animation.

The default implementation calls read(), then discards the resulting image, but the image handler may have a more efficient way of implementing this operation.

See also
jumpToImage(), QImageIOHandler::jumpToNextImage()

Definition at line 1312 of file qimagereader.cpp.

1313 {
1314  if (!d->initHandler())
1315  return false;
1316  return d->handler->jumpToNextImage();
1317 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
virtual bool jumpToNextImage()
For image formats that support animation, this function jumps to the next image.
QImageIOHandler * handler

◆ loopCount()

int QImageReader::loopCount ( ) const

For image formats that support animation, this function returns the number of times the animation should loop.

If this function returns -1, it can either mean the animation should loop forever, or that an error occurred. If an error occurred, canRead() will return false.

See also
supportsAnimation(), QImageIOHandler::loopCount(), canRead()

Definition at line 1343 of file qimagereader.cpp.

Referenced by QMoviePrivate::next().

1344 {
1345  if (!d->initHandler())
1346  return -1;
1347  return d->handler->loopCount();
1348 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
virtual int loopCount() const
For image formats that support animation, this function returns the number of times the animation sho...
QImageIOHandler * handler

◆ nextImageDelay()

int QImageReader::nextImageDelay ( ) const

For image formats that support animation, this function returns the number of milliseconds to wait until displaying the next frame in the animation.

If the image format doesn't support animation, 0 is returned.

This function returns -1 if an error occurred.

See also
supportsAnimation(), QImageIOHandler::nextImageDelay(), canRead()

Definition at line 1375 of file qimagereader.cpp.

1376 {
1377  if (!d->initHandler())
1378  return -1;
1379  return d->handler->nextImageDelay();
1380 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
virtual int nextImageDelay() const
For image formats that support animation, this function returns the number of milliseconds to wait un...
QImageIOHandler * handler

◆ quality()

int QImageReader::quality ( ) const

Returns the quality level of the image.

Since
4.2
See also
setQuality()

Definition at line 920 of file qimagereader.cpp.

Referenced by setQuality().

921 {
922  return d->quality;
923 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ read() [1/2]

QImage QImageReader::read ( )

Reads an image from the device.

On success, the image that was read is returned; otherwise, a null QImage is returned. You can then call error() to find the type of error that occurred, or errorString() to get a human readable description of the error.

For image formats that support animation, calling read() repeatedly will return the next frame. When all frames have been read, a null image will be returned.

See also
canRead(), supportedImageFormats(), supportsAnimation(), QMovie

Definition at line 1179 of file qimagereader.cpp.

Referenced by QRasterPixmapData::fromData(), QVGPixmapData::fromData(), QPixmapData::fromData(), QGLPixmapData::fromData(), QImage::fromData(), QVGPixmapData::fromFile(), QPixmapData::fromFile(), QGLPixmapData::fromFile(), QRasterPixmapData::fromImageReader(), QVGPixmapData::fromImageReader(), QPixmapData::fromImageReader(), QGLPixmapData::fromImageReader(), QImage::load(), and readImage().

1180 {
1181  // Because failed image reading might have side effects, we explicitly
1182  // return a null image instead of the image we've just created.
1183  QImage image;
1184  return read(&image) ? image : QImage();
1185 }
The QImage class provides a hardware-independent image representation that allows direct access to th...
Definition: qimage.h:87
QImage read()
Reads an image from the device.

◆ read() [2/2]

bool QImageReader::read ( QImage image)

Reads an image from the device into image, which must point to a QImage.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns true on success; otherwise, returns false.

If image has same format and size as the image data that is about to be read, this function may not need to allocate a new image before reading. Because of this, it can be faster than the other read() overload, which always constructs a new image; especially when reading several images with the same format and size.

QImageReader reader("icon_64x64.bmp");
if (reader.read(&icon)) {
// Display icon
}

For image formats that support animation, calling read() repeatedly will return the next frame. When all frames have been read, a null image will be returned.

See also
canRead(), supportedImageFormats(), supportsAnimation(), QMovie

Definition at line 1210 of file qimagereader.cpp.

1211 {
1212  if (!image) {
1213  qWarning("QImageReader::read: cannot read into null pointer");
1214  return false;
1215  }
1216 
1217  if (!d->handler && !d->initHandler())
1218  return false;
1219 
1220  // set the handler specific options.
1223  || d->clipRect.isNull()) {
1224  // Only enable the ScaledSize option if there is no clip rect, or
1225  // if the handler also supports ClipRect.
1227  }
1228  }
1235 
1236  // read the image
1237  if (!d->handler->read(image)) {
1239  d->errorString = QLatin1String(QT_TRANSLATE_NOOP(QImageReader, "Unable to read image data"));
1240  return false;
1241  }
1242 
1243  // provide default implementations for any unsupported image
1244  // options
1248  // all features are supported by the handler; nothing to do.
1249  } else {
1250  // the image is already scaled, so apply scaled clipping.
1251  if (!d->scaledClipRect.isNull())
1252  *image = image->copy(d->scaledClipRect);
1253  }
1254  } else {
1256  // supports scaled clipping but not scaling, most
1257  // likely a broken handler.
1258  } else {
1259  if (d->scaledSize.isValid()) {
1261  }
1262  if (d->scaledClipRect.isValid()) {
1263  *image = image->copy(d->scaledClipRect);
1264  }
1265  }
1266  }
1267  } else {
1269  // in this case, there's nothing we can do. if the
1270  // plugin supports scaled size but not ClipRect, then
1271  // we have to ignore ClipRect."
1272 
1274  // nothing to do (ClipRect is ignored!)
1275  } else {
1276  // provide all workarounds.
1277  if (d->scaledClipRect.isValid()) {
1278  *image = image->copy(d->scaledClipRect);
1279  }
1280  }
1281  } else {
1283  // this makes no sense; a handler that supports
1284  // ScaledClipRect but not ScaledSize is broken, and we
1285  // can't work around it.
1286  } else {
1287  // provide all workarounds.
1288  if (d->clipRect.isValid())
1289  *image = image->copy(d->clipRect);
1290  if (d->scaledSize.isValid())
1292  if (d->scaledClipRect.isValid())
1293  *image = image->copy(d->scaledClipRect);
1294  }
1295  }
1296  }
1297 
1298  return true;
1299 }
QImage copy(const QRect &rect=QRect()) const
Returns a sub-area of the image as a new image.
Definition: qimage.cpp:1410
bool isNull() const
Returns true if the rectangle is a null rectangle, otherwise returns false.
Definition: qrect.h:231
QImageReaderPrivate * d
Definition: qimagereader.h:140
virtual bool read(QImage *image)=0
Read an image from the device, and stores it in image.
#define QT_TRANSLATE_NOOP(scope, x)
Marks the string literal sourceText for dynamic translation in the given context; i...
Definition: qglobal.h:2487
QLatin1String(DBUS_INTERFACE_DBUS))) Q_GLOBAL_STATIC_WITH_ARGS(QString
QImageReader::ImageReaderError imageReaderError
virtual void setOption(ImageOption option, const QVariant &value)
Sets the option option with the value value.
Q_CORE_EXPORT void qWarning(const char *,...)
The QImageReader class provides a format independent interface for reading images from files or other...
Definition: qimagereader.h:62
bool isValid() const
Returns true if both the width and height is equal to or greater than 0; otherwise returns false...
Definition: qsize.h:123
QImageIOHandler * handler
QImage scaled(int w, int h, Qt::AspectRatioMode aspectMode=Qt::IgnoreAspectRatio, Qt::TransformationMode mode=Qt::FastTransformation) const
Definition: qimage.h:232
bool isValid() const
Returns true if the rectangle is valid, otherwise returns false.
Definition: qrect.h:237
virtual bool supportsOption(ImageOption option) const
Returns true if the QImageIOHandler supports the option option; otherwise returns false...

◆ scaledClipRect()

QRect QImageReader::scaledClipRect ( ) const

Returns the scaled clip rect of the image.

See also
setScaledClipRect()

Definition at line 1079 of file qimagereader.cpp.

1080 {
1081  return d->scaledClipRect;
1082 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ scaledSize()

QSize QImageReader::scaledSize ( ) const

Returns the scaled size of the image.

See also
setScaledSize()

Definition at line 1057 of file qimagereader.cpp.

Referenced by QMoviePrivate::infoForFrame(), and QMoviePrivate::next().

1058 {
1059  return d->scaledSize;
1060 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ setAutoDetectImageFormat()

void QImageReader::setAutoDetectImageFormat ( bool  enabled)

If enabled is true, image format autodetection is enabled; otherwise, it is disabled.

By default, autodetection is enabled.

QImageReader uses an extensive approach to detecting the image format; firstly, if you pass a file name to QImageReader, it will attempt to detect the file extension if the given file name does not point to an existing file, by appending supported default extensions to the given file name, one at a time. It then uses the following approach to detect the image format:

  • Image plugins are queried first, based on either the optional format string, or the file name suffix (if the source device is a file). No content detection is done at this stage. QImageReader will choose the first plugin that supports reading for this format.

  • If no plugin supports the image format, Qt's built-in handlers are checked based on either the optional format string, or the file name suffix.

  • If no capable plugins or built-in handlers are found, each plugin is tested by inspecting the content of the data stream.

  • If no plugins could detect the image format based on data contents, each built-in image handler is tested by inspecting the contents.

  • Finally, if all above approaches fail, QImageReader will report failure when trying to read the image.

By disabling image format autodetection, QImageReader will only query the plugins and built-in handlers based on the format string (i.e., no file name extensions are tested).

See also
QImageIOHandler::canRead(), QImageIOPlugin::capabilities()

Definition at line 774 of file qimagereader.cpp.

775 {
777 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
#define enabled

◆ setBackgroundColor()

void QImageReader::setBackgroundColor ( const QColor color)

Sets the background color to color.

Since
4.1

Image formats that support this operation are expected to initialize the background to color before reading an image.

See also
backgroundColor(), read()

Definition at line 1096 of file qimagereader.cpp.

1097 {
1098  if (!d->initHandler())
1099  return;
1102 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
virtual void setOption(ImageOption option, const QVariant &value)
Sets the option option with the value value.
QImageIOHandler * handler
virtual bool supportsOption(ImageOption option) const
Returns true if the QImageIOHandler supports the option option; otherwise returns false...

◆ setClipRect()

void QImageReader::setClipRect ( const QRect rect)

Sets the image clip rect (also known as the ROI, or Region Of Interest) to rect.

The coordinates of rect are relative to the untransformed image size, as returned by size().

See also
clipRect(), setScaledSize(), setScaledClipRect()

Definition at line 1020 of file qimagereader.cpp.

1021 {
1022  d->clipRect = rect;
1023 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ setDecideFormatFromContent()

void QImageReader::setDecideFormatFromContent ( bool  ignored)

If ignored is set to true, then the image reader will ignore specified formats or file extensions and decide which plugin to use only based on the contents in the datastream.

Setting this flag means that all image plugins gets loaded. Each plugin will read the first bytes in the image data and decide if the plugin is compatible or not.

This also disables auto detecting the image format.

See also
decideFormatFromContent()

Definition at line 805 of file qimagereader.cpp.

806 {
807  d->ignoresFormatAndExtension = ignored;
808 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ setDevice()

void QImageReader::setDevice ( QIODevice device)

Sets QImageReader's device to device.

If a device has already been set, the old device is removed from QImageReader and is otherwise left unchanged.

If the device is not already open, QImageReader will attempt to open the device in QIODevice::ReadOnly mode by calling open(). Note that this does not work for certain devices, such as QProcess, QTcpSocket and QUdpSocket, where more logic is required to open the device.

See also
device(), setFileName()

Definition at line 838 of file qimagereader.cpp.

Referenced by setFileName().

839 {
840  if (d->device && d->deleteDevice)
841  delete d->device;
842  d->device = device;
843  d->deleteDevice = false;
844  delete d->handler;
845  d->handler = 0;
846  d->text.clear();
847 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QMap< QString, QString > text
QIODevice * device() const
Returns the device currently assigned to QImageReader, or 0 if no device has been assigned...
QImageIOHandler * handler
void clear()
Removes all items from the map.
Definition: qmap.h:444

◆ setFileName()

void QImageReader::setFileName ( const QString fileName)

Sets the file name of QImageReader to fileName.

Internally, QImageReader will create a QFile object and open it in QIODevice::ReadOnly mode, and use this when reading images.

If fileName does not include a file extension (e.g., .png or .bmp), QImageReader will cycle through all supported extensions until it finds a matching file.

See also
fileName(), setDevice(), supportedImageFormats()

Definition at line 868 of file qimagereader.cpp.

869 {
870  setDevice(new QFile(fileName));
871  d->deleteDevice = true;
872 }
void setDevice(QIODevice *device)
Sets QImageReader&#39;s device to device.
QImageReaderPrivate * d
Definition: qimagereader.h:140
The QFile class provides an interface for reading from and writing to files.
Definition: qfile.h:65

◆ setFormat()

void QImageReader::setFormat ( const QByteArray format)

Sets the format QImageReader will use when reading images, to format.

format is a case insensitive text string. Example:

QImageReader reader;
reader.setFormat("png"); // same as reader.setFormat("PNG");

You can call supportedImageFormats() for the full list of formats QImageReader supports.

See also
format()

Definition at line 705 of file qimagereader.cpp.

Referenced by readImage().

706 {
707  d->format = format;
708 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QByteArray format() const
Returns the format QImageReader uses for reading images.

◆ setQuality()

void QImageReader::setQuality ( int  quality)

This is an image format specific function that sets the quality level of the image to quality.

Since
4.2

For image formats that do not support setting the quality, this value is ignored.

The value range of quality depends on the image format. For example, the "jpeg" format supports a quality range from 0 (low quality, high compression) to 100 (high quality, low compression).

See also
quality()

Definition at line 905 of file qimagereader.cpp.

906 {
907  d->quality = quality;
908 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
int quality() const
Returns the quality level of the image.

◆ setScaledClipRect()

void QImageReader::setScaledClipRect ( const QRect rect)

Sets the scaled clip rect to rect.

The scaled clip rect is the clip rect (also known as ROI, or Region Of Interest) that is applied after the image has been scaled.

See also
scaledClipRect(), setScaledSize()

Definition at line 1069 of file qimagereader.cpp.

1070 {
1071  d->scaledClipRect = rect;
1072 }
QImageReaderPrivate * d
Definition: qimagereader.h:140

◆ setScaledSize()

void QImageReader::setScaledSize ( const QSize size)

Sets the scaled size of the image to size.

The scaling is performed after the initial clip rect, but before the scaled clip rect is applied. The algorithm used for scaling depends on the image format. By default (i.e., if the image format does not support scaling), QImageReader will use QImage::scale() with Qt::SmoothScaling.

See also
scaledSize(), setClipRect(), setScaledClipRect()

Definition at line 1047 of file qimagereader.cpp.

Referenced by readImage().

1048 {
1049  d->scaledSize = size;
1050 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QSize size() const
Returns the size of the image, without actually reading the image contents.

◆ size()

QSize QImageReader::size ( ) const

Returns the size of the image, without actually reading the image contents.

If the image format does not support this feature, this function returns an invalid size. Qt's built-in image handlers all support this feature, but custom image format plugins are not required to do so.

See also
QImageIOHandler::ImageOption, QImageIOHandler::option(), QImageIOHandler::supportsOption()

Definition at line 936 of file qimagereader.cpp.

Referenced by readImage(), and setScaledSize().

937 {
938  if (!d->initHandler())
939  return QSize();
940 
943 
944  return QSize();
945 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QSize toSize() const
Returns the variant as a QSize if the variant has type() Size ; otherwise returns an invalid QSize...
Definition: qvariant.cpp:2432
QImageIOHandler * handler
The QSize class defines the size of a two-dimensional object using integer point precision.
Definition: qsize.h:53
virtual QVariant option(ImageOption option) const
Returns the value assigned to option as a QVariant.
virtual bool supportsOption(ImageOption option) const
Returns true if the QImageIOHandler supports the option option; otherwise returns false...

◆ supportedImageFormats()

QList< QByteArray > QImageReader::supportedImageFormats ( )
static

Returns the list of image formats supported by QImageReader.

By default, Qt can read the following formats:

Format Description
BMP Windows Bitmap
GIF Graphic Interchange Format (optional)
JPG Joint Photographic Experts Group
JPEG Joint Photographic Experts Group
MNG Multiple-image Network Graphics
PNG Portable Network Graphics
PBM Portable Bitmap
PGM Portable Graymap
PPM Portable Pixmap
TIFF Tagged Image File Format
XBM X11 Bitmap
XPM X11 Pixmap
SVG Scalable Vector Graphics
TGA Targa Image Format

Reading and writing SVG files is supported through Qt's QtSvg Module{SVG Module}.

TGA support only extends to reading non-RLE compressed files. In particular calls to capabilities for the tga plugin returns only QImageIOPlugin::CanRead, not QImageIOPlugin::CanWrite.

To configure Qt with GIF support, pass -qt-gif to the configure script or check the appropriate option in the graphical installer.

Note that the QApplication instance must be created before this function is called.

See also
setFormat(), QImageWriter::supportedImageFormats(), QImageIOPlugin

Definition at line 1530 of file qimagereader.cpp.

Referenced by imageReadMimeFormats(), QImageReaderPrivate::initHandler(), and QMovie::supportedFormats().

1531 {
1532  QSet<QByteArray> formats;
1533  for (int i = 0; i < _qt_NumFormats; ++i)
1534  formats << _qt_BuiltInFormats[i].extension;
1535 
1536 #ifndef QT_NO_LIBRARY
1537  QFactoryLoader *l = loader();
1538  QStringList keys = l->keys();
1539 
1540  for (int i = 0; i < keys.count(); ++i) {
1541  QImageIOPlugin *plugin = qobject_cast<QImageIOPlugin *>(l->instance(keys.at(i)));
1542  if (plugin && plugin->capabilities(0, keys.at(i).toLatin1()) & QImageIOPlugin::CanRead)
1543  formats << keys.at(i).toLatin1();
1544  }
1545 #endif // QT_NO_LIBRARY
1546 
1547  QList<QByteArray> sortedFormats;
1548  for (QSet<QByteArray>::ConstIterator it = formats.constBegin(); it != formats.constEnd(); ++it)
1549  sortedFormats << *it;
1550 
1551  qSort(sortedFormats);
1552  return sortedFormats;
1553 }
T qobject_cast(QObject *object)
Definition: qobject.h:375
virtual Capabilities capabilities(QIODevice *device, const QByteArray &format) const =0
Returns the capabilities on the plugin, based on the data in device and the format format...
#define it(className, varName)
const_iterator constEnd() const
Definition: qset.h:171
int count(const T &t) const
Returns the number of occurrences of value in the list.
Definition: qlist.h:891
QStringList keys
QStringList keys() const
const T & at(int i) const
Returns the item at index position i in the list.
Definition: qlist.h:468
The QStringList class provides a list of strings.
Definition: qstringlist.h:66
QByteArray toLatin1() const Q_REQUIRED_RESULT
Returns a Latin-1 representation of the string as a QByteArray.
Definition: qstring.cpp:3993
void qSort(RandomAccessIterator start, RandomAccessIterator end)
Definition: qalgorithms.h:177
The QImageIOPlugin class defines an interface for writing an image format plugin. ...
QObject * instance(const QString &key) const
QFactoryLoader * l
const_iterator constBegin() const
Definition: qset.h:168
static const _qt_BuiltInFormatStruct _qt_BuiltInFormats[]

◆ supportsAnimation()

bool QImageReader::supportsAnimation ( ) const

Returns true if the image format supports animation; otherwise, false is returned.

Since
4.1
See also
QMovie::supportedFormats()

Definition at line 1136 of file qimagereader.cpp.

1137 {
1138  if (!d->initHandler())
1139  return false;
1142  return false;
1143 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
bool toBool() const
Returns the variant as a bool if the variant has type() Bool.
Definition: qvariant.cpp:2691
QImageIOHandler * handler
virtual QVariant option(ImageOption option) const
Returns the value assigned to option as a QVariant.
virtual bool supportsOption(ImageOption option) const
Returns true if the QImageIOHandler supports the option option; otherwise returns false...

◆ supportsOption()

bool QImageReader::supportsOption ( QImageIOHandler::ImageOption  option) const

Returns true if the reader supports option; otherwise returns false.

Since
4.2

Different image formats support different options. Call this function to determine whether a certain option is supported by the current format. For example, the PNG format allows you to embed text into the image's metadata (see text()), and the BMP format allows you to determine the image's size without loading the whole image into memory (see size()).

QImageReader reader(":/image.png");
if (reader.supportsOption(QImageIOHandler::Size))
qDebug() << "Size:" << reader.size();
See also
QImageWriter::supportsOption()

Definition at line 1453 of file qimagereader.cpp.

1454 {
1455  if (!d->initHandler())
1456  return false;
1457  return d->handler->supportsOption(option);
1458 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QImageIOHandler * handler
virtual bool supportsOption(ImageOption option) const
Returns true if the QImageIOHandler supports the option option; otherwise returns false...

◆ text()

QString QImageReader::text ( const QString key) const

Returns the image text associated with key.

Since
4.1

Support for this option is implemented through QImageIOHandler::Description.

See also
textKeys(), QImageWriter::setText()

Definition at line 1007 of file qimagereader.cpp.

1008 {
1009  d->getText();
1010  return d->text.value(key);
1011 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QMap< QString, QString > text
const T value(const Key &key) const
Returns the value associated with the key key.
Definition: qmap.h:499

◆ textKeys()

QStringList QImageReader::textKeys ( ) const

Returns the text keys for this image.

Since
4.1

You can use these keys with text() to list the image text for a certain key.

Support for this option is implemented through QImageIOHandler::Description.

See also
text(), QImageWriter::setText(), QImage::textKeys()

Definition at line 988 of file qimagereader.cpp.

989 {
990  d->getText();
991  return d->text.keys();
992 }
QImageReaderPrivate * d
Definition: qimagereader.h:140
QMap< QString, QString > text
QList< Key > keys() const
Returns a list containing all the keys in the map in ascending order.
Definition: qmap.h:818

Properties

◆ d

QImageReaderPrivate* QImageReader::d
private

The documentation for this class was generated from the following files: