Contents

• Public Types
• Public Functions
• Static Public Members
• Related Non-Members
• Detailed Description
• Reading and Writing Image Files
• Pixmap Information
• Pixmap Conversion
• Pixmap Transformations

Detailed Description

TheQPixmap class is an off-screen image representation that can be used as a paint device.

Qt provides four classes for handling image data:QImage,QPixmap,QBitmap andQPicture.QImage is designed and optimized for I/O, and for direct pixel access and manipulation, whileQPixmap is designed and optimized for showing images on screen.QBitmap is only a convenience class that inheritsQPixmap, ensuring a depth of 1. TheisQBitmap() function returns true if aQPixmap object is really a bitmap, otherwise returns false. Finally, theQPicture class is a paint device that records and replaysQPainter commands.

AQPixmap can easily be displayed on the screen usingQLabel or one ofQAbstractButton's subclasses (such asQPushButton andQToolButton).QLabel has a pixmap property, whereasQAbstractButton has an icon property.

In addition to the ordinary constructors, aQPixmap can be constructed using the staticgrabWidget() andgrabWindow() functions which creates aQPixmap and paints the given widget, or window, into it.

QPixmap objects can be passed around by value since theQPixmap class uses implicit data sharing. For more information, see theImplicit Data Sharing documentation.QPixmap objects can also be streamed.

Note that the pixel data in a pixmap is internal and is managed by the underlying window system. BecauseQPixmap is aQPaintDevice subclass,QPainter can be used to draw directly onto pixmaps. Pixels can only be accessed throughQPainter functions or by converting theQPixmap to aQImage. However, thefill() function is available for initializing the entire pixmap with a given color.

There are functions to convert betweenQImage andQPixmap. Typically, theQImage class is used to load an image file, optionally manipulating the image data, before theQImage object is converted into aQPixmap to be shown on screen. Alternatively, if no manipulation is desired, the image file can be loaded directly into aQPixmap. On Windows, theQPixmap class also supports conversion betweenHBITMAP andQPixmap. On Symbian, theQPixmap class also supports conversion between CFbsBitmap andQPixmap.

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.

Reading and Writing Image Files

QPixmap provides several ways of reading an image file: The file can be loaded when constructing theQPixmap object, or by using theload() orloadFromData() functions later on. When loading an image, the file name can either refer to an actual file on disk or to one of the application's embedded resources. SeeThe Qt Resource System overview for details on how to embed images and other resource files in the application's executable.

Simply call thesave() function to save aQPixmap object.

The complete list of supported file formats are available through theQImageReader::supportedImageFormats() andQImageWriter::supportedImageFormats() functions. New file formats can be added as plugins. By default, Qt supports the following formats:

Pixmap Information

QPixmap provides a collection of functions that can be used to obtain a variety of information about the pixmap:

Pixmap Conversion

AQPixmap object can be converted into aQImage using thetoImage() function. Likewise, aQImage can be converted into aQPixmap using thefromImage(). If this is too expensive an operation, you can useQBitmap::fromImage() instead.

In addition, on Windows, theQPixmap class supports conversion to and from HBITMAP: thetoWinHBITMAP() function creates a HBITMAP equivalent to theQPixmap, based on the givenHBitmapFormat, and returns the HBITMAP handle. ThefromWinHBITMAP() function returns aQPixmap that is equivalent to the given bitmap which has the specified format. TheQPixmap class also supports conversion to and from HICON: thetoWinHICON() function creates a HICON equivalent to theQPixmap, and returns the HICON handle. ThefromWinHICON() function returns aQPixmap that is equivalent to the given icon.

In addition, on Symbian, theQPixmap class supports conversion to and from CFbsBitmap: thetoSymbianCFbsBitmap() function creates CFbsBitmap equivalent to theQPixmap, based on given mode and returns a CFbsBitmap object. ThefromSymbianCFbsBitmap() function returns aQPixmap that is equivalent to the given bitmap and given mode.

Pixmap Transformations

