QPixmap Class Reference


The QPixmap class is an off-screen buffer paint device. (details) (complete member list)

#include <qpixmap.h>

Inherits QPaintDevice.

Inherited by QBitmap.

Public Members

Static Public Members

Protected Members

Related Functions

(Note that these are not member functions.)

Detailed Description

The QPixmap class is an off-screen buffer paint device.

A standard use of the QPixmap class is to enable smooth updating of widgets. Whenever something complex needs to be drawn, you can use a pixmap to obtain flicker-free drawing.

  1. Create a pixmap with the necessary size.
  2. Fill the pixmap with the widget background color.
  3. Draw into the pixmap using a QPainter.
  4. bitBlt the contens of the pixmap onto the widget.

The code may look like this:

void CoolWidget::paintWidget( QPaintEvent * e) {
  QPixmap  pm( width(), height());      // create pixmap
  QPainter p;                           // our painter
  pm.fill( backgroundColor() );         // initialize pixmap
  p.begin( &pm );                       // paint inside pixmap
  ...                                   // do complex drawing
  p.end();                              // painting done
  bitBlt( this, 0, 0, &pm, 0, 0, -1, -1 );// copy pixmap to widget
}

The bitBlt() function is explained in the QPaintDevice documentation.

Pixel data in a pixmap is internal and managed by the underlying window system. Pixels can only be accessed through QImage, Painter functions and the bitBlt.

A pixmap can be converted to a QImage to get direct access to the pixels. A QImage can also be converted back to a pixmap.

The QPixmap class is internally based on implicit data sharing. Shared classes contains a data block with a reference count. The reference count reports the number of objects that are referring to the data block.

Making a copy of the object (called shallow copy) is accomplished just by setting a pointer and incrementing the reference count. An object that is destroyed decrements the reference count. If the reference count reaches zero, then the destructor deletes the data block.

It is much more expensive to make a deep copy. A deep copy requires that all data is copied.

The advantages of data sharing is that objects can easily be assigned, sent as parameters to functions and returned from functions. Shared classes also allocates less memory and require less copying of data.


Member Function Documentation

QPixmap::QPixmap ()

Constructs a null pixmap.

See also: isNull().

QPixmap::QPixmap (int w, int h, int depth=-1)

Constructs a pixmap with w width, h height and of depth bits per pixels.

The contents of the pixmap is uninitialized.

The depth can be either 1 (monochrome) or the default depth supported by the hardware (normally 8 bits). If depth is negative, then the hardware depth will be used.

QPixmap::QPixmap (QSize sz, int depth=-1)

Constructs a pixmap with size sz and of depth bits per pixels.

The contents of the pixmap is uninitialized.

The depth can be either 1 (monochrome) or the default depth supported by the hardware (normally 8 bits). If depth is negative, then the hardware depth will be used.

QPixmap::QPixmap (int w, int h, const char *bits, bool isXbitmap)

Constructs a monochrome pixmap which is initialized with the data in bits. This constructor is protected and used by the QBitmap class.

QPixmap::QPixmap (const QPixmap &pm)

Constructs a pixmap which is a shallow copy of pm.

QPixmap::~QPixmap ()

Dereferences the internal pixmap data, and deletes it if this is the last reference.

bool QPixmap::convertFromImage (const QImage &img)

Converts the image data and sets this pixmap. Returns TRUE if successful.

If image has more colors than the number of available colors, we try to pick the most important colors.

If this pixmap is an instance of QBitmap and image has 8 or 24 bits depth, then the image will be dithered using the Floyd-Steinberg dithering algorithm.

Bugs and limitations:

QImage QPixmap::convertToImage () const

Converts the pixmap to an image. Returns a null image if the operation failed.

If the pixmap has 1 bit depth, the returned image will also get 1 bit depth.
If the pixmap has 2-8 bits depth, the returned image gets 8 bit depth.
If the pixmap has greater than 8 bits depth, the returned image gets 24 bits depth.

Bugs and limitations:

QPixmap QPixmap::copy () const

Returns a deep copy of the pixmap. All pixels are copied using bitBlt().

See also: operator=().

int QPixmap::depth () const

Returns the depth of the image.

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

bool QPixmap::enableImageCache (bool enable)

Enables the internal image cache if enable is TRUE, or disables it if enable is FALSE. Returns the previous setting of the image cache.

This cache is disabled by default.

Enabling the internal image cache speeds up functions that fetch the pixmap contents; convertToImage() and xForm().

QPixmap QPixmap::grabWindow (WId window, int x=0, int y=0, int w=-1, int h=-1)

