Класс QImageWriter

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

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

Примечание: Все функции в этом классе являются реентерабельными.

Типы public

Public Функции

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

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

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

QImageWriter поддерживает установку параметров, специфичных для формата, таких как уровень гаммы, уровень сжатия и качество, перед сохранением изображения. Если такие параметры вам не нужны, можно использовать QImage::save() или QPixmap::save() вместо этого.

Для сохранения изображения необходимо начать с создания объекта QImageWriter. Передайте имя файла или указатель на устройство и формат изображения в конструктор QImageWriter. Затем можно задать несколько параметров, таких как уровень гаммы (вызвав setGamma()) и качество (вызвав setQuality()). canWrite() возвращает true если QImageWriter может записать изображение (т.е. формат изображения поддерживается и устройство открыто для записи). Вызовите write(), чтобы записать изображение в устройство.

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

Вызовите supportedImageFormats(), чтобы получить список форматов, которые может записывать QImageWriter. QImageWriter поддерживает все встроенные форматы изображений, а также любые плагины форматов изображений, поддерживающие запись.

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

Например:

    QString imagePath(QStringLiteral("path/image.jpeg"));
    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(Qt::red);
    {
        QImageWriter writer(imagePath);
        writer.write(image);
    }

    QFile::rename(imagePath,
                  QStringLiteral("path/other_image.jpeg"));

См. также QImageReader, QImageIOHandler и QImageIOPlugin.

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

перечисление QImageWriter::ImageWriterError

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

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

QImageWriter::QImageWriter()

Создаёт пустой объект QImageWriter. Перед записью необходимо вызвать setFormat() для установки формата изображения, а затем setDevice() или setFileName().

QImageWriter::QImageWriter(QIODevice *device, const QByteArray &format)

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

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

Создаёт объект QImageWriter, который будет записывать в файл с именем fileName, используя формат изображения format. Если format не указан, QImageWriter определит формат изображения, анализируя расширение fileName.

QImageWriter::~QImageWriter()

Деструктор объекта QImageWriter.

bool QImageWriter::canWrite() const

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

См. также write(), setDevice() и setFormat().

int QImageWriter::compression() const

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

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

QIODevice *QImageWriter::device() const

Возвращает устройство, текущее назначенное QImageWriter, или 0, если устройство не назначено.

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

QImageWriter::ImageWriterError QImageWriter::error() const

Возвращает тип ошибки, произошедшей последней.

См. также ImageWriterError и errorString().

QString QImageWriter::errorString() const

Возвращает удобочитаемое описание последней ошибки.

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

QString QImageWriter::fileName() const

Если текущее назначенное устройство — QFile, или если был вызван setFileName(), эта функция возвращает имя файла, в который QImageWriter записывает. В противном случае (т.е. если устройство не назначено или устройство не является QFile) возвращается пустая QString.

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

QByteArray QImageWriter::format() const

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

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

float QImageWriter::gamma() const

Возвращает значение гаммы изображения.

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

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

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

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

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

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

bool QImageWriter::optimizedWrite() const

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

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

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

bool QImageWriter::progressiveScanWrite() const

Возвращает, должно ли изображение записываться как прогрессивное изображение.

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

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

int QImageWriter::quality() const

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

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

void QImageWriter::setCompression(int compression)

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

Диапазон значений compression зависит от формата изображения. Например, формат "tiff" поддерживает два значения: 0 (без сжатия) и 1 (сжатие LZW).

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

void QImageWriter::setDevice(QIODevice *device)

Устанавливает устройство QImageWriter на device. Если устройство уже установлено, старое устройство удаляется из QImageWriter и иначе остается без изменений.

Если устройство ещё не открыто, QImageWriter попытается открыть устройство в режиме QIODevice::WriteOnly, вызвав open(). Обратите внимание, что это не работает для некоторых устройств, таких как QProcess, QTcpSocket и QUdpSocket, где требуется больше логики для открытия устройства.

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

void QImageWriter::setFileName(const QString &fileName)

Устанавливает имя файла QImageWriter на fileName. Внутренне QImageWriter создаст QFile и откроет его в режиме QIODevice::WriteOnly и будет использовать этот файл при записи изображений.

См. также fileName() и setDevice().

