Класс QImageReader

Класс QImageReader предоставляет формат-независимый интерфейс для чтения изображений из файлов или других устройств. Подробнее...

• Список всех членов, включая наследуемые
• Устаревшие члены

Примечание: Все функции в этом классе являются повторно входящими.

Типы public

Функции public

Статические public члены

Подробное описание

Наиболее распространённый способ чтения изображений — через конструкторы QImage и QPixmap, или вызов QImage::load() и QPixmap::load(). QImageReader — специализированный класс, предоставляющий больший контроль при чтении изображений. Например, можно прочитать изображение в заданный размер, вызвав setScaledSize(), и выбрать область обрезки, загрузив только части изображения, вызвав setClipRect(). В зависимости от поддержки формата изображения это может сэкономить память и ускорить загрузку.

Чтобы прочитать изображение, начните с создания объекта QImageReader. Передайте имя файла или указатель на устройство и формат изображения в конструктор QImageReader. Затем можно задать различные параметры, такие как область обрезки (вызвав setClipRect()) и размер масштабирования (вызвав setScaledSize()). canRead() возвращает изображение, если QImageReader может его прочитать (т.е. формат изображения поддерживается, и устройство открыто для чтения). Вызовите read(), чтобы прочитать изображение.

Если при чтении изображения произойдёт ошибка, read() вернёт нулевое QImage. Затем можно вызвать error(), чтобы определить тип ошибки, или errorString(), чтобы получить удобочитаемое описание произошедшей ошибки.

Примечание: QImageReader предполагает эксклюзивный контроль над файлом или устройством, которое ему назначено. Любые попытки изменить назначенный файл или устройство во время существования объекта QImageReader приведут к неопределённым результатам.

Форматы

Вызовите supportedImageFormats(), чтобы получить список форматов, которые QImageReader может читать. QImageReader поддерживает все встроенные форматы изображений, а также любые плагины форматов изображений, которые поддерживают чтение. Вызовите supportedMimeTypes(), чтобы получить список поддерживаемых MIME-типов, которые, например, можно передать в QFileDialog::setMimeTypeFilters().

QImageReader по умолчанию автоматически определяет формат изображения, анализируя предоставленную (необязательную) строку формата, суффикс имени файла и содержимое потока данных. Вы можете включить или отключить эту функцию, вызвав setAutoDetectImageFormat().

Высококачественные версии изображений

Можно предоставить высококачественные версии изображений, если существует масштабирование между пикселями устройства и пикселями, независимыми от устройства.

Высококачественная версия отмечена суффиксом @2x в базовом имени. Прочитанное изображение будет иметь свой коэффициент пикселей устройства, установленный в значение 2.

Это можно отключить, установив переменную окружения QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING.

См. также QImageWriter, QImageIOHandler, QImageIOPlugin, QMimeDatabase, QColorSpace, QImage::devicePixelRatio(), QPixmap::devicePixelRatio(), QIcon, QPainter::drawPixmap(), QPainter::drawImage(), и Qt::AA_UseHighDpiPixmaps.

Документация по типам членов

перечисление QImageReader::ImageReaderError

Это перечисление описывает различные типы ошибок, которые могут возникнуть при чтении изображений с помощью QImageReader.

Документация по функциям-членам

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

Создаёт объект QImageReader с именем файла fileName и форматом изображения format.

См. также setFileName().

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

Создаёт объект QImageReader с устройством device и форматом изображения format.

QImageReader::QImageReader()

Создаёт пустой объект QImageReader. Перед чтением изображения вызовите setDevice() или setFileName().

QImageReader::~QImageReader()

Удаляет объект QImageReader.

bool QImageReader::autoDetectImageFormat() const

Возвращает true, если автоматическое определение формата изображения включено для данного объекта; в противном случае возвращает false. По умолчанию автоматическое определение включено.

См. также setAutoDetectImageFormat().

bool QImageReader::autoTransform() const

Возвращает true, если обработчик изображения применит метаданные преобразования при вызове read().

Эта функция была введена в Qt 5.5.

См. также setAutoTransform(), transformation() и read().

QColor QImageReader::backgroundColor() const

