qpixmap.cpp

Absolute File Name:

/home/qt/qt5_coco/qt5/qtbase/src/gui/image/qpixmap.cpp

Source code

Switch to Preprocessed file

Line Source Count

1 /**************************************************************************** -

2 ** -

4 ** Contact: https://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 https://www.qt.io/terms-conditions. For further -

15 ** information use the contact form at https://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 3 as published by the Free Software -

20 ** Foundation and appearing in the file LICENSE.LGPL3 included in the -

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

22 ** ensure the GNU Lesser General Public License version 3 requirements -

23 ** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. -

24 ** -

25 ** GNU General Public License Usage -

26 ** Alternatively, this file may be used under the terms of the GNU -

27 ** General Public License version 2.0 or (at your option) the GNU General -

28 ** Public license version 3 or any later version approved by the KDE Free -

29 ** Qt Foundation. The licenses are as published by the Free Software -

30 ** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 -

31 ** included in the packaging of this file. Please review the following -

32 ** information to ensure the GNU General Public License requirements will -

33 ** be met: https://www.gnu.org/licenses/gpl-2.0.html and -

34 ** https://www.gnu.org/licenses/gpl-3.0.html. -

35 ** -

36 ** $QT_END_LICENSE$ -

37 ** -

38 ****************************************************************************/ -

39 -

40 #include <qglobal.h> -

41 -

42 #include "qpixmap.h" -

43 #include <qpa/qplatformpixmap.h> -

44 #include "qimagepixmapcleanuphooks_p.h" -

45 -

46 #include "qbitmap.h" -

47 #include "qimage.h" -

48 #include "qpainter.h" -

49 #include "qdatastream.h" -

50 #include "qbuffer.h" -

51 #include <private/qguiapplication_p.h> -

52 #include "qevent.h" -

53 #include "qfile.h" -

54 #include "qfileinfo.h" -

55 #include "qpixmapcache.h" -

56 #include "qdatetime.h" -

57 #include "qimagereader.h" -

58 #include "qimagewriter.h" -

59 #include "qpaintengine.h" -

60 #include "qscreen.h" -

61 #include "qthread.h" -

62 #include "qdebug.h" -

63 -

64 #include <qpa/qplatformintegration.h> -

65 -

66 #include "qpixmap_raster_p.h" -

67 #include "private/qhexstring_p.h" -

68 -

69 QT_BEGIN_NAMESPACE -

70 -

71 static bool qt_pixmap_thread_test() -

72 { -

if (Q_UNLIKELY(!QCoreApplication::instance())())) {

__builtin_expe...nce()), false)	Description
TRUE	never evaluated
FALSE	never evaluated

74 qFatal("QPixmap: Must construct a QGuiApplication before a QPixmap"); -

return false;

never executed: return false;

76 } -

77 -

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

(static_cast<Q...urrentThread()	Description
TRUE	never evaluated
FALSE	never evaluated

79 bool fail = false; -

if (!QGuiApplicationPrivate::platformIntegration()->hasCapability(QPlatformIntegration::ThreadedPixmaps)) {

!QGuiApplicati...readedPixmaps)	Description
TRUE	never evaluated
FALSE	never evaluated

81 printf("Lighthouse plugin does not support threaded pixmaps!\n"); -

82 fail = true; -

}

never executed: end of block

if (fail) {

fail	Description
TRUE	never evaluated
FALSE	never evaluated

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

return false;

never executed: return false;

87 } -

}

never executed: end of block

return true;

never executed: return true;

90 } -

91 -

92 void QPixmap::doInit(int w, int h, int type) -

93 { -

94 if ((w > 0 && h > 0) || type == QPlatformPixmap::BitmapType) -

95 data = QPlatformPixmap::create(w, h, (QPlatformPixmap::PixelType) type); -

96 else -

97 data = 0; -

98 } -

99 -

100 /*! -

101 Constructs a null pixmap. -

102 -

103 \sa isNull() -

104 */ -

105 -

106 QPixmap::QPixmap() -

107 : QPaintDevice() -

108 { -

109 (void) qt_pixmap_thread_test(); -

110 doInit(0, 0, QPlatformPixmap::PixmapType); -

111 } -

112 -

113 /*! -

114 \fn QPixmap::QPixmap(int width, int height) -

115 -

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

117 either \a width or \a height is zero, a null pixmap is -

118 constructed. -

119 -

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

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

122 onto it with QPainter. -

123 -

124 \sa isNull() -

125 */ -

126 -

127 QPixmap::QPixmap(int w, int h) -

128 : QPaintDevice() -

129 { -

130 if (!qt_pixmap_thread_test()) -

131 doInit(0, 0, QPlatformPixmap::PixmapType); -

132 else -

133 doInit(w, h, QPlatformPixmap::PixmapType); -

134 } -

135 -

136 /*! -

137 \overload -

138 -

139 Constructs a pixmap of the given \a size. -

140 -

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

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

143 onto it with QPainter. -

144 */ -

145 -

146 QPixmap::QPixmap(const QSize &size) -

147 : QPaintDevice() -

148 { -

149 if (!qt_pixmap_thread_test()) -

150 doInit(0, 0, QPlatformPixmap::PixmapType); -

151 else -

152 doInit(size.width(), size.height(), QPlatformPixmap::PixmapType); -

153 } -

154 -

155 /*! -

156 \internal -

157 */ -

158 QPixmap::QPixmap(const QSize &s, int type) -

159 { -

160 if (!qt_pixmap_thread_test()) -

161 doInit(0, 0, static_cast<QPlatformPixmap::PixelType>(type)); -

162 else -

163 doInit(s.width(), s.height(), static_cast<QPlatformPixmap::PixelType>(type)); -

164 } -

165 -

166 /*! -

167 \internal -

168 */ -

169 QPixmap::QPixmap(QPlatformPixmap *d) -

170 : QPaintDevice(), data(d) -

171 { -

172 } -

173 -

174 /*! -

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

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

177 null pixmap. -

178 -

179 The loader attempts to read the pixmap using the specified \a -

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

181 the loader probes the file for a header to guess the file format. -

182 -

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

184 one of the application's embedded resources. See the -

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

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

187 executable. -

188 -

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

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

191 flags to control the conversion. -

192 -

193 The \a fileName, \a format and \a flags parameters are -

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

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

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

197 relative to the runtime working directory. -

198 -

199 \sa {QPixmap#Reading and Writing Image Files}{Reading and Writing -

200 Image Files} -

201 */ -

202 -

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

204 : QPaintDevice() -

205 { -

206 doInit(0, 0, QPlatformPixmap::PixmapType); -

207 if (!qt_pixmap_thread_test()) -

208 return; -

209 -

210 load(fileName, format, flags); -

211 } -

212 -

213 /*! -

214 Constructs a pixmap that is a copy of the given \a pixmap. -

215 -

216 \sa copy() -

217 */ -

218 -

219 QPixmap::QPixmap(const QPixmap &pixmap) -

220 : QPaintDevice() -

221 { -

222 if (!qt_pixmap_thread_test()) { -

223 doInit(0, 0, QPlatformPixmap::PixmapType); -

224 return; -

225 } -

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

227 pixmap.copy().swap(*this); -

228 } else { -

229 data = pixmap.data; -

230 } -

231 } -

232 -

