Qt 4.2 User's Guide: src/gui/image/qimage.h Source File

00001 /****************************************************************************
00002 **
00003 ** Copyright (C) 1992-2006 Trolltech ASA. All rights reserved.
00004 **
00005 ** This file is part of the QtGui module of the Qt Toolkit.
00006 **
00007 ** This file may be used under the terms of the GNU General Public
00008 ** License version 2.0 as published by the Free Software Foundation
00009 ** and appearing in the file LICENSE.GPL included in the packaging of
00010 ** this file.  Please review the following information to ensure GNU
00011 ** General Public Licensing requirements will be met:
00012 ** http://www.trolltech.com/products/qt/opensource.html
00013 **
00014 ** If you are unsure which license is appropriate for your use, please
00015 ** review the following information:
00016 ** http://www.trolltech.com/products/qt/licensing.html or contact the
00017 ** sales department at sales@trolltech.com.
00018 **
00019 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
00020 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
00021 **
00022 ****************************************************************************/
00023 
00024 #ifndef QIMAGE_H
00025 #define QIMAGE_H
00026 
00027 #include <QtGui/qpaintdevice.h>
00028 #include <QtGui/qrgb.h>
00029 #include <QtCore/qbytearray.h>
00030 #include <QtCore/qrect.h>
00031 #include <QtCore/qstring.h>
00032 
00033 QT_BEGIN_HEADER
00034 
00035 QT_MODULE(Gui)
00036 
00037 class QIODevice;
00038 class QStringList;
00039 class QMatrix;
00040 class QVariant;
00041 template <class T> class QList;
00042 template <class T> class QVector;
00043 
00044 struct QImageData;
00045 class QImageDataMisc; // internal
00046 #ifndef QT_NO_IMAGE_TEXT
00047 class Q_GUI_EXPORT QImageTextKeyLang {
00048 public:
00049     QImageTextKeyLang(const char* k, const char* l) : key(k), lang(l) { }
00050     QImageTextKeyLang() { }
00051 
00052     QByteArray key;
00053     QByteArray lang;
00054 
00055     bool operator< (const QImageTextKeyLang& other) const
00056         { return key < other.key || key==other.key && lang < other.lang; }
00057     bool operator== (const QImageTextKeyLang& other) const
00058         { return key==other.key && lang==other.lang; }
00059     inline bool operator!= (const QImageTextKeyLang &other) const
00060         { return !operator==(other); }
00061 };
00062 #endif //QT_NO_IMAGE_TEXT
00063 
00064 
00065 class Q_GUI_EXPORT QImage : public QPaintDevice
00066 {
00067 public:
00068     enum InvertMode { InvertRgb, InvertRgba };
00069     enum Format {
00070         Format_Invalid,
00071         Format_Mono,
00072         Format_MonoLSB,
00073         Format_Indexed8,
00074         Format_RGB32,
00075         Format_ARGB32,
00076         Format_ARGB32_Premultiplied,
00077         Format_RGB16,
00078 #if 0
00079         // reserved for future use
00080         Format_RGB15,
00081         Format_Grayscale16,
00082         Format_Grayscale8,
00083         Format_Grayscale4,
00084         Format_Grayscale4LSB,
00085         Format_Grayscale2,
00086         Format_Grayscale2LSB
00087 #endif
00088 #ifndef qdoc
00089         NImageFormats
00090 #endif
00091     };
00092 
00093     QImage();
00094     QImage(const QSize &size, Format format);
00095     QImage(int width, int height, Format format);
00096     QImage(uchar *data, int width, int height, Format format);
00097     QImage(const uchar *data, int width, int height, Format format);
00098 
00099 #ifndef QT_NO_IMAGEFORMAT_XPM
00100     explicit QImage(const char * const xpm[]);
00101 #endif
00102     explicit QImage(const QString &fileName, const char *format = 0);
00103 #ifndef QT_NO_CAST_FROM_ASCII
00104     explicit QImage(const char *fileName, const char *format = 0);
00105 #endif
00106 
00107     QImage(const QImage &);
00108     ~QImage();
00109 
00110     QImage &operator=(const QImage &);
00111     bool isNull() const;
00112 
00113     int devType() const;
00114 
00115     bool operator==(const QImage &) const;
00116     bool operator!=(const QImage &) const;
00117     operator QVariant() const;
00118     void detach();
00119     bool isDetached() const;
00120 
00121     QImage copy(const QRect &rect = QRect()) const;
00122     inline QImage copy(int x, int y, int w, int h) const
00123         { return copy(QRect(x, y, w, h)); }
00124 
00125     Format format() const;
00126 
00127     QImage convertToFormat(Format f, Qt::ImageConversionFlags flags = Qt::AutoColor) const Q_REQUIRED_RESULT;
00128     QImage convertToFormat(Format f, const QVector<QRgb> &colorTable, Qt::ImageConversionFlags flags = Qt::AutoColor) const Q_REQUIRED_RESULT;
00129 
00130     int width() const;
00131     int height() const;
00132     QSize size() const;
00133     QRect rect() const;
00134 
00135     int depth() const;
00136     int numColors() const;
00137 
00138     QRgb color(int i) const;
00139     void setColor(int i, QRgb c);
00140     void setNumColors(int);
00141 
00142     bool allGray() const;
00143     bool isGrayscale() const;
00144 
00145     uchar *bits();
00146     const uchar *bits() const;
00147     int numBytes() const;
00148 
00149     uchar *scanLine(int);
00150     const uchar *scanLine(int) const;
00151     int bytesPerLine() const;
00152 
00153     bool valid(int x, int y) const;
00154     bool valid(const QPoint &pt) const;
00155 
00156     int pixelIndex(int x, int y) const;
00157     int pixelIndex(const QPoint &pt) const;
00158 
00159     QRgb pixel(int x, int y) const;
00160     QRgb pixel(const QPoint &pt) const;
00161 
00162     void setPixel(int x, int y, uint index_or_rgb);
00163     void setPixel(const QPoint &pt, uint index_or_rgb);
00164 
00165     QVector<QRgb> colorTable() const;
00166     void setColorTable(const QVector<QRgb> colors);
00167 
00168     void fill(uint pixel);
00169 
00170     bool hasAlphaChannel() const;
00171     void setAlphaChannel(const QImage &alphaChannel);
00172     QImage alphaChannel() const;
00173     QImage createAlphaMask(Qt::ImageConversionFlags flags = Qt::AutoColor) const;
00174 #ifndef QT_NO_IMAGE_HEURISTIC_MASK
00175     QImage createHeuristicMask(bool clipTight = true) const;
00176 #endif
00177 
00178     inline QImage scaled(int w, int h, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
00179                         Qt::TransformationMode mode = Qt::FastTransformation) const
00180         { return scaled(QSize(w, h), aspectMode, mode); }
00181     QImage scaled(const QSize &s, Qt::AspectRatioMode aspectMode = Qt::IgnoreAspectRatio,
00182                  Qt::TransformationMode mode = Qt::FastTransformation) const;
00183     QImage scaledToWidth(int w, Qt::TransformationMode mode = Qt::FastTransformation) const;
00184     QImage scaledToHeight(int h, Qt::TransformationMode mode = Qt::FastTransformation) const;
00185     QImage transformed(const QMatrix &matrix, Qt::TransformationMode mode = Qt::FastTransformation) const;
00186     static QMatrix trueMatrix(const QMatrix &, int w, int h);
00187     QImage mirrored(bool horizontally = false, bool vertically = true) const;
00188     QImage rgbSwapped() const;
00189     void invertPixels(InvertMode = InvertRgb);
00190 
00191 
00192     bool load(QIODevice *device, const char* format);
00193     bool load(const QString &fileName, const char* format=0);
00194     bool loadFromData(const uchar *buf, int len, const char *format = 0);
00195     inline bool loadFromData(const QByteArray &data, const char* aformat=0)
00196         { return loadFromData(reinterpret_cast<const uchar *>(data.constData()), data.size(), aformat); }
00197 
00198     bool save(const QString &fileName, const char* format=0, int quality=-1) const;
00199     bool save(QIODevice *device, const char* format=0, int quality=-1) const;
00200 
00201     static QImage fromData(const uchar *data, int size, const char *format = 0);
00202     inline static QImage fromData(const QByteArray &data, const char *format = 0)
00203         { return fromData(reinterpret_cast<const uchar *>(data.constData()), data.size(), format); }
00204 
00205     int serialNumber() const;
00206 
00207     QPaintEngine *paintEngine() const;
00208 
00209     // Auxiliary data
00210     int dotsPerMeterX() const;
00211     int dotsPerMeterY() const;
00212     void setDotsPerMeterX(int);
00213     void setDotsPerMeterY(int);
00214     QPoint offset() const;
00215     void setOffset(const QPoint&);
00216 #ifndef QT_NO_IMAGE_TEXT
00217     QStringList textKeys() const;
00218     QString text(const QString &key = QString()) const;
00219     void setText(const QString &key, const QString &value);
00220 
00221     // The following functions are obsolete as of 4.1
00222     QString text(const char* key, const char* lang=0) const;
00223     QList<QImageTextKeyLang> textList() const;
00224     QStringList textLanguages() const;
00225     QString text(const QImageTextKeyLang&) const;
00226     void setText(const char* key, const char* lang, const QString&);
00227 #endif
00228 
00229 #ifdef QT3_SUPPORT
00230     enum Endian { BigEndian, LittleEndian, IgnoreEndian };
00231     QT3_SUPPORT_CONSTRUCTOR QImage(int width, int height, int depth, int numColors=0, Endian bitOrder=IgnoreEndian);
00232     QT3_SUPPORT_CONSTRUCTOR QImage(const QSize&, int depth, int numColors=0, Endian bitOrder=IgnoreEndian);
00233     QT3_SUPPORT_CONSTRUCTOR QImage(uchar *data, int w, int h, int depth, const QRgb *colortable, int numColors, Endian bitOrder);
00234 #ifdef Q_WS_QWS
00235     QT3_SUPPORT_CONSTRUCTOR QImage(uchar *data, int w, int h, int depth, int pbl, const QRgb *colortable, int numColors, Endian bitOrder);
00236 #endif
00237     inline QT3_SUPPORT Endian bitOrder() const {
00238         Format f = format();
00239         return f == Format_Mono ? BigEndian : (f == Format_MonoLSB ? LittleEndian : IgnoreEndian);
00240     }
00241     QT3_SUPPORT QImage convertDepth(int, Qt::ImageConversionFlags flags = Qt::AutoColor) const;
00242     QT3_SUPPORT QImage convertDepthWithPalette(int, QRgb* p, int pc, Qt::ImageConversionFlags flags = Qt::AutoColor) const;
00243     QT3_SUPPORT QImage convertBitOrder(Endian) const;
00244     QT3_SUPPORT bool hasAlphaBuffer() const;
00245     QT3_SUPPORT void setAlphaBuffer(bool);
00246     QT3_SUPPORT uchar **jumpTable();
00247     QT3_SUPPORT const uchar * const *jumpTable() const;
00248     inline QT3_SUPPORT void reset() { *this = QImage(); }
00249     static inline QT3_SUPPORT Endian systemByteOrder()
00250         { return QSysInfo::ByteOrder == QSysInfo::BigEndian ? BigEndian : LittleEndian; }
00251     inline QT3_SUPPORT QImage swapRGB() const { return rgbSwapped(); }
00252     inline QT3_SUPPORT QImage mirror(bool horizontally = false, bool vertically = true) const
00253         { return mirrored(horizontally, vertically); }
00254     QT3_SUPPORT bool create(const QSize&, int depth, int numColors=0, Endian bitOrder=IgnoreEndian);
00255     QT3_SUPPORT bool create(int width, int height, int depth, int numColors=0, Endian bitOrder=IgnoreEndian);
00256     inline QT3_SUPPORT QImage xForm(const QMatrix &matrix) const { return transformed(matrix); }
00257     inline QT3_SUPPORT QImage smoothScale(int w, int h, Qt::AspectRatioMode mode = Qt::IgnoreAspectRatio) const
00258         { return scaled(QSize(w, h), mode, Qt::SmoothTransformation); }
00259     inline QImage QT3_SUPPORT smoothScale(const QSize &s, Qt::AspectRatioMode mode = Qt::IgnoreAspectRatio) const
00260         { return scaled(s, mode, Qt::SmoothTransformation); }
00261     inline QT3_SUPPORT QImage scaleWidth(int w) const { return scaledToWidth(w); }
00262     inline QT3_SUPPORT QImage scaleHeight(int h) const { return scaledToHeight(h); }
00263     inline QT3_SUPPORT void invertPixels(bool invertAlpha) { invertAlpha ? invertPixels(InvertRgba) : invertPixels(InvertRgb); }
00264     inline QT3_SUPPORT QImage copy(int x, int y, int w, int h, Qt::ImageConversionFlags) const
00265         { return copy(QRect(x, y, w, h)); }
00266     inline QT3_SUPPORT QImage copy(const QRect &rect, Qt::ImageConversionFlags) const
00267         { return copy(rect); }
00268     static QT3_SUPPORT Endian systemBitOrder();
00269     inline QT3_SUPPORT_CONSTRUCTOR QImage(const QByteArray &data)
00270         { d = 0; *this = QImage::fromData(data); }
00271 #endif
00272 
00273 protected:
00274     virtual int metric(PaintDeviceMetric metric) const;
00275 
00276 private:
00277 #if defined(Q_WS_QWS) && !defined(QT3_SUPPORT)
00278 public:
00279     enum Endian { BigEndian, LittleEndian, IgnoreEndian };
00280 private:
00281     QImage(uchar *data, int w, int h, int depth, int pbl, const QRgb *colortable, int numColors, Endian bitOrder);
00282 #endif
00283 
00284     QImageData *d;
00285 
00286     friend class QPixmap;
00287     friend Q_GUI_EXPORT qint64 qt_image_id(const QImage &image);
00288     friend const QVector<QRgb> *qt_image_colortable(const QImage &image);
00289 };
00290 
00291 Q_DECLARE_SHARED(QImage)
00292 Q_DECLARE_TYPEINFO(QImage, Q_MOVABLE_TYPE);
00293 
00294 // Inline functions...
00295 
00296 Q_GUI_EXPORT_INLINE bool QImage::valid(const QPoint &pt) const { return valid(pt.x(), pt.y()); }
00297 Q_GUI_EXPORT_INLINE int QImage::pixelIndex(const QPoint &pt) const { return pixelIndex(pt.x(), pt.y());}
00298 Q_GUI_EXPORT_INLINE QRgb QImage::pixel(const QPoint &pt) const { return pixel(pt.x(), pt.y()); }
00299 Q_GUI_EXPORT_INLINE void QImage::setPixel(const QPoint &pt, uint index_or_rgb) { setPixel(pt.x(), pt.y(), index_or_rgb); }
00300 
00301 // QImage stream functions
00302 
00303 #if !defined(QT_NO_DATASTREAM)
00304 Q_GUI_EXPORT QDataStream &operator<<(QDataStream &, const QImage &);
00305 Q_GUI_EXPORT QDataStream &operator>>(QDataStream &, QImage &);
00306 #endif
00307 
00308 #ifdef QT3_SUPPORT
00309 Q_GUI_EXPORT QT3_SUPPORT void bitBlt(QImage* dst, int dx, int dy, const QImage* src,
00310                                      int sx=0, int sy=0, int sw=-1, int sh=-1, Qt::ImageConversionFlags flags = Qt::AutoColor);
00311 #endif
00312 
00313 QT_END_HEADER
00314 
00315 #endif // QIMAGE_H