1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include <qglobal.h>

    43 

    44 #include "qpixmap.h"

    45 #include "qpixmapdata_p.h"

    46 #include "qimagepixmapcleanuphooks_p.h"

    47 

    48 #include "qbitmap.h"

    49 #include "qcolormap.h"

    50 #include "qimage.h"

    51 #include "qwidget.h"

    52 #include "qpainter.h"

    53 #include "qdatastream.h"

    54 #include "qbuffer.h"

    55 #include "qapplication.h"

    56 #include <private/qapplication_p.h>

    57 #include <private/qgraphicssystem_p.h>

    58 #include <private/qwidget_p.h>

    59 #include "qevent.h"

    60 #include "qfile.h"

    61 #include "qfileinfo.h"

    62 #include "qpixmapcache.h"

    63 #include "qdatetime.h"

    64 #include "qimagereader.h"

    65 #include "qimagewriter.h"

    66 #include "qpaintengine.h"

    67 #include "qthread.h"

    68 

    69 #ifdef Q_WS_MAC

    70 # include "private/qt_mac_p.h"

    71 # include "private/qpixmap_mac_p.h"

    72 #endif

    73 

    74 #if defined(Q_WS_X11)

    75 # include "qx11info_x11.h"

    76 # include <private/qt_x11_p.h>

    77 # include <private/qpixmap_x11_p.h>

    78 #endif

    79 

    80 #if defined(Q_OS_SYMBIAN)

    81 # include <private/qt_s60_p.h>

    82 #endif

    83 

    84 #include "qpixmap_raster_p.h"

    85 

    86 QT_BEGIN_NAMESPACE

    87 

    88 // ### Qt 5: remove

    89 Q_GUI_EXPORT qint64 qt_pixmap_id(const QPixmap &pixmap)

    90 {

    91     return pixmap.cacheKey();

    92 }

    93 

    94 static bool qt_pixmap_thread_test()

    95 {

    96     if (!qApp) {

    97         qFatal("QPixmap: Must construct a QApplication before a QPaintDevice");

    98         return false;

    99     }

   100 #ifndef Q_WS_WIN

   101     if (qApp->thread() != QThread::currentThread()) {

   102         qWarning("QPixmap: It is not safe to use pixmaps outside the GUI thread");

   103         return false;

   104     }

   105 #endif

   106     return true;

   107 }

   108 

   109 void QPixmap::init(int w, int h, Type type)

   110 {

   111     init(w, h, int(type));

   112 }

   113 

   114 void QPixmap::init(int w, int h, int type)

   115 {

   116     QGraphicsSystem* gs = QApplicationPrivate::graphicsSystem();

   117     if (gs)

   118         data = gs->createPixmapData(static_cast<QPixmapData::PixelType>(type));

   119     else

   120         data = QGraphicsSystem::createDefaultPixmapData(static_cast<QPixmapData::PixelType>(type));

   121 

   122     data->resize(w, h);

   123 }

   124 

   125 /*!

   126     \enum QPixmap::ColorMode

   127 

   128     \compat

   129 

   130     This enum type defines the color modes that exist for converting

   131     QImage objects to QPixmap.  It is provided here for compatibility

   132     with earlier versions of Qt.

   133 

   134     Use Qt::ImageConversionFlags instead.

   135 

   136     \value Auto  Select \c Color or \c Mono on a case-by-case basis.

   137     \value Color Always create colored pixmaps.

   138     \value Mono  Always create bitmaps.

   139 */

   140 

   141 /*!

   142     Constructs a null pixmap.

   143 

   144     \sa isNull()

   145 */

   146 

   147 QPixmap::QPixmap()

   148     : QPaintDevice()

   149 {

   150     (void) qt_pixmap_thread_test();

   151     init(0, 0, QPixmapData::PixmapType);

   152 }

   153 

   154 /*!

   155     \fn QPixmap::QPixmap(int width, int height)

   156 

   157     Constructs a pixmap with the given \a width and \a height. If

   158     either \a width or \a height is zero, a null pixmap is

   159     constructed.

   160 

   161     \warning This will create a QPixmap with uninitialized data. Call

   162     fill() to fill the pixmap with an appropriate color before drawing

   163     onto it with QPainter.

   164 

   165     \sa isNull()

   166 */

   167 

   168 QPixmap::QPixmap(int w, int h)

   169     : QPaintDevice()

   170 {

   171     if (!qt_pixmap_thread_test())

   172         init(0, 0, QPixmapData::PixmapType);

   173     else

   174         init(w, h, QPixmapData::PixmapType);

   175 }

   176 

   177 /*!

   178     \overload

   179 

   180     Constructs a pixmap of the given \a size.

   181 

   182     \warning This will create a QPixmap with uninitialized data. Call

   183     fill() to fill the pixmap with an appropriate color before drawing

   184     onto it with QPainter.

   185 */

   186 

   187 QPixmap::QPixmap(const QSize &size)

   188     : QPaintDevice()

   189 {

   190     if (!qt_pixmap_thread_test())

   191         init(0, 0, QPixmapData::PixmapType);

   192     else

   193         init(size.width(), size.height(), QPixmapData::PixmapType);

   194 }

   195 

   196 /*!

   197   \internal

   198 */

   199 QPixmap::QPixmap(const QSize &s, Type type)

   200 {

   201     if (!qt_pixmap_thread_test())

   202         init(0, 0, type);

   203     else

   204         init(s.width(), s.height(), type);

   205 }

   206 

   207 /*!

   208   \internal

   209 */

   210 QPixmap::QPixmap(const QSize &s, int type)

   211 {

   212     if (!qt_pixmap_thread_test())

   213         init(0, 0, static_cast<QPixmapData::PixelType>(type));

   214     else

   215         init(s.width(), s.height(), static_cast<QPixmapData::PixelType>(type));

   216 }

   217 

   218 /*!

   219     \internal

   220 */

   221 QPixmap::QPixmap(QPixmapData *d)

   222     : QPaintDevice(), data(d)

   223 {

   224 }

   225 

   226 /*!

   227     Constructs a pixmap from the file with the given \a fileName. If the

   228     file does not exist or is of an unknown format, the pixmap becomes a

   229     null pixmap.

   230 

   231     The loader attempts to read the pixmap using the specified \a

   232     format. If the \a format is not specified (which is the default),

   233     the loader probes the file for a header to guess the file format.

   234 

   235     The file name can either refer to an actual file on disk or to

   236     one of the application's embedded resources. See the

   237     \l{resources.html}{Resource System} overview for details on how

   238     to embed images and other resource files in the application's

   239     executable.

   240 

   241     If the image needs to be modified to fit in a lower-resolution

   242     result (e.g. converting from 32-bit to 8-bit), use the \a

   243     flags to control the conversion.

   244 

   245     The \a fileName, \a format and \a flags parameters are

   246     passed on to load(). This means that the data in \a fileName is

   247     not compiled into the binary. If \a fileName contains a relative

   248     path (e.g. the filename only) the relevant file must be found

   249     relative to the runtime working directory.

   250 

   251     \sa {QPixmap#Reading and Writing Image Files}{Reading and Writing

   252     Image Files}

   253 */

   254 

   255 QPixmap::QPixmap(const QString& fileName, const char *format, Qt::ImageConversionFlags flags)

   256     : QPaintDevice()

   257 {

   258     init(0, 0, QPixmapData::PixmapType);

   259     if (!qt_pixmap_thread_test())

   260         return;

   261 

   262     load(fileName, format, flags);

   263 }

   264 

   265 /*!

   266     Constructs a pixmap that is a copy of the given \a pixmap.

   267 

   268     \sa copy()

   269 */

   270 

   271 QPixmap::QPixmap(const QPixmap &pixmap)

   272     : QPaintDevice()

   273 {

   274     if (!qt_pixmap_thread_test()) {

   275         init(0, 0, QPixmapData::PixmapType);

   276         return;

   277     }

   278     if (pixmap.paintingActive()) {                // make a deep copy

   279         operator=(pixmap.copy());

   280     } else {

   281         data = pixmap.data;

   282     }

   283 }

   284 

   285 /*!

   286     Constructs a pixmap from the given \a xpm data, which must be a

   287     valid XPM image.

   288 

   289     Errors are silently ignored.

   290 

   291     Note that it's possible to squeeze the XPM variable a little bit

   292     by using an unusual declaration:

   293 

   294     \snippet doc/src/snippets/code/src_gui_image_qpixmap.cpp 0

   295 

   296     The extra \c const makes the entire definition read-only, which is

   297     slightly more efficient (for example, when the code is in a shared

   298     library) and ROMable when the application is to be stored in ROM.

   299 */

   300 #ifndef QT_NO_IMAGEFORMAT_XPM

   301 QPixmap::QPixmap(const char * const xpm[])

   302     : QPaintDevice()

   303 {

   304     init(0, 0, QPixmapData::PixmapType);

   305     if (!xpm)

   306         return;

   307 

   308     QImage image(xpm);

   309     if (!image.isNull()) {

   310         if (data->pixelType() == QPixmapData::BitmapType)

   311             *this = QBitmap::fromImage(image);

   312         else

   313             *this = fromImage(image);

   314     }

   315 }

   316 #endif

   317 

   318 

   319 /*!

   320     Destroys the pixmap.

   321 */

   322 

   323 QPixmap::~QPixmap()

   324 {

   325     Q_ASSERT(data->ref >= 1); // Catch if ref-counting changes again

   326     if (data->is_cached && data->ref == 1) // ref will be decrememnted after destructor returns

   327         QImagePixmapCleanupHooks::executePixmapDestructionHooks(this);

   328 }

   329 

   330 /*!

   331   \internal

   332 */

   333 int QPixmap::devType() const

   334 {

   335     return QInternal::Pixmap;

   336 }

   337 

   338 /*!

   339     \fn QPixmap QPixmap::copy(int x, int y, int width, int height) const

   340     \overload

   341 

   342     Returns a deep copy of the subset of the pixmap that is specified

   343     by the rectangle QRect( \a x, \a y, \a width, \a height).

   344 */

   345 

   346 /*!

   347     \fn QPixmap QPixmap::copy(const QRect &rectangle) const

   348 

   349     Returns a deep copy of the subset of the pixmap that is specified

   350     by the given \a rectangle. For more information on deep copies,

   351     see the \l {Implicit Data Sharing} documentation.

   352 

   353     If the given \a rectangle is empty, the whole image is copied.

   354 

   355     \sa operator=(), QPixmap(), {QPixmap#Pixmap

   356     Transformations}{Pixmap Transformations}

   357 */

   358 QPixmap QPixmap::copy(const QRect &rect) const

   359 {

   360     if (isNull())

   361         return QPixmap();

   362 

   363     const QRect r = rect.isEmpty() ? QRect(0, 0, width(), height()) : rect;

   364 

   365     QPixmapData *d = data->createCompatiblePixmapData();

   366     d->copy(data.data(), r);

   367     return QPixmap(d);

   368 }

   369 

   370 /*!

   371     \fn QPixmap::scroll(int dx, int dy, int x, int y, int width, int height, QRegion *exposed)

   372     \since 4.6

   373 

   374     This convenience function is equivalent to calling QPixmap::scroll(\a dx,

   375     \a dy, QRect(\a x, \a y, \a width, \a height), \a exposed).

   376 

   377     \sa QWidget::scroll(), QGraphicsItem::scroll()

   378 */

   379 

   380 /*!

   381     \since 4.6

   382 

   383     Scrolls the area \a rect of this pixmap by (\a dx, \a dy). The exposed

   384     region is left unchanged. You can optionally pass a pointer to an empty

   385     QRegion to get the region that is \a exposed by the scroll operation.

   386 

   387     \snippet doc/src/snippets/code/src_gui_image_qpixmap.cpp 2

   388 

   389     You cannot scroll while there is an active painter on the pixmap.

   390 

   391     \sa QWidget::scroll(), QGraphicsItem::scroll()

   392 */

   393 void QPixmap::scroll(int dx, int dy, const QRect &rect, QRegion *exposed)

   394 {

   395     if (isNull() || (dx == 0 && dy == 0))

   396         return;

   397     QRect dest = rect & this->rect();

   398     QRect src = dest.translated(-dx, -dy) & dest;

   399     if (src.isEmpty()) {

   400         if (exposed)

   401             *exposed += dest;

   402         return;

   403     }

   404 

   405     detach();

   406 

   407     if (!data->scroll(dx, dy, src)) {

   408         // Fallback

   409         QPixmap pix = *this;

   410         QPainter painter(&pix);

   411         painter.setCompositionMode(QPainter::CompositionMode_Source);

   412         painter.drawPixmap(src.translated(dx, dy), *this, src);

   413         painter.end();

   414         *this = pix;

   415     }

   416 

   417     if (exposed) {

   418         *exposed += dest;

   419         *exposed -= src.translated(dx, dy);

   420     }

   421 }

   422 

   423 /*!

   424     Assigns the given \a pixmap to this pixmap and returns a reference

   425     to this pixmap.

   426 

   427     \sa copy(), QPixmap()

   428 */

   429 

   430 QPixmap &QPixmap::operator=(const QPixmap &pixmap)

   431 {

   432     if (paintingActive()) {

   433         qWarning("QPixmap::operator=: Cannot assign to pixmap during painting");

   434         return *this;

   435     }

   436     if (pixmap.paintingActive()) {                // make a deep copy

   437         *this = pixmap.copy();

   438     } else {

   439         data = pixmap.data;

   440     }

   441     return *this;

   442 }

   443 

   444 /*!

   445    Returns the pixmap as a QVariant.

   446 */

   447 QPixmap::operator QVariant() const

   448 {

   449     return QVariant(QVariant::Pixmap, this);

   450 }

   451 

   452 /*!

   453     \fn bool QPixmap::operator!() const

   454 

   455     Returns true if this is a null pixmap; otherwise returns false.

   456 

   457     \sa isNull()

   458 */

   459 

   460 /*!

   461     \fn QPixmap::operator QImage() const

   462 

   463     Returns the pixmap as a QImage.

   464 

   465     Use the toImage() function instead.

   466 */

   467 

   468 /*!

   469     Converts the pixmap to a QImage. Returns a null image if the

   470     conversion fails.

   471 

   472     If the pixmap has 1-bit depth, the returned image will also be 1

   473     bit deep. Images with more bits will be returned in a format

   474     closely represents the underlying system. Usually this will be

   475     QImage::Format_ARGB32_Premultiplied for pixmaps with an alpha and

   476     QImage::Format_RGB32 or QImage::Format_RGB16 for pixmaps without

   477     alpha.

   478 

   479     Note that for the moment, alpha masks on monochrome images are

   480     ignored.

   481 

   482     \sa fromImage(), {QImage#Image Formats}{Image Formats}

   483 */

   484 QImage QPixmap::toImage() const

   485 {

   486     if (isNull())

   487         return QImage();

   488 

   489     return data->toImage();

   490 }

   491 

   492 /*!

   493     \fn QMatrix QPixmap::trueMatrix(const QTransform &matrix, int width, int height)

   494 

   495     Returns the actual matrix used for transforming a pixmap with the

   496     given \a width, \a height and \a matrix.

   497 

   498     When transforming a pixmap using the transformed() function, the

   499     transformation matrix is internally adjusted to compensate for

   500     unwanted translation, i.e. transformed() returns the smallest

   501     pixmap containing all transformed points of the original

   502     pixmap. This function returns the modified matrix, which maps

   503     points correctly from the original pixmap into the new pixmap.

   504 

   505     \sa transformed(), {QPixmap#Pixmap Transformations}{Pixmap

   506     Transformations}

   507 */

   508 QTransform QPixmap::trueMatrix(const QTransform &m, int w, int h)

   509 {

   510     return QImage::trueMatrix(m, w, h);

   511 }

   512 

   513 /*!

   514   \overload

   515 

   516   This convenience function loads the matrix \a m into a

   517   QTransform and calls the overloaded function with the

   518   QTransform and the width \a w and the height \a h.

   519  */

   520 QMatrix QPixmap::trueMatrix(const QMatrix &m, int w, int h)

   521 {

   522     return trueMatrix(QTransform(m), w, h).toAffine();

   523 }

   524 

   525 

   526 /*!

   527     \fn bool QPixmap::isQBitmap() const

   528 

   529     Returns true if this is a QBitmap; otherwise returns false.

   530 */

   531 

   532 bool QPixmap::isQBitmap() const

   533 {

   534     return data->type == QPixmapData::BitmapType;

   535 }

   536 

   537 /*!

   538     \fn bool QPixmap::isNull() const

   539 

   540     Returns true if this is a null pixmap; otherwise returns false.

   541 

   542     A null pixmap has zero width, zero height and no contents. You

   543     cannot draw in a null pixmap.

   544 */

   545 bool QPixmap::isNull() const

   546 {

   547     return data->isNull();

   548 }

   549 

   550 /*!

   551     \fn int QPixmap::width() const

   552 

   553     Returns the width of the pixmap.

   554 

   555     \sa size(), {QPixmap#Pixmap Information}{Pixmap Information}

   556 */

   557 int QPixmap::width() const

   558 {

   559     return data->width();

   560 }

   561 

   562 /*!

   563     \fn int QPixmap::height() const

   564 

   565     Returns the height of the pixmap.

   566 

   567     \sa size(), {QPixmap#Pixmap Information}{Pixmap Information}

   568 */

   569 int QPixmap::height() const

   570 {

   571     return data->height();

   572 }

   573 

   574 /*!

   575     \fn QSize QPixmap::size() const

   576 

   577     Returns the size of the pixmap.

   578 

   579     \sa width(), height(), {QPixmap#Pixmap Information}{Pixmap

   580     Information}

   581 */

   582 QSize QPixmap::size() const

   583 {

   584     return QSize(data->width(), data->height());

   585 }

   586 

   587 /*!

   588     \fn QRect QPixmap::rect() const

   589 

   590     Returns the pixmap's enclosing rectangle.

   591 

   592     \sa {QPixmap#Pixmap Information}{Pixmap Information}

   593 */

   594 QRect QPixmap::rect() const

   595 {

   596     return QRect(0, 0, data->width(), data->height());

   597 }

   598 

   599 /*!

   600     \fn int QPixmap::depth() const

   601 

   602     Returns the depth of the pixmap.

   603 

   604     The pixmap depth is also called bits per pixel (bpp) or bit planes

   605     of a pixmap. A null pixmap has depth 0.

   606 

   607     \sa defaultDepth(), {QPixmap#Pixmap Information}{Pixmap

   608     Information}

   609 */

   610 int QPixmap::depth() const

   611 {

   612     return data->depth();

   613 }

   614 

   615 /*!

   616     \fn void QPixmap::resize(const QSize &size)

   617     \overload

   618     \compat

   619 

   620     Use QPixmap::copy() instead to get the pixmap with the new size.

   621 

   622     \oldcode

   623         pixmap.resize(size);

   624     \newcode

   625         pixmap = pixmap.copy(QRect(QPoint(0, 0), size));

   626     \endcode

   627 */

   628 #ifdef QT3_SUPPORT

   629 void QPixmap::resize_helper(const QSize &s)

   630 {

   631     int w = s.width();

   632     int h = s.height();

   633     if (w < 1 || h < 1) {

   634         *this = QPixmap();

   635         return;

   636     }

   637 

   638     if (size() == s)

   639         return;

   640 

   641     // Create new pixmap

   642     QPixmap pm(QSize(w, h), data->type);

   643     bool uninit = false;

   644 #if defined(Q_WS_X11)

   645     QX11PixmapData *x11Data = data->classId() == QPixmapData::X11Class ? static_cast<QX11PixmapData*>(data.data()) : 0;

   646     if (x11Data) {

   647         pm.x11SetScreen(x11Data->xinfo.screen());

   648         uninit = x11Data->flags & QX11PixmapData::Uninitialized;

   649     }

   650 #elif defined(Q_WS_MAC)

   651     QMacPixmapData *macData = data->classId() == QPixmapData::MacClass ? static_cast<QMacPixmapData*>(data.data()) : 0;

   652     if (macData)

   653         uninit = macData->uninit;

   654 #endif

   655     if (!uninit && !isNull()) {

   656         // Copy old pixmap

   657         if (hasAlphaChannel())

   658             pm.fill(Qt::transparent);

   659         QPainter p(&pm);

   660         p.drawPixmap(0, 0, *this, 0, 0, qMin(width(), w), qMin(height(), h));

   661     }

   662 

   663 #if defined(Q_WS_X11)

   664     if (x11Data && x11Data->x11_mask) {

   665         QX11PixmapData *pmData = static_cast<QX11PixmapData*>(pm.data.data());

   666         pmData->x11_mask = (Qt::HANDLE)XCreatePixmap(X11->display,

   667                                                      RootWindow(x11Data->xinfo.display(),

   668                                                                 x11Data->xinfo.screen()),

   669                                                       w, h, 1);

   670         GC gc = XCreateGC(X11->display, pmData->x11_mask, 0, 0);

   671         XCopyArea(X11->display, x11Data->x11_mask, pmData->x11_mask, gc, 0, 0, qMin(width(), w), qMin(height(), h), 0, 0);

   672         XFreeGC(X11->display, gc);

   673     }

   674 #endif

   675     *this = pm;

   676 }

   677 #endif

   678 

   679 /*!

   680     \fn void QPixmap::resize(int width, int height)

   681     \compat

   682 

   683     Use QPixmap::copy() instead to get the pixmap with the new size.

   684 

   685     \oldcode

   686         pixmap.resize(10, 20);

   687     \newcode

   688         pixmap = pixmap.copy(0, 0, 10, 20);

   689     \endcode

   690 */

   691 

   692 /*!

   693     \fn bool QPixmap::selfMask() const

   694     \compat

   695 

   696     Returns whether the pixmap is its own mask or not.

   697 

   698     This function is no longer relevant since the concept of self

   699     masking doesn't exists anymore.

   700 */

   701 

   702 /*!

   703     Sets a mask bitmap.

   704 

   705     This function merges the \a mask with the pixmap's alpha channel. A pixel

   706     value of 1 on the mask means the pixmap's pixel is unchanged; a value of 0

   707     means the pixel is transparent. The mask must have the same size as this

   708     pixmap.

   709 

   710     Setting a null mask resets the mask, leaving the previously transparent

   711     pixels black. The effect of this function is undefined when the pixmap is

   712     being painted on.

   713 

   714     \warning This is potentially an expensive operation.

   715 

   716     \sa mask(), {QPixmap#Pixmap Transformations}{Pixmap Transformations},

   717     QBitmap

   718 */

   719 void QPixmap::setMask(const QBitmap &mask)

   720 {

   721     if (paintingActive()) {

   722         qWarning("QPixmap::setMask: Cannot set mask while pixmap is being painted on");

   723         return;

   724     }

   725 

   726     if (!mask.isNull() && mask.size() != size()) {

   727         qWarning("QPixmap::setMask() mask size differs from pixmap size");

   728         return;

   729     }

   730 

   731     if (static_cast<const QPixmap &>(mask).data == data) // trying to selfmask

   732        return;

   733 

   734     detach();

   735     data->setMask(mask);

   736 }

   737 

   738 #ifndef QT_NO_IMAGE_HEURISTIC_MASK

   739 /*!

   740     Creates and returns a heuristic mask for this pixmap.

   741 

   742     The function works by selecting a color from one of the corners

   743     and then chipping away pixels of that color, starting at all the

   744     edges.  If \a clipTight is true (the default) the mask is just

   745     large enough to cover the pixels; otherwise, the mask is larger

   746     than the data pixels.

   747 

   748     The mask may not be perfect but it should be reasonable, so you

   749     can do things such as the following:

   750 

   751     \snippet doc/src/snippets/code/src_gui_image_qpixmap.cpp 1

   752 

   753     This function is slow because it involves converting to/from a

   754     QImage, and non-trivial computations.

   755 

   756     \sa QImage::createHeuristicMask(), createMaskFromColor()

   757 */

   758 QBitmap QPixmap::createHeuristicMask(bool clipTight) const

   759 {

   760     QBitmap m = QBitmap::fromImage(toImage().createHeuristicMask(clipTight));

   761     return m;

   762 }

   763 #endif

   764 

   765 /*!

   766     Creates and returns a mask for this pixmap based on the given \a

   767     maskColor. If the \a mode is Qt::MaskInColor, all pixels matching the

   768     maskColor will be opaque. If \a mode is Qt::MaskOutColor, all pixels

   769     matching the maskColor will be transparent.

   770 

   771     This function is slow because it involves converting to/from a

   772     QImage.

   773 

   774     \sa createHeuristicMask(), QImage::createMaskFromColor()

   775 */

   776 QBitmap QPixmap::createMaskFromColor(const QColor &maskColor, Qt::MaskMode mode) const

   777 {

   778     QImage image = toImage().convertToFormat(QImage::Format_ARGB32);

   779     return QBitmap::fromImage(image.createMaskFromColor(maskColor.rgba(), mode));

   780 }

   781 

   782 /*! \overload

   783 

   784     Creates and returns a mask for this pixmap based on the given \a

   785     maskColor. Same as calling createMaskFromColor(maskColor,

   786     Qt::MaskInColor)

   787 

   788     \sa createHeuristicMask(), QImage::createMaskFromColor()

   789 */

   790 QBitmap QPixmap::createMaskFromColor(const QColor &maskColor) const

   791 {

   792     return createMaskFromColor(maskColor, Qt::MaskInColor);

   793 }

   794 

   795 /*!

   796     Loads a pixmap from the file with the given \a fileName. Returns

   797     true if the pixmap was successfully loaded; otherwise returns

   798     false.

   799 

   800     The loader attempts to read the pixmap using the specified \a

   801     format. If the \a format is not specified (which is the default),

   802     the loader probes the file for a header to guess the file format.

   803 

   804     The file name can either refer to an actual file on disk or to one

   805     of the application's embedded resources. See the

   806     \l{resources.html}{Resource System} overview for details on how to

   807     embed pixmaps and other resource files in the application's

   808     executable.

   809 

   810     If the data needs to be modified to fit in a lower-resolution

   811     result (e.g. converting from 32-bit to 8-bit), use the \a flags to

   812     control the conversion.

   813 

   814     Note that QPixmaps are automatically added to the QPixmapCache

   815     when loaded from a file; the key used is internal and can not

   816     be acquired.

   817 

   818     \sa loadFromData(), {QPixmap#Reading and Writing Image

   819     Files}{Reading and Writing Image Files}

   820 */

   821 

   822 bool QPixmap::load(const QString &fileName, const char *format, Qt::ImageConversionFlags flags)

   823 {

   824     if (fileName.isEmpty())

   825         return false;

   826 

   827     QFileInfo info(fileName);

   828     QString key = QLatin1String("qt_pixmap_") + info.absoluteFilePath() + QLatin1Char('_') + QString::number(info.lastModified().toTime_t()) + QLatin1Char('_') +

   829                   QString::number(info.size()) + QLatin1Char('_') + QString::number(data->pixelType());

   830 

   831     if (QPixmapCache::find(key, *this))

   832         return true;

   833 

   834     if (data->fromFile(fileName, format, flags)) {

   835         QPixmapCache::insert(key, *this);

   836         return true;

   837     }

   838 

   839     return false;

   840 }

   841 

   842 /*!

   843     \fn bool QPixmap::loadFromData(const uchar *data, uint len, const char *format, Qt::ImageConversionFlags flags)

   844 

   845     Loads a pixmap from the \a len first bytes of the given binary \a

   846     data.  Returns true if the pixmap was loaded successfully;

   847     otherwise returns false.

   848 

   849     The loader attempts to read the pixmap using the specified \a

   850     format. If the \a format is not specified (which is the default),

   851     the loader probes the file for a header to guess the file format.

   852 

   853     If the data needs to be modified to fit in a lower-resolution

   854     result (e.g. converting from 32-bit to 8-bit), use the \a flags to

   855     control the conversion.

   856 

   857     \sa load(), {QPixmap#Reading and Writing Image Files}{Reading and

   858     Writing Image Files}

   859 */

   860 

   861 bool QPixmap::loadFromData(const uchar *buf, uint len, const char *format, Qt::ImageConversionFlags flags)

   862 {

   863     return data->fromData(buf, len, format, flags);

   864 }

   865 

   866 /*!

   867     \fn bool QPixmap::loadFromData(const QByteArray &data, const char *format, Qt::ImageConversionFlags flags)

   868 

   869     \overload

   870 

   871     Loads a pixmap from the binary \a data using the specified \a

   872     format and conversion \a flags.

   873 */

   874 

   875 

   876 /*!

   877     Saves the pixmap to the file with the given \a fileName using the

   878     specified image file \a format and \a quality factor. Returns true

   879     if successful; otherwise returns false.

   880 

   881     The \a quality factor must be in the range [0,100] or -1. Specify

   882     0 to obtain small compressed files, 100 for large uncompressed

   883     files, and -1 to use the default settings.

   884 

   885     If \a format is 0, an image format will be chosen from \a fileName's

   886     suffix.

   887 

   888     \sa {QPixmap#Reading and Writing Image Files}{Reading and Writing

   889     Image Files}

   890 */

   891 

   892 bool QPixmap::save(const QString &fileName, const char *format, int quality) const

   893 {

   894     if (isNull())

   895         return false;                                // nothing to save

   896     QImageWriter writer(fileName, format);

   897     return doImageIO(&writer, quality);

   898 }

   899 

   900 /*!

   901     \overload

   902 

   903     This function writes a QPixmap to the given \a device using the

   904     specified image file \a format and \a quality factor. This can be

   905     used, for example, to save a pixmap directly into a QByteArray:

   906 

   907     \snippet doc/src/snippets/image/image.cpp 1

   908 */

   909 

   910 bool QPixmap::save(QIODevice* device, const char* format, int quality) const

   911 {

   912     if (isNull())

   913         return false;                                // nothing to save

   914     QImageWriter writer(device, format);

   915     return doImageIO(&writer, quality);

   916 }

   917 

   918 /*! \internal

   919 */

   920 bool QPixmap::doImageIO(QImageWriter *writer, int quality) const

   921 {

   922     if (quality > 100  || quality < -1)

   923         qWarning("QPixmap::save: quality out of range [-1,100]");

   924     if (quality >= 0)

   925         writer->setQuality(qMin(quality,100));

   926     return writer->write(toImage());

   927 }

   928 

   929 

   930 // The implementation (and documentation) of

   931 // QPixmap::fill(const QWidget *, const QPoint &)

   932 // is in qwidget.cpp

   933 

   934 /*!

   935     \fn void QPixmap::fill(const QWidget *widget, int x, int y)

   936     \overload

   937 

   938     Fills the pixmap with the \a widget's background color or pixmap.

   939     The given point, (\a x, \a y), defines an offset in widget

   940     coordinates to which the pixmap's top-left pixel will be mapped

   941     to.

   942 */

   943 

   944 /*!

   945     Fills the pixmap with the given \a color.

   946 

   947     The effect of this function is undefined when the pixmap is

   948     being painted on.

   949 

   950     \sa {QPixmap#Pixmap Transformations}{Pixmap Transformations}

   951 */

   952 

   953 void QPixmap::fill(const QColor &color)

   954 {

   955     if (isNull())

   956         return;

   957 

   958     // Some people are probably already calling fill while a painter is active, so to not break

   959     // their programs, only print a warning and return when the fill operation could cause a crash.

   960     if (paintingActive() && (color.alpha() != 255) && !hasAlphaChannel()) {

   961         qWarning("QPixmap::fill: Cannot fill while pixmap is being painted on");

   962         return;

   963     }

   964 

   965     if (data->ref == 1) {

   966         // detach() will also remove this pixmap from caches, so

   967         // it has to be called even when ref == 1.

   968         detach();

   969     } else {

   970         // Don't bother to make a copy of the data object, since

   971         // it will be filled with new pixel data anyway.

   972         QPixmapData *d = data->createCompatiblePixmapData();

   973         d->resize(data->width(), data->height());

   974         data = d;

   975     }

   976     data->fill(color);

   977 }

   978 

   979 /*! \obsolete

   980     Returns a number that identifies the contents of this QPixmap

   981     object. Distinct QPixmap objects can only have the same serial

   982     number if they refer to the same contents (but they don't have

   983     to).

   984 

   985     Use cacheKey() instead.

   986 

   987     \warning The serial number doesn't necessarily change when

   988     the pixmap is altered. This means that it may be dangerous to use

   989     it as a cache key. For caching pixmaps, we recommend using the

   990     QPixmapCache class whenever possible.

   991 */

   992 int QPixmap::serialNumber() const

   993 {

   994     if (isNull())

   995         return 0;

   996     return data->serialNumber();

   997 }

   998 

   999 /*!

  1000     Returns a number that identifies this QPixmap. Distinct QPixmap

  1001     objects can only have the same cache key if they refer to the same

  1002     contents.

  1003 

  1004     The cacheKey() will change when the pixmap is altered.

  1005 */

  1006 qint64 QPixmap::cacheKey() const

  1007 {

  1008     int classKey = data->classId();

  1009     if (classKey >= 1024)

  1010         classKey = -(classKey >> 10);

  1011     return ((((qint64) classKey) << 56)

  1012             | (((qint64) data->serialNumber()) << 32)

  1013             | ((qint64) (data->detach_no)));

  1014 }

  1015 

  1016 static void sendResizeEvents(QWidget *target)

  1017 {

  1018     QResizeEvent e(target->size(), QSize());

  1019     QApplication::sendEvent(target, &e);

  1020 

  1021     const QObjectList children = target->children();

  1022     for (int i = 0; i < children.size(); ++i) {

  1023         QWidget *child = static_cast<QWidget*>(children.at(i));

  1024         if (child->isWidgetType() && !child->isWindow() && child->testAttribute(Qt::WA_PendingResizeEvent))

  1025             sendResizeEvents(child);

  1026     }

  1027 }

  1028 

  1029 /*!

  1030     \fn QPixmap QPixmap::grabWidget(QWidget * widget, const QRect &rectangle)

  1031 

  1032     Creates a pixmap and paints the given \a widget, restricted by the

  1033     given \a rectangle, in it. If the \a widget has any children, then

  1034     they are also painted in the appropriate positions.

  1035 

  1036     If no rectangle is specified (the default) the entire widget is

  1037     painted.

  1038 

  1039     If \a widget is 0, the specified rectangle doesn't overlap the

  1040     widget's rectangle, or an error occurs, the function will return a

  1041     null QPixmap.  If the rectangle is a superset of the given \a

  1042     widget, the areas outside the \a widget are covered with the

  1043     widget's background.

  1044 

  1045     This function actually asks \a widget to paint itself (and its

  1046     children to paint themselves) by calling paintEvent() with painter

  1047     redirection turned on. But QPixmap also provides the grabWindow()

  1048     function which is a bit faster by grabbing pixels directly off the

  1049     screen. In addition, if there are overlaying windows,

  1050     grabWindow(), unlike grabWidget(), will see them.

  1051 

  1052     \warning Do not grab a widget from its QWidget::paintEvent().

  1053     However, it is safe to grab a widget from another widget's

  1054     \l {QWidget::}{paintEvent()}.

  1055 

  1056     \sa grabWindow()

  1057 */

  1058 

  1059 QPixmap QPixmap::grabWidget(QWidget * widget, const QRect &rect)

  1060 {

  1061     if (!widget)

  1062         return QPixmap();

  1063 

  1064     if (widget->testAttribute(Qt::WA_PendingResizeEvent) || !widget->testAttribute(Qt::WA_WState_Created))

  1065         sendResizeEvents(widget);

  1066 

  1067     QRect r(rect);

  1068     if (r.width() < 0)

  1069         r.setWidth(widget->width() - rect.x());

  1070     if (r.height() < 0)

  1071         r.setHeight(widget->height() - rect.y());

  1072 

  1073     if (!r.intersects(widget->rect()))

  1074         return QPixmap();

  1075 

  1076     QPixmap res(r.size());

  1077     widget->render(&res, QPoint(), r,

  1078                    QWidget::DrawWindowBackground | QWidget::DrawChildren | QWidget::IgnoreMask);

  1079     return res;

  1080 }

  1081 

  1082 /*!

  1083     \fn QPixmap QPixmap::grabWidget(QWidget *widget, int x, int y, int

  1084     width, int height)

  1085 

  1086     \overload

  1087 

  1088     Creates a pixmap and paints the given \a widget, restricted by

  1089     QRect(\a x, \a y, \a width, \a height), in it.

  1090 

  1091     \warning Do not grab a widget from its QWidget::paintEvent().

  1092     However, it is safe to grab a widget from another widget's

  1093     \l {QWidget::}{paintEvent()}.

  1094 */

  1095 

  1096 

  1097 /*!

  1098     \since 4.5

  1099 

  1100     \enum QPixmap::ShareMode

  1101 

  1102     This enum type defines the share modes that are available when

  1103     creating a QPixmap object from a raw X11 Pixmap handle.

  1104 

  1105     \value ImplicitlyShared  This mode will cause the QPixmap object to

  1106     create a copy of the internal data before it is modified, thus

  1107     keeping the original X11 pixmap intact.

  1108 

  1109     \value ExplicitlyShared  In this mode, the pixmap data will \e not be

  1110     copied before it is modified, which in effect will change the

  1111     original X11 pixmap.

  1112 

  1113     \warning This enum is only used for X11 specific functions; using

  1114     it is non-portable.

  1115 

  1116     \sa QPixmap::fromX11Pixmap()

  1117 */

  1118 

  1119 /*!

  1120     \since 4.5

  1121 

  1122     \fn QPixmap QPixmap::fromX11Pixmap(Qt::HANDLE pixmap, QPixmap::ShareMode mode)

  1123 

  1124     Creates a QPixmap from the native X11 Pixmap handle \a pixmap,

  1125     using \a mode as the share mode. The default share mode is

  1126     QPixmap::ImplicitlyShared, which means that a copy of the pixmap is

  1127     made if someone tries to modify it by e.g. drawing onto it.

  1128 

  1129     QPixmap does \e not take ownership of the \a pixmap handle, and

  1130     have to be deleted by the user.

  1131 

  1132     \warning This function is X11 specific; using it is non-portable.

  1133 

  1134     \sa QPixmap::ShareMode