Возвращает цвет фона, используемый при чтении изображения. Если формат изображения не поддерживает установку цвета фона, возвращается недействительный цвет.

Эта функция была введена в Qt 4.1.

См. также setBackgroundColor() и read().

bool QImageReader::canRead() const

Возвращает true, если изображение может быть прочитано с устройства (т.е. формат изображения поддерживается, и устройство содержит валидные данные); в противном случае возвращает false.

canRead() — это лёгкая функция, которая выполняет только быструю проверку, чтобы определить, являются ли данные изображения валидными. read() может всё ещё вернуть false после того, как canRead() вернула true, если данные изображения повреждены.

Примечание: Обращение к QMimeDatabase обычно является лучшим подходом для идентификации потенциально не являющихся изображениями файлов или данных.

Для изображений, которые поддерживают анимацию, 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(), а не формат фактического изображения.

Если формат изображения не поддерживает эту функцию, эта функция возвращает недопустимый формат.

Эта функция была добавлена в Qt 4.5.

См. также QImageIOHandler::ImageOption, QImageIOHandler::option() и QImageIOHandler::supportsOption().

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

Если поддерживается, эта функция возвращает формат изображения файла fileName. В противном случае возвращается пустая строка.

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

Если поддерживается, эта функция возвращает формат изображения устройства device. В противном случае возвращается пустая строка.

См. также QImageReader::autoDetectImageFormat().

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

Возвращает список форматов изображений, соответствующих mimeType.

Обратите внимание, что экземпляр QGuiApplication должен быть создан перед вызовом этой функции.

Эта функция была добавлена в Qt 5.12.

См. также 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

Возвращает значение качества формата изображения.

Эта функция была добавлена в Qt 4.2.

См. также 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().

void QImageReader::setAutoDetectImageFormat(bool enabled)

Если enabled равно true, включена автоматическая детекция формата изображения; в противном случае — выключена. По умолчанию автоматическая детекция включена.

QImageReader использует расширенный подход к определению формата изображения; во-первых, если вы передаёте имя файла в QImageReader, он попытается определить расширение файла, если переданное имя файла не указывает на существующий файл, добавляя поддерживаемые расширения по умолчанию к переданному имени файла по одному.

• Плагины изображений запрошиваются в первую очередь, основываясь на необязательной строке формата или суффиксе имени файла (если устройство источника — файл). На этом этапе распознавание содержимого не выполняется. QImageReader выберет первый плагин, поддерживающий чтение для этого формата.
• Если ни один плагин не поддерживает формат изображения, проверяются встроенные обработчики Qt, основываясь на необязательной строке формата или суффиксе имени файла.
• Если не найдены ни подходящие плагины, ни встроенные обработчики, каждый плагин тестируется путем проверки содержимого потока данных.
• Если ни один плагин не смог определить формат изображения на основе содержимого данных, тестируются каждый встроенный обработчик изображений, проверяя содержимое.
• Наконец, если все вышеперечисленные подходы не увенчались успехом, QImageReader сообщит об ошибке при попытке чтения изображения.

Отключив автоматическое определение формата изображения, QImageReader будет запросывать только плагины и встроенные обработчики, основываясь на строке формата (т.е. расширения имен файлов не проверяются).

См. также autoDetectImageFormat(), QImageIOHandler::canRead() и QImageIOPlugin::capabilities().

void QImageReader::setAutoTransform(bool enabled)

Определяет, что изображения, возвращаемые функцией read(), должны иметь метаданные преобразования, автоматически применяемые, если enabled равно true.

Эта функция была добавлена в Qt 5.5.

См. также autoTransform(), transformation() и read().

void QImageReader::setBackgroundColor(const QColor &color)

Устанавливает цвет фона на color. Ожидается, что форматы изображений, поддерживающие эту операцию, инициализируют фон значением color перед чтением изображения.

Эта функция была добавлена в Qt 4.1.

См. также 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 попытается открыть устройство в режиме QIODevice::ReadOnly с помощью вызова open(). Обратите внимание, что это не работает для определенных устройств, таких как QProcess, QTcpSocket и QUdpSocket, где для открытия устройства требуется больше логики.

