1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the QtGui module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 or version 3 as published by the Free
20 ** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21 ** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22 ** following information to ensure the GNU Lesser General Public License
23 ** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 **
26 ** As a special exception, The Qt Company gives you certain additional
27 ** rights. These rights are described in The Qt Company LGPL Exception
28 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 **
30 ** GNU General Public License Usage
31 ** Alternatively, this file may be used under the terms of the GNU
32 ** General Public License version 3.0 as published by the Free Software
33 ** Foundation and appearing in the file LICENSE.GPL included in the
34 ** packaging of this file. Please review the following information to
35 ** ensure the GNU General Public License version 3.0 requirements will be
36 ** met: http://www.gnu.org/copyleft/gpl.html.
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 #ifdef Q_WS_QPA
75 # include "qplatformintegration_qpa.h"
76 #endif
77
78 #if defined(Q_WS_X11)
79 # include "qx11info_x11.h"
80 # include <private/qt_x11_p.h>
81 # include <private/qpixmap_x11_p.h>
82 #endif
83
84 #if defined(Q_OS_SYMBIAN)
85 # include <private/qt_s60_p.h>
86 #endif
87
88 #include "qpixmap_raster_p.h"
89 #include "private/qstylehelper_p.h"
90
91 QT_BEGIN_NAMESPACE
92
93 // ### Qt 5: remove
qt_pixmap_id(const QPixmap & pixmap)94 Q_GUI_EXPORT qint64 qt_pixmap_id(const QPixmap &pixmap)
95 {
96 return pixmap.cacheKey();
97 }
98
qt_pixmap_thread_test()99 static bool qt_pixmap_thread_test()
100 {
101 if (!qApp) {
102 qFatal("QPixmap: Must construct a QApplication before a QPaintDevice");
103 return false;
104 }
105
106 if (qApp->thread() != QThread::currentThread()) {
107 bool fail = false;
108 #if defined (Q_WS_X11)
109 if (!QApplication::testAttribute(Qt::AA_X11InitThreads))
110 fail = true;
111 #elif defined (Q_WS_QPA)
112 if (!QApplicationPrivate::platformIntegration()->hasCapability(QPlatformIntegration::ThreadedPixmaps)) {
113 printf("Lighthouse plugin does not support threaded pixmaps!\n");
114 fail = true;
115 }
116 #else
117 if (QApplicationPrivate::graphics_system_name != QLatin1String("raster"))
118 fail = true;
119 #endif
120 if (fail) {
121 qWarning("QPixmap: It is not safe to use pixmaps outside the GUI thread");
122 return false;
123 }
124 }
125 return true;
126 }
127
init(int w,int h,Type type)128 void QPixmap::init(int w, int h, Type type)
129 {
130 init(w, h, int(type));
131 }
132
133 extern QApplication::Type qt_appType;
134
init(int w,int h,int type)135 void QPixmap::init(int w, int h, int type)
136 {
137 if ((w > 0 && h > 0) || type == QPixmapData::BitmapType)
138 data = QPixmapData::create(w, h, (QPixmapData::PixelType) type);
139 else
140 data = 0;
141 }
142
143 /*!
144 \enum QPixmap::ColorMode
145
146 \compat
147
148 This enum type defines the color modes that exist for converting
149 QImage objects to QPixmap. It is provided here for compatibility
150 with earlier versions of Qt.
151
152 Use Qt::ImageConversionFlags instead.
153
154 \value Auto Select \c Color or \c Mono on a case-by-case basis.
155 \value Color Always create colored pixmaps.
156 \value Mono Always create bitmaps.
157 */
158
159 /*!
160 Constructs a null pixmap.
161
162 \sa isNull()
163 */
164
QPixmap()165 QPixmap::QPixmap()
166 : QPaintDevice()
167 {
168 (void) qt_pixmap_thread_test();
169 init(0, 0, QPixmapData::PixmapType);
170 }
171
172 /*!
173 \fn QPixmap::QPixmap(int width, int height)
174
175 Constructs a pixmap with the given \a width and \a height. If
176 either \a width or \a height is zero, a null pixmap is
177 constructed.
178
179 \warning This will create a QPixmap with uninitialized data. Call
180 fill() to fill the pixmap with an appropriate color before drawing
181 onto it with QPainter.
182
183 \sa isNull()
184 */
185
QPixmap(int w,int h)186 QPixmap::QPixmap(int w, int h)
187 : QPaintDevice()
188 {
189 if (!qt_pixmap_thread_test())
190 init(0, 0, QPixmapData::PixmapType);
191 else
192 init(w, h, QPixmapData::PixmapType);
193 }
194
195 /*!
196 \overload
197
198 Constructs a pixmap of the given \a size.
199
200 \warning This will create a QPixmap with uninitialized data. Call
201 fill() to fill the pixmap with an appropriate color before drawing
202 onto it with QPainter.
203 */
204
QPixmap(const QSize & size)205 QPixmap::QPixmap(const QSize &size)
206 : QPaintDevice()
207 {
208 if (!qt_pixmap_thread_test())
209 init(0, 0, QPixmapData::PixmapType);
210 else
211 init(size.width(), size.height(), QPixmapData::PixmapType);
212 }
213
214 /*!
215 \internal
216 */
QPixmap(const QSize & s,Type type)217 QPixmap::QPixmap(const QSize &s, Type type)
218 {
219 if (!qt_pixmap_thread_test())
220 init(0, 0, type);
221 else
222 init(s.width(), s.height(), type);
223 }
224
225 /*!
226 \internal
227 */
QPixmap(const QSize & s,int type)228 QPixmap::QPixmap(const QSize &s, int type)
229 {
230 if (!qt_pixmap_thread_test())
231 init(0, 0, static_cast<QPixmapData::PixelType>(type));
232 else
233 init(s.width(), s.height(), static_cast<QPixmapData::PixelType>(type));
234 }
235
236 /*!
237 \internal
238 */
QPixmap(QPixmapData * d)239 QPixmap::QPixmap(QPixmapData *d)
240 : QPaintDevice(), data(d)
241 {
242 }
243
244 /*!
245 Constructs a pixmap from the file with the given \a fileName. If the
246 file does not exist or is of an unknown format, the pixmap becomes a
247 null pixmap.
248
249 The loader attempts to read the pixmap using the specified \a
250 format. If the \a format is not specified (which is the default),
251 the loader probes the file for a header to guess the file format.
252
253 The file name can either refer to an actual file on disk or to
254 one of the application's embedded resources. See the
255 \l{resources.html}{Resource System} overview for details on how
256 to embed images and other resource files in the application's
257 executable.
258
259 If the image needs to be modified to fit in a lower-resolution
260 result (e.g. converting from 32-bit to 8-bit), use the \a
261 flags to control the conversion.
262
263 The \a fileName, \a format and \a flags parameters are
264 passed on to load(). This means that the data in \a fileName is
265 not compiled into the binary. If \a fileName contains a relative
266 path (e.g. the filename only) the relevant file must be found
267 relative to the runtime working directory.
268
269 \sa {QPixmap#Reading and Writing Image Files}{Reading and Writing
270 Image Files}
271 */
272
QPixmap(const QString & fileName,const char * format,Qt::ImageConversionFlags flags)273 QPixmap::QPixmap(const QString& fileName, const char *format, Qt::ImageConversionFlags flags)
274 : QPaintDevice()
275 {
276 init(0, 0, QPixmapData::PixmapType);
277 if (!qt_pixmap_thread_test())
278 return;
279
280 load(fileName, format, flags);
281 }
282
283 /*!
284 Constructs a pixmap that is a copy of the given \a pixmap.
285
286 \sa copy()
287 */
288
QPixmap(const QPixmap & pixmap)289 QPixmap::QPixmap(const QPixmap &pixmap)
290 : QPaintDevice()
291 {
292 if (!qt_pixmap_thread_test()) {
293 init(0, 0, QPixmapData::PixmapType);
294 return;
295 }
296 if (pixmap.paintingActive()) { // make a deep copy
297 operator=(pixmap.copy());
298 } else {
299 data = pixmap.data;
300 }
301 }
302
303 /*!
304 Constructs a pixmap from the given \a xpm data, which must be a
305 valid XPM image.
306
307 Errors are silently ignored.
308
309 Note that it's possible to squeeze the XPM variable a little bit
310 by using an unusual declaration:
311
312 \snippet doc/src/snippets/code/src_gui_image_qpixmap.cpp 0
313
314 The extra \c const makes the entire definition read-only, which is
315 slightly more efficient (for example, when the code is in a shared
316 library) and ROMable when the application is to be stored in ROM.
317 */
318 #ifndef QT_NO_IMAGEFORMAT_XPM
QPixmap(const char * const xpm[])319 QPixmap::QPixmap(const char * const xpm[])
320 : QPaintDevice()
321 {
322 init(0, 0, QPixmapData::PixmapType);
323 if (!xpm)
324 return;
325
326 QImage image(xpm);
327 if (!image.isNull()) {
328 if (data && data->pixelType() == QPixmapData::BitmapType)
329 *this = QBitmap::fromImage(image);
330 else
331 *this = fromImage(image);
332 }
333 }
334 #endif
335
336
337 /*!
338 Destroys the pixmap.
339 */
340
~QPixmap()341 QPixmap::~QPixmap()
342 {
343 Q_ASSERT(!data || data->ref >= 1); // Catch if ref-counting changes again
344 }
345
346 /*!
347 \internal
348 */
devType() const349 int QPixmap::devType() const
350 {
351 return QInternal::Pixmap;
352 }
353
354 /*!
355 \fn QPixmap QPixmap::copy(int x, int y, int width, int height) const
356 \overload
357
358 Returns a deep copy of the subset of the pixmap that is specified
359 by the rectangle QRect( \a x, \a y, \a width, \a height).
360 */
361
362 /*!
363 \fn QPixmap QPixmap::copy(const QRect &rectangle) const
364
365 Returns a deep copy of the subset of the pixmap that is specified
366 by the given \a rectangle. For more information on deep copies,
367 see the \l {Implicit Data Sharing} documentation.
368
369 If the given \a rectangle is empty, the whole image is copied.
370
371 \sa operator=(), QPixmap(), {QPixmap#Pixmap
372 Transformations}{Pixmap Transformations}
373 */
copy(const QRect & rect) const374 QPixmap QPixmap::copy(const QRect &rect) const
375 {
376 if (isNull())
377 return QPixmap();
378
379 QRect r(0, 0, width(), height());
380 if (!rect.isEmpty())
381 r = r.intersected(rect);
382
383 QPixmapData *d = data->createCompatiblePixmapData();
384 d->copy(data.data(), r);
385 return QPixmap(d);
386 }
387
388 /*!
389 \fn QPixmap::scroll(int dx, int dy, int x, int y, int width, int height, QRegion *exposed)
390 \since 4.6
391
392 This convenience function is equivalent to calling QPixmap::scroll(\a dx,
393 \a dy, QRect(\a x, \a y, \a width, \a height), \a exposed).
394
395 \sa QWidget::scroll(), QGraphicsItem::scroll()
396 */
397
398 /*!
399 \since 4.6
400
401 Scrolls the area \a rect of this pixmap by (\a dx, \a dy). The exposed
402 region is left unchanged. You can optionally pass a pointer to an empty
403 QRegion to get the region that is \a exposed by the scroll operation.
404
405 \snippet doc/src/snippets/code/src_gui_image_qpixmap.cpp 2
406
407 You cannot scroll while there is an active painter on the pixmap.
408
409 \sa QWidget::scroll(), QGraphicsItem::scroll()
410 */
scroll(int dx,int dy,const QRect & rect,QRegion * exposed)411 void QPixmap::scroll(int dx, int dy, const QRect &rect, QRegion *exposed)
412 {
413 if (isNull() || (dx == 0 && dy == 0))
414 return;
415 QRect dest = rect & this->rect();
416 QRect src = dest.translated(-dx, -dy) & dest;
417 if (src.isEmpty()) {
418 if (exposed)
419 *exposed += dest;
420 return;
421 }
422
423 detach();
424
425 if (!data->scroll(dx, dy, src)) {
426 // Fallback
427 QPixmap pix = *this;
428 QPainter painter(&pix);
429 painter.setCompositionMode(QPainter::CompositionMode_Source);
430 painter.drawPixmap(src.translated(dx, dy), *this, src);
431 painter.end();
432 *this = pix;
433 }
434
435 if (exposed) {
436 *exposed += dest;
437 *exposed -= src.translated(dx, dy);
438 }
439 }
440
441 /*!
442 Assigns the given \a pixmap to this pixmap and returns a reference
443 to this pixmap.
444
445 \sa copy(), QPixmap()
446 */
447
operator =(const QPixmap & pixmap)448 QPixmap &QPixmap::operator=(const QPixmap &pixmap)
449 {
450 if (paintingActive()) {
451 qWarning("QPixmap::operator=: Cannot assign to pixmap during painting");
452 return *this;
453 }
454 if (pixmap.paintingActive()) { // make a deep copy
455 *this = pixmap.copy();
456 } else {
457 data = pixmap.data;
458 }
459 return *this;
460 }
461
462 /*!
463 \fn void QPixmap::swap(QPixmap &other)
464 \since 4.8
465
466 Swaps pixmap \a other with this pixmap. This operation is very
467 fast and never fails.
468 */
469
470 /*!
471 Returns the pixmap as a QVariant.
472 */
operator QVariant() const473 QPixmap::operator QVariant() const
474 {
475 return QVariant(QVariant::Pixmap, this);
476 }
477
478 /*!
479 \fn bool QPixmap::operator!() const
480
481 Returns true if this is a null pixmap; otherwise returns false.
482
483 \sa isNull()
484 */
485
486 /*!
487 \fn QPixmap::operator QImage() const
488
489 Returns the pixmap as a QImage.
490
491 Use the toImage() function instead.
492 */
493
494 /*!
495 Converts the pixmap to a QImage. Returns a null image if the
496 conversion fails.
497
498 If the pixmap has 1-bit depth, the returned image will also be 1
499 bit deep. Images with more bits will be returned in a format
500 closely represents the underlying system. Usually this will be
501 QImage::Format_ARGB32_Premultiplied for pixmaps with an alpha and
502 QImage::Format_RGB32 or QImage::Format_RGB16 for pixmaps without
503 alpha.
504
505 Note that for the moment, alpha masks on monochrome images are
506 ignored.
507
508 \sa fromImage(), {QImage#Image Formats}{Image Formats}
509 */
toImage() const510 QImage QPixmap::toImage() const
511 {
512 if (isNull())
513 return QImage();
514
515 return data->toImage();
516 }
517
518 /*!
519 \fn QMatrix QPixmap::trueMatrix(const QTransform &matrix, int width, int height)
520
521 Returns the actual matrix used for transforming a pixmap with the
522 given \a width, \a height and \a matrix.
523
524 When transforming a pixmap using the transformed() function, the
525 transformation matrix is internally adjusted to compensate for
526 unwanted translation, i.e. transformed() returns the smallest
527 pixmap containing all transformed points of the original
528 pixmap. This function returns the modified matrix, which maps
529 points correctly from the original pixmap into the new pixmap.
530
531 \sa transformed(), {QPixmap#Pixmap Transformations}{Pixmap
532 Transformations}
533 */
trueMatrix(const QTransform & m,int w,int h)534 QTransform QPixmap::trueMatrix(const QTransform &m, int w, int h)
535 {
536 return QImage::trueMatrix(m, w, h);
537 }
538
539 /*!
540 \overload
541
542 This convenience function loads the matrix \a m into a
543 QTransform and calls the overloaded function with the
544 QTransform and the width \a w and the height \a h.
545 */
trueMatrix(const QMatrix & m,int w,int h)546 QMatrix QPixmap::trueMatrix(const QMatrix &m, int w, int h)
547 {
548 return trueMatrix(QTransform(m), w, h).toAffine();
549 }
550
551
552 /*!
553 \fn bool QPixmap::isQBitmap() const
554
555 Returns true if this is a QBitmap; otherwise returns false.
556 */
557
isQBitmap() const558 bool QPixmap::isQBitmap() const
559 {
560 return data->type == QPixmapData::BitmapType;
561 }
562
563 /*!
564 \fn bool QPixmap::isNull() const
565
566 Returns true if this is a null pixmap; otherwise returns false.
567
568 A null pixmap has zero width, zero height and no contents. You
569 cannot draw in a null pixmap.
570 */
isNull() const571 bool QPixmap::isNull() const
572 {
573 return !data || data->isNull();
574 }
575
576 /*!
577 \fn int QPixmap::width() const
578
579 Returns the width of the pixmap.
580
581 \sa size(), {QPixmap#Pixmap Information}{Pixmap Information}
582 */
width() const583 int QPixmap::width() const
584 {
585 return data ? data->width() : 0;
586 }
587
588 /*!
589 \fn int QPixmap::height() const
590
591 Returns the height of the pixmap.
592
593 \sa size(), {QPixmap#Pixmap Information}{Pixmap Information}
594 */
height() const595 int QPixmap::height() const
596 {
597 return data ? data->height() : 0;
598 }
599
600 /*!
601 \fn QSize QPixmap::size() const
602
603 Returns the size of the pixmap.
604
605 \sa width(), height(), {QPixmap#Pixmap Information}{Pixmap
606 Information}
607 */
size() const608 QSize QPixmap::size() const
609 {
610 return data ? QSize(data->width(), data->height()) : QSize(0, 0);
611 }
612
613 /*!
614 \fn QRect QPixmap::rect() const
615
616 Returns the pixmap's enclosing rectangle.
617
618 \sa {QPixmap#Pixmap Information}{Pixmap Information}
619 */
rect() const620 QRect QPixmap::rect() const
621 {
622 return data ? QRect(0, 0, data->width(), data->height()) : QRect();
623 }
624
625 /*!
626 \fn int QPixmap::depth() const
627
628 Returns the depth of the pixmap.
629
630 The pixmap depth is also called bits per pixel (bpp) or bit planes
631 of a pixmap. A null pixmap has depth 0.
632
633 \sa defaultDepth(), {QPixmap#Pixmap Information}{Pixmap
634 Information}
635 */
depth() const636 int QPixmap::depth() const
637 {
638 return data ? data->depth() : 0;
639 }
640
641 /*!
642 \fn void QPixmap::resize(const QSize &size)
643 \overload
644 \compat
645
646 Use QPixmap::copy() instead to get the pixmap with the new size.
647
648 \oldcode
649 pixmap.resize(size);
650 \newcode
651 pixmap = pixmap.copy(QRect(QPoint(0, 0), size));
652 \endcode
653 */
654 #ifdef QT3_SUPPORT
resize_helper(const QSize & s)655 void QPixmap::resize_helper(const QSize &s)
656 {
657 int w = s.width();
658 int h = s.height();
659 if (w < 1 || h < 1) {
660 *this = QPixmap();
661 return;
662 }
663
664 if (size() == s)
665 return;
666
667 // QPixmap.data member may be QRuntimePixmapData so use pixmapData() function to get
668 // the actual underlaying runtime pixmap data.
669 QPixmapData *pd = pixmapData();
670
671 // Create new pixmap
672 QPixmap pm(QSize(w, h), pd ? pd->type : QPixmapData::PixmapType);
673 bool uninit = false;
674 #if defined(Q_WS_X11)
675 QX11PixmapData *x11Data = pd && pd->classId() == QPixmapData::X11Class ? static_cast<QX11PixmapData*>(pd) : 0;
676 if (x11Data) {
677 pm.x11SetScreen(x11Data->xinfo.screen());
678 uninit = x11Data->flags & QX11PixmapData::Uninitialized;
679 }
680 #elif defined(Q_WS_MAC)
681 QMacPixmapData *macData = pd && pd->classId() == QPixmapData::MacClass ? static_cast<QMacPixmapData*>(pd) : 0;
682 if (macData)
683 uninit = macData->uninit;
684 #endif
685 if (!uninit && !isNull()) {
686 // Copy old pixmap
687 if (hasAlphaChannel())
688 pm.fill(Qt::transparent);
689 QPainter p(&pm);
690 p.drawPixmap(0, 0, *this, 0, 0, qMin(width(), w), qMin(height(), h));
691 }
692
693 #if defined(Q_WS_X11)
694 if (x11Data && x11Data->x11_mask) {
695 QPixmapData *newPd = pm.pixmapData();
696 QX11PixmapData *pmData = (newPd && newPd->classId() == QPixmapData::X11Class)
697 ? static_cast<QX11PixmapData*>(newPd) : 0;
698 if (pmData) {
699 pmData->x11_mask = (Qt::HANDLE)XCreatePixmap(X11->display,
700 RootWindow(x11Data->xinfo.display(),
701 x11Data->xinfo.screen()),
702 w, h, 1);
703 GC gc = XCreateGC(X11->display, pmData->x11_mask, 0, 0);
704 XCopyArea(X11->display, x11Data->x11_mask, pmData->x11_mask, gc, 0, 0,
705 qMin(width(), w), qMin(height(), h), 0, 0);
706 XFreeGC(X11->display, gc);
707 }
708 }
709 #endif
710 *this = pm;
711 }
712 #endif
713
714 /*!
715 \fn void QPixmap::resize(int width, int height)
716 \compat
717
718 Use QPixmap::copy() instead to get the pixmap with the new size.
719
720 \oldcode
721 pixmap.resize(10, 20);
722 \newcode
723 pixmap = pixmap.copy(0, 0, 10, 20);
724 \endcode
725 */
726
727 /*!
728 \fn bool QPixmap::selfMask() const
729 \compat
730
731 Returns whether the pixmap is its own mask or not.
732
733 This function is no longer relevant since the concept of self
734 masking doesn't exists anymore.
735 */
736
737 /*!
738 Sets a mask bitmap.
739
740 This function merges the \a mask with the pixmap's alpha channel. A pixel
741 value of 1 on the mask means the pixmap's pixel is unchanged; a value of 0
742 means the pixel is transparent. The mask must have the same size as this
743 pixmap.
744
745 Setting a null mask resets the mask, leaving the previously transparent
746 pixels black. The effect of this function is undefined when the pixmap is
747 being painted on.
748
749 \warning This is potentially an expensive operation.
750
751 \sa mask(), {QPixmap#Pixmap Transformations}{Pixmap Transformations},
752 QBitmap
753 */
setMask(const QBitmap & mask)754 void QPixmap::setMask(const QBitmap &mask)
755 {
756 if (paintingActive()) {
757 qWarning("QPixmap::setMask: Cannot set mask while pixmap is being painted on");
758 return;
759 }
760
761 if (!mask.isNull() && mask.size() != size()) {
762 qWarning("QPixmap::setMask() mask size differs from pixmap size");
763 return;
764 }
765
766 if (isNull())
767 return;
768
769 if (static_cast<const QPixmap &>(mask).data == data) // trying to selfmask
770 return;
771
772 detach();
773 data->setMask(mask);
774 }
775
776 #ifndef QT_NO_IMAGE_HEURISTIC_MASK
777 /*!
778 Creates and returns a heuristic mask for this pixmap.
779
780 The function works by selecting a color from one of the corners
781 and then chipping away pixels of that color, starting at all the
782 edges. If \a clipTight is true (the default) the mask is just
783 large enough to cover the pixels; otherwise, the mask is larger
784 than the data pixels.
785
786 The mask may not be perfect but it should be reasonable, so you
787 can do things such as the following:
788
789 \snippet doc/src/snippets/code/src_gui_image_qpixmap.cpp 1
790
791 This function is slow because it involves converting to/from a
792 QImage, and non-trivial computations.
793
794 \sa QImage::createHeuristicMask(), createMaskFromColor()
795 */
createHeuristicMask(bool clipTight) const796 QBitmap QPixmap::createHeuristicMask(bool clipTight) const
797 {
798 QBitmap m = QBitmap::fromImage(toImage().createHeuristicMask(clipTight));
799 return m;
800 }
801 #endif
802
803 /*!
804 Creates and returns a mask for this pixmap based on the given \a
805 maskColor. If the \a mode is Qt::MaskInColor, all pixels matching the
806 maskColor will be transparent. If \a mode is Qt::MaskOutColor, all pixels
807 matching the maskColor will be opaque.
808
809 This function is slow because it involves converting to/from a
810 QImage.
811
812 \sa createHeuristicMask(), QImage::createMaskFromColor()
813 */
createMaskFromColor(const QColor & maskColor,Qt::MaskMode mode) const814 QBitmap QPixmap::createMaskFromColor(const QColor &maskColor, Qt::MaskMode mode) const
815 {
816 QImage image = toImage().convertToFormat(QImage::Format_ARGB32);
817 return QBitmap::fromImage(image.createMaskFromColor(maskColor.rgba(), mode));
818 }
819
820 /*! \overload
821
822 Creates and returns a mask for this pixmap based on the given \a
823 maskColor. Same as calling createMaskFromColor(maskColor,
824 Qt::MaskInColor)
825
826 \sa createHeuristicMask(), QImage::createMaskFromColor()
827 */
createMaskFromColor(const QColor & maskColor) const828 QBitmap QPixmap::createMaskFromColor(const QColor &maskColor) const
829 {
830 return createMaskFromColor(maskColor, Qt::MaskInColor);
831 }
832
833 /*!
834 Loads a pixmap from the file with the given \a fileName. Returns
835 true if the pixmap was successfully loaded; otherwise returns
836 false.
837
838 The loader attempts to read the pixmap using the specified \a
839 format. If the \a format is not specified (which is the default),
840 the loader probes the file for a header to guess the file format.
841
842 The file name can either refer to an actual file on disk or to one
843 of the application's embedded resources. See the
844 \l{resources.html}{Resource System} overview for details on how to
845 embed pixmaps and other resource files in the application's
846 executable.
847
848 If the data needs to be modified to fit in a lower-resolution
849 result (e.g. converting from 32-bit to 8-bit), use the \a flags to
850 control the conversion.
851
852 Note that QPixmaps are automatically added to the QPixmapCache
853 when loaded from a file; the key used is internal and can not
854 be acquired.
855
856 \sa loadFromData(), {QPixmap#Reading and Writing Image
857 Files}{Reading and Writing Image Files}
858 */
859
load(const QString & fileName,const char * format,Qt::ImageConversionFlags flags)860 bool QPixmap::load(const QString &fileName, const char *format, Qt::ImageConversionFlags flags)
861 {
862 if (fileName.isEmpty())
863 return false;
864
865 QFileInfo info(fileName);
866 QString key = QLatin1Literal("qt_pixmap")
867 % info.absoluteFilePath()
868 % HexString<uint>(info.lastModified().toTime_t())
869 % HexString<quint64>(info.size())
870 % HexString<uint>(data ? data->pixelType() : QPixmapData::PixmapType);
871
872 // Note: If no extension is provided, we try to match the
873 // file against known plugin extensions
874 if (!info.completeSuffix().isEmpty() && !info.exists())
875 return false;
876
877 if (QPixmapCache::find(key, *this))
878 return true;
879
880 QScopedPointer<QPixmapData> tmp(QPixmapData::create(0, 0, data ? data->type : QPixmapData::PixmapType));
881 if (tmp->fromFile(fileName, format, flags)) {
882 data = tmp.take();
883 QPixmapCache::insert(key, *this);
884 return true;
885 }
886
887 return false;
888 }
889
890 /*!
891 \fn bool QPixmap::loadFromData(const uchar *data, uint len, const char *format, Qt::ImageConversionFlags flags)
892
893 Loads a pixmap from the \a len first bytes of the given binary \a
894 data. Returns true if the pixmap was loaded successfully;
895 otherwise returns false.
896
897 The loader attempts to read the pixmap using the specified \a
898 format. If the \a format is not specified (which is the default),
899 the loader probes the file for a header to guess the file format.
900
901 If the data needs to be modified to fit in a lower-resolution
902 result (e.g. converting from 32-bit to 8-bit), use the \a flags to
903 control the conversion.
904
905 \sa load(), {QPixmap#Reading and Writing Image Files}{Reading and
906 Writing Image Files}
907 */
908
loadFromData(const uchar * buf,uint len,const char * format,Qt::ImageConversionFlags flags)909 bool QPixmap::loadFromData(const uchar *buf, uint len, const char *format, Qt::ImageConversionFlags flags)
910 {
911 if (len == 0 || buf == 0)
912 return false;
913
914 if (!data)
915 data = QPixmapData::create(0, 0, QPixmapData::PixmapType);
916
917 return data->fromData(buf, len, format, flags);
918 }
919
920 /*!
921 \fn bool QPixmap::loadFromData(const QByteArray &data, const char *format, Qt::ImageConversionFlags flags)
922
923 \overload
924
925 Loads a pixmap from the binary \a data using the specified \a
926 format and conversion \a flags.
927 */
928
929
930 /*!
931 Saves the pixmap to the file with the given \a fileName using the
932 specified image file \a format and \a quality factor. Returns true
933 if successful; otherwise returns false.
934
935 The \a quality factor must be in the range [0,100] or -1. Specify
936 0 to obtain small compressed files, 100 for large uncompressed
937 files, and -1 to use the default settings.
938
939 If \a format is 0, an image format will be chosen from \a fileName's
940 suffix.
941
942 \sa {QPixmap#Reading and Writing Image Files}{Reading and Writing
943 Image Files}
944 */
945
save(const QString & fileName,const char * format,int quality) const946 bool QPixmap::save(const QString &fileName, const char *format, int quality) const
947 {
948 if (isNull())
949 return false; // nothing to save
950 QImageWriter writer(fileName, format);
951 return doImageIO(&writer, quality);
952 }
953
954 /*!
955 \overload
956
957 This function writes a QPixmap to the given \a device using the
958 specified image file \a format and \a quality factor. This can be
959 used, for example, to save a pixmap directly into a QByteArray:
960
961 \snippet doc/src/snippets/image/image.cpp 1
962 */
963
save(QIODevice * device,const char * format,int quality) const964 bool QPixmap::save(QIODevice* device, const char* format, int quality) const
965 {
966 if (isNull())
967 return false; // nothing to save
968 QImageWriter writer(device, format);
969 return doImageIO(&writer, quality);
970 }
971
972 /*! \internal
973 */
doImageIO(QImageWriter * writer,int quality) const974 bool QPixmap::doImageIO(QImageWriter *writer, int quality) const
975 {
976 if (quality > 100 || quality < -1)
977 qWarning("QPixmap::save: quality out of range [-1,100]");
978 if (quality >= 0)
979 writer->setQuality(qMin(quality,100));
980 return writer->write(toImage());
981 }
982
983
984 // The implementation (and documentation) of
985 // QPixmap::fill(const QWidget *, const QPoint &)
986 // is in qwidget.cpp
987
988 /*!
989 \fn void QPixmap::fill(const QWidget *widget, int x, int y)
990 \overload
991
992 Fills the pixmap with the \a widget's background color or pixmap.
993 The given point, (\a x, \a y), defines an offset in widget
994 coordinates to which the pixmap's top-left pixel will be mapped
995 to.
996 */
997
998 /*!
999 Fills the pixmap with the given \a color.
1000
1001 The effect of this function is undefined when the pixmap is
1002 being painted on.
1003
1004 \sa {QPixmap#Pixmap Transformations}{Pixmap Transformations}
1005 */
1006
fill(const QColor & color)1007 void QPixmap::fill(const QColor &color)
1008 {
1009 if (isNull())
1010 return;
1011
1012 // Some people are probably already calling fill while a painter is active, so to not break
1013 // their programs, only print a warning and return when the fill operation could cause a crash.
1014 if (paintingActive() && (color.alpha() != 255) && !hasAlphaChannel()) {
1015 qWarning("QPixmap::fill: Cannot fill while pixmap is being painted on");
1016 return;
1017 }
1018
1019 if (data->ref == 1) {
1020 // detach() will also remove this pixmap from caches, so
1021 // it has to be called even when ref == 1.
1022 detach();
1023 } else {
1024 // Don't bother to make a copy of the data object, since
1025 // it will be filled with new pixel data anyway.
1026 QPixmapData *d = data->createCompatiblePixmapData();
1027 d->resize(data->width(), data->height());
1028 data = d;
1029 }
1030 data->fill(color);
1031 }
1032
1033 /*! \obsolete
1034 Returns a number that identifies the contents of this QPixmap
1035 object. Distinct QPixmap objects can only have the same serial
1036 number if they refer to the same contents (but they don't have
1037 to).
1038
1039 Use cacheKey() instead.
1040
1041 \warning The serial number doesn't necessarily change when
1042 the pixmap is altered. This means that it may be dangerous to use
1043 it as a cache key. For caching pixmaps, we recommend using the
1044 QPixmapCache class whenever possible.
1045 */
serialNumber() const1046 int QPixmap::serialNumber() const
1047 {
1048 if (isNull())
1049 return 0;
1050 return data->serialNumber();
1051 }
1052
1053 /*!
1054 Returns a number that identifies this QPixmap. Distinct QPixmap
1055 objects can only have the same cache key if they refer to the same
1056 contents.
1057
1058 The cacheKey() will change when the pixmap is altered.
1059 */
cacheKey() const1060 qint64 QPixmap::cacheKey() const
1061 {
1062 if (isNull())
1063 return 0;
1064
1065 Q_ASSERT(data);
1066 return data->cacheKey();
1067 }
1068
sendResizeEvents(QWidget * target)1069 static void sendResizeEvents(QWidget *target)
1070 {
1071 QResizeEvent e(target->size(), QSize());
1072 QApplication::sendEvent(target, &e);
1073
1074 const QObjectList children = target->children();
1075 for (int i = 0; i < children.size(); ++i) {
1076 QWidget *child = static_cast<QWidget*>(children.at(i));
1077 if (child->isWidgetType() && !child->isWindow() && child->testAttribute(Qt::WA_PendingResizeEvent))
1078 sendResizeEvents(child);
1079 }
1080 }
1081
1082 /*!
1083 \fn QPixmap QPixmap::grabWidget(QWidget * widget, const QRect &rectangle)
1084
1085 Creates a pixmap and paints the given \a widget, restricted by the
1086 given \a rectangle, in it. If the \a widget has any children, then
1087 they are also painted in the appropriate positions.
1088
1089 If no rectangle is specified (the default) the entire widget is
1090 painted.
1091
1092 If \a widget is 0, the specified rectangle doesn't overlap the
1093 widget's rectangle, or an error occurs, the function will return a
1094 null QPixmap. If the rectangle is a superset of the given \a
1095 widget, the areas outside the \a widget are covered with the
1096 widget's background.
1097
1098 This function actually asks \a widget to paint itself (and its
1099 children to paint themselves) by calling paintEvent() with painter
1100 redirection turned on. But QPixmap also provides the grabWindow()
1101 function which is a bit faster by grabbing pixels directly off the
1102 screen. In addition, if there are overlaying windows,
1103 grabWindow(), unlike grabWidget(), will see them.
1104
1105 \warning Do not grab a widget from its QWidget::paintEvent().
1106 However, it is safe to grab a widget from another widget's
1107 \l {QWidget::}{paintEvent()}.
1108
1109 \sa grabWindow()
1110 */
1111
grabWidget(QWidget * widget,const QRect & rect)1112 QPixmap QPixmap::grabWidget(QWidget * widget, const QRect &rect)
1113 {
1114 if (!widget)
1115 return QPixmap();
1116
1117 if (widget->testAttribute(Qt::WA_PendingResizeEvent) || !widget->testAttribute(Qt::WA_WState_Created))
1118 sendResizeEvents(widget);
1119
1120 widget->d_func()->prepareToRender(QRegion(),
1121 QWidget::DrawWindowBackground | QWidget::DrawChildren | QWidget::IgnoreMask);
1122
1123 QRect r(rect);
1124 if (r.width() < 0)
1125 r.setWidth(widget->width() - rect.x());
1126 if (r.height() < 0)
1127 r.setHeight(widget->height() - rect.y());
1128
1129 if (!r.intersects(widget->rect()))
1130 return QPixmap();
1131
1132 QPixmap res(r.size());
1133 if (!qt_widget_private(widget)->isOpaque)
1134 res.fill(Qt::transparent);
1135
1136 widget->d_func()->render(&res, QPoint(), r, QWidget::DrawWindowBackground
1137 | QWidget::DrawChildren | QWidget::IgnoreMask, true);
1138 return res;
1139 }
1140
1141 /*!
1142 \fn QPixmap QPixmap::grabWidget(QWidget *widget, int x, int y, int
1143 width, int height)
1144
1145 \overload
1146
1147 Creates a pixmap and paints the given \a widget, restricted by
1148 QRect(\a x, \a y, \a width, \a height), in it.
1149
1150 \warning Do not grab a widget from its QWidget::paintEvent().
1151 However, it is safe to grab a widget from another widget's
1152 \l {QWidget::}{paintEvent()}.
1153 */
1154
1155
1156 /*!
1157 \since 4.5
1158
1159 \enum QPixmap::ShareMode
1160
1161 This enum type defines the share modes that are available when
1162 creating a QPixmap object from a raw X11 Pixmap handle.
1163
1164 \value ImplicitlyShared This mode will cause the QPixmap object to
1165 create a copy of the internal data before it is modified, thus
1166 keeping the original X11 pixmap intact.
1167
1168 \value ExplicitlyShared In this mode, the pixmap data will \e not be
1169 copied before it is modified, which in effect will change the
1170 original X11 pixmap.
1171
1172 \warning This enum is only used for X11 specific functions; using
1173 it is non-portable.
1174
1175 \sa QPixmap::fromX11Pixmap()
1176 */
1177
1178 /*!
1179 \since 4.5
1180
1181 \fn QPixmap QPixmap::fromX11Pixmap(Qt::HANDLE pixmap, QPixmap::ShareMode mode)
1182
1183 Creates a QPixmap from the native X11 Pixmap handle \a pixmap,
1184 using \a mode as the share mode. The default share mode is
1185 QPixmap::ImplicitlyShared, which means that a copy of the pixmap is
1186 made if someone tries to modify it by e.g. drawing onto it.
1187
1188 QPixmap does \e not take ownership of the \a pixmap handle, and
1189 have to be deleted by the user.
1190
1191 \warning This function is X11 specific; using it is non-portable.
1192
1193 \sa QPixmap::ShareMode
1194 */
1195
1196
1197 #if defined(Q_WS_X11) || defined(Q_WS_QWS)
1198
1199 /*!
1200 Returns the pixmap's handle to the device context.
1201
1202 Note that, since QPixmap make use of \l {Implicit Data
1203 Sharing}{implicit data sharing}, the detach() function must be
1204 called explicitly to ensure that only \e this pixmap's data is
1205 modified if the pixmap data is shared.
1206
1207 \warning This function is X11 specific; using it is non-portable.
1208
1209 \warning Since 4.8, pixmaps do not have an X11 handle unless
1210 created with \l {QPixmap::}{fromX11Pixmap()}, or if the native
1211 graphics system is explicitly enabled.
1212
1213 \sa detach()
1214 \sa QApplication::setGraphicsSystem()
1215 */
1216
handle() const1217 Qt::HANDLE QPixmap::handle() const
1218 {
1219 #if defined(Q_WS_X11)
1220 const QPixmapData *pd = pixmapData();
1221 if (pd && pd->classId() == QPixmapData::X11Class)
1222 return static_cast<const QX11PixmapData*>(pd)->handle();
1223 #endif
1224 return 0;
1225 }
1226 #endif
1227
1228
1229 #ifdef QT3_SUPPORT
colorModeToFlags(QPixmap::ColorMode mode)1230 static Qt::ImageConversionFlags colorModeToFlags(QPixmap::ColorMode mode)
1231 {
1232 Qt::ImageConversionFlags flags = Qt::AutoColor;
1233 switch (mode) {
1234 case QPixmap::Color:
1235 flags |= Qt::ColorOnly;
1236 break;
1237 case QPixmap::Mono:
1238 flags |= Qt::MonoOnly;
1239 break;
1240 default:
1241 break;// Nothing.
1242 }
1243 return flags;
1244 }
1245
1246 /*!
1247 Use the constructor that takes a Qt::ImageConversionFlag instead.
1248 */
1249
QPixmap(const QString & fileName,const char * format,ColorMode mode)1250 QPixmap::QPixmap(const QString& fileName, const char *format, ColorMode mode)
1251 : QPaintDevice()
1252 {
1253 init(0, 0, QPixmapData::PixmapType);
1254 if (!qt_pixmap_thread_test())
1255 return;
1256
1257 load(fileName, format, colorModeToFlags(mode));
1258 }
1259
1260 /*!
1261 Constructs a pixmap from the QImage \a image.
1262
1263 Use the static fromImage() function instead.
1264 */
QPixmap(const QImage & image)1265 QPixmap::QPixmap(const QImage& image)
1266 : QPaintDevice()
1267 {
1268 init(0, 0, QPixmapData::PixmapType);
1269 if (!qt_pixmap_thread_test())
1270 return;
1271
1272 if (data && data->pixelType() == QPixmapData::BitmapType)
1273 *this = QBitmap::fromImage(image);
1274 else
1275 *this = fromImage(image);
1276 }
1277
1278 /*!
1279 \overload
1280
1281 Converts the given \a image to a pixmap that is assigned to this
1282 pixmap.
1283
1284 Use the static fromImage() function instead.
1285 */
1286
operator =(const QImage & image)1287 QPixmap &QPixmap::operator=(const QImage &image)
1288 {
1289 if (data && data->pixelType() == QPixmapData::BitmapType)
1290 *this = QBitmap::fromImage(image);
1291 else
1292 *this = fromImage(image);
1293 return *this;
1294 }
1295
1296 /*!
1297 Use the load() function that takes a Qt::ImageConversionFlag instead.
1298 */
1299
load(const QString & fileName,const char * format,ColorMode mode)1300 bool QPixmap::load(const QString &fileName, const char *format, ColorMode mode)
1301 {
1302 return load(fileName, format, colorModeToFlags(mode));
1303 }
1304
1305 /*!
1306 Use the loadFromData() function that takes a Qt::ImageConversionFlag instead.
1307 */
1308
loadFromData(const uchar * buf,uint len,const char * format,ColorMode mode)1309 bool QPixmap::loadFromData(const uchar *buf, uint len, const char *format, ColorMode mode)
1310 {
1311 return loadFromData(buf, len, format, colorModeToFlags(mode));
1312 }
1313
1314 /*!
1315 Use the static fromImage() function instead.
1316 */
convertFromImage(const QImage & image,ColorMode mode)1317 bool QPixmap::convertFromImage(const QImage &image, ColorMode mode)
1318 {
1319 if (data && data->pixelType() == QPixmapData::BitmapType)
1320 *this = QBitmap::fromImage(image, colorModeToFlags(mode));
1321 else
1322 *this = fromImage(image, colorModeToFlags(mode));
1323 return !isNull();
1324 }
1325
1326 #endif
1327
1328 /*****************************************************************************
1329 QPixmap stream functions
1330 *****************************************************************************/
1331 #if !defined(QT_NO_DATASTREAM)
1332 /*!
1333 \relates QPixmap
1334
1335 Writes the given \a pixmap to the given \a stream as a PNG
1336 image. Note that writing the stream to a file will not produce a
1337 valid image file.
1338
1339 \sa QPixmap::save(), {Serializing Qt Data Types}
1340 */
1341
operator <<(QDataStream & stream,const QPixmap & pixmap)1342 QDataStream &operator<<(QDataStream &stream, const QPixmap &pixmap)
1343 {
1344 return stream << pixmap.toImage();
1345 }
1346
1347 /*!
1348 \relates QPixmap
1349
1350 Reads an image from the given \a stream into the given \a pixmap.
1351
1352 \sa QPixmap::load(), {Serializing Qt Data Types}
1353 */
1354
operator >>(QDataStream & stream,QPixmap & pixmap)1355 QDataStream &operator>>(QDataStream &stream, QPixmap &pixmap)
1356 {
1357 QImage image;
1358 stream >> image;
1359
1360 if (image.isNull()) {
1361 pixmap = QPixmap();
1362 } else if (image.depth() == 1) {
1363 pixmap = QBitmap::fromImage(image);
1364 } else {
1365 pixmap = QPixmap::fromImage(image);
1366 }
1367 return stream;
1368 }
1369
1370 #endif // QT_NO_DATASTREAM
1371
1372 #ifdef QT3_SUPPORT
copyBlt(QPixmap * dst,int dx,int dy,const QPixmap * src,int sx,int sy,int sw,int sh)1373 Q_GUI_EXPORT void copyBlt(QPixmap *dst, int dx, int dy,
1374 const QPixmap *src, int sx, int sy, int sw, int sh)
1375 {
1376 Q_ASSERT_X(dst, "::copyBlt", "Destination pixmap must be non-null");
1377 Q_ASSERT_X(src, "::copyBlt", "Source pixmap must be non-null");
1378
1379 if (src->hasAlphaChannel()) {
1380 if (dst->paintEngine()->hasFeature(QPaintEngine::PorterDuff)) {
1381 QPainter p(dst);
1382 p.setCompositionMode(QPainter::CompositionMode_Source);
1383 p.drawPixmap(dx, dy, *src, sx, sy, sw, sh);
1384 } else {
1385 QImage image = dst->toImage().convertToFormat(QImage::Format_ARGB32_Premultiplied);
1386 QPainter p(&image);
1387 p.setCompositionMode(QPainter::CompositionMode_Source);
1388 p.drawPixmap(dx, dy, *src, sx, sy, sw, sh);
1389 p.end();
1390 *dst = QPixmap::fromImage(image);
1391 }
1392 } else {
1393 QPainter p(dst);
1394 p.drawPixmap(dx, dy, *src, sx, sy, sw, sh);
1395 }
1396
1397 }
1398 #endif
1399
1400 /*!
1401 \internal
1402 */
1403
isDetached() const1404 bool QPixmap::isDetached() const
1405 {
1406 return data && data->ref == 1;
1407 }
1408
1409 /*! \internal
1410 ### Qt5 - remove me.
1411 */
deref()1412 void QPixmap::deref()
1413 {
1414 Q_ASSERT_X(false, "QPixmap::deref()", "Do not call this function anymore!");
1415 }
1416
1417 /*!
1418 \fn QImage QPixmap::convertToImage() const
1419
1420 Use the toImage() function instead.
1421 */
1422
1423 /*!
1424 Replaces this pixmap's data with the given \a image using the
1425 specified \a flags to control the conversion. The \a flags
1426 argument is a bitwise-OR of the \l{Qt::ImageConversionFlags}.
1427 Passing 0 for \a flags sets all the default options. Returns true
1428 if the result is that this pixmap is not null.
1429
1430 Note: this function was part of Qt 3 support in Qt 4.6 and earlier.
1431 It has been promoted to official API status in 4.7 to support updating
1432 the pixmap's image without creating a new QPixmap as fromImage() would.
1433
1434 \sa fromImage()
1435 \since 4.7
1436 */
convertFromImage(const QImage & image,Qt::ImageConversionFlags flags)1437 bool QPixmap::convertFromImage(const QImage &image, Qt::ImageConversionFlags flags)
1438 {
1439 if (image.isNull() || !data)
1440 *this = QPixmap::fromImage(image, flags);
1441 else
1442 data->fromImage(image, flags);
1443 return !isNull();
1444 }
1445
1446 /*!
1447 \fn QPixmap QPixmap::xForm(const QMatrix &matrix) const
1448
1449 Use transformed() instead.
1450 */
1451
1452 /*!
1453 \fn QPixmap QPixmap::scaled(int width, int height,
1454 Qt::AspectRatioMode aspectRatioMode, Qt::TransformationMode
1455 transformMode) const
1456
1457 \overload
1458
1459 Returns a copy of the pixmap scaled to a rectangle with the given
1460 \a width and \a height according to the given \a aspectRatioMode and
1461 \a transformMode.
1462
1463 If either the \a width or the \a height is zero or negative, this
1464 function returns a null pixmap.
1465 */
1466
1467 /*!
1468 \fn QPixmap QPixmap::scaled(const QSize &size, Qt::AspectRatioMode
1469 aspectRatioMode, Qt::TransformationMode transformMode) const
1470
1471 Scales the pixmap to the given \a size, using the aspect ratio and
1472 transformation modes specified by \a aspectRatioMode and \a
1473 transformMode.
1474
1475 \image qimage-scaling.png
1476
1477 \list
1478 \i If \a aspectRatioMode is Qt::IgnoreAspectRatio, the pixmap
1479 is scaled to \a size.
1480 \i If \a aspectRatioMode is Qt::KeepAspectRatio, the pixmap is
1481 scaled to a rectangle as large as possible inside \a size, preserving the aspect ratio.
1482 \i If \a aspectRatioMode is Qt::KeepAspectRatioByExpanding,
1483 the pixmap is scaled to a rectangle as small as possible
1484 outside \a size, preserving the aspect ratio.
1485 \endlist
1486
1487 If the given \a size is empty, this function returns a null
1488 pixmap.
1489
1490
1491 In some cases it can be more beneficial to draw the pixmap to a
1492 painter with a scale set rather than scaling the pixmap. This is
1493 the case when the painter is for instance based on OpenGL or when
1494 the scale factor changes rapidly.
1495
1496 \sa isNull(), {QPixmap#Pixmap Transformations}{Pixmap
1497 Transformations}
1498
1499 */
scaled(const QSize & s,Qt::AspectRatioMode aspectMode,Qt::TransformationMode mode) const1500 QPixmap QPixmap::scaled(const QSize& s, Qt::AspectRatioMode aspectMode, Qt::TransformationMode mode) const
1501 {
1502 if (isNull()) {
1503 qWarning("QPixmap::scaled: Pixmap is a null pixmap");
1504 return QPixmap();
1505 }
1506 if (s.isEmpty())
1507 return QPixmap();
1508
1509 QSize newSize = size();
1510 newSize.scale(s, aspectMode);
1511 newSize.rwidth() = qMax(newSize.width(), 1);
1512 newSize.rheight() = qMax(newSize.height(), 1);
1513 if (newSize == size())
1514 return *this;
1515
1516 QTransform wm = QTransform::fromScale((qreal)newSize.width() / width(),
1517 (qreal)newSize.height() / height());
1518 QPixmap pix = transformed(wm, mode);
1519 return pix;
1520 }
1521
1522 /*!
1523 \fn QPixmap QPixmap::scaledToWidth(int width, Qt::TransformationMode
1524 mode) const
1525
1526 Returns a scaled copy of the image. The returned image is scaled
1527 to the given \a width using the specified transformation \a mode.
1528 The height of the pixmap is automatically calculated so that the
1529 aspect ratio of the pixmap is preserved.
1530
1531 If \a width is 0 or negative, a null pixmap is returned.
1532
1533 \sa isNull(), {QPixmap#Pixmap Transformations}{Pixmap
1534 Transformations}
1535 */
scaledToWidth(int w,Qt::TransformationMode mode) const1536 QPixmap QPixmap::scaledToWidth(int w, Qt::TransformationMode mode) const
1537 {
1538 if (isNull()) {
1539 qWarning("QPixmap::scaleWidth: Pixmap is a null pixmap");
1540 return copy();
1541 }
1542 if (w <= 0)
1543 return QPixmap();
1544
1545 qreal factor = (qreal) w / width();
1546 QTransform wm = QTransform::fromScale(factor, factor);
1547 return transformed(wm, mode);
1548 }
1549
1550 /*!
1551 \fn QPixmap QPixmap::scaledToHeight(int height,
1552 Qt::TransformationMode mode) const
1553
1554 Returns a scaled copy of the image. The returned image is scaled
1555 to the given \a height using the specified transformation \a mode.
1556 The width of the pixmap is automatically calculated so that the
1557 aspect ratio of the pixmap is preserved.
1558
1559 If \a height is 0 or negative, a null pixmap is returned.
1560
1561 \sa isNull(), {QPixmap#Pixmap Transformations}{Pixmap
1562 Transformations}
1563 */
scaledToHeight(int h,Qt::TransformationMode mode) const1564 QPixmap QPixmap::scaledToHeight(int h, Qt::TransformationMode mode) const
1565 {
1566 if (isNull()) {
1567 qWarning("QPixmap::scaleHeight: Pixmap is a null pixmap");
1568 return copy();
1569 }
1570 if (h <= 0)
1571 return QPixmap();
1572
1573 qreal factor = (qreal) h / height();
1574 QTransform wm = QTransform::fromScale(factor, factor);
1575 return transformed(wm, mode);
1576 }
1577
1578 /*!
1579 Returns a copy of the pixmap that is transformed using the given
1580 transformation \a transform and transformation \a mode. The original
1581 pixmap is not changed.
1582
1583 The transformation \a transform is internally adjusted to compensate
1584 for unwanted translation; i.e. the pixmap produced is the smallest
1585 pixmap that contains all the transformed points of the original
1586 pixmap. Use the trueMatrix() function to retrieve the actual
1587 matrix used for transforming the pixmap.
1588
1589 This function is slow because it involves transformation to a
1590 QImage, non-trivial computations and a transformation back to a
1591 QPixmap.
1592
1593 \sa trueMatrix(), {QPixmap#Pixmap Transformations}{Pixmap
1594 Transformations}
1595 */
transformed(const QTransform & transform,Qt::TransformationMode mode) const1596 QPixmap QPixmap::transformed(const QTransform &transform,
1597 Qt::TransformationMode mode) const
1598 {
1599 if (isNull() || transform.type() <= QTransform::TxTranslate)
1600 return *this;
1601
1602 return data->transformed(transform, mode);
1603 }
1604
1605 /*!
1606 \overload
1607
1608 This convenience function loads the \a matrix into a
1609 QTransform and calls the overloaded function.
1610 */
transformed(const QMatrix & matrix,Qt::TransformationMode mode) const1611 QPixmap QPixmap::transformed(const QMatrix &matrix, Qt::TransformationMode mode) const
1612 {
1613 return transformed(QTransform(matrix), mode);
1614 }
1615
1616
1617
1618
1619
1620
1621
1622
1623 /*!
1624 \class QPixmap
1625
1626 \brief The QPixmap class is an off-screen image representation
1627 that can be used as a paint device.
1628
1629 \ingroup painting
1630 \ingroup shared
1631
1632
1633 Qt provides four classes for handling image data: QImage, QPixmap,
1634 QBitmap and QPicture. QImage is designed and optimized for I/O,
1635 and for direct pixel access and manipulation, while QPixmap is
1636 designed and optimized for showing images on screen. QBitmap is
1637 only a convenience class that inherits QPixmap, ensuring a depth
1638 of 1. The isQBitmap() function returns true if a QPixmap object is
1639 really a bitmap, otherwise returns false. Finally, the QPicture class
1640 is a paint device that records and replays QPainter commands.
1641
1642 A QPixmap can easily be displayed on the screen using QLabel or
1643 one of QAbstractButton's subclasses (such as QPushButton and
1644 QToolButton). QLabel has a pixmap property, whereas
1645 QAbstractButton has an icon property.
1646
1647 In addition to the ordinary constructors, a QPixmap can be
1648 constructed using the static grabWidget() and grabWindow()
1649 functions which creates a QPixmap and paints the given widget, or
1650 window, into it.
1651
1652 QPixmap objects can be passed around by value since the QPixmap
1653 class uses implicit data sharing. For more information, see the \l
1654 {Implicit Data Sharing} documentation. QPixmap objects can also be
1655 streamed.
1656
1657 Note that the pixel data in a pixmap is internal and is managed by
1658 the underlying window system. Because QPixmap is a QPaintDevice
1659 subclass, QPainter can be used to draw directly onto pixmaps.
1660 Pixels can only be accessed through QPainter functions or by
1661 converting the QPixmap to a QImage. However, the fill() function
1662 is available for initializing the entire pixmap with a given color.
1663
1664 There are functions to convert between QImage and
1665 QPixmap. Typically, the QImage class is used to load an image
1666 file, optionally manipulating the image data, before the QImage
1667 object is converted into a QPixmap to be shown on
1668 screen. Alternatively, if no manipulation is desired, the image
1669 file can be loaded directly into a QPixmap. On Windows, the
1670 QPixmap class also supports conversion between \c HBITMAP and
1671 QPixmap. On Symbian, the QPixmap class also supports conversion
1672 between CFbsBitmap and QPixmap.
1673
1674 QPixmap provides a collection of functions that can be used to
1675 obtain a variety of information about the pixmap. In addition,
1676 there are several functions that enables transformation of the
1677 pixmap.
1678
1679 \tableofcontents
1680
1681 \section1 Reading and Writing Image Files
1682
1683 QPixmap provides several ways of reading an image file: The file
1684 can be loaded when constructing the QPixmap object, or by using
1685 the load() or loadFromData() functions later on. When loading an
1686 image, the file name can either refer to an actual file on disk or
1687 to one of the application's embedded resources. See \l{The Qt
1688 Resource System} overview for details on how to embed images and
1689 other resource files in the application's executable.
1690
1691 Simply call the save() function to save a QPixmap object.
1692
1693 The complete list of supported file formats are available through
1694 the QImageReader::supportedImageFormats() and
1695 QImageWriter::supportedImageFormats() functions. New file formats
1696 can be added as plugins. By default, Qt supports the following
1697 formats:
1698
1699 \table
1700 \header \o Format \o Description \o Qt's support
1701 \row \o BMP \o Windows Bitmap \o Read/write
1702 \row \o GIF \o Graphic Interchange Format (optional) \o Read
1703 \row \o JPG \o Joint Photographic Experts Group \o Read/write
1704 \row \o JPEG \o Joint Photographic Experts Group \o Read/write
1705 \row \o PNG \o Portable Network Graphics \o Read/write
1706 \row \o PBM \o Portable Bitmap \o Read
1707 \row \o PGM \o Portable Graymap \o Read
1708 \row \o PPM \o Portable Pixmap \o Read/write
1709 \row \o XBM \o X11 Bitmap \o Read/write
1710 \row \o XPM \o X11 Pixmap \o Read/write
1711 \endtable
1712
1713 \section1 Pixmap Information
1714
1715 QPixmap provides a collection of functions that can be used to
1716 obtain a variety of information about the pixmap:
1717
1718 \table
1719 \header
1720 \o \o Available Functions
1721 \row
1722 \o Geometry
1723 \o
1724 The size(), width() and height() functions provide information
1725 about the pixmap's size. The rect() function returns the image's
1726 enclosing rectangle.
1727
1728 \row
1729 \o Alpha component
1730 \o
1731
1732 The hasAlphaChannel() returns true if the pixmap has a format that
1733 respects the alpha channel, otherwise returns false. The hasAlpha(),
1734 setMask() and mask() functions are legacy and should not be used.
1735 They are potentially very slow.
1736
1737 The createHeuristicMask() function creates and returns a 1-bpp
1738 heuristic mask (i.e. a QBitmap) for this pixmap. It works by
1739 selecting a color from one of the corners and then chipping away
1740 pixels of that color, starting at all the edges. The
1741 createMaskFromColor() function creates and returns a mask (i.e. a
1742 QBitmap) for the pixmap based on a given color.
1743
1744 \row
1745 \o Low-level information
1746 \o
1747
1748 The depth() function returns the depth of the pixmap. The
1749 defaultDepth() function returns the default depth, i.e. the depth
1750 used by the application on the given screen.
1751
1752 The cacheKey() function returns a number that uniquely
1753 identifies the contents of the QPixmap object.
1754
1755 The x11Info() function returns information about the configuration
1756 of the X display used by the screen to which the pixmap currently
1757 belongs. The x11PictureHandle() function returns the X11 Picture
1758 handle of the pixmap for XRender support. Note that the two latter
1759 functions are only available on x11.
1760
1761 \endtable
1762
1763 \section1 Pixmap Conversion
1764
1765 A QPixmap object can be converted into a QImage using the
1766 toImage() function. Likewise, a QImage can be converted into a
1767 QPixmap using the fromImage(). If this is too expensive an
1768 operation, you can use QBitmap::fromImage() instead.
1769
1770 In addition, on Windows, the QPixmap class supports conversion to
1771 and from HBITMAP: the toWinHBITMAP() function creates a HBITMAP
1772 equivalent to the QPixmap, based on the given HBitmapFormat, and
1773 returns the HBITMAP handle. The fromWinHBITMAP() function returns
1774 a QPixmap that is equivalent to the given bitmap which has the
1775 specified format. The QPixmap class also supports conversion to
1776 and from HICON: the toWinHICON() function creates a HICON equivalent
1777 to the QPixmap, and returns the HICON handle. The fromWinHICON()
1778 function returns a QPixmap that is equivalent to the given icon.
1779
1780 In addition, on Symbian, the QPixmap class supports conversion to
1781 and from CFbsBitmap: the toSymbianCFbsBitmap() function creates
1782 CFbsBitmap equivalent to the QPixmap, based on given mode and returns
1783 a CFbsBitmap object. The fromSymbianCFbsBitmap() function returns a
1784 QPixmap that is equivalent to the given bitmap and given mode.
1785
1786 \section1 Pixmap Transformations
1787
1788 QPixmap supports a number of functions for creating a new pixmap
1789 that is a transformed version of the original:
1790
1791 The scaled(), scaledToWidth() and scaledToHeight() functions
1792 return scaled copies of the pixmap, while the copy() function
1793 creates a QPixmap that is a plain copy of the original one.
1794
1795 The transformed() function returns a copy of the pixmap that is
1796 transformed with the given transformation matrix and
1797 transformation mode: Internally, the transformation matrix is
1798 adjusted to compensate for unwanted translation,
1799 i.e. transformed() returns the smallest pixmap containing all
1800 transformed points of the original pixmap. The static trueMatrix()
1801 function returns the actual matrix used for transforming the
1802 pixmap.
1803
1804 \note When using the native X11 graphics system, the pixmap
1805 becomes invalid when the QApplication instance is destroyed.
1806
1807 \sa QBitmap, QImage, QImageReader, QImageWriter
1808 */
1809
1810
1811 /*!
1812 \typedef QPixmap::DataPtr
1813 \internal
1814 */
1815
1816 /*!
1817 \fn DataPtr &QPixmap::data_ptr()
1818 \internal
1819 */
1820
1821 /*!
1822 Returns true if this pixmap has an alpha channel, \e or has a
1823 mask, otherwise returns false.
1824
1825 \sa hasAlphaChannel(), mask()
1826 */
hasAlpha() const1827 bool QPixmap::hasAlpha() const
1828 {
1829 #if defined(Q_WS_X11)
1830 if (data && data->hasAlphaChannel())
1831 return true;
1832 QPixmapData *pd = pixmapData();
1833 if (pd && pd->classId() == QPixmapData::X11Class) {
1834 QX11PixmapData *x11Data = static_cast<QX11PixmapData*>(pd);
1835 #ifndef QT_NO_XRENDER
1836 if (x11Data->picture && x11Data->d == 32)
1837 return true;
1838 #endif
1839 if (x11Data->d == 1 || x11Data->x11_mask)
1840 return true;
1841 }
1842 return false;
1843 #else
1844 return data && data->hasAlphaChannel();
1845 #endif
1846 }
1847
1848 /*!
1849 Returns true if the pixmap has a format that respects the alpha
1850 channel, otherwise returns false.
1851
1852 \sa hasAlpha()
1853 */
hasAlphaChannel() const1854 bool QPixmap::hasAlphaChannel() const
1855 {
1856 return data && data->hasAlphaChannel();
1857 }
1858
1859 /*!
1860 \internal
1861 */
metric(PaintDeviceMetric metric) const1862 int QPixmap::metric(PaintDeviceMetric metric) const
1863 {
1864 return data ? data->metric(metric) : 0;
1865 }
1866
1867 /*!
1868 \fn void QPixmap::setAlphaChannel(const QPixmap &alphaChannel)
1869 \obsolete
1870
1871 Sets the alpha channel of this pixmap to the given \a alphaChannel
1872 by converting the \a alphaChannel into 32 bit and using the
1873 intensity of the RGB pixel values.
1874
1875 The effect of this function is undefined when the pixmap is being
1876 painted on.
1877
1878 \warning This is potentially an expensive operation. Most usecases
1879 for this function are covered by QPainter and compositionModes
1880 which will normally execute faster.
1881
1882 \sa alphaChannel(), {QPixmap#Pixmap Transformations}{Pixmap
1883 Transformations}
1884 */
setAlphaChannel(const QPixmap & alphaChannel)1885 void QPixmap::setAlphaChannel(const QPixmap &alphaChannel)
1886 {
1887 if (alphaChannel.isNull())
1888 return;
1889
1890 if (paintingActive()) {
1891 qWarning("QPixmap::setAlphaChannel: "
1892 "Cannot set alpha channel while pixmap is being painted on");
1893 return;
1894 }
1895
1896 if (width() != alphaChannel.width() && height() != alphaChannel.height()) {
1897 qWarning("QPixmap::setAlphaChannel: "
1898 "The pixmap and the alpha channel pixmap must have the same size");
1899 return;
1900 }
1901
1902 detach();
1903 data->setAlphaChannel(alphaChannel);
1904 }
1905
1906 /*!
1907 \obsolete
1908
1909 Returns the alpha channel of the pixmap as a new grayscale QPixmap in which
1910 each pixel's red, green, and blue values are given the alpha value of the
1911 original pixmap. The color depth of the returned pixmap is the system depth
1912 on X11 and 8-bit on Windows and Mac OS X.
1913
1914 You can use this function while debugging
1915 to get a visible image of the alpha channel. If the pixmap doesn't have an
1916 alpha channel, i.e., the alpha channel's value for all pixels equals
1917 0xff), a null pixmap is returned. You can check this with the \c isNull()
1918 function.
1919
1920 We show an example:
1921
1922 \snippet doc/src/snippets/alphachannel.cpp 0
1923
1924 \image alphachannelimage.png The pixmap and channelImage QPixmaps
1925
1926 \warning This is an expensive operation. The alpha channel of the
1927 pixmap is extracted dynamically from the pixeldata. Most usecases of this
1928 function are covered by QPainter and compositionModes which will normally
1929 execute faster.
1930
1931 \sa setAlphaChannel(), {QPixmap#Pixmap Information}{Pixmap
1932 Information}
1933 */
alphaChannel() const1934 QPixmap QPixmap::alphaChannel() const
1935 {
1936 return data ? data->alphaChannel() : QPixmap();
1937 }
1938
1939 /*!
1940 \internal
1941 */
paintEngine() const1942 QPaintEngine *QPixmap::paintEngine() const
1943 {
1944 return data ? data->paintEngine() : 0;
1945 }
1946
1947 /*!
1948 \fn QBitmap QPixmap::mask() const
1949
1950 Extracts a bitmap mask from the pixmap's alpha channel.
1951
1952 \warning This is potentially an expensive operation. The mask of
1953 the pixmap is extracted dynamically from the pixeldata.
1954
1955 \sa setMask(), {QPixmap#Pixmap Information}{Pixmap Information}
1956 */
mask() const1957 QBitmap QPixmap::mask() const
1958 {
1959 return data ? data->mask() : QBitmap();
1960 }
1961
1962 /*!
1963 Returns the default pixmap depth used by the application.
1964
1965 On Windows and Mac, the default depth is always 32. On X11 and
1966 embedded, the depth of the screen will be returned by this
1967 function.
1968
1969 \sa depth(), QColormap::depth(), {QPixmap#Pixmap Information}{Pixmap Information}
1970
1971 */
defaultDepth()1972 int QPixmap::defaultDepth()
1973 {
1974 #if defined(Q_WS_QWS)
1975 return QScreen::instance()->depth();
1976 #elif defined(Q_WS_X11)
1977 return QX11Info::appDepth();
1978 #elif defined(Q_WS_WINCE)
1979 return QColormap::instance().depth();
1980 #elif defined(Q_WS_WIN)
1981 return 32; // XXX
1982 #elif defined(Q_WS_MAC)
1983 return 32;
1984 #elif defined(Q_OS_SYMBIAN)
1985 return S60->screenDepth;
1986 #elif defined(Q_WS_QPA)
1987 return 32; //LITE: use graphicssystem (we should do that in general)
1988 #endif
1989 }
1990
1991 /*!
1992 Detaches the pixmap from shared pixmap data.
1993
1994 A pixmap is automatically detached by Qt whenever its contents are
1995 about to change. This is done in almost all QPixmap member
1996 functions that modify the pixmap (fill(), fromImage(),
1997 load(), etc.), and in QPainter::begin() on a pixmap.
1998
1999 There are two exceptions in which detach() must be called
2000 explicitly, that is when calling the handle() or the
2001 x11PictureHandle() function (only available on X11). Otherwise,
2002 any modifications done using system calls, will be performed on
2003 the shared data.
2004
2005 The detach() function returns immediately if there is just a
2006 single reference or if the pixmap has not been initialized yet.
2007 */
detach()2008 void QPixmap::detach()
2009 {
2010 if (!data)
2011 return;
2012
2013 // QPixmap.data member may be QRuntimePixmapData so use pixmapData() function to get
2014 // the actual underlaying runtime pixmap data.
2015 QPixmapData *pd = pixmapData();
2016 QPixmapData::ClassId id = pd->classId();
2017 if (id == QPixmapData::RasterClass) {
2018 QRasterPixmapData *rasterData = static_cast<QRasterPixmapData*>(pd);
2019 rasterData->image.detach();
2020 }
2021
2022 if (data->is_cached && data->ref == 1)
2023 QImagePixmapCleanupHooks::executePixmapDataModificationHooks(data.data());
2024
2025 #if defined(Q_WS_MAC)
2026 QMacPixmapData *macData = id == QPixmapData::MacClass ? static_cast<QMacPixmapData*>(pd) : 0;
2027 if (macData) {
2028 if (macData->cg_mask) {
2029 CGImageRelease(macData->cg_mask);
2030 macData->cg_mask = 0;
2031 }
2032 }
2033 #endif
2034
2035 if (data->ref != 1) {
2036 *this = copy();
2037 }
2038 ++data->detach_no;
2039
2040 #if defined(Q_WS_X11)
2041 if (pd->classId() == QPixmapData::X11Class) {
2042 QX11PixmapData *d = static_cast<QX11PixmapData*>(pd);
2043 d->flags &= ~QX11PixmapData::Uninitialized;
2044
2045 // reset the cache data
2046 if (d->hd2) {
2047 XFreePixmap(X11->display, d->hd2);
2048 d->hd2 = 0;
2049 }
2050 }
2051 #elif defined(Q_WS_MAC)
2052 if (macData) {
2053 macData->macReleaseCGImageRef();
2054 macData->uninit = false;
2055 }
2056 #endif
2057 }
2058
2059 /*!
2060 \fn QPixmap QPixmap::fromImage(const QImage &image, Qt::ImageConversionFlags flags)
2061
2062 Converts the given \a image to a pixmap using the specified \a
2063 flags to control the conversion. The \a flags argument is a
2064 bitwise-OR of the \l{Qt::ImageConversionFlags}. Passing 0 for \a
2065 flags sets all the default options.
2066
2067 In case of monochrome and 8-bit images, the image is first
2068 converted to a 32-bit pixmap and then filled with the colors in
2069 the color table. If this is too expensive an operation, you can
2070 use QBitmap::fromImage() instead.
2071
2072 \sa fromImageReader(), toImage(), {QPixmap#Pixmap Conversion}{Pixmap Conversion}
2073 */
fromImage(const QImage & image,Qt::ImageConversionFlags flags)2074 QPixmap QPixmap::fromImage(const QImage &image, Qt::ImageConversionFlags flags)
2075 {
2076 if (image.isNull())
2077 return QPixmap();
2078
2079 QGraphicsSystem* gs = QApplicationPrivate::graphicsSystem();
2080 QScopedPointer<QPixmapData> data(gs ? gs->createPixmapData(QPixmapData::PixmapType)
2081 : QGraphicsSystem::createDefaultPixmapData(QPixmapData::PixmapType));
2082 data->fromImage(image, flags);
2083 return QPixmap(data.take());
2084 }
2085
2086 /*!
2087 \fn QPixmap QPixmap::fromImageReader(QImageReader *imageReader, Qt::ImageConversionFlags flags)
2088
2089 Create a QPixmap from an image read directly from an \a imageReader.
2090 The \a flags argument is a bitwise-OR of the \l{Qt::ImageConversionFlags}.
2091 Passing 0 for \a flags sets all the default options.
2092
2093 On some systems, reading an image directly to QPixmap can use less memory than
2094 reading a QImage to convert it to QPixmap.
2095
2096 \sa fromImage(), toImage(), {QPixmap#Pixmap Conversion}{Pixmap Conversion}
2097 */
fromImageReader(QImageReader * imageReader,Qt::ImageConversionFlags flags)2098 QPixmap QPixmap::fromImageReader(QImageReader *imageReader, Qt::ImageConversionFlags flags)
2099 {
2100 QGraphicsSystem *gs = QApplicationPrivate::graphicsSystem();
2101 QScopedPointer<QPixmapData> data(gs ? gs->createPixmapData(QPixmapData::PixmapType)
2102 : QGraphicsSystem::createDefaultPixmapData(QPixmapData::PixmapType));
2103 data->fromImageReader(imageReader, flags);
2104 return QPixmap(data.take());
2105 }
2106
2107 /*!
2108 \fn QPixmap QPixmap::grabWindow(WId window, int x, int y, int
2109 width, int height)
2110
2111 Creates and returns a pixmap constructed by grabbing the contents
2112 of the given \a window restricted by QRect(\a x, \a y, \a width,
2113 \a height).
2114
2115 The arguments (\a{x}, \a{y}) specify the offset in the window,
2116 whereas (\a{width}, \a{height}) specify the area to be copied. If
2117 \a width is negative, the function copies everything to the right
2118 border of the window. If \a height is negative, the function
2119 copies everything to the bottom of the window.
2120
2121 The window system identifier (\c WId) can be retrieved using the
2122 QWidget::winId() function. The rationale for using a window
2123 identifier and not a QWidget, is to enable grabbing of windows
2124 that are not part of the application, window system frames, and so
2125 on.
2126
2127 The grabWindow() function grabs pixels from the screen, not from
2128 the window, i.e. if there is another window partially or entirely
2129 over the one you grab, you get pixels from the overlying window,
2130 too. The mouse cursor is generally not grabbed.
2131
2132 Note on X11 that if the given \a window doesn't have the same depth
2133 as the root window, and another window partially or entirely
2134 obscures the one you grab, you will \e not get pixels from the
2135 overlying window. The contents of the obscured areas in the
2136 pixmap will be undefined and uninitialized.
2137
2138 On Windows Vista and above grabbing a layered window, which is
2139 created by setting the Qt::WA_TranslucentBackground attribute, will
2140 not work. Instead grabbing the desktop widget should work.
2141
2142 \warning In general, grabbing an area outside the screen is not
2143 safe. This depends on the underlying window system.
2144
2145 \sa grabWidget(), {Screenshot Example}
2146 */
2147
2148 /*!
2149 \internal
2150 */
pixmapData() const2151 QPixmapData* QPixmap::pixmapData() const
2152 {
2153 if (data) {
2154 QPixmapData* pm = data.data();
2155 return pm->runtimeData() ? pm->runtimeData() : pm;
2156 }
2157
2158 return 0;
2159 }
2160
2161
2162 /*!
2163 \enum QPixmap::HBitmapFormat
2164
2165 \bold{Win32 only:} This enum defines how the conversion between \c
2166 HBITMAP and QPixmap is performed.
2167
2168 \warning This enum is only available on Windows.
2169
2170 \value NoAlpha The alpha channel is ignored and always treated as
2171 being set to fully opaque. This is preferred if the \c HBITMAP is
2172 used with standard GDI calls, such as \c BitBlt().
2173
2174 \value PremultipliedAlpha The \c HBITMAP is treated as having an
2175 alpha channel and premultiplied colors. This is preferred if the
2176 \c HBITMAP is accessed through the \c AlphaBlend() GDI function.
2177
2178 \value Alpha The \c HBITMAP is treated as having a plain alpha
2179 channel. This is the preferred format if the \c HBITMAP is going
2180 to be used as an application icon or systray icon.
2181
2182 \sa fromWinHBITMAP(), toWinHBITMAP()
2183 */
2184
2185 /*! \fn HBITMAP QPixmap::toWinHBITMAP(HBitmapFormat format) const
2186 \bold{Win32 only:} Creates a \c HBITMAP equivalent to the QPixmap,
2187 based on the given \a format. Returns the \c HBITMAP handle.
2188
2189 It is the caller's responsibility to free the \c HBITMAP data
2190 after use.
2191
2192 \warning This function is only available on Windows.
2193
2194 \sa fromWinHBITMAP(), {QPixmap#Pixmap Conversion}{Pixmap Conversion}
2195 */
2196
2197 /*! \fn QPixmap QPixmap::fromWinHBITMAP(HBITMAP bitmap, HBitmapFormat format)
2198 \bold{Win32 only:} Returns a QPixmap that is equivalent to the
2199 given \a bitmap. The conversion is based on the specified \a
2200 format.
2201
2202 \warning This function is only available on Windows.
2203
2204 \sa toWinHBITMAP(), {QPixmap#Pixmap Conversion}{Pixmap Conversion}
2205
2206 */
2207
2208 /*! \fn HICON QPixmap::toWinHICON() const
2209 \since 4.6
2210
2211 \bold{Win32 only:} Creates a \c HICON equivalent to the QPixmap.
2212 Returns the \c HICON handle.
2213
2214 It is the caller's responsibility to free the \c HICON data after use.
2215
2216 \warning This function is only available on Windows.
2217
2218 \sa fromWinHICON(), {QPixmap#Pixmap Conversion}{Pixmap Conversion}
2219 */
2220
2221 /*! \fn QPixmap QPixmap::fromWinHICON(HICON icon)
2222 \since 4.6
2223
2224 \bold{Win32 only:} Returns a QPixmap that is equivalent to the given
2225 \a icon.
2226
2227 \warning This function is only available on Windows.
2228
2229 \sa toWinHICON(), {QPixmap#Pixmap Conversion}{Pixmap Conversion}
2230
2231 */
2232
2233 /*! \fn const QX11Info &QPixmap::x11Info() const
2234 \bold{X11 only:} Returns information about the configuration of
2235 the X display used by the screen to which the pixmap currently belongs.
2236
2237 \warning This function is only available on X11.
2238
2239 \sa {QPixmap#Pixmap Information}{Pixmap Information}
2240 */
2241
2242 /*! \fn Qt::HANDLE QPixmap::x11PictureHandle() const
2243 \bold{X11 only:} Returns the X11 Picture handle of the pixmap for
2244 XRender support.
2245
2246 This function will return 0 if XRender support is not compiled
2247 into Qt, if the XRender extension is not supported on the X11
2248 display, or if the handle could not be created. Use of this
2249 function is not portable.
2250
2251 \warning This function is only available on X11.
2252
2253 \sa {QPixmap#Pixmap Information}{Pixmap Information}
2254 */
2255
2256 /*! \fn int QPixmap::x11SetDefaultScreen(int screen)
2257 \internal
2258 */
2259
2260 /*! \fn void QPixmap::x11SetScreen(int screen)
2261 \internal
2262 */
2263
2264 /*! \fn QRgb* QPixmap::clut() const
2265 \internal
2266 */
2267
2268 /*! \fn int QPixmap::numCols() const
2269 \obsolete
2270 \internal
2271 \sa colorCount()
2272 */
2273
2274 /*! \fn int QPixmap::colorCount() const
2275 \since 4.6
2276 \internal
2277 */
2278
2279 /*! \fn const uchar* QPixmap::qwsBits() const
2280 \internal
2281 \since 4.1
2282 */
2283
2284 /*! \fn int QPixmap::qwsBytesPerLine() const
2285 \internal
2286 \since 4.1
2287 */
2288
2289 QT_END_NAMESPACE
2290