QImageReader Class

成员函数文档

QImageReader::QImageReader()

构造一个空的 QImageReader 对象。在读取图像之前，请调用setDevice() 或setFileName() 。

[explicit] QImageReader::QImageReader(QIODevice *device, const QByteArray &format = QByteArray())

使用设备device 和图像格式format 构造一个 QImageReader 对象。

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

使用文件名fileName 和图像格式format 构造一个 QImageReader 对象。

另请参见 setFileName().

[noexcept] QImageReader::~QImageReader()

销毁QImageReader 对象。

[static, since 6.0] int QImageReader::allocationLimit()

返回当前的分配限制（以 MB 为单位）。

此函数在 Qt 6.0 中引入。

另请参阅 setAllocationLimit()。

bool QImageReader::autoDetectImageFormat() const

如果此图像阅读器启用了图像格式自动检测，则返回true ；否则返回false 。默认情况下，自动检测已启用。

另请参阅 setAutoDetectImageFormat().

bool QImageReader::autoTransform() const

如果图像处理程序将在read() 上应用转换元数据，则返回true 。

另请参阅 setAutoTransform()、transformation() 和read()。

QColor QImageReader::backgroundColor() const

返回读取图像时使用的背景颜色。如果图像格式不支持设置背景颜色，则会返回无效颜色。

另请参阅 setBackgroundColor() 和read()。

bool QImageReader::canRead() const

如果可以读取设备的图像（即支持图像格式，且设备似乎包含有效数据），则返回true ；否则返回false 。

canRead()是一个轻量级函数，只会快速测试图像数据是否有效。read如果图像数据损坏，在 canRead() 返回true 后，() 仍可能返回 false。

对于支持动画的图像，canRead() 会在读取完所有帧后返回false 。

另请参阅 read()、supportedImageFormats() 和QMimeDatabase 。

QRect QImageReader::clipRect() const

返回图像的剪辑矩形（也称为 ROI 或感兴趣区域）。如果没有设置剪辑矩形，则返回无效的QRect 。

另请参阅 setClipRect().

int QImageReader::currentImageNumber() const

对于支持动画的图像格式，该函数返回当前帧的序列号。如果图像格式不支持动画，则返回 0。

如果出现错误，此函数将返回-1。

另请参阅 supportsAnimation()、QImageIOHandler::currentImageNumber() 和canRead()。

QRect QImageReader::currentImageRect() const

对于支持动画的图像格式，此函数返回当前帧的矩形。否则，将返回空矩形。

另请参阅 supportsAnimation() 和QImageIOHandler::currentImageRect()。

bool QImageReader::decideFormatFromContent() const

返回图像阅读器是否应仅根据数据流的内容而不是文件扩展名来决定使用哪个插件。

另请参见 setDecideFormatFromContent()。

QIODevice *QImageReader::device() const

返回当前分配给QImageReader 的设备，如果没有分配设备，则返回nullptr 。

另请参阅 setDevice()。

QImageReader::ImageReaderError QImageReader::error() const

返回最后发生的错误类型。

另请参阅 ImageReaderError 和errorString()。

QString QImageReader::errorString() const

返回对上次发生的错误的可读描述。

另请参见 error()。

QString QImageReader::fileName() const

如果当前分配的设备是QFile ，或已调用setFileName() ，则该函数返回QImageReader 读取的文件名。否则（即未分配设备或设备不是QFile ），将返回空QString 。

另请参阅 setFileName() 和setDevice()。

QByteArray QImageReader::format() const

返回QImageReader 用来读取图像的格式。

您可以在将设备分配给读取器后调用此函数，以确定设备的格式。例如

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

如果读取器无法从设备读取任何图像（例如，没有图像，或图像已被读取），或如果格式不支持，则此函数将返回空 QByteArray()。

另请参阅 setFormat() 和supportedImageFormats()。

int QImageReader::imageCount() const

对于支持动画的图像格式，该函数将返回动画中的图像总数。如果格式不支持动画，则返回 0。

如果出现错误，此函数将返回-1。

另请参阅 supportsAnimation()、QImageIOHandler::imageCount() 和canRead()。