См. также device() и setFileName().

void QImageReader::setFileName(const QString &fileName)

Устанавливает имя файла QImageReader на fileName. Внутренне QImageReader создаст объект QFile и откроет его в режиме QIODevice::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 (высокое визуальное качество).

Эта функция была добавлена в Qt 4.2.

См. также quality() и setScaledSize().

void QImageReader::setScaledClipRect(const QRect &rect)

Устанавливает область масштабированной обрезки на rect. Область масштабированной обрезки — это область обрезки (также известная как ROI, или область интереса), которая применяется после масштабирования изображения.

См. также scaledClipRect() и setScaledSize().

void QImageReader::setScaledSize(const QSize &size)

Устанавливает размер изображения после масштабирования на size. Масштабирование выполняется после начальной области обрезки, но перед применением области масштабированной обрезки. Алгоритм, используемый для масштабирования, зависит от формата изображения. По умолчанию (т.е. если формат изображения не поддерживает масштабирование), QImageReader будет использовать QImage::scale() с Qt::SmoothScaling.

См. также scaledSize(), setClipRect() и setScaledClipRect().

QSize QImageReader::size() const

Возвращает размер изображения без фактического чтения содержимого изображения.

Если формат изображения не поддерживает эту функцию, эта функция возвращает недействительный размер. Встроенные обработчики изображений Qt поддерживают эту функцию, но пользовательские плагины форматов изображений не обязаны это делать.

См. также QImageIOHandler::ImageOption, QImageIOHandler::option() и QImageIOHandler::supportsOption().

QByteArray QImageReader::subType() const

Возвращает подтип изображения.

Эта функция была добавлена в Qt 5.4.

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

Возвращает список форматов изображений, поддерживаемых QImageReader.

По умолчанию Qt может читать следующие форматы:

Чтение и запись файлов SVG поддерживаются модулем Qt SVG. Модуль Qt Image Formats предоставляет поддержку дополнительных форматов изображений.

Обратите внимание, что экземпляр QApplication должен быть создан до вызова этой функции.

См. также setFormat(), QImageWriter::supportedImageFormats() и QImageIOPlugin.

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

Возвращает список MIME-типов, поддерживаемых QImageReader.

Обратите внимание, что экземпляр QApplication должен быть создан до вызова этой функции.

См. также supportedImageFormats() и QImageWriter::supportedMimeTypes().

QList<QByteArray> QImageReader::supportedSubTypes() const

Возвращает список поддерживаемых подтипов изображения.

Эта функция была добавлена в Qt 5.4.

bool QImageReader::supportsAnimation() const

Возвращает true если формат изображения поддерживает анимацию; в противном случае возвращает false.

Эта функция была добавлена в Qt 4.1.

См. также QMovie::supportedFormats().

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

Возвращает true если чтение поддерживает option; в противном случае возвращает false.

Разные форматы изображений поддерживают разные опции. Используйте эту функцию, чтобы определить, поддерживает ли текущий формат определённую опцию. Например, формат PNG позволяет встраивать текст в метаданные изображения (см. text()), а формат BMP позволяет определить размер изображения, не загружая всё изображение в память (см. size()).

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

Эта функция была добавлена в Qt 4.2.

См. также QImageWriter::supportsOption().

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

Возвращает текст изображения, связанный с key.

Поддержка этой опции реализована через QImageIOHandler::Description.

Эта функция была добавлена в Qt 4.1.

См. также textKeys() и QImageWriter::setText().

QStringList QImageReader::textKeys() const

Возвращает ключи текста для этого изображения. Вы можете использовать эти ключи с text() для отображения текста изображения для определённого ключа.

Поддержка этой опции реализована через QImageIOHandler::Description.

Эта функция была добавлена в Qt 4.1.

См. также text(), QImageWriter::setText(), и QImage::textKeys().

QImageIOHandler::Transformations QImageReader::transformation() const

Возвращает метаданные преобразования изображения, включая ориентацию изображения. Если формат не поддерживает метаданные преобразования, возвращается QImageIOHandler::TransformationNone.

Эта функция была добавлена в Qt 5.5.

См. также setAutoTransform() и autoTransform().