QImageWriter Class Reference

The QImageWriter class provides a format independent interface for writing images to files or other devices. More...

#include <qimagewriter.h>

Public Types
enum	ImageWriterError { UnknownError, DeviceError, UnsupportedFormatError }
	This enum describes errors that can occur when writing images with QImageWriter. More...

Public Functions
bool	canWrite () const
	Returns true if QImageWriter can write the image; i.e., the image format is supported and the assigned device is open for reading. More...
int	compression () const
	Returns the compression of the image. More...
QString	description () const
	Use QImageReader::text() instead. More...
QIODevice *	device () const
	Returns the device currently assigned to QImageWriter, or 0 if no device has been assigned. More...
ImageWriterError	error () const
	Returns the type of error that last occurred. 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 QImageWriter writes to. More...
QByteArray	format () const
	Returns the format QImageWriter uses for writing images. More...
float	gamma () const
	Returns the gamma level of the image. More...
	QImageWriter ()
	Constructs an empty QImageWriter object. More...
	QImageWriter (QIODevice *device, const QByteArray &format)
	Constructs a QImageWriter object using the device device and image format format. More...
	QImageWriter (const QString &fileName, const QByteArray &format=QByteArray())
	Constructs a QImageWriter objects that will write to a file with the name fileName, using the image format format. More...
int	quality () const
	Returns the quality level of the image. More...
void	setCompression (int compression)
	This is an image format specific function that set the compression of an image. More...
void	setDescription (const QString &description)
	Use setText() instead. More...
void	setDevice (QIODevice *device)
	Sets QImageWriter's device to device. More...
void	setFileName (const QString &fileName)
	Sets the file name of QImageWriter to fileName. More...
void	setFormat (const QByteArray &format)
	Sets the format QImageWriter will use when writing images, to format. More...
void	setGamma (float gamma)
	This is an image format specific function that sets the gamma level of the image to gamma. More...
void	setQuality (int quality)
	This is an image format specific function that sets the quality level of the image to quality. More...
void	setText (const QString &key, const QString &text)
	Sets the image text associated with the key key to text. More...
bool	supportsOption (QImageIOHandler::ImageOption option) const
	Returns true if the writer supports option; otherwise returns false. More...
bool	write (const QImage &image)
	Writes the image image to the assigned device or file name. More...
	~QImageWriter ()
	Destructs the QImageWriter object. More...

Static Public Functions
static QList< QByteArray >	supportedImageFormats ()
	Returns the list of image formats supported by QImageWriter. More...

Properties
QImageWriterPrivate *	d

Detailed Description

The QImageWriter class provides a format independent interface for writing images to files or other devices.

Note

This class or function is reentrant.

QImageWriter supports setting format specific options, such as the gamma level, compression level and quality, prior to storing the image. If you do not need such options, you can use QImage::save() or QPixmap::save() instead.

To store an image, you start by constructing a QImageWriter object. Pass either a file name or a device pointer, and the image format to QImageWriter's constructor. You can then set several options, such as the gamma level (by calling setGamma()) and quality (by calling setQuality()). canWrite() returns true if QImageWriter can write the image (i.e., the image format is supported and the device is open for writing). Call write() to write the image to the device.

If any error occurs when writing the image, write() will return false. 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 QImageWriter can write. QImageWriter supports all built-in image formats, in addition to any image format plugins that support writing.

See also

QImageReader, QImageIOHandler, QImageIOPlugin

Definition at line 59 of file qimagewriter.h.

Enumerations

ImageWriterError

enum QImageWriter::ImageWriterError

This enum describes errors that can occur when writing images with QImageWriter.

• DeviceError QImageWriter encountered a device error when writing the image data. Consult your device for more details on what went wrong.

• UnsupportedFormatError Qt does not support the requested image format.

• UnknownError An unknown error occurred. If you get this value after calling write(), it is most likely caused by a bug in QImageWriter.

Enumerator
UnknownError
DeviceError
UnsupportedFormatError

Definition at line 62 of file qimagewriter.h.

                          {
        UnknownError,
        DeviceError,
        UnsupportedFormatError
    };

Constructors and Destructors

QImageWriter() [1/3]

QImageWriter::QImageWriter

(

)