QImage::Format QImageReader::imageFormat() const

返回图像格式，而不实际读取图像内容。格式描述的是QImageReader::read() 返回的图像格式，而不是实际图像的格式。

如果图像格式不支持此功能，此函数将返回无效格式。

另请参阅 QImageIOHandler::ImageOption,QImageIOHandler::option() 和QImageIOHandler::supportsOption()。

[static] QByteArray QImageReader::imageFormat(QIODevice *device)

如果支持，该函数将返回设备device 的图像格式。否则将返回空字符串。

另请参阅 QImageReader::autoDetectImageFormat()。

[static] QByteArray QImageReader::imageFormat(const QString &fileName)

如果支持，该函数将返回文件fileName 的图像格式。否则将返回空字符串。

[static] QList<QByteArray> QImageReader::imageFormatsForMimeType(const QByteArray &mimeType)

返回与mimeType 对应的图像格式列表。

请注意，必须在调用此函数前创建QGuiApplication 实例。

另请参阅 supportedImageFormats() 和supportedMimeTypes()。

bool QImageReader::jumpToImage(int imageNumber)

对于支持动画的图像格式，该函数会跳至序列号为imageNumber 的图像，如果成功则返回 true，如果找不到相应图像则返回 false。

下一次调用read() 时将尝试读取该图像。

另请参阅 jumpToNextImage() 和QImageIOHandler::jumpToImage()。

bool QImageReader::jumpToNextImage()

对于支持动画的图像格式，该函数会跳过当前图像，如果成功则返回 true，如果动画中没有后续图像则返回 false。

默认实现调用read() ，然后丢弃生成的图像，但图像处理程序可能有更有效的方法来实现此操作。

另请参阅 jumpToImage() 和QImageIOHandler::jumpToNextImage()。

int QImageReader::loopCount() const

对于支持动画的图像格式，此函数返回动画循环的次数。如果此函数返回 -1，则表示动画应永远循环，或者表示发生了错误。如果发生错误，canRead() 将返回 false。

另请参见 supportsAnimation()、QImageIOHandler::loopCount() 和canRead()。

int QImageReader::nextImageDelay() const

对于支持动画的图像格式，该函数将返回显示动画中下一帧之前的等待毫秒数。如果图像格式不支持动画，则返回 0。

如果出现错误，此函数将返回 -1。

另请参阅 supportsAnimation()、QImageIOHandler::nextImageDelay() 和canRead()。

int QImageReader::quality() const

返回图像格式的质量设置。

另请参阅 setQuality()。

QImage QImageReader::read()

从设备读取图像。成功时，将返回已读取的图像；否则，将返回空QImage 。然后，您可以调用error() 查找发生错误的类型，或调用errorString() 获取可读的错误描述。

对于支持动画的图像格式，反复调用 read() 将返回下一帧图像。当读取完所有帧后，将返回一个空图像。

另请参阅 canRead()、supportedImageFormats()、supportsAnimation() 和QMovie 。

bool QImageReader::read(QImage *image)

这是一个重载函数。

从设备读取图像到image ，而 必须指向QImage 。如果成功，则返回true ；否则，返回false 。

如果image 的格式和大小与即将读取的图像数据相同，则该函数在读取前可能无需分配新图像。因此，该函数比其他 read() 重载函数更快，后者总是构建一个新图像，尤其是在读取多个格式和大小相同的图像时。

QImage icon(64, 64, QImage::Format_RGB32);
QImageReader reader("icon_64x64.bmp");
if (reader.read(&icon)) {
    // Display icon
}

对于支持动画的图像格式，重复调用 read() 会返回下一帧图像。当读取完所有帧后，将返回一个空图像。

另请参阅 canRead()、supportedImageFormats()、supportsAnimation() 和QMovie 。

QRect QImageReader::scaledClipRect() const

返回图像的缩放剪切矩形。

另请参阅 setScaledClipRect()。

QSize QImageReader::scaledSize() const

返回图像的缩放尺寸。

另请参阅 setScaledSize()。

[static, since 6.0] void QImageReader::setAllocationLimit(int mbLimit)