233 /*! -

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

235 valid XPM image. -

236 -

237 Errors are silently ignored. -

238 -

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

240 by using an unusual declaration: -

241 -

242 \snippet code/src_gui_image_qpixmap.cpp 0 -

243 -

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

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

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

247 */ -

248 #ifndef QT_NO_IMAGEFORMAT_XPM -

249 QPixmap::QPixmap(const char * const xpm[]) -

250 : QPaintDevice() -

251 { -

252 doInit(0, 0, QPlatformPixmap::PixmapType); -

253 if (!xpm) -

254 return; -

255 -

256 QImage image(xpm); -

257 if (!image.isNull()) { -

258 if (data && data->pixelType() == QPlatformPixmap::BitmapType) -

259 *this = QBitmap::fromImage(image); -

260 else -

261 *this = fromImage(image); -

262 } -

263 } -

264 #endif -

265 -

266 -

267 /*! -

268 Destroys the pixmap. -

269 */ -

270 -

271 QPixmap::~QPixmap() -

272 { -

273 Q_ASSERT(!data || data->ref.load() >= 1); // Catch if ref-counting changes again -

274 } -

275 -

276 /*! -

277 \internal -

278 */ -

279 int QPixmap::devType() const -

280 { -

281 return QInternal::Pixmap; -

282 } -

283 -

284 /*! -

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

286 \overload -

287 -

288 Returns a deep copy of the subset of the pixmap that is specified -

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

290 */ -

291 -

292 /*! -

293 \fn QPixmap QPixmap::copy(const QRect &rectangle) const -

294 -

295 Returns a deep copy of the subset of the pixmap that is specified -

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

297 see the \l {Implicit Data Sharing} documentation. -

298 -

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

300 -

301 \sa operator=(), QPixmap(), {QPixmap#Pixmap -

302 Transformations}{Pixmap Transformations} -

303 */ -

304 QPixmap QPixmap::copy(const QRect &rect) const -

305 { -

306 if (isNull()) -

307 return QPixmap(); -

308 -

309 QRect r(0, 0, width(), height()); -

310 if (!rect.isEmpty()) -

311 r = r.intersected(rect); -

312 -

313 QPlatformPixmap *d = data->createCompatiblePlatformPixmap(); -

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

315 return QPixmap(d); -

316 } -

317 -

318 /*! -

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

320 \since 4.6 -

321 -

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

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

324 -

325 \sa QWidget::scroll(), QGraphicsItem::scroll() -

326 */ -

327 -

328 /*! -

329 \since 4.6 -

330 -

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

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

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

334 -

335 \snippet code/src_gui_image_qpixmap.cpp 2 -

336 -

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

338 -

339 \sa QWidget::scroll(), QGraphicsItem::scroll() -

340 */ -

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

342 { -

343 if (isNull() || (dx == 0 && dy == 0)) -

344 return; -

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

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

347 if (src.isEmpty()) { -

348 if (exposed) -

349 *exposed += dest; -

350 return; -

351 } -

352 -

353 detach(); -

354 -

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

356 // Fallback -

357 QPixmap pix = *this; -

358 QPainter painter(&pix); -

359 painter.setCompositionMode(QPainter::CompositionMode_Source); -

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

361 painter.end(); -

362 *this = pix; -

363 } -

364 -

365 if (exposed) { -

366 *exposed += dest; -

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

368 } -

369 } -

370 -

371 /*! -

372 Assigns the given \a pixmap to this pixmap and returns a reference -

373 to this pixmap. -

374 -

375 \sa copy(), QPixmap() -

376 */ -

377 -

378 QPixmap &QPixmap::operator=(const QPixmap &pixmap) -

379 { -

380 if (paintingActive()) { -

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

382 return *this; -

383 } -

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

385 pixmap.copy().swap(*this); -

386 } else { -

387 data = pixmap.data; -

388 } -

389 return *this; -

390 } -

391 -

392 /*! -

393 \fn QPixmap &QPixmap::operator=(QPixmap &&other) -

394 -

395 Move-assigns \a other to this QPixmap instance. -

396 -

397 \since 5.2 -

398 */ -

399 -

400 /*! -

401 \fn void QPixmap::swap(QPixmap &other) -

402 \since 4.8 -

403 -

404 Swaps pixmap \a other with this pixmap. This operation is very -

405 fast and never fails. -

406 */ -

407 -

408 /*! -

409 Returns the pixmap as a QVariant. -

410 */ -

411 QPixmap::operator QVariant() const -

412 { -

413 return QVariant(QVariant::Pixmap, this); -

414 } -

415 -

416 /*! -

417 \fn bool QPixmap::operator!() const -

418 -

419 Returns \c true if this is a null pixmap; otherwise returns \c false. -

420 -

421 \sa isNull() -

422 */ -

423 -

424 /*! -

425 Converts the pixmap to a QImage. Returns a null image if the -

426 conversion fails. -

427 -

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

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

430 closely represents the underlying system. Usually this will be -

431 QImage::Format_ARGB32_Premultiplied for pixmaps with an alpha and -

432 QImage::Format_RGB32 or QImage::Format_RGB16 for pixmaps without -

433 alpha. -

434 -

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

436 ignored. -

437 -

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

439 */ -

440 QImage QPixmap::toImage() const -

441 { -

442 if (isNull()) -

443 return QImage(); -

444 -

445 return data->toImage(); -

446 } -

447 -

448 /*! -

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

450 -

451 Returns the actual matrix used for transforming a pixmap with the -

452 given \a width, \a height and \a matrix. -

453 -

454 When transforming a pixmap using the transformed() function, the -

455 transformation matrix is internally adjusted to compensate for -

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

457 pixmap containing all transformed points of the original -

458 pixmap. This function returns the modified matrix, which maps -

459 points correctly from the original pixmap into the new pixmap. -

460 -

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

462 Transformations} -

463 */ -

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

465 { -

466 return QImage::trueMatrix(m, w, h); -

467 } -

468 -

469 /*! -

470 \overload -

471 -

472 This convenience function loads the matrix \a m into a -

473 QTransform and calls the overloaded function with the -

474 QTransform and the width \a w and the height \a h. -

475 */ -

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

477 { -

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

479 } -

480 -

481 -

482 /*! -

483 \fn bool QPixmap::isQBitmap() const -

484 -

485 Returns \c true if this is a QBitmap; otherwise returns \c false. -

486 */ -

487 -

488 bool QPixmap::isQBitmap() const -

489 { -

490 return data && data->type == QPlatformPixmap::BitmapType; -

491 } -

492 -

493 /*! -

494 \fn bool QPixmap::isNull() const -

495 -

496 Returns \c true if this is a null pixmap; otherwise returns \c false. -

497 -

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

499 cannot draw in a null pixmap. -

500 */ -

501 bool QPixmap::isNull() const -

502 { -

503 return !data || data->isNull(); -

504 } -

505 -

506 /*! -

507 \fn int QPixmap::width() const -

508 -

509 Returns the width of the pixmap. -

510 -

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

512 */ -

513 int QPixmap::width() const -

514 { -

515 return data ? data->width() : 0; -

516 } -

517 -

518 /*! -

519 \fn int QPixmap::height() const -

520 -

521 Returns the height of the pixmap. -

522 -

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

524 */ -

525 int QPixmap::height() const -