Grabs the contents of a window and makes a pixmap out of it. Returns the pixmap.

The argments x and y specify the offset in the window, while w and h specify the width and height of the area to be copied.

If w is negative, the function copies everything to the right border of the window. If h is negative, the function copies everything to the bottom of the window.

int QPixmap::height () const

Returns the height of the pixmap.

const char * QPixmap::imageFormat (const char *fileName)

Returns a string that specifies the image format of the file fileName, or null if the file cannot be read or if the format cannot be recognized.

See also: load() and save().

bool QPixmap::isNull () const

Returns TRUE if it is a null pixmap.

A null pixmap has zero width, zero height and no contents. You cannot draw in a null pixmap or bitBlt anything to it.

See also: isNull().

bool QPixmap::load (const char *fileName, const char *format=0)

Loads an image from the file fileName into the pixmap. Returns TRUE if successful, or FALSE if the image could not be loaded.

If format is specified, then the loader will try to read the image using the specified format. If format is not specified (default), the loader reads a few bytes from the header to guess the file format.

The QImageIO documentation describes the different image formats.

See also: save() and imageFormat().

int QPixmap::numColors () const

Returns the maximum number of colors that can be used for the pixmap.

Similar to 2^depth.

QPixmap & QPixmap::operator= (const QPixmap &p)

Assigns a shallow copy of p to this pixmap and returns a reference to this pixmap.

See also: copy().

QPixmap & QPixmap::operator= (const QImage &im)

Converts the image im to a pixmap that is assigned to this pixmap. Returns a reference to the pixmap.

See also: convertFromImage().

QRect QPixmap::rect () const

Returns the enclosing rectangle of the pixmap.

void QPixmap::resize (const QSize &s)

Synonymous resize() which takes a QSize parameter.

void QPixmap::resize (int w, int h)

Resizes the pixmap to w width and h height.

New pixels will be uninitialized (random) if the pixmap is expanded.

A valid pixmap will be created if it is a null pixmap.

bool QPixmap::save (const char *fileName, const char *format) const

Saves the pixmap to the file fileName, using the image file format format. Returns TRUE if successful, or FALSE if the image could not be saved.

See also: load() and imageFormat().

QSize QPixmap::size () const

Returns the size of the pixmap.

Q2DMatrix QPixmap::trueMatrix (const Q2DMatrix &matrix, int w, int h)

Returns the actual matrix used for transforming a pixmap with w width and h height.

When transforming a pixmap with xForm(), the transformation matrix is internally adjusted to compensate for unwanted translation, i.e. xForm() 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 also: xForm().

int QPixmap::width () const

Returns the width of the pixmap.

QPixmap QPixmap::xForm (const Q2DMatrix &matrix) const

Transforms the pixmap using matrix, and returns the transformed pixmap.

Qt uses this function to implement rotated text on window systems that do not support such complex features.

Example of how to manually draw a rotated text at (100,200) in a widget:

  QWidget  w;                           // our widget
  char    *str = "Trolls R Qt";         // text to be drawn
  QFont    f( "Charter", 24 );          // use Charter 24pt font
  QFontMetrics fm( f );                 // get font metrics
  QRect    r = fm.boundingRect( str );  // get text rectangle

  QPixmap  pm( r.width(), r.height() ); // pixmap to be rotated
  QPoint   bl = -r.topLeft();           // baseline position
  QPainter p;                           // paints pm

  pm.fill();                            // fills pm with white
  p.begin( &pm );                       // begin painting pm
  p.setFont( f );                       // set the font
  p.setPen( blue );                     // set blue text color
  p.drawText( 0,bl, str );              // draw the text
  p.end();                              // painting done

  Q2DMatrix m;                          // transformation matrix
  m.rotate( -33.4 );                    // rotate coordinate system
  QPixmap rp = pm.xForm( m );           // rp is rotated pixmap

  Q2DMatrix t = QPixmap::trueMatrix( m, pm.width(), pm.height() );
  int x, y;
  t.map( bl.x(),bl.y(), &x,&y );        // get pm's baseline pos in rp

  bitBlt( &w, 100-x, 200-y,             // blt rp into the widget
          &rp, 0, 0, -1, -1 );

See also: trueMatrix().

Bugs and limitations:


Related Functions

QDataStream & operator<< (QDataStream &s, const QPixmap &pixmap)

Writes a pixmap to the stream as a BMP image.

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

Reads a pixmap from the stream as a BMP image.


This file is part of the Qt toolkit, copyright 1995 Troll Tech, all rights reserved.

It was generated from the following files:


Generated at 04:27, 1995/05/20 by the webmaster at Troll Tech