void QImageWriter::setFormat(const QByteArray &format)

Устанавливает формат QImageWriter для записи изображений на format. format — это строка текста, регистронезависимая. Пример:

QImageWriter writer;
writer.setFormat("png"); // same as writer.setFormat("PNG");

Вы можете вызвать supportedImageFormats() для получения полного списка форматов, которые поддерживает QImageWriter.

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

void QImageWriter::setGamma(float gamma)

Эта функция, специфичная для формата изображения, устанавливает значение гаммы изображения на gamma. Для форматов изображений, которые не поддерживают настройку гаммы, это значение игнорируется.

Диапазон значений gamma зависит от формата изображения. Например, формат "png" поддерживает диапазон гаммы от 0,0 до 1,0.

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

void QImageWriter::setOptimizedWrite(bool optimize)

Эта функция, специфичная для формата изображения, устанавливает флаги optimize при записи изображений. Для форматов изображений, которые не поддерживают настройку флага optimize, это значение игнорируется.

Значение по умолчанию — false.

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

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

void QImageWriter::setProgressiveScanWrite(bool progressive)

Эта функция, специфичная для формата изображения, включает прогрессивную развертку при записи изображений. Для форматов изображений, которые не поддерживают настройку флага progressive, это значение игнорируется.

Значение по умолчанию — false.

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

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

void QImageWriter::setQuality(int quality)

Устанавливает значение качества формата изображения на quality.

Некоторые форматы изображений, особенно с потерей качества, предполагают компромисс между а) визуальным качеством результирующего изображения и б) временем кодирования и уровнем сжатия. Эта функция устанавливает уровень этого компромисса для форматов изображений, которые его поддерживают. Для других форматов это значение игнорируется.

Диапазон значений quality зависит от формата изображения. Например, формат «jpeg» поддерживает диапазон качества от 0 (низкое визуальное качество, высокое сжатие) до 100 (высокое визуальное качество, низкое сжатие).

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

void QImageWriter::setSubType(const QByteArray &type)

Это функция, специфичная для формата изображения, которая устанавливает подтип изображения на type. Подтип может быть использован обработчиком для определения формата, который должен использоваться при сохранении изображения.

Например, сохранение изображения в формате DDS с подтипом A8R8G8R8:

QImageWriter writer("some/image.dds");
if (writer.supportsOption(QImageIOHandler::SubType))
    writer.setSubType("A8R8G8B8");
writer.write(image);

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

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

void QImageWriter::setText(const QString &key, const QString &text)

Устанавливает текстовую информацию изображения, связанную с ключом key, на text. Это полезно для хранения информации об авторских правах или другой информации об изображении. Пример:

QImage image("some/image.jpeg");
QImageWriter writer("images/outimage.png", "png");
writer.setText("Author", "John Smith");
writer.write(image);

Если вы хотите сохранить один блок данных (например, комментарий), вы можете передать пустой ключ или использовать универсальный ключ, например, «Описание».

Ключ и текст будут встроены в данные изображения после вызова write().

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

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

См. также QImage::setText() и QImageReader::text().

void QImageWriter::setTransformation(QImageIOHandler::Transformations transform)

Устанавливает метаданные преобразований изображения, включая ориентацию, на transform.

Если метаданные преобразования не поддерживаются форматом изображения, преобразование применяется до записи.

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

См. также transformation() и write().

QByteArray QImageWriter::subType() const

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

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

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

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

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

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

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

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

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

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

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

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

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

QList<QByteArray> QImageWriter::supportedSubTypes() const

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

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

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

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

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

QImageWriter writer(fileName);
if (writer.supportsOption(QImageIOHandler::Description))
    writer.setText("Author", "John Smith");

Параметры могут быть проверены после того, как писатель был связан с форматом.

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

См. также QImageReader::supportsOption() и setFormat().

QImageIOHandler::Transformations QImageWriter::transformation() const

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

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

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

bool QImageWriter::write(const QImage &image)

Записывает изображение image в назначенное устройство или имя файла. Возвращает true при успехе; в противном случае возвращает false. Если операция завершается неудачей, вы можете вызвать error() для определения типа произошедшей ошибки или errorString() для получения удобочитаемого описания ошибки.

См. также canWrite(), error(), и errorString().