526 { -

527 return data ? data->height() : 0; -

528 } -

529 -

530 /*! -

531 \fn QSize QPixmap::size() const -

532 -

533 Returns the size of the pixmap. -

534 -

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

536 Information} -

537 */ -

538 QSize QPixmap::size() const -

539 { -

540 return data ? QSize(data->width(), data->height()) : QSize(0, 0); -

541 } -

542 -

543 /*! -

544 \fn QRect QPixmap::rect() const -

545 -

546 Returns the pixmap's enclosing rectangle. -

547 -

548 \sa {QPixmap#Pixmap Information}{Pixmap Information} -

549 */ -

550 QRect QPixmap::rect() const -

551 { -

552 return data ? QRect(0, 0, data->width(), data->height()) : QRect(); -

553 } -

554 -

555 /*! -

556 \fn int QPixmap::depth() const -

557 -

558 Returns the depth of the pixmap. -

559 -

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

561 of a pixmap. A null pixmap has depth 0. -

562 -

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

564 Information} -

565 */ -

566 int QPixmap::depth() const -

567 { -

568 return data ? data->depth() : 0; -

569 } -

570 -

571 /*! -

572 Sets a mask bitmap. -

573 -

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

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

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

577 pixmap. -

578 -

579 Setting a null mask resets the mask, leaving the previously transparent -

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

581 being painted on. -

582 -

583 \warning This is potentially an expensive operation. -

584 -

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

586 QBitmap -

587 */ -

588 void QPixmap::setMask(const QBitmap &mask) -

589 { -

590 if (paintingActive()) { -

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

592 return; -

593 } -

594 -

595 if (!mask.isNull() && mask.size() != size()) { -

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

597 return; -

598 } -

599 -

600 if (isNull()) -

601 return; -

602 -

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

604 return; -

605 -

606 detach(); -

607 -

608 QImage image = data->toImage(); -

609 if (mask.size().isEmpty()) { -

610 if (image.depth() != 1) { // hw: ???? -

611 image = image.convertToFormat(QImage::Format_RGB32); -

612 } -

613 } else { -

614 const int w = image.width(); -

615 const int h = image.height(); -

616 -

617 switch (image.depth()) { -

618 case 1: { -

619 const QImage imageMask = mask.toImage().convertToFormat(image.format()); -

620 for (int y = 0; y < h; ++y) { -

621 const uchar *mscan = imageMask.scanLine(y); -

622 uchar *tscan = image.scanLine(y); -

623 int bytesPerLine = image.bytesPerLine(); -

624 for (int i = 0; i < bytesPerLine; ++i) -

625 tscan[i] &= mscan[i]; -

626 } -

627 break; -

628 } -

629 default: { -

630 const QImage imageMask = mask.toImage().convertToFormat(QImage::Format_MonoLSB); -

631 image = image.convertToFormat(QImage::Format_ARGB32_Premultiplied); -

632 for (int y = 0; y < h; ++y) { -

633 const uchar *mscan = imageMask.scanLine(y); -

634 QRgb *tscan = (QRgb *)image.scanLine(y); -

635 for (int x = 0; x < w; ++x) { -

636 if (!(mscan[x>>3] & (1 << (x&7)))) -

637 tscan[x] = 0; -

638 } -

639 } -

640 break; -

641 } -

642 } -

643 } -

644 data->fromImage(image, Qt::AutoColor); -

645 } -

646 -

647 /*! -

648 Returns the device pixel ratio for the pixmap. This is the -

649 ratio between \e{device pixels} and \e{device independent pixels}. -

650 -

651 Use this function when calculating layout geometry based on -

652 the pixmap size: QSize layoutSize = image.size() / image.devicePixelRatio() -

653 -

654 The default value is 1.0. -

655 -

656 \sa setDevicePixelRatio(), QImageReader -

657 */ -

658 qreal QPixmap::devicePixelRatio() const -

659 { -

660 if (!data) -

661 return qreal(1.0); -

662 return data->devicePixelRatio(); -

663 } -

664 -

665 /*! -

666 Sets the device pixel ratio for the pixmap. This is the -

667 ratio between image pixels and device-independent pixels. -

668 -

669 The default \a scaleFactor is 1.0. Setting it to something else has -

670 two effects: -

671 -

672 QPainters that are opened on the pixmap will be scaled. For -

673 example, painting on a 200x200 image if with a ratio of 2.0 -

674 will result in effective (device-independent) painting bounds -

675 of 100x100. -

676 -

677 Code paths in Qt that calculate layout geometry based on the -

678 pixmap size will take the ratio into account: -

679 QSize layoutSize = pixmap.size() / pixmap.devicePixelRatio() -

680 The net effect of this is that the pixmap is displayed as -

681 high-DPI pixmap rather than a large pixmap -

682 (see \l{Drawing High Resolution Versions of Pixmaps and Images}). -

683 -

684 \sa devicePixelRatio() -

685 */ -

686 void QPixmap::setDevicePixelRatio(qreal scaleFactor) -

687 { -

688 if (isNull()) -

689 return; -

690 -

691 if (scaleFactor == data->devicePixelRatio()) -

692 return; -

693 -

694 detach(); -

695 data->setDevicePixelRatio(scaleFactor); -

696 } -

697 -

698 #ifndef QT_NO_IMAGE_HEURISTIC_MASK -

699 /*! -

700 Creates and returns a heuristic mask for this pixmap. -

701 -

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

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

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

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

706 than the data pixels. -

707 -

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

709 can do things such as the following: -

710 -

711 \snippet code/src_gui_image_qpixmap.cpp 1 -

712 -

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

714 QImage, and non-trivial computations. -

715 -

716 \sa QImage::createHeuristicMask(), createMaskFromColor() -

717 */ -

718 QBitmap QPixmap::createHeuristicMask(bool clipTight) const -

719 { -

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

721 return m; -

722 } -

723 #endif -

724 -

725 /*! -

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

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

728 maskColor will be transparent. If \a mode is Qt::MaskOutColor, all pixels -

729 matching the maskColor will be opaque. -

730 -

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

732 QImage. -

733 -

734 \sa createHeuristicMask(), QImage::createMaskFromColor() -

735 */ -

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

737 { -

738 QImage image = toImage().convertToFormat(QImage::Format_ARGB32); -

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

740 } -

741 -

742 /*! -

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

744 true if the pixmap was successfully loaded; otherwise invalidates -

745 the pixmap and returns \c false. -

746 -

747 The loader attempts to read the pixmap using the specified \a -

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

749 the loader probes the file for a header to guess the file format. -

750 -

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

752 of the application's embedded resources. See the -

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

754 embed pixmaps and other resource files in the application's -

755 executable. -

756 -

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

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

759 control the conversion. -

760 -

761 Note that QPixmaps are automatically added to the QPixmapCache -

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

763 be acquired. -

764 -

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

766 Files}{Reading and Writing Image Files} -

767 */ -

768 -

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