Constructs an empty QImageWriter object.

Before writing, you must call setFormat() to set an image format, then setDevice() or setFileName().

Definition at line 298 of file qimagewriter.cpp.

    : d(new QImageWriterPrivate(this))
{
}

QImageWriter() [2/3]

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

explicit

Constructs a QImageWriter object using the device device and image format format.

Definition at line 307 of file qimagewriter.cpp.

    : d(new QImageWriterPrivate(this))
{
    d->device = device;
    d->format = format;
}

QImageWriter() [3/3]

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

explicit

Constructs a QImageWriter objects that will write to a file with the name fileName, using the image format format.

If format is not provided, QImageWriter will detect the image format by inspecting the extension of fileName.

Definition at line 320 of file qimagewriter.cpp.

    : d(new QImageWriterPrivate(this))
{
    QFile *file = new QFile(fileName);
    d->device = file;
    d->deleteDevice = true;
    d->format = format;
}

~QImageWriter()

QImageWriter::~QImageWriter

(

)

Destructs the QImageWriter object.

Definition at line 332 of file qimagewriter.cpp.

{
    if (d->deleteDevice)
        delete d->device;
    delete d->handler;
    delete d;
}

Functions

canWrite()

bool QImageWriter::canWrite

(

)

const

Returns true if QImageWriter can write the image; i.e., the image format is supported and the assigned device is open for reading.

See also

write(), setDevice(), setFormat()

Definition at line 578 of file qimagewriter.cpp.

Referenced by write().

{
    if (d->device && !d->handler && (d->handler = createWriteHandlerHelper(d->device, d->format)) == 0) {
        d->imageWriterError = QImageWriter::UnsupportedFormatError;
        d->errorString = QT_TRANSLATE_NOOP(QImageWriter,
                                           QLatin1String("Unsupported image format"));
        return false;
    }
    if (d->device && !d->device->isOpen())
        d->device->open(QIODevice::WriteOnly);
    if (!d->device || !d->device->isWritable()) {
        d->imageWriterError = QImageWriter::DeviceError;
        d->errorString = QT_TRANSLATE_NOOP(QImageWriter,
                                           QLatin1String("Device not writable"));
        return false;
    }
    return true;
}

compression()

int QImageWriter::compression

(

)

const

Returns the compression of the image.

See also

setCompression()

Definition at line 473 of file qimagewriter.cpp.

Referenced by setCompression().

{
    return d->compression;
}

description()

QString QImageWriter::description

(

)

const

Use QImageReader::text() instead.

Returns the description of the image.

See also

setDescription()

Definition at line 536 of file qimagewriter.cpp.

Referenced by setDescription().

{
    return d->description;
}

device()

QIODevice * QImageWriter::device

(

)

const

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

Definition at line 394 of file qimagewriter.cpp.

Referenced by QImageWriter(), and setDevice().

{
    return d->device;
}

error()

QImageWriter::ImageWriterError QImageWriter::error

(

)

const

Returns the type of error that last occurred.

See also

ImageWriterError, errorString()

Definition at line 632 of file qimagewriter.cpp.

{
    return d->imageWriterError;
}

errorString()

QString QImageWriter::errorString

(

)

const

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

See also

error()

Definition at line 642 of file qimagewriter.cpp.

{
    return d->errorString;
}

fileName()

QString QImageWriter::fileName

(

)

const

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

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 420 of file qimagewriter.cpp.

{
    QFile *file = qobject_cast<QFile *>(d->device);
    return file ? file->fileName() : QString();
}

format()

QByteArray QImageWriter::format

(

)

const

Returns the format QImageWriter uses for writing images.

See also

setFormat()

Definition at line 361 of file qimagewriter.cpp.

Referenced by QImageWriter(), and setFormat().

{
    return d->format;
}

gamma()

float QImageWriter::gamma

(

)

const

Returns the gamma level of the image.

See also

setGamma()

Definition at line 498 of file qimagewriter.cpp.

Referenced by setGamma().

{
    return d->gamma;
}

quality()

int QImageWriter::quality

(

)

const

Returns the quality level of the image.

See also

setQuality()

Definition at line 447 of file qimagewriter.cpp.

Referenced by setQuality().

{
    return d->quality;
}

