diff options
Diffstat (limited to 'src/gui/image/qimageiohandler.cpp')
| -rw-r--r-- | src/gui/image/qimageiohandler.cpp | 570 |
1 files changed, 570 insertions, 0 deletions
diff --git a/src/gui/image/qimageiohandler.cpp b/src/gui/image/qimageiohandler.cpp new file mode 100644 index 0000000000..da1d236998 --- /dev/null +++ b/src/gui/image/qimageiohandler.cpp @@ -0,0 +1,570 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtGui module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QImageIOHandler + \brief The QImageIOHandler class defines the common image I/O + interface for all image formats in Qt. + \reentrant + + Qt uses QImageIOHandler for reading and writing images through + QImageReader and QImageWriter. You can also derive from this class + to write your own image format handler using Qt's plugin mechanism. + + Call setDevice() to assign a device to the handler, and + setFormat() to assign a format to it. One QImageIOHandler may + support more than one image format. canRead() returns true if an + image can be read from the device, and read() and write() return + true if reading or writing an image was completed successfully. + + QImageIOHandler also has support for animations formats, through + the functions loopCount(), imageCount(), nextImageDelay() and + currentImageNumber(). + + In order to determine what options an image handler supports, Qt + will call supportsOption() and setOption(). Make sure to + reimplement these functions if you can provide support for any of + the options in the ImageOption enum. + + To write your own image handler, you must at least reimplement + canRead() and read(). Then create a QImageIOPlugin that + can create the handler. Finally, install your plugin, and + QImageReader and QImageWriter will then automatically load the + plugin, and start using it. + + \sa QImageIOPlugin, QImageReader, QImageWriter +*/ + +/*! \enum QImageIOHandler::ImageOption + + This enum describes the different options supported by + QImageIOHandler. Some options are used to query an image for + properties, and others are used to toggle the way in which an + image should be written. + + \value Size The original size of an image. A handler that supports + this option is expected to read the size of the image from the + image metadata, and return this size from option() as a QSize. + + \value ClipRect The clip rect, or ROI (Region Of Interest). A + handler that supports this option is expected to only read the + provided QRect area from the original image in read(), before any + other transformation is applied. + + \value ScaledSize The scaled size of the image. A handler that + supports this option is expected to scale the image to the + provided size (a QSize), after applying any clip rect + transformation (ClipRect). If the handler does not support this + option, QImageReader will perform the scaling after the image has + been read. + + \value ScaledClipRect The scaled clip rect (or ROI, Region Of + Interest) of the image. A handler that supports this option is + expected to apply the provided clip rect (a QRect), after applying + any scaling (ScaleSize) or regular clipping (ClipRect). If the + handler does not support this option, QImageReader will apply the + scaled clip rect after the image has been read. + + \value Description The image description. Some image formats, + such as GIF and PNG, allow embedding of text + or comments into the image data (e.g., for storing copyright + information). It's common that the text is stored in key-value + pairs, but some formats store all text in one continuous block. + QImageIOHandler returns the text as one + QString, where keys and values are separated by a ':', and + keys-value pairs are separated by two newlines (\\n\\n). For example, + "Title: Sunset\\n\\nAuthor: Jim Smith\\nSarah Jones\\n\\n". Formats that + store text in a single block can use "Description" as the key. + + \value CompressionRatio The compression ratio of the image data. A + handler that supports this option is expected to set its + compression rate depending on the value of this option (an int) + when writing. + + \value Gamma The gamma level of the image. A handler that supports + this option is expected to set the image gamma level depending on + the value of this option (a float) when writing. + + \value Quality The quality level of the image. A handler that + supports this option is expected to set the image quality level + depending on the value of this option (an int) when writing. + + \value Name The name of the image. A handler that supports this + option is expected to read the name from the image metadata and + return this as a QString, or when writing an image it is expected + to store the name in the image metadata. + + \value SubType The subtype of the image. A handler that supports + this option can use the subtype value to help when reading and + writing images. For example, a PPM handler may have a subtype + value of "ppm" or "ppmraw". + + \value IncrementalReading A handler that supports this option is + expected to read the image in several passes, as if it was an + animation. QImageReader will treat the image as an animation. + + \value Endianness The endianness of the image. Certain image + formats can be stored as BigEndian or LittleEndian. A handler that + supports Endianness uses the value of this option to determine how + the image should be stored. + + \value Animation Image formats that support animation return + true for this value in supportsOption(); otherwise, false is returned. + + \value BackgroundColor Certain image formats allow the + background color to be specified. A handler that supports + BackgroundColor initializes the background color to this option + (a QColor) when reading an image. + + \value ImageFormat The image's data format returned by the handler. + This can be any of the formats listed in QImage::Format. +*/ + +/*! + \class QImageIOPlugin + \brief The QImageIOPlugin class defines an interface for writing + an image format plugin. + \reentrant + + \ingroup plugins + + QImageIOPlugin is a factory for creating QImageIOHandler objects, + which are used internally by QImageReader and QImageWriter to add + support for different image formats to Qt. + + Writing an image I/O plugin is achieved by subclassing this + base class, reimplementing the pure virtual functions capabilities(), + create(), and keys(), and exporting the class with the + Q_EXPORT_PLUGIN2() macro. See \l{How to Create Qt Plugins} for details. + + An image format plugin can support three capabilities: reading (\l + CanRead), writing (\l CanWrite) and \e incremental reading (\l + CanReadIncremental). Reimplement capabilities() in you subclass to + expose the capabilities of your image format. + + create() should create an instance of your QImageIOHandler + subclass, with the provided device and format properly set, and + return this handler. You must also reimplement keys() so that Qt + knows which image formats your plugin supports. + + Different plugins can support different capabilities. For example, + you may have one plugin that supports reading the GIF format, and + another that supports writing. Qt will select the correct plugin + for the job, depending on the return value of capabilities(). If + several plugins support the same capability, Qt will select one + arbitrarily. + + \sa QImageIOHandler, {How to Create Qt Plugins} +*/ + +/*! + \enum QImageIOPlugin::Capability + + This enum describes the capabilities of a QImageIOPlugin. + + \value CanRead The plugin can read images. + \value CanWrite The plugin can write images. + \value CanReadIncremental The plugin can read images incrementally. +*/ + +/*! + \class QImageIOHandlerFactoryInterface + \brief The QImageIOHandlerFactoryInterface class provides the factory + interface for QImageIOPlugin. + \reentrant + + \internal + + \sa QImageIOPlugin +*/ + +#include "qimageiohandler.h" + +#include <qbytearray.h> +#include <qimage.h> +#include <qvariant.h> + +QT_BEGIN_NAMESPACE + +class QIODevice; + +class QImageIOHandlerPrivate +{ + Q_DECLARE_PUBLIC(QImageIOHandler) +public: + QImageIOHandlerPrivate(QImageIOHandler *q); + virtual ~QImageIOHandlerPrivate(); + + QIODevice *device; + mutable QByteArray format; + + QImageIOHandler *q_ptr; +}; + +QImageIOHandlerPrivate::QImageIOHandlerPrivate(QImageIOHandler *q) +{ + device = 0; + q_ptr = q; +} + +QImageIOHandlerPrivate::~QImageIOHandlerPrivate() +{ +} + +/*! + Constructs a QImageIOHandler object. +*/ +QImageIOHandler::QImageIOHandler() + : d_ptr(new QImageIOHandlerPrivate(this)) +{ +} + +/*! \internal + + Constructs a QImageIOHandler object, using the private member \a + dd. +*/ +QImageIOHandler::QImageIOHandler(QImageIOHandlerPrivate &dd) + : d_ptr(&dd) +{ +} + +/*! + Destructs the QImageIOHandler object. +*/ +QImageIOHandler::~QImageIOHandler() +{ +} + +/*! + Sets the device of the QImageIOHandler to \a device. The image + handler will use this device when reading and writing images. + + The device can only be set once and must be set before calling + canRead(), read(), write(), etc. If you need to read multiple + files, construct multiple instances of the appropriate + QImageIOHandler subclass. + + \sa device() +*/ +void QImageIOHandler::setDevice(QIODevice *device) +{ + Q_D(QImageIOHandler); + d->device = device; +} + +/*! + Returns the device currently assigned to the QImageIOHandler. If + not device has been assigned, 0 is returned. +*/ +QIODevice *QImageIOHandler::device() const +{ + Q_D(const QImageIOHandler); + return d->device; +} + +/*! + Sets the format of the QImageIOHandler to \a format. The format is + most useful for handlers that support multiple image formats. + + \sa format() +*/ +void QImageIOHandler::setFormat(const QByteArray &format) +{ + Q_D(QImageIOHandler); + d->format = format; +} + +/*! + Sets the format of the QImageIOHandler to \a format. The format is + most useful for handlers that support multiple image formats. + + This function is declared const so that it can be called from canRead(). + + \sa format() +*/ +void QImageIOHandler::setFormat(const QByteArray &format) const +{ + Q_D(const QImageIOHandler); + d->format = format; +} + +/*! + Returns the format that is currently assigned to + QImageIOHandler. If no format has been assigned, an empty string + is returned. + + \sa setFormat() +*/ +QByteArray QImageIOHandler::format() const +{ + Q_D(const QImageIOHandler); + return d->format; +} + +/*! + \fn bool QImageIOHandler::read(QImage *image) + + Read an image from the device, and stores it in \a image. + Returns true if the image is successfully read; otherwise returns + false. + + For image formats that support incremental loading, and for animation + formats, the image handler can assume that \a image points to the + previous frame. + + \sa canRead() +*/ + +/*! + \fn bool QImageIOHandler::canRead() const + + Returns true if an image can be read from the device (i.e., the + image format is supported, the device can be read from and the + initial header information suggests that the image can be read); + otherwise returns false. + + When reimplementing canRead(), make sure that the I/O device + (device()) is left in its original state (e.g., by using peek() + rather than read()). + + \sa read(), QIODevice::peek() +*/ + +/*! + \obsolete + + Use format() instead. +*/ + +QByteArray QImageIOHandler::name() const +{ + return format(); +} + +/*! + Writes the image \a image to the assigned device. Returns true on + success; otherwise returns false. + + The default implementation does nothing, and simply returns false. +*/ +bool QImageIOHandler::write(const QImage &image) +{ + Q_UNUSED(image); + return false; +} + +/*! + Sets the option \a option with the value \a value. + + \sa option(), ImageOption +*/ +void QImageIOHandler::setOption(ImageOption option, const QVariant &value) +{ + Q_UNUSED(option); + Q_UNUSED(value); +} + +/*! + Returns the value assigned to \a option as a QVariant. The type of + the value depends on the option. For example, option(Size) returns + a QSize variant. + + \sa setOption(), supportsOption() +*/ +QVariant QImageIOHandler::option(ImageOption option) const +{ + Q_UNUSED(option); + return QVariant(); +} + +/*! + Returns true if the QImageIOHandler supports the option \a option; + otherwise returns false. For example, if the QImageIOHandler + supports the \l Size option, supportsOption(Size) must return + true. + + \sa setOption(), option() +*/ +bool QImageIOHandler::supportsOption(ImageOption option) const +{ + Q_UNUSED(option); + return false; +} + +/*! + For image formats that support animation, this function returns + the sequence number of the current image in the animation. If + this function is called before any image is read(), -1 is + returned. The number of the first image in the sequence is 0. + + If the image format does not support animation, 0 is returned. + + \sa read() +*/ +int QImageIOHandler::currentImageNumber() const +{ + return 0; +} + +/*! + Returns the rect of the current image. If no rect is defined for the + image, and empty QRect() is returned. + + This function is useful for animations, where only parts of the frame + may be updated at a time. +*/ +QRect QImageIOHandler::currentImageRect() const +{ + return QRect(); +} + +/*! + For image formats that support animation, this function returns + the number of images in the animation. If the image format does + not support animation, or if it is unable to determine the number + of images, 0 is returned. + + The default implementation returns 1 if canRead() returns true; + otherwise 0 is returned. +*/ +int QImageIOHandler::imageCount() const +{ + return canRead() ? 1 : 0; +} + +/*! + For image formats that support animation, this function jumps to the + next image. + + The default implementation does nothing, and returns false. +*/ +bool QImageIOHandler::jumpToNextImage() +{ + return false; +} + +/*! + For image formats that support animation, this function jumps to the image + whose sequence number is \a imageNumber. The next call to read() will + attempt to read this image. + + The default implementation does nothing, and returns false. +*/ +bool QImageIOHandler::jumpToImage(int imageNumber) +{ + Q_UNUSED(imageNumber); + return false; +} + +/*! + For image formats that support animation, this function returns + the number of times the animation should loop. If the image format + does not support animation, 0 is returned. +*/ +int QImageIOHandler::loopCount() const +{ + return 0; +} + +/*! + For image formats that support animation, this function returns + the number of milliseconds to wait until reading the next + image. If the image format does not support animation, 0 is + returned. +*/ +int QImageIOHandler::nextImageDelay() const +{ + return 0; +} + +/*! + Constructs an image plugin with the given \a parent. This is + invoked automatically by the Q_EXPORT_PLUGIN2() macro. +*/ +QImageIOPlugin::QImageIOPlugin(QObject *parent) + : QObject(parent) +{ +} + +/*! + Destroys the picture format plugin. + + You never have to call this explicitly. Qt destroys a plugin + automatically when it is no longer used. +*/ +QImageIOPlugin::~QImageIOPlugin() +{ +} + +/*! \fn QImageIOPlugin::capabilities(QIODevice *device, const QByteArray &format) const + + Returns the capabilities on the plugin, based on the data in \a + device and the format \a format. For example, if the + QImageIOHandler supports the BMP format, and the data in the + device starts with the characters "BM", this function should + return \l CanRead. If \a format is "bmp" and the handler supports + both reading and writing, this function should return \l CanRead | + \l CanWrite. +*/ + +/*! + \fn QImageIOPlugin::keys() const + + Returns the list of image keys this plugin supports. + + These keys are usually the names of the image formats that are implemented + in the plugin (e.g., "jpg" or "gif"). + + \sa capabilities() +*/ + +/*! + \fn QImageIOHandler *QImageIOPlugin::create(QIODevice *device, const QByteArray &format) const + + Creates and returns a QImageIOHandler subclass, with \a device + and \a format set. The \a format must come from the list returned by keys(). + Format names are case sensitive. + + \sa keys() +*/ + +QT_END_NAMESPACE |