770 { -

771 if (!fileName.isEmpty()) { -

772 -

773 QFileInfo info(fileName); -

774 // Note: If no extension is provided, we try to match the -

775 // file against known plugin extensions -

776 if (info.completeSuffix().isEmpty() || info.exists()) { -

777 -

778 QString key = QLatin1String("qt_pixmap") -

779 % info.absoluteFilePath() -

780 % HexString<uint>(info.lastModified().toTime_t()) -

781 % HexString<quint64>(info.size()) -

782 % HexString<uint>(data ? data->pixelType() : QPlatformPixmap::PixmapType); -

783 -

784 if (QPixmapCache::find(key, this)) -

785 return true; -

786 -

787 data = QPlatformPixmap::create(0, 0, data ? data->pixelType() : QPlatformPixmap::PixmapType); -

788 -

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

790 QPixmapCache::insert(key, *this); -

791 return true; -

792 } -

793 } -

794 } -

795 -

796 if (!isNull()) { -

797 if (isQBitmap()) -

798 *this = QBitmap(); -

799 else -

800 data.reset(); -

801 } -

802 return false; -

803 } -

804 -

805 /*! -

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

807 -

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

809 data. Returns \c true if the pixmap was loaded successfully; -

810 otherwise invalidates the pixmap and returns \c false. -

811 -

812 The loader attempts to read the pixmap using the specified \a -

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

814 the loader probes the file for a header to guess the file format. -

815 -

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

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

818 control the conversion. -

819 -

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

821 Writing Image Files} -

822 */ -

823 -

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

825 { -

826 if (len == 0 || buf == 0) { -

827 data.reset(); -

828 return false; -

829 } -

830 -

831 data = QPlatformPixmap::create(0, 0, QPlatformPixmap::PixmapType); -

832 -

833 if (data->fromData(buf, len, format, flags)) -

834 return true; -

835 -

836 data.reset(); -

837 return false; -

838 } -

839 -

840 /*! -

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

842 -

843 \overload -

844 -

845 Loads a pixmap from the binary \a data using the specified \a -

846 format and conversion \a flags. -

847 */ -

848 -

849 -

850 /*! -

851 Saves the pixmap to the file with the given \a fileName using the -

852 specified image file \a format and \a quality factor. Returns \c true -

853 if successful; otherwise returns \c false. -

854 -

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

856 0 to obtain small compressed files, 100 for large uncompressed -

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

858 -

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

860 suffix. -

861 -

862 \sa {QPixmap#Reading and Writing Image Files}{Reading and Writing -

863 Image Files} -

864 */ -

865 -

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

867 { -

868 if (isNull()) -

869 return false; // nothing to save -

870 QImageWriter writer(fileName, format); -

871 return doImageIO(&writer, quality); -

872 } -

873 -

874 /*! -

875 \overload -

876 -

877 This function writes a QPixmap to the given \a device using the -

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

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

880 -

881 \snippet image/image.cpp 1 -

882 */ -

883 -

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

885 { -

886 if (isNull()) -

887 return false; // nothing to save -

888 QImageWriter writer(device, format); -

889 return doImageIO(&writer, quality); -

890 } -

891 -

892 /*! \internal -

893 */ -

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

895 { -

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

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

898 if (quality >= 0) -

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

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

901 } -

902 -

903 -

904 /*! -

905 \obsolete -

906 -

907 Use QPainter or the fill(QColor) overload instead. -

908 */ -

909 -

910 void QPixmap::fill(const QPaintDevice *device, const QPoint &p) -

911 { -

912 Q_UNUSED(device) -

913 Q_UNUSED(p) -

914 qWarning("this function is deprecated, ignored"); -

915 } -

916 -

917 -

918 /*! -

919 \fn void QPixmap::fill(const QPaintDevice *device, int x, int y) -

920 \obsolete -

921 -

922 Use QPainter or the fill(QColor) overload instead. -

923 */ -

924 -

925 -

926 /*! -

927 Fills the pixmap with the given \a color. -

928 -

929 The effect of this function is undefined when the pixmap is -

930 being painted on. -

931 -

932 \sa {QPixmap#Pixmap Transformations}{Pixmap Transformations} -

933 */ -

934 -

935 void QPixmap::fill(const QColor &color) -

936 { -

937 if (isNull()) -

938 return; -

939 -

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

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

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

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

944 return; -

945 } -

946 -

947 if (data->ref.load() == 1) { -

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

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

950 detach(); -

951 } else { -

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

953 // it will be filled with new pixel data anyway. -

954 QPlatformPixmap *d = data->createCompatiblePlatformPixmap(); -

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

956 data = d; -

957 } -

958 data->fill(color); -

959 } -

960 -

961 /*! \fn int QPixmap::serialNumber() const -

962 \obsolete -

963 Returns a number that identifies the contents of this QPixmap -

964 object. Distinct QPixmap objects can only have the same serial -

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

966 to). -

967 -

968 Use cacheKey() instead. -

969 -

970 \warning The serial number doesn't necessarily change when -

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

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

973 QPixmapCache class whenever possible. -

974 */ -

975 -

976 /*! -

977 Returns a number that identifies this QPixmap. Distinct QPixmap -

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

979 contents. -

980 -

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

982 */ -

983 qint64 QPixmap::cacheKey() const -

984 { -

985 if (isNull()) -

986 return 0; -

987 -

988 Q_ASSERT(data); -

989 return data->cacheKey(); -

990 } -

991 -

992 #if 0 -

993 static void sendResizeEvents(QWidget *target) -

994 { -

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

996 QApplication::sendEvent(target, &e); -

997 -

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

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

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

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

1002 sendResizeEvents(child); -

1003 } -

1004 } -

1005 #endif -

1006 -

1007 /*! -

1008 \obsolete -

1009 -

1010 Use QWidget::grab() instead. -

1011 */ -

1012 QPixmap QPixmap::grabWidget(QObject *widget, const QRect &rectangle) -

1013 { -

1014 QPixmap pixmap; -

1015 qWarning("QPixmap::grabWidget is deprecated, use QWidget::grab() instead"); -

1016 if (!widget) -

1017 return pixmap; -

1018 QMetaObject::invokeMethod(widget, "grab", Qt::DirectConnection, -

1019 Q_RETURN_ARG(QPixmap, pixmap), -

1020 Q_ARG(QRect, rectangle)); -

1021 return pixmap; -

1022 } -

1023 -

1024 /*! -

1025 \fn QPixmap QPixmap::grabWidget(QObject *widget, int x, int y, int w, int h) -

1026 \obsolete -

1027 -

1028 Use QWidget::grab() instead. -

1029 */ -

1030 -

1031 /***************************************************************************** -

1032 QPixmap stream functions -

1033 *****************************************************************************/ -

1034 #if !defined(QT_NO_DATASTREAM) -

1035 /*! -

1036 \relates QPixmap -

1037 -

1038 Writes the given \a pixmap to the given \a stream as a PNG -

1039 image. Note that writing the stream to a file will not produce a -

1040 valid image file. -

1041 -

1042 \sa QPixmap::save(), {Serializing Qt Data Types} -

1043 */ -

1044 -

1045 QDataStream &operator<<(QDataStream &stream, const QPixmap &pixmap) -

1046 { -

1047 return stream << pixmap.toImage(); -

1048 } -

1049 -

1050 /*! -

1051 \relates QPixmap -

1052 -

1053 Reads an image from the given \a stream into the given \a pixmap. -

1054 -

1055 \sa QPixmap::load(), {Serializing Qt Data Types} -

1056 */ -

1057 -

1058 QDataStream &operator>>(QDataStream &stream, QPixmap &pixmap) -

