|  | Home · Overviews · Examples |

# QPixmap Class Reference
[com.trolltech.qt.gui module]

The `QPixmap` class is an off-screen image representation that can be used as a paint device. More...

Inherits .

Inherited by `QBitmap`.

## Detailed Description

The `QPixmap` 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` and `QPicture`. `QImage` 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. `QBitmap` is only a convenience class that inherits `QPixmap`, ensuring a depth of 1. The `isQBitmap` function returns true if a `QPixmap` object is really a bitmap, otherwise returns false. Finally, the `QPicture` class is a paint device that records and replays `QPainter` commands.

A `QPixmap` can easily be displayed on the screen using `QLabel` or one of `QAbstractButton`'s subclasses (such as `QPushButton` and `QToolButton`). `QLabel` has a pixmap property, whereas `QAbstractButton` has an icon property. And because `QPixmap` is a `QPaintDevice` subclass, `QPainter` can be used to draw directly onto pixmaps.

In addition to the ordinary constructors, a `QPixmap` can be constructed using the static `grabWidget` and `grabWindow` functions which creates a `QPixmap` and paints the given widget, or window, in it.

Note that the pixel data in a pixmap is internal and is managed by the underlying window system. Pixels can only be accessed through `QPainter` functions or by converting the `QPixmap` to a `QImage`. 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 `QImage`, may be hardware dependent. On X11 and Mac, a `QPixmap` is stored on the server side while a `QImage` is stored on the client side (on Windows, these two classes have an equivalent internal representation, i.e. both `QImage` and `QPixmap` are stored on the client side and don't use any GDI resources).

There are functions to convert between `QImage` and `QPixmap`. Typically, the `QImage` class is used to load an image file, optionally manipulating the image data, before the `QImage` 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 `HBITMAP` and `QPixmap`.

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

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

- Reading and Writing Image Files
- Pixmap Information
- Pixmap Conversion
- Pixmap Transformations

### Reading and Writing Image Files

`QPixmap` provides several ways of reading an image file: The file can be loaded when constructing the `QPixmap` object, or by using the load() or loadFromData() 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. See The Qt Resource System overview for details on how to embed images and other resource files in the application's executable.

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

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

Format | Description | Qt's support
--- | --- | ---
BMP | Windows Bitmap | Read/write
GIF | Graphic Interchange Format (optional) | Read
JPG | Joint Photographic Experts Group | Read/write
JPEG | Joint Photographic Experts Group | Read/write
PNG | Portable Network Graphics | Read/write
PBM | Portable Bitmap | Read
PGM | Portable Graymap | Read
PPM | Portable Pixmap | Read/write
XBM | X11 Bitmap | Read/write
XPM | X11 Pixmap | Read/write

(To configure Qt with GIF support, pass `-qt-gif` to the `configure` script or check the appropriate option in the graphical installer.)

### Pixmap Information

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

| Available Functions
--- | ---
Geometry | The `size`, `width` and `height` functions provide information about the pixmap's size. The `rect` function returns the image's enclosing rectangle.
Alpha component | The `hasAlphaChannel` returns true if the pixmap has a format that respects the alpha channel, otherwise returns false, while the `hasAlpha` function returns true if the pixmap has an alpha channel or a mask (otherwise false). The `alphaChannel` function returns the alpha channel as a new `QPixmap` object, while the `mask` function returns the mask as a `QBitmap` object. The alpha channel and mask can be set using the `setAlphaChannel` and `setMask` functions, respectively.
Low-level information | The `depth` function returns the depth of the pixmap. The `defaultDepth` function returns the default depth, i.e. the depth used by the application on the given screen. The `cacheKey` function returns a number that uniquely identifies the contents of the `QPixmap` object. The x11Info() function returns information about the configuration of the X display used to display the widget. The x11PictureHandle() function returns the X11 Picture handle of the pixmap for XRender support. Note that the two latter functions are only available on x11.

### Pixmap Conversion

A `QPixmap` object can be converted into a `QImage` using the `toImage` function. Likewise, a `QImage` can be converted into a `QPixmap` using the `fromImage`. If this is too expensive an operation, you can use QBitmap::fromImage() instead.

In addition, on Windows, the `QPixmap` class supports conversion to and from HBitmap: the toWinHBITMAP() function creates a HBITMAP equivalent to the `QPixmap`, based on the given HBitmapFormat, and returns the HBITMAP handle. The fromWinHBITMAP() function returns a `QPixmap` that is equivalent to the given bitmap which has the specified format.

### Pixmap Transformations

`QPixmap` supports a number of functions for creating a new pixmap that is a transformed version of the original: The `createHeuristicMask` function creates and returns a 1-bpp heuristic mask (i.e. a `QBitmap`) for this pixmap. It works by selecting a color from one of the corners and then chipping away pixels of that color, starting at all the edges. The `createMaskFromColor` function creates and returns a mask (i.e. a `QBitmap`) for the pixmap based on a given color.

The `scaled`, `scaledToWidth` and `scaledToHeight` functions return scaled copies of the pixmap, while the `copy` function creates a `QPixmap` that is a plain copy of the original one.

The `transformed` 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 static `trueMatrix` function returns the actual matrix used for transforming the pixmap.

There are also functions for changing attributes of a pixmap. in-place: The `fill` function fills the entire image with the given color, the `setMask` function sets a mask bitmap, and the `setAlphaChannel` function sets the pixmap's alpha channel.

See also `QBitmap`, `QImage`, `QImageReader`, and `QImageWriter`.