将分配限制设置为mbLimit 兆字节。如果QImage 需要的内存分配超过此限制，则图像将被拒绝。如果mbLimit 为 0，分配大小检查将被禁用。

此限制可帮助应用程序避免因加载损坏的图像文件而意外占用大量内存。通常不需要更改。默认限制对于所有常用的图像大小都足够大。

运行时，可通过环境变量QT_IMAGEIO_MAXALLOC 来覆盖该值。

此函数在 Qt 6.0 中引入。

另请参见 allocationLimit()。

void QImageReader::setAutoDetectImageFormat(bool enabled)

如果enabled 为 true，则启用图像格式自动检测；否则禁用。默认情况下，自动检测是启用的。

QImageReader 首先，如果您向 传递一个文件名，如果给定的文件名没有指向一个现有文件，它将尝试检测文件扩展名，方法是在给定的文件名中一次添加一个受支持的默认扩展名。然后，它会使用以下方法检测图像格式：QImageReader

• 首先根据可选格式字符串或文件名后缀（如果源设备是文件）查询图像插件。QImageReader 将选择第一个支持读取该格式的插件。
• 如果没有插件支持图像格式，则会根据可选格式字符串或文件名后缀检查 Qt 内置处理程序。
• 如果找不到支持的插件或内置处理程序，则通过检查数据流的内容来测试每个插件。
• 如果没有插件能根据数据内容检测图像格式，则通过检查内容来测试每个内置图像处理器。
• 最后，如果上述所有方法都失败，QImageReader 将在尝试读取图像时报告失败。

禁用图像格式自动检测后，QImageReader 将仅根据格式字符串查询插件和内置处理程序（即不测试文件扩展名）。

另请参阅 autoDetectImageFormat()、QImageIOHandler::canRead() 和QImageIOPlugin::capabilities()。

void QImageReader::setAutoTransform(bool enabled)

如果enabled 是true ，则确定read() 返回的图像应自动应用转换元数据。

另请参阅 autoTransform()、transformation() 和read()。

void QImageReader::setBackgroundColor(const QColor &color)

将背景颜色设置为color 。支持此操作的图像格式应在读取图像前将背景初始化为color 。

另请参阅 backgroundColor() 和read()。

void QImageReader::setClipRect(const QRect &rect)

将图像剪辑矩形（也称为 ROI 或感兴趣区域）设置为rect 。rect 的坐标相对于size() 返回的未转换图像大小。

另请参阅 clipRect()、setScaledSize() 和setScaledClipRect()。

void QImageReader::setDecideFormatFromContent(bool ignored)

如果ignored 设置为 true，那么图像阅读器将忽略指定的格式或文件扩展名，仅根据数据流中的内容决定使用哪个插件。

设置该标志意味着将加载所有图像插件。每个插件都将读取图像数据的第一个字节，并决定插件是否兼容。

这也会禁止自动检测图像格式。

另请参见 decideFormatFromContent()。

void QImageReader::setDevice(QIODevice *device)

将QImageReader 的设备设置为device 。如果已经设置了设备，旧设备将从QImageReader 删除，否则保持不变。

如果设备尚未打开，QImageReader 将调用 open() 试图以ReadOnly 模式打开设备。请注意，这不适用于某些设备，如QProcess 、QTcpSocket 和QUdpSocket ，在这些设备中，打开设备需要更多逻辑。

另请参阅 device() 和setFileName()。

void QImageReader::setFileName(const QString &fileName)

将QImageReader 的文件名设置为fileName 。在内部，QImageReader 将创建一个QFile 对象，并以ReadOnly 模式打开，在读取图像时使用该对象。

如果fileName 不包含文件扩展名（如 .png 或 .bmp），QImageReader 将循环浏览所有支持的扩展名，直到找到匹配的文件。

另请参阅 fileName()、setDevice() 和supportedImageFormats()。

void QImageReader::setFormat(const QByteArray &format)

将QImageReader 读取图像时使用的格式设置为format 。format 是一个不区分大小写的文本字符串。举例说明：

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

您可以调用supportedImageFormats() 查看QImageReader 支持的全部格式列表。

另请参阅 format()。