1059 { -

1060 QImage image; -

1061 stream >> image; -

1062 -

1063 if (image.isNull()) { -

1064 pixmap = QPixmap(); -

1065 } else if (image.depth() == 1) { -

1066 pixmap = QBitmap::fromImage(image); -

1067 } else { -

1068 pixmap = QPixmap::fromImage(image); -

1069 } -

1070 return stream; -

1071 } -

1072 -

1073 #endif // QT_NO_DATASTREAM -

1074 -

1075 /*! -

1076 \internal -

1077 */ -

1078 -

1079 bool QPixmap::isDetached() const -

1080 { -

1081 return data && data->ref.load() == 1; -

1082 } -

1083 -

1084 /*! -

1085 Replaces this pixmap's data with the given \a image using the -

1086 specified \a flags to control the conversion. The \a flags -

1087 argument is a bitwise-OR of the \l{Qt::ImageConversionFlags}. -

1088 Passing 0 for \a flags sets all the default options. Returns \c true -

1089 if the result is that this pixmap is not null. -

1090 -

1091 Note: this function was part of Qt 3 support in Qt 4.6 and earlier. -

1092 It has been promoted to official API status in 4.7 to support updating -

1093 the pixmap's image without creating a new QPixmap as fromImage() would. -

1094 -

1095 \sa fromImage() -

1096 \since 4.7 -

1097 */ -

1098 bool QPixmap::convertFromImage(const QImage &image, Qt::ImageConversionFlags flags) -

1099 { -

1100 detach(); -

1101 if (image.isNull() || !data) -

1102 *this = QPixmap::fromImage(image, flags); -

1103 else -

1104 data->fromImage(image, flags); -

1105 return !isNull(); -

1106 } -

1107 -

1108 /*! -

1109 \fn QPixmap QPixmap::scaled(int width, int height, -

1110 Qt::AspectRatioMode aspectRatioMode, Qt::TransformationMode -

1111 transformMode) const -

1112 -

1113 \overload -

1114 -

1115 Returns a copy of the pixmap scaled to a rectangle with the given -

1116 \a width and \a height according to the given \a aspectRatioMode and -

1117 \a transformMode. -

1118 -

1119 If either the \a width or the \a height is zero or negative, this -

1120 function returns a null pixmap. -

1121 */ -

1122 -

1123 /*! -

1124 \fn QPixmap QPixmap::scaled(const QSize &size, Qt::AspectRatioMode -

1125 aspectRatioMode, Qt::TransformationMode transformMode) const -

1126 -

1127 Scales the pixmap to the given \a size, using the aspect ratio and -

1128 transformation modes specified by \a aspectRatioMode and \a -

1129 transformMode. -

1130 -

1131 \image qimage-scaling.png -

1132 -

1133 \list -

1134 \li If \a aspectRatioMode is Qt::IgnoreAspectRatio, the pixmap -

1135 is scaled to \a size. -

1136 \li If \a aspectRatioMode is Qt::KeepAspectRatio, the pixmap is -

1137 scaled to a rectangle as large as possible inside \a size, preserving the aspect ratio. -

1138 \li If \a aspectRatioMode is Qt::KeepAspectRatioByExpanding, -

1139 the pixmap is scaled to a rectangle as small as possible -

1140 outside \a size, preserving the aspect ratio. -

1141 \endlist -

1142 -

1143 If the given \a size is empty, this function returns a null -

1144 pixmap. -

1145 -

1146 -

1147 In some cases it can be more beneficial to draw the pixmap to a -

1148 painter with a scale set rather than scaling the pixmap. This is -

1149 the case when the painter is for instance based on OpenGL or when -

1150 the scale factor changes rapidly. -

1151 -

1152 \sa isNull(), {QPixmap#Pixmap Transformations}{Pixmap -

1153 Transformations} -

1154 -

1155 */ -

1156 QPixmap QPixmap::scaled(const QSize& s, Qt::AspectRatioMode aspectMode, Qt::TransformationMode mode) const -

1157 { -

1158 if (isNull()) { -

1159 qWarning("QPixmap::scaled: Pixmap is a null pixmap"); -

1160 return QPixmap(); -

1161 } -

1162 if (s.isEmpty()) -

1163 return QPixmap(); -

1164 -

1165 QSize newSize = size(); -

1166 newSize.scale(s, aspectMode); -

1167 newSize.rwidth() = qMax(newSize.width(), 1); -

1168 newSize.rheight() = qMax(newSize.height(), 1); -

1169 if (newSize == size()) -

1170 return *this; -

1171 -

1172 QTransform wm = QTransform::fromScale((qreal)newSize.width() / width(), -

1173 (qreal)newSize.height() / height()); -

1174 QPixmap pix = transformed(wm, mode); -

1175 return pix; -

1176 } -

1177 -

1178 /*! -

1179 \fn QPixmap QPixmap::scaledToWidth(int width, Qt::TransformationMode -

1180 mode) const -

1181 -

1182 Returns a scaled copy of the image. The returned image is scaled -

1183 to the given \a width using the specified transformation \a mode. -

1184 The height of the pixmap is automatically calculated so that the -

1185 aspect ratio of the pixmap is preserved. -

1186 -

1187 If \a width is 0 or negative, a null pixmap is returned. -

1188 -

1189 \sa isNull(), {QPixmap#Pixmap Transformations}{Pixmap -

1190 Transformations} -

1191 */ -

1192 QPixmap QPixmap::scaledToWidth(int w, Qt::TransformationMode mode) const -

1193 { -

1194 if (isNull()) { -

1195 qWarning("QPixmap::scaleWidth: Pixmap is a null pixmap"); -

1196 return copy(); -

1197 } -

1198 if (w <= 0) -

1199 return QPixmap(); -

1200 -

1201 qreal factor = (qreal) w / width(); -

1202 QTransform wm = QTransform::fromScale(factor, factor); -

1203 return transformed(wm, mode); -

1204 } -

1205 -

1206 /*! -

1207 \fn QPixmap QPixmap::scaledToHeight(int height, -

1208 Qt::TransformationMode mode) const -

1209 -

1210 Returns a scaled copy of the image. The returned image is scaled -

1211 to the given \a height using the specified transformation \a mode. -

1212 The width of the pixmap is automatically calculated so that the -

1213 aspect ratio of the pixmap is preserved. -

1214 -

1215 If \a height is 0 or negative, a null pixmap is returned. -

1216 -

1217 \sa isNull(), {QPixmap#Pixmap Transformations}{Pixmap -

1218 Transformations} -

1219 */ -

1220 QPixmap QPixmap::scaledToHeight(int h, Qt::TransformationMode mode) const -

1221 { -

1222 if (isNull()) { -

1223 qWarning("QPixmap::scaleHeight: Pixmap is a null pixmap"); -

1224 return copy(); -

1225 } -

1226 if (h <= 0) -

1227 return QPixmap(); -

1228 -

1229 qreal factor = (qreal) h / height(); -

1230 QTransform wm = QTransform::fromScale(factor, factor); -

1231 return transformed(wm, mode); -

1232 } -

1233 -

