3
3
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
4
4
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5
<!-- /tmp/qt-4.1.4-harald-1150713676011/qt-x11-opensource-src-4.1.4/src/gui/image/qpixmap.cpp -->
6
<!-- /tmp/qt-4.1.4-harald-1150713676011/qt-x11-opensource-src-4.1.4/src/gui/image/qpixmap.cpp -->
5
<!-- /tmp/qt-4.2.0-qt-1159540607313/qt-x11-opensource-src-4.2.0/src/gui/image/qpixmap.cpp -->
8
<title>Qt 4.1: QPixmap Class Reference</title>
9
<style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; }
10
a:link { color: #004faf; text-decoration: none }
11
a:visited { color: #672967; text-decoration: none }
12
td.postheader { font-family: sans-serif }
13
tr.address { font-family: sans-serif }
14
body { background: #ffffff; color: black; }</style>
7
<title>Qt 4.2: QPixmap Class Reference</title>
8
<link href="classic.css" rel="stylesheet" type="text/css" />
17
11
<table border="0" cellpadding="0" cellspacing="0" width="100%">
19
<td align="left" valign="top" width="32"><img src="images/qt-logo.png" align="left" width="32" height="32" border="0" /></td>
13
<td align="left" valign="top" width="32"><a href="http://www.trolltech.com/products/qt"><img src="images/qt-logo.png" align="left" width="32" height="32" border="0" /></a></td>
20
14
<td width="1"> </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="mainclasses.html"><font color="#004faf">Main Classes</font></a> · <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td>
21
<td align="right" valign="top" width="230"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></td></tr></table><h1 align="center">QPixmap Class Reference<br /><sup><sup>[<a href="qtgui.html">QtGui</a> module]</sup></sup></h1>
15
<td align="right" valign="top" width="230"><a href="http://www.trolltech.com"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></a></td></tr></table><h1 align="center">QPixmap Class Reference<br /><sup><sup>[<a href="qtgui.html">QtGui</a> module]</sup></sup></h1>
22
16
<p>The QPixmap class is an off-screen image representation that can be used as a paint device. <a href="#details">More...</a></p>
23
<pre>#include <QPixmap></pre><p>Inherits <a href="qpaintdevice.html">QPaintDevice</a>.</p>
17
<pre> #include <QPixmap></pre><p>Inherits <a href="qpaintdevice.html">QPaintDevice</a>.</p>
24
18
<p>Inherited by <a href="q3canvaspixmap.html">Q3CanvasPixmap</a> and <a href="qbitmap.html">QBitmap</a>.</p>
26
20
<li><a href="qpixmap-members.html">List of all members, including inherited members</a></li>
62
56
<li><div class="fn"/>bool <b><a href="qpixmap.html#loadFromData-3">loadFromData</a></b> ( const QByteArray & <i>data</i>, const char * <i>format</i> = 0, Qt::ImageConversionFlags <i>flags</i> = Qt::AutoColor )</li>
63
57
<li><div class="fn"/>QBitmap <b><a href="qpixmap.html#mask">mask</a></b> () const</li>
64
58
<li><div class="fn"/>QRect <b><a href="qpixmap.html#rect">rect</a></b> () const</li>
65
<li><div class="fn"/>bool <b><a href="qpixmap.html#save">save</a></b> ( const QString & <i>fileName</i>, const char * <i>format</i>, int <i>quality</i> = -1 ) const</li>
66
<li><div class="fn"/>bool <b><a href="qpixmap.html#save-2">save</a></b> ( QIODevice * <i>device</i>, const char * <i>format</i>, int <i>quality</i> = -1 ) const</li>
59
<li><div class="fn"/>bool <b><a href="qpixmap.html#save">save</a></b> ( const QString & <i>fileName</i>, const char * <i>format</i> = 0, int <i>quality</i> = -1 ) const</li>
60
<li><div class="fn"/>bool <b><a href="qpixmap.html#save-2">save</a></b> ( QIODevice * <i>device</i>, const char * <i>format</i> = 0, int <i>quality</i> = -1 ) const</li>
67
61
<li><div class="fn"/>QPixmap <b><a href="qpixmap.html#scaled">scaled</a></b> ( const QSize & <i>size</i>, Qt::AspectRatioMode <i>aspectRatioMode</i> = Qt::IgnoreAspectRatio, Qt::TransformationMode <i>transformMode</i> = Qt::FastTransformation ) const</li>
68
62
<li><div class="fn"/>QPixmap <b><a href="qpixmap.html#scaled-2">scaled</a></b> ( int <i>width</i>, int <i>height</i>, Qt::AspectRatioMode <i>aspectRatioMode</i> = Qt::IgnoreAspectRatio, Qt::TransformationMode <i>transformMode</i> = Qt::FastTransformation ) const</li>
69
63
<li><div class="fn"/>QPixmap <b><a href="qpixmap.html#scaledToHeight">scaledToHeight</a></b> ( int <i>height</i>, Qt::TransformationMode <i>mode</i> = Qt::FastTransformation ) const</li>
113
109
<p>Qt provides four classes for handling image data: <a href="qimage.html">QImage</a>, QPixmap, <a href="qbitmap.html">QBitmap</a> and <a href="qpicture.html">QPicture</a>. <a href="qimage.html">QImage</a> is designed and optimized for I/O, and for direct pixel access and manipulation, while QPixmap is designed and optimized for showing images on screen. <a href="qbitmap.html">QBitmap</a> is only a convenience class that inherits QPixmap, ensuring a depth of 1. The <a href="qpixmap.html#isQBitmap">isQBitmap</a>() function returns true if a QPixmap object is really a bitmap, otherwise returns false. Finally, the <a href="qpicture.html">QPicture</a> class is a paint device that records and replays <a href="qpainter.html">QPainter</a> commands.</p>
114
110
<p>A QPixmap can easily be displayed on the screen using <a href="qlabel.html">QLabel</a> or one of <a href="qabstractbutton.html">QAbstractButton</a>'s subclasses (such as <a href="qpushbutton.html">QPushButton</a> and <a href="qtoolbutton.html">QToolButton</a>). <a href="qlabel.html">QLabel</a> has a pixmap property, whereas <a href="qabstractbutton.html">QAbstractButton</a> has an icon property. And because QPixmap is a <a href="qpaintdevice.html">QPaintDevice</a> subclass, <a href="qpainter.html">QPainter</a> can be used to draw directly onto pixmaps.</p>
115
111
<p>In addition to the ordinary constructors, a QPixmap can be constructed using the static <a href="qpixmap.html#grabWidget">grabWidget</a>() and <a href="qpixmap.html#grabWindow">grabWindow</a>() functions which creates a QPixmap and paints the given widget, or window, in it.</p>
116
<p>Note that the pixel data in a pixmap is internal and is managed by the underlying window system. Pixels can only be accessed through <a href="qpainter.html">QPainter</a> functions or by converting the QPixmap to a <a href="qimage.html">QImage</a>. Depending on the system, QPixmap is stored using a RGB32 or a premultiplied alpha format. If the image has an alpha channel, and if the system allows, the preferred format is premultiplied alpha. Note also that QPixmap, unlike <a href="qimage.html">QImage</a>, may be hardware dependent. On X11 and Mac, a QPixmap is stored on the server side while a <a href="qimage.html">QImage</a> is stored on the client side(on Windows, these two classes have an equivalent internal representation, i.e. both <a href="qimage.html">QImage</a> and QPixmap are stored on the client side which means that QPixmap doesn't use GDI resources).</p>
112
<p>Note that the pixel data in a pixmap is internal and is managed by the underlying window system. Pixels can only be accessed through <a href="qpainter.html">QPainter</a> functions or by converting the QPixmap to a <a href="qimage.html">QImage</a>. Depending on the system, QPixmap is stored using a RGB32 or a premultiplied alpha format. If the image has an alpha channel, and if the system allows, the preferred format is premultiplied alpha. Note also that QPixmap, unlike <a href="qimage.html">QImage</a>, may be hardware dependent. On X11 and Mac, a QPixmap is stored on the server side while a <a href="qimage.html">QImage</a> is stored on the client side (on Windows, these two classes have an equivalent internal representation, i.e. both <a href="qimage.html">QImage</a> and QPixmap are stored on the client side and don't use any GDI resources).</p>
117
113
<p>There are functions to convert between <a href="qimage.html">QImage</a> and QPixmap. Typically, the <a href="qimage.html">QImage</a> class is used to load an image file, optionally manipulating the image data, before the <a href="qimage.html">QImage</a> object is converted into a QPixmap to be shown on screen. Alternatively, if no manipulation is desired, the image file can be loaded directly into a QPixmap. On Windows, the QPixmap class also supports conversion between <tt>HBITMAP</tt> and QPixmap.</p>
118
114
<p>QPixmap provides a collection of functions that can be used to obtain a variety of information about the pixmap. In addition, there are several functions that enables transformation of the pixmap.</p>
119
<p>QPixmap objects can be passed around by value since the QPixmap class uses implicit data sharing. For more information, see the <a href="shclass.html">Implicit Data Sharing</a> documentation. QPixmap objects can also be streamed.</p>
115
<p>QPixmap objects can be passed around by value since the QPixmap class uses implicit data sharing. For more information, see the <a href="shared.html#implicit-data-sharing">Implicit Data Sharing</a> documentation. QPixmap objects can also be streamed.</p>
120
116
<ul><li><a href="#reading-and-writing-image-files">Reading and Writing Image Files</a></li>
121
117
<li><a href="#pixmap-information">Pixmap Information</a></li>
122
118
<li><a href="#pixmap-conversion">Pixmap Conversion</a></li>
128
124
<p>Simply call the <a href="qpixmap.html#save">save</a>() function to save a QPixmap object.</p>
129
125
<p>The complete list of supported file formats are available through the <a href="qimagereader.html#supportedImageFormats">QImageReader::supportedImageFormats</a>() and <a href="qimagewriter.html#supportedImageFormats">QImageWriter::supportedImageFormats</a>() functions. New file formats can be added as plugins. By default, Qt supports the following formats:</p>
130
126
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
131
<tr valign="top" bgcolor="#a2c511"><th>Format</th><th>Description</th><th>Qt's support</th></tr>
132
<tr valign="top" bgcolor="#f0f0f0"><td>BMP</td><td>Windows Bitmap</td><td>Read/write</td></tr>
133
<tr valign="top" bgcolor="#e0e0e0"><td>GIF</td><td>Graphic Interchange Format (optional)</td><td>Read</td></tr>
134
<tr valign="top" bgcolor="#f0f0f0"><td>JPG</td><td>Joint Photographic Experts Group</td><td>Read/write</td></tr>
135
<tr valign="top" bgcolor="#e0e0e0"><td>JPEG</td><td>Joint Photographic Experts Group</td><td>Read/write</td></tr>
136
<tr valign="top" bgcolor="#f0f0f0"><td>PNG</td><td>Portable Network Graphics</td><td>Read/write</td></tr>
137
<tr valign="top" bgcolor="#e0e0e0"><td>PBM</td><td>Portable Bitmap</td><td>Read</td></tr>
138
<tr valign="top" bgcolor="#f0f0f0"><td>PGM</td><td>Portable Graymap</td><td>Read</td></tr>
139
<tr valign="top" bgcolor="#e0e0e0"><td>PPM</td><td>Portable Pixmap</td><td>Read/write</td></tr>
140
<tr valign="top" bgcolor="#f0f0f0"><td>XBM</td><td>X11 Bitmap</td><td>Read/write</td></tr>
141
<tr valign="top" bgcolor="#e0e0e0"><td>XPM</td><td>X11 Pixmap</td><td>Read/write</td></tr>
127
<thead><tr valign="top" class="qt-style"><th>Format</th><th>Description</th><th>Qt's support</th></tr></thead>
128
<tr valign="top" class="odd"><td>BMP</td><td>Windows Bitmap</td><td>Read/write</td></tr>
129
<tr valign="top" class="even"><td>GIF</td><td>Graphic Interchange Format (optional)</td><td>Read</td></tr>
130
<tr valign="top" class="odd"><td>JPG</td><td>Joint Photographic Experts Group</td><td>Read/write</td></tr>
131
<tr valign="top" class="even"><td>JPEG</td><td>Joint Photographic Experts Group</td><td>Read/write</td></tr>
132
<tr valign="top" class="odd"><td>PNG</td><td>Portable Network Graphics</td><td>Read/write</td></tr>
133
<tr valign="top" class="even"><td>PBM</td><td>Portable Bitmap</td><td>Read</td></tr>
134
<tr valign="top" class="odd"><td>PGM</td><td>Portable Graymap</td><td>Read</td></tr>
135
<tr valign="top" class="even"><td>PPM</td><td>Portable Pixmap</td><td>Read/write</td></tr>
136
<tr valign="top" class="odd"><td>XBM</td><td>X11 Bitmap</td><td>Read/write</td></tr>
137
<tr valign="top" class="even"><td>XPM</td><td>X11 Pixmap</td><td>Read/write</td></tr>
143
139
<p>(To configure Qt with GIF support, pass <tt>-qt-gif</tt> to the <tt>configure</tt> script or check the appropriate option in the graphical installer.)</p>
144
140
<a name="pixmap-information"></a>
145
141
<h3>Pixmap Information</h3>
146
142
<p>QPixmap provides a collection of functions that can be used to obtain a variety of information about the pixmap:</p>
147
143
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
148
<tr valign="top" bgcolor="#a2c511"><th></th><th>Available Functions</th></tr>
149
<tr valign="top" bgcolor="#f0f0f0"><td>Geometry</td><td>The <a href="qpixmap.html#size">size</a>(), <a href="qpixmap.html#width">width</a>() and <a href="qpixmap.html#height">height</a>() functions provide information about the pixmap's size. The <a href="qpixmap.html#rect">rect</a>() function returns the image's enclosing rectangle.</td></tr>
150
<tr valign="top" bgcolor="#e0e0e0"><td>Alpha component</td><td>The <a href="qpixmap.html#hasAlphaChannel">hasAlphaChannel</a>() returns true if the pixmap has a format that respects the alpha channel, otherwise returns false, while the <a href="qpixmap.html#hasAlpha">hasAlpha</a>() function returns true if the pixmap has an alpha channel <i>or</i> a mask (otherwise false).<p>The <a href="qpixmap.html#alphaChannel">alphaChannel</a>() function returns the alpha channel as a new QPixmap object, while the <a href="qpixmap.html#mask">mask</a>() function returns the mask as a <a href="qbitmap.html">QBitmap</a> object. The alpha channel and mask can be set using the <a href="qpixmap.html#setAlphaChannel">setAlphaChannel</a>() and <a href="qpixmap.html#setMask">setMask</a>() functions, respectively.</p>
144
<thead><tr valign="top" class="qt-style"><th></th><th>Available Functions</th></tr></thead>
145
<tr valign="top" class="odd"><td>Geometry</td><td>The <a href="qpixmap.html#size">size</a>(), <a href="qpixmap.html#width">width</a>() and <a href="qpixmap.html#height">height</a>() functions provide information about the pixmap's size. The <a href="qpixmap.html#rect">rect</a>() function returns the image's enclosing rectangle.</td></tr>
146
<tr valign="top" class="even"><td>Alpha component</td><td>The <a href="qpixmap.html#hasAlphaChannel">hasAlphaChannel</a>() returns true if the pixmap has a format that respects the alpha channel, otherwise returns false, while the <a href="qpixmap.html#hasAlpha">hasAlpha</a>() function returns true if the pixmap has an alpha channel <i>or</i> a mask (otherwise false).<p>The <a href="qpixmap.html#alphaChannel">alphaChannel</a>() function returns the alpha channel as a new QPixmap object, while the <a href="qpixmap.html#mask">mask</a>() function returns the mask as a <a href="qbitmap.html">QBitmap</a> object. The alpha channel and mask can be set using the <a href="qpixmap.html#setAlphaChannel">setAlphaChannel</a>() and <a href="qpixmap.html#setMask">setMask</a>() functions, respectively.</p>
152
<tr valign="top" bgcolor="#f0f0f0"><td>Low-level information</td><td>The <a href="qpixmap.html#depth">depth</a>() function returns the depth of the pixmap. The <a href="qpixmap.html#defaultDepth">defaultDepth</a>() function returns the default depth, i.e. the depth used by the application on the given screen.<p>The <a href="qpixmap.html#serialNumber">serialNumber</a>() function returns a number that uniquely identifies the contents of the QPixmap object.</p>
148
<tr valign="top" class="odd"><td>Low-level information</td><td>The <a href="qpixmap.html#depth">depth</a>() function returns the depth of the pixmap. The <a href="qpixmap.html#defaultDepth">defaultDepth</a>() function returns the default depth, i.e. the depth used by the application on the given screen.<p>The <a href="qpixmap.html#serialNumber">serialNumber</a>() function returns a number that uniquely identifies the contents of the QPixmap object.</p>
153
149
<p>The <a href="qpixmap.html#x11Info">x11Info</a>() function returns information about the configuration of the X display used to display the widget. The <a href="qpixmap.html#x11PictureHandle">x11PictureHandle</a>() function returns the X11 Picture handle of the pixmap for XRender support. Note that the two latter functions are only available on x11.</p>
211
207
<p>Returns the alpha channel of the pixmap. If the pixmap doesn't have an alpha channel (i.e. the alpha channel's value equals 0xff), a null pixmap is returned.</p>
212
208
<p>See also <a href="qpixmap.html#setAlphaChannel">setAlphaChannel</a>() and <a href="qpixmap.html#pixmap-information">Pixmap Information</a>.</p>
213
209
<h3 class="fn"><a name="copy"></a>QPixmap QPixmap::copy ( const <a href="qrect.html">QRect</a> & <i>rectangle</i> = QRect() ) const</h3>
214
<p>Returns a deep copy of the subset of the pixmap that is specified by the given <i>rectangle</i>. For more information on deep copies, see the <a href="shclass.html">Implicit Data Sharing</a> documentation.</p>
210
<p>Returns a deep copy of the subset of the pixmap that is specified by the given <i>rectangle</i>. For more information on deep copies, see the <a href="shared.html#implicit-data-sharing">Implicit Data Sharing</a> documentation.</p>
215
211
<p>If the given <i>rectangle</i> is empty, the whole image is copied.</p>
216
212
<p>See also <a href="qpixmap.html#operator-eq">operator=</a>(), <a href="qpixmap.html#QPixmap">QPixmap</a>(), and <a href="qpixmap.html#pixmap-transformations">Pixmap Transformations</a>.</p>
217
213
<h3 class="fn"><a name="copy-2"></a>QPixmap QPixmap::copy ( int <i>x</i>, int <i>y</i>, int <i>width</i>, int <i>height</i> ) const</h3>
238
234
<p>See also <a href="qpixmap.html#defaultDepth">defaultDepth</a>() and <a href="qpixmap.html#pixmap-information">Pixmap Information</a>.</p>
239
235
<h3 class="fn"><a name="detach"></a>void QPixmap::detach ()</h3>
240
236
<p>Detaches the pixmap from shared pixmap data.</p>
241
<p>A pixmap is automatically detached by Qt whenever its contents are about to change. This is done in almost all <a href="qpixmap.html">QPixmap</a> member functions that modify the pixmap (<a href="qpixmap.html#fill">fill</a>(), <a href="qpixmap-qt3.html#convertFromImage">convertFromImage</a>(), <a href="qpixmap.html#load">load</a>(), etc.), and in <a href="qpainter.html#begin">QPainter::begin</a>() on a pixmap.</p>
237
<p>A pixmap is automatically detached by Qt whenever its contents are about to change. This is done in almost all <a href="qpixmap.html">QPixmap</a> member functions that modify the pixmap (<a href="qpixmap.html#fill">fill</a>(), <a href="qpixmap.html#fromImage">fromImage</a>(), <a href="qpixmap.html#load">load</a>(), etc.), and in <a href="qpainter.html#begin">QPainter::begin</a>() on a pixmap.</p>
242
238
<p>There are two exceptions in which detach() must be called explicitly, that is when calling the <a href="qpixmap.html#handle">handle</a>() or the <a href="qpixmap.html#x11PictureHandle">x11PictureHandle</a>() function (only available on X11). Otherwise, any modifications done using system calls, will be performed on the shared data.</p>
243
239
<p>The detach() function returns immediately if there is just a single reference or if the pixmap has not been initialized yet.</p>
244
240
<h3 class="fn"><a name="fill"></a>void QPixmap::fill ( const <a href="qcolor.html">QColor</a> & <i>fillColor</i> = Qt::white )</h3>
255
251
<p>Converts the given <i>image</i> to a pixmap using the specified <i>flags</i> to control the conversion. The <i>flags</i> argument is a bitwise-OR of the <a href="qt.html#ImageConversionFlag-enum">Qt::ImageConversionFlags</a>. Passing 0 for <i>flags</i> sets all the default options.</p>
256
252
<p>In case of monochrome and 8-bit images, the image is first converted to a 32-bit pixmap and then filled with the colors in the color table. If this is too expensive an operation, you can use <a href="qbitmap.html#fromImage">QBitmap::fromImage</a>() instead.</p>
257
253
<p>See also <a href="qpixmap.html#toImage">toImage</a>() and <a href="qpixmap.html#pixmap-conversion">Pixmap Conversion</a>.</p>
254
<h3 class="fn"><a name="fromMacCGImageRef"></a>QPixmap QPixmap::fromMacCGImageRef ( CGImageRef <i>image</i> ) <tt> [static]</tt></h3>
255
<p>Returns a <a href="qpixmap.html">QPixmap</a> that is equivalent to the given <i>image</i>.</p>
256
<p><b>Warning:</b> This function is only available on Mac OS X.</p>
257
<p>This function was introduced in Qt 4.2.</p>
258
<p>See also <a href="qpixmap.html#toMacCGImageRef">toMacCGImageRef</a>() and <a href="qpixmap.html#pixmap-conversion">Pixmap Conversion</a>.</p>
258
259
<h3 class="fn"><a name="fromWinHBITMAP"></a>QPixmap QPixmap::fromWinHBITMAP ( HBITMAP <i>bitmap</i>, <a href="qpixmap.html#HBitmapFormat-enum">HBitmapFormat</a> <i>format</i> = NoAlpha ) <tt> [static]</tt></h3>
259
260
<p>Returns a <a href="qpixmap.html">QPixmap</a> that is equivalent to the given <i>bitmap</i>. The conversion is based on the specified <i>format</i>.</p>
260
261
<p><b>Warning:</b> This function is only available on Windows.</p>
273
274
<h3 class="fn"><a name="grabWindow"></a>QPixmap QPixmap::grabWindow ( WId <i>window</i>, int <i>x</i> = 0, int <i>y</i> = 0, int <i>width</i> = -1, int <i>height</i> = -1 ) <tt> [static]</tt></h3>
274
275
<p>Creates and returns a pixmap constructed by grabbing the contents of the given <i>window</i> restricted by <a href="qrect.html">QRect</a>(<i>x</i>, <i>y</i>, <i>width</i>, <i>height</i>).</p>
275
276
<p>The arguments (<i>x</i>, <i>y</i>) specify the offset in the window, whereas (<i>width</i>, <i>height</i>) specify the area to be copied. If <i>width</i> is negative, the function copies everything to the right border of the window. If <i>height</i> is negative, the function copies everything to the bottom of the window.</p>
276
<p>The window system identifier (<tt>WId</tt>) can be retrieved using the QWidget::WId() function. The rationale for using a window identifier and not a <a href="qwidget.html">QWidget</a>, is to enable grabbing of windows that are not part of the application, window system frames, and so on.</p>
277
<p>The window system identifier (<tt>WId</tt>) can be retrieved using the <a href="qwidget.html#winId">QWidget::winId</a>() function. The rationale for using a window identifier and not a <a href="qwidget.html">QWidget</a>, is to enable grabbing of windows that are not part of the application, window system frames, and so on.</p>
277
278
<p>The grabWindow() function grabs pixels from the screen, not from the window, i.e. if there is another window partially or entirely over the one you grab, you get pixels from the overlying window, too. The mouse cursor is generally not grabbed.</p>
278
279
<p>Note on X11that if the given <i>window</i> doesn't have the same depth as the root window, and another window partially or entirely obscures the one you grab, you will <i>not</i> get pixels from the overlying window. The contents of the obscured areas in the pixmap will be undefined and uninitialized.</p>
279
280
<p><b>Warning:</b> In general, grabbing an area outside the screen is not safe. This depends on the underlying window system.</p>
280
<p>See also <a href="qpixmap.html#grabWidget">grabWidget</a>().</p>
281
<p>See also <a href="qpixmap.html#grabWidget">grabWidget</a>() and <a href="desktop-screenshot.html">Screenshot Example</a>.</p>
281
282
<h3 class="fn"><a name="handle"></a><a href="qt.html#HANDLE-typedef">Qt::HANDLE</a> QPixmap::handle () const</h3>
282
283
<p>Returns the pixmap's handle to the device context.</p>
283
<p>Note that, since <a href="qpixmap.html">QPixmap</a> make use of <a href="shclass.html">implicit data sharing</a>, the <a href="qpixmap.html#detach">detach</a>() function must be called explicitly to ensure that only <i>this</i> pixmap's data is modified if the pixmap data is shared.</p>
284
<p>Note that, since <a href="qpixmap.html">QPixmap</a> make use of <a href="shared.html#implicit-data-sharing">implicit data sharing</a>, the <a href="qpixmap.html#detach">detach</a>() function must be called explicitly to ensure that only <i>this</i> pixmap's data is modified if the pixmap data is shared.</p>
284
285
<p><b>Warning:</b> This function is X11 specific; using it is non-portable.</p>
285
286
<p>See also <a href="qpixmap.html#detach">detach</a>().</p>
286
287
<h3 class="fn"><a name="hasAlpha"></a>bool QPixmap::hasAlpha () const</h3>
317
318
<h3 class="fn"><a name="rect"></a><a href="qrect.html">QRect</a> QPixmap::rect () const</h3>
318
319
<p>Returns the pixmap's enclosing rectangle.</p>
319
320
<p>See also <a href="qpixmap.html#pixmap-information">Pixmap Information</a>.</p>
320
<h3 class="fn"><a name="save"></a>bool QPixmap::save ( const <a href="qstring.html">QString</a> & <i>fileName</i>, const char * <i>format</i>, int <i>quality</i> = -1 ) const</h3>
321
<h3 class="fn"><a name="save"></a>bool QPixmap::save ( const <a href="qstring.html">QString</a> & <i>fileName</i>, const char * <i>format</i> = 0, int <i>quality</i> = -1 ) const</h3>
321
322
<p>Saves the pixmap to the file with the given <i>fileName</i> using the specified image file <i>format</i> and <i>quality</i> factor. Returns true if successful; otherwise returns false.</p>
322
323
<p>The <i>quality</i> factor must be in the range [0,100] or -1. Specify 0 to obtain small compressed files, 100 for large uncompressed files, and -1 to use the default settings.</p>
324
<p>If <i>format</i> is 0, an image format will be chosen from <i>fileName</i>'s suffix.</p>
323
325
<p>See also <a href="qpixmap.html#reading-and-writing-image-files">Reading and Writing Image Files</a>.</p>
324
<h3 class="fn"><a name="save-2"></a>bool QPixmap::save ( <a href="qiodevice.html">QIODevice</a> * <i>device</i>, const char * <i>format</i>, int <i>quality</i> = -1 ) const</h3>
326
<h3 class="fn"><a name="save-2"></a>bool QPixmap::save ( <a href="qiodevice.html">QIODevice</a> * <i>device</i>, const char * <i>format</i> = 0, int <i>quality</i> = -1 ) const</h3>
325
327
<p>This is an overloaded member function, provided for convenience.</p>
326
328
<p>This function writes a <a href="qpixmap.html">QPixmap</a> to the given <i>device</i> using the specified image file <i>format</i> and <i>quality</i> factor. This can be used, for example, to save a pixmap directly into a <a href="qbytearray.html">QByteArray</a>:</p>
327
<pre> QPixmap pixmap;
329
QBuffer buffer(&bytes);
330
buffer.open(QIODevice::WriteOnly);
331
pixmap.save(&buffer, "PNG"); // writes pixmap into bytes in PNG format</pre>
329
<pre> QPixmap pixmap;
331
QBuffer buffer(&bytes);
332
buffer.open(QIODevice::WriteOnly);
333
pixmap.save(&buffer, "PNG"); <span class="comment">// writes pixmap into bytes in PNG format</span></pre>
332
334
<h3 class="fn"><a name="scaled"></a>QPixmap QPixmap::scaled ( const <a href="qsize.html">QSize</a> & <i>size</i>, <a href="qt.html#AspectRatioMode-enum">Qt::AspectRatioMode</a> <i>aspectRatioMode</i> = Qt::IgnoreAspectRatio, <a href="qt.html#TransformationMode-enum">Qt::TransformationMode</a> <i>transformMode</i> = Qt::FastTransformation ) const</h3>
333
335
<p>Scales the pixmap to the given <i>size</i>, using the aspect ratio and transformation modes specified by <i>aspectRatioMode</i> and <i>transformMode</i>.</p>
334
336
<p align="center"><img src="images/qimage-scaling.png" /></p><ul>
357
359
<p>See also <a href="qpixmap.html#pixmap-information">Pixmap Information</a>.</p>
358
360
<h3 class="fn"><a name="setAlphaChannel"></a>void QPixmap::setAlphaChannel ( const QPixmap & <i>alphaChannel</i> )</h3>
359
361
<p>Sets the alpha channel of this pixmap to the given <i>alphaChannel</i> by converting the <i>alphaChannel</i> into 32 bit and using the intensity of the RGB pixel values.</p>
362
<p>The effect of this function is undefined when the pixmap is being painted on.</p>
360
363
<p>See also <a href="qpixmap.html#alphaChannel">alphaChannel</a>() and <a href="qpixmap.html#pixmap-transformations">Pixmap Transformations</a>.</p>
361
364
<h3 class="fn"><a name="setMask"></a>void QPixmap::setMask ( const <a href="qbitmap.html">QBitmap</a> & <i>newmask</i> )</h3>
362
365
<p>Sets a mask bitmap.</p>
363
366
<p>The <i>newmask</i> bitmap defines the clip mask for this pixmap. Every pixel in <i>newmask</i> corresponds to a pixel in this pixmap. Pixel value 1 means opaque and pixel value 0 means transparent. The mask must have the same size as this pixmap.</p>
364
367
<p><b>Warning:</b> Setting the mask on a pixmap will cause any alpha channel data to be cleared. For example:</p>
365
<pre> QPixmap alpha("image-with-alpha.png");
366
QPixmap alphacopy = alpha;
367
alphacopy.setMask(alphacopy.mask());</pre>
368
<pre> QPixmap alpha("image-with-alpha.png");
369
QPixmap alphacopy = alpha;
370
alphacopy.setMask(alphacopy.mask());</pre>
368
371
<p>Now, alpha and alphacopy are visually different.</p>
369
372
<p>Setting a null mask resets the mask.</p>
373
<p>The effect of this function is undefined when the pixmap is being painted on.</p>
370
374
<p>See also <a href="qpixmap.html#mask">mask</a>(), <a href="qpixmap.html#pixmap-transformations">Pixmap Transformations</a>, and <a href="qbitmap.html">QBitmap</a>.</p>
371
375
<h3 class="fn"><a name="size"></a><a href="qsize.html">QSize</a> QPixmap::size () const</h3>
372
376
<p>Returns the size of the pixmap.</p>
375
379
<p>Converts the pixmap to a <a href="qimage.html">QImage</a>. Returns a null image if the conversion fails.</p>
376
380
<p>If the pixmap has 1-bit depth, the returned image will also be 1 bit deep. If the pixmap has 2- to 8-bit depth, the returned image has 8-bit depth. If the pixmap has greater than 8-bit depth, the returned image has 32-bit depth.</p>
377
381
<p>Note that for the moment, alpha masks on monochrome images are ignored.</p>
378
<p>See also <a href="qpixmap-qt3.html#convertFromImage">convertFromImage</a>() and <a href="qimage.html#image-formats">Image Formats</a>.</p>
382
<p>See also <a href="qpixmap.html#fromImage">fromImage</a>() and <a href="qimage.html#image-formats">Image Formats</a>.</p>
383
<h3 class="fn"><a name="toMacCGImageRef"></a>CGImageRef QPixmap::toMacCGImageRef () const</h3>
384
<p>Creates a <tt>CGImageRef</tt> equivalent to the <a href="qpixmap.html">QPixmap</a>. Returns the <tt>CGImageRef</tt> handle.</p>
385
<p>It is the caller's responsibility to release the <tt>CGImageRef</tt> data after use.</p>
386
<p><b>Warning:</b> This function is only available on Mac OS X.</p>
387
<p>This function was introduced in Qt 4.2.</p>
388
<p>See also <a href="qpixmap.html#fromMacCGImageRef">fromMacCGImageRef</a>().</p>
379
389
<h3 class="fn"><a name="toWinHBITMAP"></a>HBITMAP QPixmap::toWinHBITMAP ( <a href="qpixmap.html#HBitmapFormat-enum">HBitmapFormat</a> <i>format</i> = NoAlpha ) const</h3>
380
390
<p>Creates a <tt>HBITMAP</tt> equivalent to the <a href="qpixmap.html">QPixmap</a>, based on the given <i>format</i>. Returns the <tt>HBITMAP</tt> handle.</p>
381
391
<p>It is the caller's responsibility to free the <tt>HBITMAP</tt> data after use.</p>
420
430
<p>This is an overloaded member function, provided for convenience.</p>
421
431
<p>Reads an image from the given <i>stream</i> into the given <i>pixmap</i>.</p>
422
432
<p>See also <a href="qpixmap.html#load">QPixmap::load</a>() and <a href="datastreamformat.html">Format of the QDataStream Operators</a>.</p>
434
<h2>Member Type Documentation</h2>
435
<h3 class="fn"><a name="ColorMode-enum"></a>enum QPixmap::ColorMode</h3>
436
<p>This enum type defines the color modes that exist for converting <a href="qimage.html">QImage</a> objects to <a href="qpixmap.html">QPixmap</a>. It is provided here for compatibility with earlier versions of Qt.</p>
437
<p>Use <a href="qt.html#ImageConversionFlag-enum">Qt::ImageConversionFlags</a> instead.</p>
438
<p><table border="1" cellpadding="2" cellspacing="1" width="100%">
439
<tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr>
440
<tr><td valign="top"><tt>QPixmap::Auto</tt></td><td align="center" valign="top"><tt>0</tt></td><td valign="top">Select <tt>Color</tt> or <tt>Mono</tt> on a case-by-case basis.</td></tr>
441
<tr><td valign="top"><tt>QPixmap::Color</tt></td><td align="center" valign="top"><tt>1</tt></td><td valign="top">Always create colored pixmaps.</td></tr>
442
<tr><td valign="top"><tt>QPixmap::Mono</tt></td><td align="center" valign="top"><tt>2</tt></td><td valign="top">Always create bitmaps.</td></tr>
445
<h2>Member Function Documentation</h2>
446
<h3 class="fn"><a name="QPixmap-6"></a>QPixmap::QPixmap ( const <a href="qstring.html">QString</a> & <i>fileName</i>, const char * <i>format</i>, <a href="qpixmap-qt3.html#ColorMode-enum">ColorMode</a> <i>mode</i> )</h3>
447
<p>Use the constructor that takes a <a href="qt.html#ImageConversionFlag-enum">Qt::ImageConversionFlag</a> instead.</p>
448
<h3 class="fn"><a name="QPixmap-7"></a>QPixmap::QPixmap ( const <a href="qimage.html">QImage</a> & <i>image</i> )</h3>
449
<p>Constructs a pixmap from the <a href="qimage.html">QImage</a> <i>image</i>.</p>
450
<p>Use the static <a href="qpixmap.html#fromImage">fromImage</a>() function instead.</p>
451
<h3 class="fn"><a name="convertFromImage"></a>bool QPixmap::convertFromImage ( const <a href="qimage.html">QImage</a> & <i>image</i>, <a href="qpixmap-qt3.html#ColorMode-enum">ColorMode</a> <i>mode</i> )</h3>
452
<p>Use the static <a href="qpixmap.html#fromImage">fromImage</a>() function instead.</p>
453
<h3 class="fn"><a name="convertFromImage-2"></a>bool QPixmap::convertFromImage ( const <a href="qimage.html">QImage</a> & <i>image</i>, <a href="qt.html#ImageConversionFlag-enum">Qt::ImageConversionFlags</a> <i>flags</i> = Qt::AutoColor )</h3>
454
<p>This is an overloaded member function, provided for convenience.</p>
455
<p>Use the static <a href="qpixmap.html#fromImage">fromImage</a>() function instead.</p>
456
<h3 class="fn"><a name="convertToImage"></a><a href="qimage.html">QImage</a> QPixmap::convertToImage () const</h3>
457
<p>Use the <a href="qpixmap.html#toImage">toImage</a>() function instead.</p>
458
<h3 class="fn"><a name="load-2"></a>bool QPixmap::load ( const <a href="qstring.html">QString</a> & <i>fileName</i>, const char * <i>format</i>, <a href="qpixmap-qt3.html#ColorMode-enum">ColorMode</a> <i>mode</i> )</h3>
459
<p>This is an overloaded member function, provided for convenience.</p>
460
<p>Use the <a href="qpixmap.html#load">load</a>() function that takes a <a href="qt.html#ImageConversionFlag-enum">Qt::ImageConversionFlag</a> instead.</p>
461
<h3 class="fn"><a name="loadFromData-2"></a>bool QPixmap::loadFromData ( const <a href="qtglobal.html#uchar-typedef">uchar</a> * <i>buf</i>, <a href="qtglobal.html#uint-typedef">uint</a> <i>len</i>, const char * <i>format</i>, <a href="qpixmap-qt3.html#ColorMode-enum">ColorMode</a> <i>mode</i> )</h3>
462
<p>This is an overloaded member function, provided for convenience.</p>
463
<p>Use the <a href="qpixmap.html#loadFromData">loadFromData</a>() function that takes a <a href="qt.html#ImageConversionFlag-enum">Qt::ImageConversionFlag</a> instead.</p>
464
<h3 class="fn"><a name="resize"></a>void QPixmap::resize ( int <i>width</i>, int <i>height</i> )</h3>
465
<p>Use the <a href="qpixmap.html">QPixmap</a> constructor that takes two <tt>int</tt>s (<i>width</i> and <i>height</i>) instead.</p>
466
<p>For example, if you have code like</p>
467
<pre><font color="#404040"> pixmap.resize(10, 20);</font></pre>
468
<p>you can rewrite it as</p>
469
<pre> pixmap = QPixmap(10, 20);</pre>
470
<h3 class="fn"><a name="resize-2"></a>void QPixmap::resize ( const <a href="qsize.html">QSize</a> & <i>size</i> )</h3>
471
<p>This is an overloaded member function, provided for convenience.</p>
472
<p>Use the <a href="qpixmap.html">QPixmap</a> constructor that takes a <a href="qsize.html">QSize</a> (<i>size</i>) instead.</p>
473
<p>For example, if you have code like</p>
474
<pre><font color="#404040"> pixmap.resize(size);</font></pre>
475
<p>you can rewrite it as</p>
476
<pre> pixmap = QPixmap(size);</pre>
477
<h3 class="fn"><a name="selfMask"></a>bool QPixmap::selfMask () const</h3>
478
<p>Returns whether the pixmap is its own mask or not.</p>
479
<p>This function is no longer relevant since the concept of self masking doesn't exists anymore.</p>
480
<h3 class="fn"><a name="xForm"></a>QPixmap QPixmap::xForm ( const <a href="qmatrix.html">QMatrix</a> & <i>matrix</i> ) const</h3>
481
<p>Use <a href="qpixmap.html#transformed">transformed</a>() instead.</p>
482
<h3 class="fn"><a name="operator-QImage"></a>QPixmap::operator QImage () const</h3>
483
<p>Returns the pixmap as a <a href="qimage.html">QImage</a>.</p>
484
<p>Use the <a href="qpixmap.html#toImage">toImage</a>() function instead.</p>
485
<h3 class="fn"><a name="operator-eq-2"></a>QPixmap & QPixmap::operator= ( const <a href="qimage.html">QImage</a> & <i>image</i> )</h3>
486
<p>This is an overloaded member function, provided for convenience.</p>
487
<p>Converts the given <i>image</i> to a pixmap that is assigned to this pixmap.</p>
488
<p>Use the static <a href="qpixmap.html#fromImage">fromImage</a>() function instead.</p>
423
489
<p /><address><hr /><div align="center">
424
490
<table width="100%" cellspacing="0" border="0"><tr class="address">
425
491
<td width="30%">Copyright © 2006 <a href="trolltech.html">Trolltech</a></td>
426
492
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
427
<td width="30%" align="right"><div align="right">Qt 4.1.4</div></td>
493
<td width="30%" align="right"><div align="right">Qt 4.2.0</div></td>
428
494
</tr></table></div></address></body>
added
removed
doc/html/qpixmap.html
