Contents

• Public Types
• Public Functions
• Static Public Members
• Detailed Description

Detailed Description

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

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 useQImage::save() orQPixmap::save() instead.

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

If any error occurs when writing the image,write() will return false. You can then callerror() to find the type of error that occurred, orerrorString() to get a human readable description of what went wrong.

CallsupportedImageFormats() for a list of formats thatQImageWriter can write.QImageWriter supports all built-in image formats, in addition to any image format plugins that support writing.

Member Type Documentation

enum QImageWriter::ImageWriterError

This enum describes errors that can occur when writing images withQImageWriter.

Member Function Documentation

QImageWriter::QImageWriter()

Constructs an emptyQImageWriter object. Before writing, you must callsetFormat() to set an image format, thensetDevice() orsetFileName().

QImageWriter::QImageWriter(QIODevice * device, constQByteArray & format)

Constructs aQImageWriter object using the devicedevice and image formatformat.

QImageWriter::QImageWriter(constQString & fileName, constQByteArray & format = QByteArray())

Constructs aQImageWriter objects that will write to a file with the namefileName, using the image formatformat. Ifformat is not provided,QImageWriter will detect the image format by inspecting the extension offileName.

QImageWriter::~QImageWriter()

Destructs theQImageWriter object.

bool QImageWriter::canWrite() const

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

See alsowrite(),setDevice(), andsetFormat().

int QImageWriter::compression() const

Returns the compression of the image.

See alsosetCompression().

QIODevice * QImageWriter::device() const

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

See alsosetDevice().

ImageWriterError QImageWriter::error() const

Returns the type of error that last occurred.

See alsoImageWriterError anderrorString().

QString QImageWriter::errorString() const

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

See alsoerror().

QString QImageWriter::fileName() const

If the currently assigned device is aQFile, or ifsetFileName() has been called, this function returns the name of the fileQImageWriter writes to. Otherwise (i.e., if no device has been assigned or the device is not aQFile), an emptyQString is returned.

See alsosetFileName() andsetDevice().

QByteArray QImageWriter::format() const

Returns the formatQImageWriter uses for writing images.

See alsosetFormat().

float QImageWriter::gamma() const

Returns the gamma level of the image.

See alsosetGamma().

int QImageWriter::quality() const

Returns the quality level of the image.

See alsosetQuality().

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 ofcompression depends on the image format. For example, the "tiff" format supports two values, 0(no compression) and 1(LZW-compression).

See alsocompression().

void QImageWriter::setDevice(QIODevice * device)

SetsQImageWriter's device todevice. If a device has already been set, the old device is removed fromQImageWriter and is otherwise left unchanged.

If the device is not already open,QImageWriter will attempt to open the device inQIODevice::WriteOnly mode by calling open(). Note that this does not work for certain devices, such asQProcess,QTcpSocket andQUdpSocket, where more logic is required to open the device.

See alsodevice() andsetFileName().

void QImageWriter::setFileName(constQString & fileName)

Sets the file name ofQImageWriter tofileName. Internally,QImageWriter will create aQFile and open it inQIODevice::WriteOnly mode, and use this file when writing images.

See alsofileName() andsetDevice().

void QImageWriter::setFormat(constQByteArray & format)

Sets the formatQImageWriter will use when writing images, toformat.format is a case insensitive text string. Example:

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

You can callsupportedImageFormats() for the full list of formatsQImageWriter supports.

See alsoformat().

void QImageWriter::setGamma(float gamma)

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

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

See alsogamma() andquality().

void QImageWriter::setQuality(int quality)

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

The value range ofquality 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 alsoquality().

void QImageWriter::setText(constQString & key, constQString & text)

Sets the image text associated with the keykey totext. 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 callingwrite().

Support for this option is implemented throughQImageIOHandler::Description.

This function was introduced in Qt 4.1.

See alsoQImage::setText() andQImageReader::text().

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

Returns the list of image formats supported byQImageWriter.

By default, Qt can write the following formats:

Reading and writing SVG files is supported through Qt'sSVG Module.

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

See alsosetFormat(),QImageReader::supportedImageFormats(), andQImageIOPlugin.

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

Returns true if the writer supportsoption; otherwise returns false.

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.

This function was introduced in Qt 4.2.

See alsoQImageReader::supportsOption() andsetFormat().

bool QImageWriter::write(constQImage & image)

Writes the imageimage to the assigned device or file name. Returns true on success; otherwise returns false. If the operation fails, you can callerror() to find the type of error that occurred, orerrorString() to get a human readable description of the error.

See alsocanWrite(),error(), anderrorString().