setCompression()

void QImageWriter::setCompression

(

int

compression

)

This is an image format specific function that set the compression of an image.

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

The value range of compression depends on the image format. For example, the "tiff" format supports two values, 0(no compression) and 1(LZW-compression).

See also

compression()

Definition at line 463 of file qimagewriter.cpp.

{
    d->compression = compression;
}

setDescription()

void QImageWriter::setDescription

(

const QString &

description

)

Use setText() instead.

This is an image format specific function that sets the description of the image to description. For image formats that do not support setting the description, this value is ignored.

The contents of description depends on the image format.

See also

description()

Definition at line 519 of file qimagewriter.cpp.

{
    d->description = description;
}

setDevice()

void QImageWriter::setDevice

(

QIODevice *

device

)

Sets QImageWriter's device to device.

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

If the device is not already open, QImageWriter will attempt to open the device in QIODevice::WriteOnly 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 379 of file qimagewriter.cpp.

Referenced by QXlibMime::mimeConvertToFormat(), setFileName(), and QX11Data::xdndMimeConvertToFormat().

{
    if (d->device && d->deleteDevice)
        delete d->device;

    d->device = device;
    d->deleteDevice = false;
    delete d->handler;
    d->handler = 0;
}

setFileName()

void QImageWriter::setFileName

(

const QString &

fileName

)

Sets the file name of QImageWriter to fileName.

Internally, QImageWriter will create a QFile and open it in QIODevice::WriteOnly mode, and use this file when writing images.

See also

fileName(), setDevice()

Definition at line 405 of file qimagewriter.cpp.

{
    setDevice(new QFile(fileName));
    d->deleteDevice = true;
}

setFormat()

void QImageWriter::setFormat

(

const QByteArray &

format

)

Sets the format QImageWriter will use when writing images, to format.

format is a case insensitive text string. Example:

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

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

See also

format()

Definition at line 351 of file qimagewriter.cpp.

Referenced by QXlibMime::mimeConvertToFormat(), and QX11Data::xdndMimeConvertToFormat().

{
    d->format = format;
}

setGamma()

void QImageWriter::setGamma

(

float

gamma

)

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

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

The value range of gamma depends on the image format. For example, the "png" format supports a gamma range from 0.0 to 1.0.

See also

quality()

Definition at line 488 of file qimagewriter.cpp.

{
    d->gamma = gamma;
}

setQuality()

void QImageWriter::setQuality

(

int

quality

)

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

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 437 of file qimagewriter.cpp.

Referenced by QPdfEnginePrivate::addImage(), compressHelper(), QImageData::doImageIO(), and QPixmap::doImageIO().

{
    d->quality = quality;
}

setText()

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

Sets the image text associated with the key key to text.

Since

4.1

This is useful for storing copyright information or other information about the image. Example:

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

If you want to store a single block of data (e.g., a comment), you can pass an empty key, or use a generic key like "Description".

The key and text will be embedded into the image data after calling write().

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

See also

QImage::setText(), QImageReader::text()

Definition at line 565 of file qimagewriter.cpp.

{
    if (!d->description.isEmpty())
        d->description += QLatin1String("\n\n");
    d->description += key.simplified() + QLatin1String(": ") + text.simplified();
}

supportedImageFormats()

QList< QByteArray > QImageWriter::supportedImageFormats ( )

static

Returns the list of image formats supported by QImageWriter.

By default, Qt can write the following formats:

Format	Description
BMP	Windows Bitmap
JPG	Joint Photographic Experts Group
JPEG	Joint Photographic Experts Group
PNG	Portable Network Graphics
PPM	Portable Pixmap
TIFF	Tagged Image File Format
XBM	X11 Bitmap
XPM	X11 Pixmap

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

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

See also

setFormat(), QImageReader::supportedImageFormats(), QImageIOPlugin

Definition at line 704 of file qimagewriter.cpp.

Referenced by QPdfEnginePrivate::addImage(), compressHelper(), and imageWriteMimeFormats().