QPixmap supports a number of functions for creating a new pixmap that is a transformed version of the original:

Thescaled(),scaledToWidth() andscaledToHeight() functions return scaled copies of the pixmap, while thecopy() function creates aQPixmap that is a plain copy of the original one.

Thetransformed() function returns a copy of the pixmap that is transformed with the given transformation matrix and transformation mode: Internally, the transformation matrix is adjusted to compensate for unwanted translation, i.e.transformed() returns the smallest pixmap containing all transformed points of the original pixmap. The statictrueMatrix() function returns the actual matrix used for transforming the pixmap.

Note:When using the native X11 graphics system, the pixmap becomes invalid when theQApplication instance is destroyed.

Member Type Documentation

enum QPixmap::HBitmapFormat

Win32 only: This enum defines how the conversion betweenHBITMAP andQPixmap is performed.

Warning: This enum is only available on Windows.

See alsofromWinHBITMAP() andtoWinHBITMAP().

enum QPixmap::ShareMode

This enum type defines the share modes that are available when creating aQPixmap object from a raw X11 Pixmap handle.

Warning: This enum is only used for X11 specific functions; using it is non-portable.

This enum was introduced or modified in Qt 4.5.

See alsoQPixmap::fromX11Pixmap().

Member Function Documentation

QPixmap::QPixmap()

Constructs a null pixmap.

See alsoisNull().

QPixmap::QPixmap(int width,int height)

Constructs a pixmap with the givenwidth andheight. If eitherwidth orheight is zero, a null pixmap is constructed.

Warning: This will create aQPixmap with uninitialized data. Callfill() to fill the pixmap with an appropriate color before drawing onto it withQPainter.

See alsoisNull().

QPixmap::QPixmap(constQString & fileName, constchar * format = 0,Qt::ImageConversionFlags flags = Qt::AutoColor)

Constructs a pixmap from the file with the givenfileName. If the file does not exist or is of an unknown format, the pixmap becomes a null pixmap.

The loader attempts to read the pixmap using the specifiedformat. If theformat is not specified (which is the default), the loader probes the file for a header to guess the file format.

The file name can either refer to an actual file on disk or to one of the application's embedded resources. See theResource System overview for details on how to embed images and other resource files in the application's executable.

If the image needs to be modified to fit in a lower-resolution result (e.g. converting from 32-bit to 8-bit), use theflags to control the conversion.

ThefileName,format andflags parameters are passed on toload(). This means that the data infileName is not compiled into the binary. IffileName contains a relative path (e.g. the filename only) the relevant file must be found relative to the runtime working directory.

See alsoReading and Writing Image Files.

QPixmap::QPixmap(constchar * const[] xpm)

Constructs a pixmap from the givenxpm data, which must be a valid XPM image.

Errors are silently ignored.

Note that it's possible to squeeze the XPM variable a little bit by using an unusual declaration:

