![]() |
Home · Overviews · Examples |
The QPixmap class is an off-screen image representation that can be used as a paint device. More...
Inherited by QBitmap.
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.
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.)
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. |
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.
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.
Copyright © 2008 Trolltech | Trademarks | Qt Jambi 4.3.5_01 |