1234 /*! -

1235 Returns a copy of the pixmap that is transformed using the given -

1236 transformation \a transform and transformation \a mode. The original -

1237 pixmap is not changed. -

1238 -

1239 The transformation \a transform is internally adjusted to compensate -

1240 for unwanted translation; i.e. the pixmap produced is the smallest -

1241 pixmap that contains all the transformed points of the original -

1242 pixmap. Use the trueMatrix() function to retrieve the actual -

1243 matrix used for transforming the pixmap. -

1244 -

1245 This function is slow because it involves transformation to a -

1246 QImage, non-trivial computations and a transformation back to a -

1247 QPixmap. -

1248 -

1249 \sa trueMatrix(), {QPixmap#Pixmap Transformations}{Pixmap -

1250 Transformations} -

1251 */ -

1252 QPixmap QPixmap::transformed(const QTransform &transform, -

1253 Qt::TransformationMode mode) const -

1254 { -

1255 if (isNull() || transform.type() <= QTransform::TxTranslate) -

1256 return *this; -

1257 -

1258 return data->transformed(transform, mode); -

1259 } -

1260 -

1261 /*! -

1262 \overload -

1263 -

1264 This convenience function loads the \a matrix into a -

1265 QTransform and calls the overloaded function. -

1266 */ -

1267 QPixmap QPixmap::transformed(const QMatrix &matrix, Qt::TransformationMode mode) const -

1268 { -

1269 return transformed(QTransform(matrix), mode); -

1270 } -

1271 -

1272 -

1273 -

1274 -

1275 -

1276 -

1277 -

1278 -

1279 /*! -

1280 \class QPixmap -

1281 \inmodule QtGui -

1282 -

1283 \brief The QPixmap class is an off-screen image representation -

1284 that can be used as a paint device. -

1285 -

1286 \ingroup painting -

1287 \ingroup shared -

1288 -

1289 -

1290 Qt provides four classes for handling image data: QImage, QPixmap, -

1291 QBitmap and QPicture. QImage is designed and optimized for I/O, -

1292 and for direct pixel access and manipulation, while QPixmap is -

1293 designed and optimized for showing images on screen. QBitmap is -

1294 only a convenience class that inherits QPixmap, ensuring a depth -

1295 of 1. The isQBitmap() function returns \c true if a QPixmap object is -

1296 really a bitmap, otherwise returns \c false. Finally, the QPicture class -

1297 is a paint device that records and replays QPainter commands. -

1298 -

1299 A QPixmap can easily be displayed on the screen using QLabel or -

1300 one of QAbstractButton's subclasses (such as QPushButton and -

1301 QToolButton). QLabel has a pixmap property, whereas -

1302 QAbstractButton has an icon property. -

1303 -

1304 QPixmap objects can be passed around by value since the QPixmap -

1305 class uses implicit data sharing. For more information, see the \l -

1306 {Implicit Data Sharing} documentation. QPixmap objects can also be -

1307 streamed. -

1308 -

1309 Note that the pixel data in a pixmap is internal and is managed by -

1310 the underlying window system. Because QPixmap is a QPaintDevice -

1311 subclass, QPainter can be used to draw directly onto pixmaps. -

1312 Pixels can only be accessed through QPainter functions or by -

1313 converting the QPixmap to a QImage. However, the fill() function -

1314 is available for initializing the entire pixmap with a given color. -

1315 -

1316 There are functions to convert between QImage and -

1317 QPixmap. Typically, the QImage class is used to load an image -

1318 file, optionally manipulating the image data, before the QImage -

1319 object is converted into a QPixmap to be shown on -

1320 screen. Alternatively, if no manipulation is desired, the image -

1321 file can be loaded directly into a QPixmap. -

1322 -

1323 QPixmap provides a collection of functions that can be used to -

1324 obtain a variety of information about the pixmap. In addition, -

1325 there are several functions that enables transformation of the -

1326 pixmap. -

1327 -

1328 \tableofcontents -

1329 -

1330 \section1 Reading and Writing Image Files -

1331 -

1332 QPixmap provides several ways of reading an image file: The file -

1333 can be loaded when constructing the QPixmap object, or by using -

1334 the load() or loadFromData() functions later on. When loading an -

1335 image, the file name can either refer to an actual file on disk or -

1336 to one of the application's embedded resources. See \l{The Qt -

1337 Resource System} overview for details on how to embed images and -

1338 other resource files in the application's executable. -

1339 -

1340 Simply call the save() function to save a QPixmap object. -

1341 -

1342 The complete list of supported file formats are available through -

1343 the QImageReader::supportedImageFormats() and -

1344 QImageWriter::supportedImageFormats() functions. New file formats -

1345 can be added as plugins. By default, Qt supports the following -

1346 formats: -

1347 -

1348 \table -

1349 \header \li Format \li Description \li Qt's support -

1350 \row \li BMP \li Windows Bitmap \li Read/write -

1351 \row \li GIF \li Graphic Interchange Format (optional) \li Read -

1352 \row \li JPG \li Joint Photographic Experts Group \li Read/write -

1353 \row \li JPEG \li Joint Photographic Experts Group \li Read/write -

1354 \row \li PNG \li Portable Network Graphics \li Read/write -

1355 \row \li PBM \li Portable Bitmap \li Read -

1356 \row \li PGM \li Portable Graymap \li Read -

1357 \row \li PPM \li Portable Pixmap \li Read/write -

1358 \row \li XBM \li X11 Bitmap \li Read/write -

1359 \row \li XPM \li X11 Pixmap \li Read/write -

1360 \endtable -

1361 -

1362 \section1 Pixmap Information -

1363 -

1364 QPixmap provides a collection of functions that can be used to -

1365 obtain a variety of information about the pixmap: -

1366 -

1367 \table -

1368 \header -

1369 \li \li Available Functions -

1370 \row -

1371 \li Geometry -

1372 \li -

1373 The size(), width() and height() functions provide information -

1374 about the pixmap's size. The rect() function returns the image's -

1375 enclosing rectangle. -

1376 -

1377 \row -

1378 \li Alpha component -

1379 \li -

1380 -

1381 The hasAlphaChannel() returns \c true if the pixmap has a format that -

1382 respects the alpha channel, otherwise returns \c false. The hasAlpha(), -

1383 setMask() and mask() functions are legacy and should not be used. -

1384 They are potentially very slow. -

1385 -

1386 The createHeuristicMask() function creates and returns a 1-bpp -

1387 heuristic mask (i.e. a QBitmap) for this pixmap. It works by -

1388 selecting a color from one of the corners and then chipping away -

1389 pixels of that color, starting at all the edges. The -

1390 createMaskFromColor() function creates and returns a mask (i.e. a -

1391 QBitmap) for the pixmap based on a given color. -

1392 -

1393 \row -

1394 \li Low-level information -

1395 \li -

1396 -

1397 The depth() function returns the depth of the pixmap. The -

1398 defaultDepth() function returns the default depth, i.e. the depth -

1399 used by the application on the given screen. -

1400 -

1401 The cacheKey() function returns a number that uniquely -

1402 identifies the contents of the QPixmap object. -

1403 -

1404 The x11Info() function returns information about the configuration -

1405 of the X display used by the screen to which the pixmap currently -

1406 belongs. The x11PictureHandle() function returns the X11 Picture -

1407 handle of the pixmap for XRender support. Note that the two latter -

1408 functions are only available on x11. -

1409 -

1410 \endtable -

1411 -

1412 \section1 Pixmap Conversion -

1413 -

1414 A QPixmap object can be converted into a QImage using the -

1415 toImage() function. Likewise, a QImage can be converted into a -

1416 QPixmap using the fromImage(). If this is too expensive an -

1417 operation, you can use QBitmap::fromImage() instead. -

1418 -

1419 To convert a QPixmap to and from HICON you can use the QtWinExtras -

1420 functions QtWin::toHICON() and QtWin::fromHICON() respectively. -

1421 -

1422 \section1 Pixmap Transformations -

1423 -

1424 QPixmap supports a number of functions for creating a new pixmap -

1425 that is a transformed version of the original: -

1426 -

1427 The scaled(), scaledToWidth() and scaledToHeight() functions -

1428 return scaled copies of the pixmap, while the copy() function -

1429 creates a QPixmap that is a plain copy of the original one. -

1430 -

1431 The transformed() function returns a copy of the pixmap that is -

1432 transformed with the given transformation matrix and -

1433 transformation mode: Internally, the transformation matrix is -

1434 adjusted to compensate for unwanted translation, -

1435 i.e. transformed() returns the smallest pixmap containing all -

1436 transformed points of the original pixmap. The static trueMatrix() -

1437 function returns the actual matrix used for transforming the -

1438 pixmap. -

1439 -

1440 \note When using the native X11 graphics system, the pixmap -

1441 becomes invalid when the QApplication instance is destroyed. -

1442 -

1443 \sa QBitmap, QImage, QImageReader, QImageWriter -

1444 */ -