staticconstchar*const start_xpm[]={"16 15 8 1","a c #cec6bd",....

The extraconst makes the entire definition read-only, which is slightly more efficient (for example, when the code is in a shared library) and ROMable when the application is to be stored in ROM.

QPixmap::QPixmap(constQPixmap & pixmap)

Constructs a pixmap that is a copy of the givenpixmap.

See alsocopy().

QPixmap::QPixmap(constQSize & size)

This is an overloaded function.

Constructs a pixmap of the givensize.

Warning: This will create aQPixmap with uninitialized data. Callfill() to fill the pixmap with an appropriate color before drawing onto it withQPainter.

QPixmap::~QPixmap()

Destroys the pixmap.

qint64 QPixmap::cacheKey() const

Returns a number that identifies thisQPixmap. DistinctQPixmap objects can only have the same cache key if they refer to the same contents.

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

bool QPixmap::convertFromImage(constQImage & image,Qt::ImageConversionFlags flags = Qt::AutoColor)

Replaces this pixmap's data with the givenimage using the specifiedflags to control the conversion. Theflags argument is a bitwise-OR of theQt::ImageConversionFlags. Passing 0 forflags sets all the default options. Returns true if the result is that this pixmap is not null.

Note: this function was part of Qt 3 support in Qt 4.6 and earlier. It has been promoted to official API status in 4.7 to support updating the pixmap's image without creating a newQPixmap asfromImage() would.

This function was introduced in Qt 4.7.

See alsofromImage().

QPixmap QPixmap::copy(constQRect & rectangle = QRect()) const

Returns a deep copy of the subset of the pixmap that is specified by the givenrectangle. For more information on deep copies, see theImplicit Data Sharing documentation.

If the givenrectangle is empty, the whole image is copied.

See alsooperator=(),QPixmap(), andPixmap Transformations.

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

This is an overloaded function.

Returns a deep copy of the subset of the pixmap that is specified by the rectangleQRect(x,y,width,height).

QBitmap QPixmap::createHeuristicMask(bool clipTight = true) const

Creates and returns a heuristic mask for this pixmap.

The function works by selecting a color from one of the corners and then chipping away pixels of that color, starting at all the edges. IfclipTight is true (the default) the mask is just large enough to cover the pixels; otherwise, the mask is larger than the data pixels.

The mask may not be perfect but it should be reasonable, so you can do things such as the following:

QPixmap myPixmap;myPixmap->setMask(myPixmap->createHeuristicMask());

This function is slow because it involves converting to/from aQImage, and non-trivial computations.

See alsoQImage::createHeuristicMask() andcreateMaskFromColor().

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

Creates and returns a mask for this pixmap based on the givenmaskColor. If themode isQt::MaskInColor, all pixels matching the maskColor will be transparent. Ifmode isQt::MaskOutColor, all pixels matching the maskColor will be opaque.

This function is slow because it involves converting to/from aQImage.

See alsocreateHeuristicMask() andQImage::createMaskFromColor().

QBitmap QPixmap::createMaskFromColor(constQColor & maskColor) const

This is an overloaded function.

Creates and returns a mask for this pixmap based on the givenmaskColor. Same as callingcreateMaskFromColor(maskColor,Qt::MaskInColor)

See alsocreateHeuristicMask() andQImage::createMaskFromColor().

[static]int QPixmap::defaultDepth()

Returns the default pixmap depth used by the application.

On Windows and Mac, the default depth is always 32. On X11 and embedded, the depth of the screen will be returned by this function.

See alsodepth(),QColormap::depth(), andPixmap Information.

int QPixmap::depth() const

Returns the depth of the pixmap.

The pixmap depth is also called bits per pixel (bpp) or bit planes of a pixmap. A null pixmap has depth 0.

See alsodefaultDepth() andPixmap Information.

void QPixmap::detach()

Detaches the pixmap from shared pixmap data.

A pixmap is automatically detached by Qt whenever its contents are about to change. This is done in almost allQPixmap member functions that modify the pixmap (fill(),fromImage(),load(), etc.), and inQPainter::begin() on a pixmap.

There are two exceptions in which detach() must be called explicitly, that is when calling thehandle() or thex11PictureHandle() function (only available on X11). Otherwise, any modifications done using system calls, will be performed on the shared data.

The detach() function returns immediately if there is just a single reference or if the pixmap has not been initialized yet.

void QPixmap::fill(constQColor & color = Qt::white)

Fills the pixmap with the givencolor.

The effect of this function is undefined when the pixmap is being painted on.

See alsoPixmap Transformations.

void QPixmap::fill(constQWidget * widget, constQPoint & offset)

Fills the pixmap with thewidget's background color or pixmap according to the given offset.

TheQPointoffset defines a point in widget coordinates to which the pixmap's top-left pixel will be mapped to. This is only significant if the widget has a background pixmap; otherwise the pixmap will simply be filled with the background color of the widget.

void QPixmap::fill(constQWidget * widget,int x,int y)

This is an overloaded function.

Fills the pixmap with thewidget's background color or pixmap. The given point, (x,y), defines an offset in widget coordinates to which the pixmap's top-left pixel will be mapped to.

[static]QPixmap QPixmap::fromImage(constQImage & image,Qt::ImageConversionFlags flags = Qt::AutoColor)

Converts the givenimage to a pixmap using the specifiedflags to control the conversion. Theflags argument is a bitwise-OR of theQt::ImageConversionFlags. Passing 0 forflags sets all the default options.

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 useQBitmap::fromImage() instead.

See alsofromImageReader(),toImage(), andPixmap Conversion.

[static]QPixmap QPixmap::fromImageReader(QImageReader * imageReader,Qt::ImageConversionFlags flags = Qt::AutoColor)

Create aQPixmap from an image read directly from animageReader. Theflags argument is a bitwise-OR of theQt::ImageConversionFlags. Passing 0 forflags sets all the default options.

On some systems, reading an image directly toQPixmap can use less memory than reading aQImage to convert it toQPixmap.

See alsofromImage(),toImage(), andPixmap Conversion.

[static]QPixmap QPixmap::fromMacCGImageRef(CGImageRef image)

Returns aQPixmap that is equivalent to the givenimage.

Warning: This function is only available on Mac OS X.

This function was introduced in Qt 4.2.

See alsotoMacCGImageRef() andPixmap Conversion.

[static]QPixmap QPixmap::fromSymbianCFbsBitmap(CFbsBitmap * bitmap)

Creates aQPixmap from aCFbsBitmapbitmap. Internally this function will try to duplicate the bitmap handle instead of copying the data, however in scenarios where this is not possible the data will be copied. To be sure thatQPixmap does not modify your original instance, you should make a copy of yourCFbsBitmap before calling this function. If the CFbsBitmap is not valid this function will return a nullQPixmap. For performance reasons it is recommended to use abitmap with a display mode of EColor16MAP or EColor16MU whenever possible.

Warning: This function is only available on Symbian OS.

This function was introduced in Qt 4.6.

See alsotoSymbianCFbsBitmap() andPixmap Conversion.

[static]QPixmap QPixmap::fromSymbianRSgImage(RSgImage * sgImage)

Returns aQPixmap that wraps givensgImage graphics resource. The data should be valid even when original RSgImage handle has been closed.

Warning: This function is only available on Symbian OS.

This function was introduced in Qt 4.6.

See alsotoSymbianRSgImage() andPixmap Conversion.

[static]QPixmap QPixmap::fromWinHBITMAP(HBITMAP bitmap,HBitmapFormat format = NoAlpha)

Win32 only: Returns aQPixmap that is equivalent to the givenbitmap. The conversion is based on the specifiedformat.

Warning: This function is only available on Windows.

See alsotoWinHBITMAP() andPixmap Conversion.

[static]QPixmap QPixmap::fromWinHICON(HICON icon)

Win32 only: Returns aQPixmap that is equivalent to the givenicon.

Warning: This function is only available on Windows.

This function was introduced in Qt 4.6.

See alsotoWinHICON() andPixmap Conversion.

[static]QPixmap QPixmap::fromX11Pixmap(Qt::HANDLE pixmap,ShareMode mode = ImplicitlyShared)

Creates aQPixmap from the native X11 Pixmap handlepixmap, usingmode as the share mode. The default share mode isQPixmap::ImplicitlyShared, which means that a copy of the pixmap is made if someone tries to modify it by e.g. drawing onto it.

QPixmap doesnot take ownership of thepixmap handle, and have to be deleted by the user.

Warning: This function is X11 specific; using it is non-portable.

This function was introduced in Qt 4.5.

See alsoQPixmap::ShareMode.

[static]QPixmap QPixmap::grabWidget(QWidget * widget, constQRect & rectangle)

Creates a pixmap and paints the givenwidget, restricted by the givenrectangle, in it. If thewidget has any children, then they are also painted in the appropriate positions.

If no rectangle is specified (the default) the entire widget is painted.

Ifwidget is 0, the specified rectangle doesn't overlap the widget's rectangle, or an error occurs, the function will return a nullQPixmap. If the rectangle is a superset of the givenwidget, the areas outside thewidget are covered with the widget's background.

This function actually askswidget to paint itself (and its children to paint themselves) by calling paintEvent() with painter redirection turned on. ButQPixmap also provides thegrabWindow() function which is a bit faster by grabbing pixels directly off the screen. In addition, if there are overlaying windows,grabWindow(), unlike grabWidget(), will see them.

Warning: Do not grab a widget from itsQWidget::paintEvent(). However, it is safe to grab a widget from another widget'spaintEvent().

See alsograbWindow().

[static]QPixmap QPixmap::grabWidget(QWidget * widget,int x = 0,int y = 0,int width = -1,int height = -1)

This is an overloaded function.

Creates a pixmap and paints the givenwidget, restricted byQRect(x,y,width,height), in it.

Warning: Do not grab a widget from itsQWidget::paintEvent(). However, it is safe to grab a widget from another widget'spaintEvent().

[static]QPixmap QPixmap::grabWindow(WId window,int x = 0,int y = 0,int width = -1,int height = -1)

Creates and returns a pixmap constructed by grabbing the contents of the givenwindow restricted byQRect(x,y,width,height).

The arguments (x,y) specify the offset in the window, whereas (width,height) specify the area to be copied. Ifwidth is negative, the function copies everything to the right border of the window. Ifheight is negative, the function copies everything to the bottom of the window.

The window system identifier (WId) can be retrieved using theQWidget::winId() function. The rationale for using a window identifier and not aQWidget, is to enable grabbing of windows that are not part of the application, window system frames, and so on.

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.

Note on X11 that if the givenwindow doesn't have the same depth as the root window, and another window partially or entirely obscures the one you grab, you willnot get pixels from the overlying window. The contents of the obscured areas in the pixmap will be undefined and uninitialized.

On Windows Vista and above grabbing a layered window, which is created by setting theQt::WA_TranslucentBackground attribute, will not work. Instead grabbing the desktop widget should work.

Warning: In general, grabbing an area outside the screen is not safe. This depends on the underlying window system.

See alsograbWidget() andScreenshot Example.

Qt::HANDLE QPixmap::handle() const

Returns the pixmap's handle to the device context.

Note that, sinceQPixmap make use ofimplicit data sharing, thedetach() function must be called explicitly to ensure that onlythis pixmap's data is modified if the pixmap data is shared.

Warning: This function is X11 specific; using it is non-portable.

Warning: Since 4.8, pixmaps do not have an X11 handle unless created withfromX11Pixmap(), or if the native graphics system is explicitly enabled.

See alsodetach() andQApplication::setGraphicsSystem().

bool QPixmap::hasAlpha() const

Returns true if this pixmap has an alpha channel,or has a mask, otherwise returns false.

See alsohasAlphaChannel() andmask().

bool QPixmap::hasAlphaChannel() const

Returns true if the pixmap has a format that respects the alpha channel, otherwise returns false.

See alsohasAlpha().

int QPixmap::height() const

Returns the height of the pixmap.

See alsosize() andPixmap Information.

bool QPixmap::isNull() const

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

A null pixmap has zero width, zero height and no contents. You cannot draw in a null pixmap.

bool QPixmap::isQBitmap() const

Returns true if this is aQBitmap; otherwise returns false.

bool QPixmap::load(constQString & fileName, constchar * format = 0,Qt::ImageConversionFlags flags = Qt::AutoColor)

Loads a pixmap from the file with the givenfileName. Returns true if the pixmap was successfully loaded; otherwise returns false.

The loader attempts to read the pixmap using the specifiedformat. If theformat is not specified (which is the default), the loader probes the file for a header to guess the file format.

The file name can either refer to an actual file on disk or to one of the application's embedded resources. See theResource System overview for details on how to embed pixmaps and other resource files in the application's executable.

If the data needs to be modified to fit in a lower-resolution result (e.g. converting from 32-bit to 8-bit), use theflags to control the conversion.

Note that QPixmaps are automatically added to theQPixmapCache when loaded from a file; the key used is internal and can not be acquired.

See alsoloadFromData() andReading and Writing Image Files.

bool QPixmap::loadFromData(constuchar * data,uint len, constchar * format = 0,Qt::ImageConversionFlags flags = Qt::AutoColor)

Loads a pixmap from thelen first bytes of the given binarydata. Returns true if the pixmap was loaded successfully; otherwise returns false.

The loader attempts to read the pixmap using the specifiedformat. If theformat is not specified (which is the default), the loader probes the file for a header to guess the file format.

If the data needs to be modified to fit in a lower-resolution result (e.g. converting from 32-bit to 8-bit), use theflags to control the conversion.

See alsoload() andReading and Writing Image Files.

bool QPixmap::loadFromData(constQByteArray & data, constchar * format = 0,Qt::ImageConversionFlags flags = Qt::AutoColor)

This is an overloaded function.

Loads a pixmap from the binarydata using the specifiedformat and conversionflags.

QBitmap QPixmap::mask() const

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

Warning: This is potentially an expensive operation. The mask of the pixmap is extracted dynamically from the pixeldata.

See alsosetMask() andPixmap Information.

QRect QPixmap::rect() const

Returns the pixmap's enclosing rectangle.

See alsoPixmap Information.

bool QPixmap::save(constQString & fileName, constchar * format = 0,int quality = -1) const

Saves the pixmap to the file with the givenfileName using the specified image fileformat andquality factor. Returns true if successful; otherwise returns false.

Thequality 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.

Ifformat is 0, an image format will be chosen fromfileName's suffix.

See alsoReading and Writing Image Files.

bool QPixmap::save(QIODevice * device, constchar * format = 0,int quality = -1) const

This is an overloaded function.

This function writes aQPixmap to the givendevice using the specified image fileformat andquality factor. This can be used, for example, to save a pixmap directly into aQByteArray:

QPixmap pixmap;QByteArray bytes;QBuffer buffer(&bytes);        buffer.open(QIODevice::WriteOnly);        pixmap.save(&buffer,"PNG");// writes pixmap into bytes in PNG format

QPixmap QPixmap::scaled(constQSize & size,Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio,Qt::TransformationMode transformMode = Qt::FastTransformation) const

Scales the pixmap to the givensize, using the aspect ratio and transformation modes specified byaspectRatioMode andtransformMode.

• IfaspectRatioMode isQt::IgnoreAspectRatio, the pixmap is scaled tosize.
• IfaspectRatioMode isQt::KeepAspectRatio, the pixmap is scaled to a rectangle as large as possible insidesize, preserving the aspect ratio.
• IfaspectRatioMode isQt::KeepAspectRatioByExpanding, the pixmap is scaled to a rectangle as small as possible outsidesize, preserving the aspect ratio.

If the givensize is empty, this function returns a null pixmap.

In some cases it can be more beneficial to draw the pixmap to a painter with a scale set rather than scaling the pixmap. This is the case when the painter is for instance based onOpenGL or when the scale factor changes rapidly.

See alsoisNull() andPixmap Transformations.

QPixmap QPixmap::scaled(int width,int height,Qt::AspectRatioMode aspectRatioMode = Qt::IgnoreAspectRatio,Qt::TransformationMode transformMode = Qt::FastTransformation) const

This is an overloaded function.

Returns a copy of the pixmap scaled to a rectangle with the givenwidth andheight according to the givenaspectRatioMode andtransformMode.

If either thewidth or theheight is zero or negative, this function returns a null pixmap.

QPixmap QPixmap::scaledToHeight(int height,Qt::TransformationMode mode = Qt::FastTransformation) const

Returns a scaled copy of the image. The returned image is scaled to the givenheight using the specified transformationmode. The width of the pixmap is automatically calculated so that the aspect ratio of the pixmap is preserved.

Ifheight is 0 or negative, a null pixmap is returned.

See alsoisNull() andPixmap Transformations.

QPixmap QPixmap::scaledToWidth(int width,Qt::TransformationMode mode = Qt::FastTransformation) const

Returns a scaled copy of the image. The returned image is scaled to the givenwidth using the specified transformationmode. The height of the pixmap is automatically calculated so that the aspect ratio of the pixmap is preserved.

Ifwidth is 0 or negative, a null pixmap is returned.

See alsoisNull() andPixmap Transformations.

void QPixmap::scroll(int dx,int dy,int x,int y,int width,int height,QRegion * exposed = 0)

This convenience function is equivalent to calling QPixmap::scroll(dx,dy,QRect(x,y,width,height),exposed).

This function was introduced in Qt 4.6.

See alsoQWidget::scroll() andQGraphicsItem::scroll().

void QPixmap::scroll(int dx,int dy, constQRect & rect,QRegion * exposed = 0)

Scrolls the arearect of this pixmap by (dx,dy). The exposed region is left unchanged. You can optionally pass a pointer to an emptyQRegion to get the region that isexposed by the scroll operation.

QPixmap pixmap("background.png");QRegion exposed;pixmap.scroll(10,10, pixmap.rect(),&exposed);

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

This function was introduced in Qt 4.6.

See alsoQWidget::scroll() andQGraphicsItem::scroll().

void QPixmap::setMask(constQBitmap & mask)

Sets a mask bitmap.

This function merges themask with the pixmap's alpha channel. A pixel value of 1 on the mask means the pixmap's pixel is unchanged; a value of 0 means the pixel is transparent. The mask must have the same size as this pixmap.

Setting a null mask resets the mask, leaving the previously transparent pixels black. The effect of this function is undefined when the pixmap is being painted on.

Warning: This is potentially an expensive operation.

See alsomask(),Pixmap Transformations, andQBitmap.

QSize QPixmap::size() const

Returns the size of the pixmap.

See alsowidth(),height(), andPixmap Information.

void QPixmap::swap(QPixmap & other)

Swaps pixmapother with this pixmap. This operation is very fast and never fails.

This function was introduced in Qt 4.8.

QImage QPixmap::toImage() const

Converts the pixmap to aQImage. Returns a null image if the conversion fails.

If the pixmap has 1-bit depth, the returned image will also be 1 bit deep. Images with more bits will be returned in a format closely represents the underlying system. Usually this will beQImage::Format_ARGB32_Premultiplied for pixmaps with an alpha andQImage::Format_RGB32 orQImage::Format_RGB16 for pixmaps without alpha.

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

See alsofromImage() andImage Formats.

CGImageRef QPixmap::toMacCGImageRef() const

Creates aCGImageRef equivalent to theQPixmap. Returns theCGImageRef handle.

It is the caller's responsibility to release theCGImageRef data after use.

Warning: This function is only available on Mac OS X.

This function was introduced in Qt 4.2.

See alsofromMacCGImageRef().

CFbsBitmap * QPixmap::toSymbianCFbsBitmap() const

Creates aCFbsBitmap that is equivalent to theQPixmap. Internally this function will try to duplicate the handle instead of copying the data, however in scenarios where this is not possible the data will be copied. If the creation fails or the pixmap is null, then this function returns 0.

It is the caller's responsibility to release theCFbsBitmap data after use either by deleting the bitmap or callingReset().

Warning: On S60 3.1 and S60 3.2, semi-transparent pixmaps are always copied and not duplicated.

Warning: This function is only available on Symbian OS.

This function was introduced in Qt 4.6.

See alsofromSymbianCFbsBitmap().

RSgImage * QPixmap::toSymbianRSgImage() const

Returns aRSgImage that is equivalent to theQPixmap by copying the data.

It is the caller's responsibility to close/delete theRSgImage after use.

Warning: This function is only available on Symbian OS.

This function was introduced in Qt 4.6.

See alsofromSymbianRSgImage().

HBITMAP QPixmap::toWinHBITMAP(HBitmapFormat format = NoAlpha) const

Win32 only: Creates aHBITMAP equivalent to theQPixmap, based on the givenformat. Returns theHBITMAP handle.

It is the caller's responsibility to free theHBITMAP data after use.

Warning: This function is only available on Windows.

See alsofromWinHBITMAP() andPixmap Conversion.

HICON QPixmap::toWinHICON() const

Win32 only: Creates aHICON equivalent to theQPixmap. Returns theHICON handle.

It is the caller's responsibility to free theHICON data after use.

Warning: This function is only available on Windows.

This function was introduced in Qt 4.6.

See alsofromWinHICON() andPixmap Conversion.

QPixmap QPixmap::transformed(constQTransform & transform,Qt::TransformationMode mode = Qt::FastTransformation) const

Returns a copy of the pixmap that is transformed using the given transformationtransform and transformationmode. The original pixmap is not changed.

The transformationtransform is internally adjusted to compensate for unwanted translation; i.e. the pixmap produced is the smallest pixmap that contains all the transformed points of the original pixmap. Use thetrueMatrix() function to retrieve the actual matrix used for transforming the pixmap.

This function is slow because it involves transformation to aQImage, non-trivial computations and a transformation back to aQPixmap.

See alsotrueMatrix() andPixmap Transformations.

QPixmap QPixmap::transformed(constQMatrix & matrix,Qt::TransformationMode mode = Qt::FastTransformation) const

This is an overloaded function.

This convenience function loads thematrix into aQTransform and calls the overloaded function.

[static]QTransform QPixmap::trueMatrix(constQTransform & matrix,int width,int height)

Returns the actual matrix used for transforming a pixmap with the givenwidth,height andmatrix.

When transforming a pixmap using thetransformed() function, the transformation matrix is internally adjusted to compensate for unwanted translation, i.e.transformed() returns the smallest pixmap containing all transformed points of the original pixmap. This function returns the modified matrix, which maps points correctly from the original pixmap into the new pixmap.

See alsotransformed() andPixmap Transformations.

[static]QMatrix QPixmap::trueMatrix(constQMatrix & m,int w,int h)

This is an overloaded function.

This convenience function loads the matrixm into aQTransform and calls the overloaded function with theQTransform and the widthw and the heighth.

int QPixmap::width() const

Returns the width of the pixmap.

See alsosize() andPixmap Information.

constQX11Info & QPixmap::x11Info() const

X11 only: Returns information about the configuration of the X display used by the screen to which the pixmap currently belongs.

Warning: This function is only available on X11.

See alsoPixmap Information.

Qt::HANDLE QPixmap::x11PictureHandle() const

X11 only: Returns the X11 Picture handle of the pixmap for XRender support.

This function will return 0 if XRender support is not compiled into Qt, if the XRender extension is not supported on the X11 display, or if the handle could not be created. Use of this function is not portable.

Warning: This function is only available on X11.

See alsoPixmap Information.

QPixmap::operator QVariant() const

Returns the pixmap as aQVariant.

bool QPixmap::operator!() const

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

See alsoisNull().

QPixmap & QPixmap::operator=(constQPixmap & pixmap)

Assigns the givenpixmap to this pixmap and returns a reference to this pixmap.

See alsocopy() andQPixmap().

QPixmap & QPixmap::operator=(QPixmap && other)

Related Non-Members

QDataStream &operator<<(QDataStream & stream, constQPixmap & pixmap)

Writes the givenpixmap to the givenstream as a PNG image. Note that writing the stream to a file will not produce a valid image file.

See alsoQPixmap::save() andSerializing Qt Data Types.

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

Reads an image from the givenstream into the givenpixmap.

See alsoQPixmap::load() andSerializing Qt Data Types.