QImageReader Class
The QImageReader class provides a format independent interface for reading images from files or other devices. More...
| Header: | #include <QImageReader> |
| qmake: | QT += gui |
Note: All functions in this class are reentrant.
Public Types
| enum | ImageReaderError { FileNotFoundError, DeviceError, UnsupportedFormatError, InvalidDataError, UnknownError } |
Detailed Description
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.
Note: QImageReader assumes exclusive control over the file or device that is assigned. Any attempts to modify the assigned file or device during the lifetime of the QImageReader object will yield undefined results.
Formats
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. Call supportedMimeTypes() to obtain a list of supported MIME types, which for example can be passed to QFileDialog::setMimeTypeFilters().
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().
High Resolution Versions of Images
It is possible to provide high resolution versions of images should a scaling between device pixels and device independent pixels be in effect.
The high resolution version is marked by the suffix @2x on the base name. The image read will have its device pixel ratio set to a value of 2.
This can be disabled by setting the environment variable QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING.
See also QImageWriter, QImageIOHandler, QImageIOPlugin, QMimeDatabase, QColorSpace, QImage::devicePixelRatio(), QPixmap::devicePixelRatio(), QIcon, QPainter::drawPixmap(), QPainter::drawImage(), and Qt::AA_UseHighDpiPixmaps.
Member Type Documentation
enum QImageReader::ImageReaderError
This enum describes the different types of errors that can occur when reading images with QImageReader.
| Constant | Value | Description |
|---|---|---|
QImageReader::FileNotFoundError | 1 | 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. |
QImageReader::DeviceError | 2 | QImageReader encountered a device error when reading the image. You can consult your particular device for more details on what went wrong. |
QImageReader::UnsupportedFormatError | 3 | Qt does not support the requested image format. |
QImageReader::InvalidDataError | 4 | The image data was invalid, and QImageReader was unable to read an image from it. The can happen if the image file is damaged. |
QImageReader::UnknownError | 0 | An unknown error occurred. If you get this value after calling read(), it is most likely caused by a bug in QImageReader. |