1445 -

1446 -

1447 /*! -

1448 \typedef QPixmap::DataPtr -

1449 \internal -

1450 */ -

1451 -

1452 /*! -

1453 \fn DataPtr &QPixmap::data_ptr() -

1454 \internal -

1455 */ -

1456 -

1457 /*! -

1458 Returns \c true if this pixmap has an alpha channel, \e or has a -

1459 mask, otherwise returns \c false. -

1460 -

1461 \sa hasAlphaChannel(), mask() -

1462 */ -

1463 bool QPixmap::hasAlpha() const -

1464 { -

1465 return data && data->hasAlphaChannel(); -

1466 } -

1467 -

1468 /*! -

1469 Returns \c true if the pixmap has a format that respects the alpha -

1470 channel, otherwise returns \c false. -

1471 -

1472 \sa hasAlpha() -

1473 */ -

1474 bool QPixmap::hasAlphaChannel() const -

1475 { -

1476 return data && data->hasAlphaChannel(); -

1477 } -

1478 -

1479 /*! -

1480 \internal -

1481 */ -

1482 int QPixmap::metric(PaintDeviceMetric metric) const -

1483 { -

1484 return data ? data->metric(metric) : 0; -

1485 } -

1486 -

1487 /*! -

1488 \internal -

1489 */ -

1490 QPaintEngine *QPixmap::paintEngine() const -

1491 { -

1492 return data ? data->paintEngine() : 0; -

1493 } -

1494 -

1495 /*! -

1496 \fn QBitmap QPixmap::mask() const -

1497 -

1498 Extracts a bitmap mask from the pixmap's alpha channel. -

1499 -

1500 \warning This is potentially an expensive operation. The mask of -

1501 the pixmap is extracted dynamically from the pixeldata. -

1502 -

1503 \sa setMask(), {QPixmap#Pixmap Information}{Pixmap Information} -

1504 */ -

1505 QBitmap QPixmap::mask() const -

1506 { -

1507 if (!data || !hasAlphaChannel()) -

1508 return QBitmap(); -

1509 -

1510 const QImage img = toImage(); -

1511 bool shouldConvert = (img.format() != QImage::Format_ARGB32 && img.format() != QImage::Format_ARGB32_Premultiplied); -

1512 const QImage image = (shouldConvert ? img.convertToFormat(QImage::Format_ARGB32_Premultiplied) : img); -

1513 const int w = image.width(); -

1514 const int h = image.height(); -

1515 -

1516 QImage mask(w, h, QImage::Format_MonoLSB); -

1517 if (mask.isNull()) // allocation failed -

1518 return QBitmap(); -

1519 -

1520 mask.setColorCount(2); -

1521 mask.setColor(0, QColor(Qt::color0).rgba()); -

1522 mask.setColor(1, QColor(Qt::color1).rgba()); -

1523 -

1524 const int bpl = mask.bytesPerLine(); -

1525 -

1526 for (int y = 0; y < h; ++y) { -

1527 const QRgb *src = reinterpret_cast<const QRgb*>(image.scanLine(y)); -

1528 uchar *dest = mask.scanLine(y); -

1529 memset(dest, 0, bpl); -

1530 for (int x = 0; x < w; ++x) { -

1531 if (qAlpha(*src) > 0) -

1532 dest[x >> 3] |= (1 << (x & 7)); -

1533 ++src; -

1534 } -

1535 } -

1536 -

1537 return QBitmap::fromImage(mask); -

1538 } -

1539 -

1540 /*! -

1541 Returns the default pixmap depth used by the application. -

1542 -

1543 On all platforms the depth of the primary screen will be returned. -

1544 -

1545 \sa depth(), QColormap::depth(), {QPixmap#Pixmap Information}{Pixmap Information} -

1546 -

1547 */ -

1548 int QPixmap::defaultDepth() -

1549 { -

1550 return QGuiApplication::primaryScreen()->depth(); -

1551 } -

1552 -

1553 /*! -

1554 Detaches the pixmap from shared pixmap data. -

1555 -

1556 A pixmap is automatically detached by Qt whenever its contents are -

1557 about to change. This is done in almost all QPixmap member -

1558 functions that modify the pixmap (fill(), fromImage(), -

1559 load(), etc.), and in QPainter::begin() on a pixmap. -

1560 -

1561 There are two exceptions in which detach() must be called -

1562 explicitly, that is when calling the handle() or the -

1563 x11PictureHandle() function (only available on X11). Otherwise, -

1564 any modifications done using system calls, will be performed on -

1565 the shared data. -

1566 -

1567 The detach() function returns immediately if there is just a -

1568 single reference or if the pixmap has not been initialized yet. -

1569 */ -

1570 void QPixmap::detach() -

1571 { -

1572 if (!data) -

1573 return; -

1574 -

1575 // QPixmap.data member may be QRuntimePlatformPixmap so use handle() function to get -

1576 // the actual underlaying runtime pixmap data. -

1577 QPlatformPixmap *pd = handle(); -

1578 QPlatformPixmap::ClassId id = pd->classId(); -

1579 if (id == QPlatformPixmap::RasterClass) { -

1580 QRasterPlatformPixmap *rasterData = static_cast<QRasterPlatformPixmap*>(pd); -

1581 rasterData->image.detach(); -

1582 } -

1583 -

1584 if (data->is_cached && data->ref.load() == 1) -

1585 QImagePixmapCleanupHooks::executePlatformPixmapModificationHooks(data.data()); -

1586 -

1587 if (data->ref.load() != 1) { -

1588 *this = copy(); -

1589 } -

1590 ++data->detach_no; -

1591 } -

1592 -