void QImageReader::setQuality(int quality)

将图像格式的质量设置设为quality 。

某些图像格式，尤其是有损图像格式，需要在 a) 生成图像的视觉质量和 b) 解码执行时间之间进行权衡。该功能可为支持该功能的图像格式设置权衡水平。

在缩放图像读取的情况下，质量设置也会影响视觉质量和缩放算法执行速度之间的权衡。

quality 的取值范围取决于图像格式。例如，"jpeg "格式支持从 0（低视觉质量）到 100（高视觉质量）的质量范围。

另请参阅 quality() 和setScaledSize()。

void QImageReader::setScaledClipRect(const QRect &rect)

将缩放后的剪辑矩形设置为rect 。缩放后的剪辑矩形是图像缩放后应用的剪辑矩形（也称为 ROI 或感兴趣区域）。

另请参阅 scaledClipRect() 和setScaledSize()。

void QImageReader::setScaledSize(const QSize &size)

将图像的缩放尺寸设置为size 。缩放在初始剪切矩形之后，但在应用缩放的剪切矩形之前进行。缩放所使用的算法取决于图像格式。默认情况下（即如果图像格式不支持缩放），QImageReader 将使用 Qt::SmoothScaling 的 QImage::scale()。

如果在size 中只设置了一个维度，另一个维度将根据图像的natural size 计算，以保持纵横比。

另请参阅 scaledSize(),setClipRect() 和setScaledClipRect()。

QSize QImageReader::size() const

在不实际读取图像内容的情况下，返回图像的大小。

如果图像格式不支持此功能，此函数将返回无效大小。Qt 内置的图像处理器都支持此功能，但自定义图像格式插件不需要支持此功能。

另请参阅 QImageIOHandler::ImageOption 、QImageIOHandler::option() 和QImageIOHandler::supportsOption()。

QByteArray QImageReader::subType() const

返回图像的子类型。

[static] QList<QByteArray> QImageReader::supportedImageFormats()

返回QImageReader 支持的图像格式列表。

默认情况下，Qt 可读取以下格式：

模块支持读写 SVG 文件。 Qt SVG模块支持读写 SVG 文件。该 Qt Image Formats模块提供对其他图像格式的支持。

请注意，必须在调用此函数之前创建QCoreApplication 实例。

另请参阅 setFormat(),QImageWriter::supportedImageFormats() 和QImageIOPlugin 。

[static] QList<QByteArray> QImageReader::supportedMimeTypes()

返回QImageReader 支持的 MIME 类型列表。

请注意，必须在调用此函数前创建QApplication 实例。

另请参阅 supportedImageFormats() 和QImageWriter::supportedMimeTypes()。

QList<QByteArray> QImageReader::supportedSubTypes() const

返回图像支持的子类型列表。

bool QImageReader::supportsAnimation() const

如果图像格式支持动画，则返回true ；否则返回 false。

另请参阅 QMovie::supportedFormats().

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

如果阅读器支持option ，则返回true ；否则返回 false。

不同的图像格式支持不同的选项。调用此函数可确定当前格式是否支持某个选项。例如，PNG 格式允许在图像元数据中嵌入文本（请参阅text() ），BMP 格式允许在不将整幅图像载入内存的情况下确定图像大小（请参阅size() ）。

QImageReaderreader(":/image.png");if(reader.supportsOption(QImageIOHandler::Size))    qDebug() << "Size:" << reader.size();

另见 QImageWriter::supportsOption().

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

返回与key 相关联的图像文本。

对该选项的支持通过QImageIOHandler::Description 实现。

另请参阅 textKeys() 和QImageWriter::setText()。

QStringList QImageReader::textKeys() const

返回此图像的文本键。您可以使用text() 列出某个键的图像文本。

对该选项的支持通过QImageIOHandler::Description 实现。

另请参阅 text()、QImageWriter::setText() 和QImage::textKeys()。

QImageIOHandler::Transformations QImageReader::transformation() const

返回图像的变换元数据，包括图像方向。如果格式不支持变换元数据，则返回QImageIOHandler::TransformationNone 。

另请参阅 setAutoTransform() 和autoTransform()。