{
    QSet<QByteArray> formats;
    formats << "bmp";
#ifndef QT_NO_IMAGEFORMAT_PPM
    formats << "ppm";
#endif
#ifndef QT_NO_IMAGEFORMAT_XBM
    formats << "xbm";
#endif
#ifndef QT_NO_IMAGEFORMAT_XPM
    formats << "xpm";
#endif
#ifndef QT_NO_IMAGEFORMAT_PNG
    formats << "png";
#endif
#ifndef QT_NO_IMAGEFORMAT_JPEG
    formats << "jpg" << "jpeg";
#endif
#ifndef QT_NO_IMAGEFORMAT_MNG
    formats << "mng";
#endif
#ifndef QT_NO_IMAGEFORMAT_TIFF
    formats << "tif" << "tiff";
#endif
#ifdef QT_BUILTIN_GIF_READER
    formats << "gif";
#endif

#ifndef QT_NO_LIBRARY
    QFactoryLoader *l = loader();
    QStringList keys = l->keys();
    for (int i = 0; i < keys.count(); ++i) {
        QImageIOPlugin *plugin = qobject_cast<QImageIOPlugin *>(l->instance(keys.at(i)));
        if (plugin && (plugin->capabilities(0, keys.at(i).toLatin1()) & QImageIOPlugin::CanWrite) != 0)
            formats << keys.at(i).toLatin1();
    }
#endif // QT_NO_LIBRARY

    QList<QByteArray> sortedFormats;
    for (QSet<QByteArray>::ConstIterator it = formats.constBegin(); it != formats.constEnd(); ++it)
        sortedFormats << *it;

    qSort(sortedFormats);
    return sortedFormats;
}

supportsOption()

bool QImageWriter::supportsOption

(

QImageIOHandler::ImageOption

option

)

const

Returns true if the writer 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()).

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

Options can be tested after the writer has been associated with a format.

See also

QImageReader::supportsOption(), setFormat()

Definition at line 667 of file qimagewriter.cpp.

{
    if (!d->handler && (d->handler = createWriteHandlerHelper(d->device, d->format)) == 0) {
        d->imageWriterError = QImageWriter::UnsupportedFormatError;
        d->errorString = QT_TRANSLATE_NOOP(QImageWriter,
                                           QLatin1String("Unsupported image format"));
        return false;
    }

    return d->handler->supportsOption(option);
}

write()

bool QImageWriter::write

(

const QImage &

image

)

Writes the image image to the assigned device or file name.

Returns true on success; otherwise returns false. If the operation fails, you can call error() to find the type of error that occurred, or errorString() to get a human readable description of the error.

See also

canWrite(), error(), errorString()

Definition at line 606 of file qimagewriter.cpp.

Referenced by QPdfEnginePrivate::addImage(), compressHelper(), QImageData::doImageIO(), QPixmap::doImageIO(), QXlibMime::mimeConvertToFormat(), operator<<(), QSystemTrayIconPrivate::showMessage_sys(), QTextOdfWriter::writeInlineCharacter(), and QX11Data::xdndMimeConvertToFormat().

{
    if (!canWrite())
        return false;

    if (d->handler->supportsOption(QImageIOHandler::Quality))
        d->handler->setOption(QImageIOHandler::Quality, d->quality);
    if (d->handler->supportsOption(QImageIOHandler::CompressionRatio))
        d->handler->setOption(QImageIOHandler::CompressionRatio, d->compression);
    if (d->handler->supportsOption(QImageIOHandler::Gamma))
        d->handler->setOption(QImageIOHandler::Gamma, d->gamma);
    if (!d->description.isEmpty() && d->handler->supportsOption(QImageIOHandler::Description))
        d->handler->setOption(QImageIOHandler::Description, d->description);

    if (!d->handler->write(image))
        return false;
    if (QFile *file = qobject_cast<QFile *>(d->device))
        file->flush();
    return true;
}

Properties

d

QImageWriterPrivate* QImageWriter::d

private

Definition at line 109 of file qimagewriter.h.

Referenced by canWrite(), compression(), description(), device(), error(), errorString(), fileName(), format(), gamma(), QImageWriter(), quality(), setCompression(), setDescription(), setDevice(), setFileName(), setFormat(), setGamma(), setQuality(), setText(), supportsOption(), write(), and ~QImageWriter().

---

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

• /src/gui/image/qimagewriter.h
• /src/gui/image/qimagewriter.cpp