1593 /*! -

1594 \fn QPixmap QPixmap::fromImage(const QImage &image, Qt::ImageConversionFlags flags) -

1595 -

1596 Converts the given \a image to a pixmap using the specified \a -

1597 flags to control the conversion. The \a flags argument is a -

1598 bitwise-OR of the \l{Qt::ImageConversionFlags}. Passing 0 for \a -

1599 flags sets all the default options. -

1600 -

1601 In case of monochrome and 8-bit images, the image is first -

1602 converted to a 32-bit pixmap and then filled with the colors in -

1603 the color table. If this is too expensive an operation, you can -

1604 use QBitmap::fromImage() instead. -

1605 -

1606 \sa fromImageReader(), toImage(), {QPixmap#Pixmap Conversion}{Pixmap Conversion} -

1607 */ -

1608 QPixmap QPixmap::fromImage(const QImage &image, Qt::ImageConversionFlags flags) -

1609 { -

1610 if (image.isNull()) -

1611 return QPixmap(); -

1612 -

1613 QScopedPointer<QPlatformPixmap> data(QGuiApplicationPrivate::platformIntegration()->createPlatformPixmap(QPlatformPixmap::PixmapType)); -

1614 data->fromImage(image, flags); -

1615 return QPixmap(data.take()); -

1616 } -

1617 -

1618 /*! -

1619 \fn QPixmap QPixmap::fromImage(QImage &&image, Qt::ImageConversionFlags flags) -

1620 \since 5.3 -

1621 \overload -

1622 -

1623 Converts the given \a image to a pixmap without copying if possible. -

1624 */ -

1625 -

1626 -

1627 /*! -

1628 \internal -

1629 */ -

1630 QPixmap QPixmap::fromImageInPlace(QImage &image, Qt::ImageConversionFlags flags) -

1631 { -

1632 if (image.isNull()) -

1633 return QPixmap(); -

1634 -

1635 QScopedPointer<QPlatformPixmap> data(QGuiApplicationPrivate::platformIntegration()->createPlatformPixmap(QPlatformPixmap::PixmapType)); -

1636 data->fromImageInPlace(image, flags); -

1637 return QPixmap(data.take()); -

1638 } -

1639 -

1640 /*! -

1641 \fn QPixmap QPixmap::fromImageReader(QImageReader *imageReader, Qt::ImageConversionFlags flags) -

1642 -

1643 Create a QPixmap from an image read directly from an \a imageReader. -

1644 The \a flags argument is a bitwise-OR of the \l{Qt::ImageConversionFlags}. -

1645 Passing 0 for \a flags sets all the default options. -

1646 -

1647 On some systems, reading an image directly to QPixmap can use less memory than -

1648 reading a QImage to convert it to QPixmap. -

1649 -

1650 \sa fromImage(), toImage(), {QPixmap#Pixmap Conversion}{Pixmap Conversion} -

1651 */ -

1652 QPixmap QPixmap::fromImageReader(QImageReader *imageReader, Qt::ImageConversionFlags flags) -

1653 { -

1654 QScopedPointer<QPlatformPixmap> data(QGuiApplicationPrivate::platformIntegration()->createPlatformPixmap(QPlatformPixmap::PixmapType)); -

1655 data->fromImageReader(imageReader, flags); -

1656 return QPixmap(data.take()); -

1657 } -

1658 -

1659 /*! -

1660 \fn QPixmap QPixmap::grabWindow(WId window, int x, int y, int -

1661 width, int height) -

1662 -

1663 Creates and returns a pixmap constructed by grabbing the contents -

1664 of the given \a window restricted by QRect(\a x, \a y, \a width, -

1665 \a height). -

1666 -

1667 The arguments (\a{x}, \a{y}) specify the offset in the window, -

1668 whereas (\a{width}, \a{height}) specify the area to be copied. If -

1669 \a width is negative, the function copies everything to the right -

1670 border of the window. If \a height is negative, the function -

1671 copies everything to the bottom of the window. -

1672 -

1673 The window system identifier (\c WId) can be retrieved using the -

1674 QWidget::winId() function. The rationale for using a window -

1675 identifier and not a QWidget, is to enable grabbing of windows -

1676 that are not part of the application, window system frames, and so -

1677 on. -

1678 -

1679 The grabWindow() function grabs pixels from the screen, not from -

1680 the window, i.e. if there is another window partially or entirely -

1681 over the one you grab, you get pixels from the overlying window, -

1682 too. The mouse cursor is generally not grabbed. -

1683 -

1684 Note on X11 that if the given \a window doesn't have the same depth -

1685 as the root window, and another window partially or entirely -

1686 obscures the one you grab, you will \e not get pixels from the -

1687 overlying window. The contents of the obscured areas in the -

1688 pixmap will be undefined and uninitialized. -

1689 -

1690 On Windows Vista and above grabbing a layered window, which is -

1691 created by setting the Qt::WA_TranslucentBackground attribute, will -

1692 not work. Instead grabbing the desktop widget should work. -

1693 -

1694 \warning In general, grabbing an area outside the screen is not -

1695 safe. This depends on the underlying window system. -

1696 -

1697 \warning The function is deprecated in Qt 5.0 since there might be -

1698 platform plugins in which window system identifiers (\c WId) -

1699 are local to a screen. Use QScreen::grabWindow() instead. -

1700 -

1701 \sa grabWidget(), {Screenshot Example} -

1702 \sa QScreen -

1703 \deprecated -

1704 */ -

1705 -

1706 QPixmap QPixmap::grabWindow(WId window, int x, int y, int w, int h) -

1707 { -

1708 qWarning("this function is deprecated, use QScreen::grabWindow() instead." -

1709 " Defaulting to primary screen."); -

1710 return QGuiApplication::primaryScreen()->grabWindow(window, x, y, w, h); -

1711 } -

1712 -

1713 /*! -

1714 \internal -

1715 */ -

1716 QPlatformPixmap* QPixmap::handle() const -

1717 { -

1718 return data.data(); -

1719 } -

1720 -

1721 #ifndef QT_NO_DEBUG_STREAM -

1722 QDebug operator<<(QDebug dbg, const QPixmap &r) -

1723 { -

1724 QDebugStateSaver saver(dbg); -

1725 dbg.resetFormat(); -

1726 dbg.nospace(); -

1727 dbg << "QPixmap("; -

1728 if (r.isNull()) { -

1729 dbg << "null"; -

1730 } else { -

1731 dbg << r.size() << ",depth=" << r.depth() -

1732 << ",devicePixelRatio=" << r.devicePixelRatio() -

1733 << ",cacheKey=" << showbase << hex << r.cacheKey() << dec << noshowbase; -

1734 } -

1735 dbg << ')'; -

1736 return dbg; -

1737 } -

1738 #endif -

1739 -

1740 /*! -

1741 \fn QPixmap QPixmap::alphaChannel() const -

1742 -

1743 Most use cases for this can be achieved using a QPainter and QPainter::CompositionMode instead. -

1744 */ -

1745 -

1746 /*! -

1747 \fn void QPixmap::setAlphaChannel(const QPixmap &p) -

1748 -

1749 Most use cases for this can be achieved using \a p with QPainter and QPainter::CompositionMode instead. -

1750 */ -

1751 -

1752 QT_END_NAMESPACE -

Source code

Switch to Preprocessed file

Generated by Squish Coco Non-Commercial 4.3.0-BETA-master-30-08-2018-4cb69e9