qpixmap.3qt

tmark1.11:用于生成QT/EMBEDDED应用工程的Markfile文件

.TH QPixmap 3qt "6 July 1999" "Troll Tech AS" \" -*- nroff -*-
.\" Copyright 1992-1999 Troll Tech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QPixmap \- Off-screen pixel-based paint device
.SH SYNOPSIS
.br
.PP
\fC#include <qpixmap.h>\fR
.PP
Inherits QPaintDevice and Qt.
.PP
Inherited by QBitmap.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "enum \fBColorMode\fR { Auto, Color, Mono }"
.br
.ti -1c
.BI "enum \fBOptimization\fR { DefaultOptim, NoOptim, MemoryOptim=NoOptim, NormalOptim, BestOptim }"
.br
.ti -1c
.BI "\fBQPixmap\fR ()"
.br
.ti -1c
.BI "\fBQPixmap\fR ( int " "w" ", int " "h" ", int " "depth" " = -1, Optimization = DefaultOptim )"
.br
.ti -1c
.BI "\fBQPixmap\fR ( const QSize &, int " "depth" " = -1, Optimization = DefaultOptim )"
.br
.ti -1c
.BI "\fBQPixmap\fR ( const QString & " "fileName" ", const char * " "format" "=0, ColorMode " "mode" "=Auto )"
.br
.ti -1c
.BI "\fBQPixmap\fR ( const QString & " "fileName" ", const char * " "format" ", int conversion_flags )"
.br
.ti -1c
.BI "\fBQPixmap\fR ( const char * xpm[] )"
.br
.ti -1c
.BI "\fBQPixmap\fR ( const QByteArray & data )"
.br
.ti -1c
.BI "\fBQPixmap\fR ( const QPixmap & )"
.br
.ti -1c
.BI "\fB~QPixmap\fR ()"
.br
.ti -1c
.BI "QPixmap& \fBoperator=\fR ( const QPixmap & )"
.br
.ti -1c
.BI "QPixmap& \fBoperator=\fR ( const QImage & )"
.br
.ti -1c
.BI "bool \fBisNull\fR () const"
.br
.ti -1c
.BI "int \fBwidth\fR () const"
.br
.ti -1c
.BI "int \fBheight\fR () const"
.br
.ti -1c
.BI "QSize \fBsize\fR () const"
.br
.ti -1c
.BI "QRect \fBrect\fR () const"
.br
.ti -1c
.BI "int \fBdepth\fR () const"
.br
.ti -1c
.BI "void \fBfill\fR ( const QColor & fillColor = Qt::white )"
.br
.ti -1c
.BI "void \fBfill\fR ( const QWidget *, int " "xofs" ", int yofs )"
.br
.ti -1c
.BI "void \fBfill\fR ( const QWidget *, const QPoint & ofs )"
.br
.ti -1c
.BI "void \fBresize\fR ( int " "width" ", int height )"
.br
.ti -1c
.BI "void \fBresize\fR ( const QSize & )"
.br
.ti -1c
.BI "const QBitmap* \fBmask\fR () const"
.br
.ti -1c
.BI "void \fBsetMask\fR ( const QBitmap & )"
.br
.ti -1c
.BI "bool \fBselfMask\fR () const"
.br
.ti -1c
.BI "QBitmap \fBcreateHeuristicMask\fR ( bool " "clipTight" " = TRUE ) const"
.br
.ti -1c
.BI "QPixmap \fBxForm\fR ( const QWMatrix & ) const"
.br
.ti -1c
.BI "QImage \fBconvertToImage\fR () const"
.br
.ti -1c
.BI "bool \fBconvertFromImage\fR ( const QImage &, ColorMode " "mode" "=Auto )"
.br
.ti -1c
.BI "bool \fBconvertFromImage\fR ( const QImage &, int conversion_flags )"
.br
.ti -1c
.BI "bool \fBload\fR ( const QString & " "fileName" ", const char * " "format" "=0, ColorMode " "mode" "=Auto )"
.br
.ti -1c
.BI "bool \fBload\fR ( const QString & " "fileName" ", const char * " "format" ", int conversion_flags )"
.br
.ti -1c
.BI "bool \fBloadFromData\fR ( const uchar * " "buf" ", uint " "len" ", const char * " "format" "=0, ColorMode " "mode" "=Auto )"
.br
.ti -1c
.BI "bool \fBloadFromData\fR ( const uchar * " "buf" ", uint " "len" ", const char * " "format" ", int conversion_flags )"
.br
.ti -1c
.BI "bool \fBloadFromData\fR ( const QByteArray & " "data" ", const char * " "format" "=0, int " "conversion_flags" "=0 )"
.br
.ti -1c
.BI "bool \fBsave\fR ( const QString & " "fileName" ", const char * format ) const"
.br
.ti -1c
.BI "int \fBserialNumber\fR () const"
.br
.ti -1c
.BI "Optimization \fBoptimization\fR () const"
.br
.ti -1c
.BI "void \fBsetOptimization\fR ( Optimization )"
.br
.ti -1c
.BI "virtual void \fBdetach\fR ()"
.br
.ti -1c
.BI "bool \fBisQBitmap\fR () const"
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "int \fBdefaultDepth\fR ()"
.br
.ti -1c
.BI "QPixmap \fBgrabWindow\fR ( WId, int " "x" "=0, int " "y" "=0, int " "w" "=-1, int " "h" "=-1 )"
.br
.ti -1c
.BI "QWMatrix \fBtrueMatrix\fR ( const QWMatrix &, int " "w" ", int h )"
.br
.ti -1c
.BI "const char* \fBimageFormat\fR ( const QString & fileName )"
.br
.ti -1c
.BI "Optimization \fBdefaultOptimization\fR ()"
.br
.ti -1c
.BI "void \fBsetDefaultOptimization\fR ( Optimization )"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "\fBQPixmap\fR ( int " "w" ", int " "h" ", const uchar * " "data" ", bool isXbitmap )"
.br
.ti -1c
.BI "virtual int \fBmetric\fR ( int ) const"
.br
.in -1c
.SH RELATED FUNCTION DOCUMENTATION
(Note that these are not member functions.)
.in +1c
.ti -1c
.BI "QDataStream & \fBoperator>>\fR (QDataStream & " "s" ", QPixmap & " "pixmap" ")"
.br
.ti -1c
.BI "QDataStream & \fBoperator<<\fR (QDataStream & " "s" ", const QPixmap & " "pixmap" ")"
.br
.in -1c
.SH DESCRIPTION
The QPixmap class is an off-screen pixel-based paint device.
.PP
It is one of the two classes Qt provides for dealing with images, the other being QImage. QPixmap is designed and optimized for drawing; QImage is designed and optimized for I/O and for direct pixel access/manipulation. There are (slow) functions to convert between QImage and QPixmap; convertToImage() and convertFromImage().
.PP
One common 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, like this:
.IP 1
Create a pixmap with the same size as the widget.
.IP 2
Fill the pixmap with the widget background color.
.IP 3
Paint the pixmap.
.IP 4
bitBlt() the pixmap contents onto the widget.
.PP
Pixel data in a pixmap is internal and managed by the underlying window system. Pixels can only be accessed through QPainter functions, through bitBlt(), and by converting the QPixmap to a QImage.
.PP
You can display a QPixmap on the screen easily using e.g. QLabel::setPixmap(), and all the button classes support pixmap use.
.PP
There are also convenience functions to get and set single pixels and to load and save the entire pixmap; these work by converting the pixmap to a QImage internally.
.PP
The QPixmap class is optimized by the use of implicit sharing, so it is very efficient to pass QPixmap objects as arguments.
.PP
\fBNote about Windows 95 and 98:\fR Because of internal limitations in the operating system, Windows 9x easily crashes if you create around 1000 pixmaps or more. Qt will work around this problem if you set the pixmap optimization to \fCQPixmap::MemoryOptim.\fR Read more about this in the setOptimization() documentation.
.PP
See also: QBitmap, QImage, QImageIO and Shared Classes
.PP
Examples:
.(l
qtimage/qtimage.cpp grapher/grapher.cpp xform/xform.cpp menu/menu.cpp qmag/qmag.cpp desktop/desktop.cpp scrollview/scrollview.cpp movies/main.cpp picture/picture.cpp
.)l
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QPixmap::QPixmap ()"
Constructs a null pixmap.
.PP
See also: isNull().
.SH "QPixmap::QPixmap ( const QString & fileName, const char * format, int conversion_flags )"
Constructs a pixmap from the file \fIfileName.\fR If the file does not exist, or is of an unknown format, the pixmap becomes a null pixmap.
.PP
The parameters are passed on to load().
.PP
See also: isNull(), load(), loadFromData(), save() and imageFormat().
.SH "QPixmap::QPixmap ( const QString & fileName, const char * format=0, ColorMode mode=Auto )"
Constructs a pixmap from the file \fIfileName.\fR If the file does not exist, or is of an unknown format, the pixmap becomes a null pixmap.
.PP
The parameters are passed on to load().
.PP
See also: isNull(), load(), loadFromData(), save() and imageFormat().
.SH "QPixmap::QPixmap ( const QByteArray & img_data )"
Constructs a pixmaps by loading from \fIimg_data.\fR The data can be in any image format supported by Qt.
.PP
See also: loadFromData().
.SH "QPixmap::QPixmap ( const QPixmap & pixmap )"
Constructs a pixmap which is a copy of \fIpixmap.\fR
.SH "QPixmap::QPixmap ( const char * xpm[] )"
Constructs a pixmap from \fIxpm,\fR which must be a valid XPM image.
.SH "QPixmap::QPixmap ( int w, int h, const uchar * bits, bool isXbitmap ) \fC[protected]\fR"
Constructs a monochrome pixmap which is initialized with the data in \fIbits.\fR This constructor is protected and used by the QBitmap class.
.SH "QPixmap::QPixmap ( int w, int h, int depth = -1, Optimization optimization = DefaultOptim )"
Constructs a pixmap with \fIw\fR width, \fIh\fR height and of \fIdepth\fR bits per pixels.
.PP
The contents of the pixmap is uninitialized.
.PP
The \fIdepth\fR can be either 1 (monochrome) or the depth of the current video mode. If \fIdepth\fR is negative, then the hardware depth of the current video mode will be used.
.PP
If either \fIwidth\fR or \fIheight\fR is zero, a null pixmap is constructed.
.PP
See also: isNull().
.SH "QPixmap::QPixmap ( const QSize & size, int depth = -1, Optimization optimization = DefaultOptim )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "QPixmap::~QPixmap ()"
Destroys the pixmap.
.SH "bool QPixmap::convertFromImage ( const QImage & img, int conversion_flags )"
Converts an image and sets this pixmap. Returns TRUE if successful.
.PP
The \fIconversion_flags\fR argument is a bitwise-OR from the following choices. The options marked \fI(default)\fR are the choice if no other choice from the list is included (they are zero):
.IP "Color/Mono preference (ignored for QBitmap)" 1c
.TP
\fCAutoColor\fR (default) - If the \fIimage\fR has depth 1 and contains only black and white pixels, then the pixmap becomes monochrome.
.TP
\fCColorOnly\fR - The pixmap is dithered/converted to the native display depth.
.TP
\fCMonoOnly\fR - The pixmap becomes monochrome. If necessary, it is dithered using the chosen dithering algorithm.
.IP "Dithering mode preference, for RGB channels" 1c
.TP
\fCDiffuseDither\fR (default) - a high quality dither
.TP
\fCOrderedDither\fR - a faster more ordered dither
.TP
\fCThresholdDither\fR - no dithering, closest color is used
.IP "Dithering mode preference, for alpha channel" 1c
.TP
\fCDiffuseAlphaDither\fR - a high quality dither
.TP
\fCOrderedAlphaDither\fR - a faster more ordered dither
.TP
\fCThresholdAlphaDither\fR (default) - no dithering
.IP "Color matching versus dithering preference" 1c
.TP
\fCPreferDither\fR - always dither 32-bit images when the image is being converted to 8-bits. This is the default when converting to a pixmap.
.TP
\fCAvoidDither\fR - only dither 32-bit images if the image has more than 256 colors and it is being converted to 8-bits. This is the default when an image is converted for the purpose of saving to a file.
.PP
Passing 0 for \fIconversion_flags\fR gives all the default options.
.PP
Note that even though a QPixmap with depth 1 behaves much like a QBitmap, isQBitmap() returns FALSE.
.PP
If a pixmap with depth 1 is painted with color0 and color1 and converted to an image, the pixels painted with color0 will produce pixel index 0 in the image and those painted with color1 will produce pixel index 1.
.PP
See also: convertToImage(), isQBitmap(), QImage::convertDepth(), defaultDepth() and hasAlphaBuffer().
.PP
Bugs and limitations:
.TP
Does not support 2 or 4 bit display hardware.
.PP
Examples:
.(l
qtimage/qtimage.cpp
.)l
.SH "bool QPixmap::convertFromImage ( const QImage & image, ColorMode mode=Auto )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "QImage QPixmap::convertToImage () const"
Converts the pixmap to an image. Returns a null image if the operation failed.
.PP
If the pixmap has 1 bit depth, the returned image will also be 1 bits deep. If the pixmap has 2-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.
.PP
See also: convertFromImage().
.PP
Bugs and limitations:
.TP
Does not support 2 or 4 bit display hardware.
.TP
Alpha masks on monochrome images are ignored.
.PP
Examples:
.(l
qmag/qmag.cpp
.)l
.SH "QBitmap QPixmap::createHeuristicMask ( bool clipTight = TRUE ) const"
Creates and returns a heuristic mask for this pixmap. It works by selecting a color from one of the corners, then chipping away pixels of that color, starting at all the edges.
.PP
The mask may not be perfect but should be reasonable, so you can do things like:
.PP
.nf
.br
    pm->setMask( pm->createHeuristicMask() );
.fi
.PP
This function is slow because it involves transformation to a QImage, non-trivial computations and a transformation back to QBitmap.
.PP
See also: QImage::createHeuristicMask().
.SH "int QPixmap::defaultDepth () \fC[static]\fR"
Returns the default pixmap depth, i.e. the depth a pixmap gets if -1 is specified.
.PP
See also: depth().
.SH "int QPixmap::depth () const"
Returns the depth of the image.
.PP
The pixmap depth is also called bits per pixel (bpp) or bit planes of a pixmap. A null pixmap has depth 0.
.PP
See also: defaultDepth(), isNull() and QImage::convertDepth().
.SH "void QPixmap::detach () \fC[virtual]\fR"
Special-purpose function that detaches the pixmap from shared pixmap data.
.PP
A pixmap is automatically detached by Qt whenever its contents is about to change. This is done in all QPixmap member functions that modify the pixmap (fill(), resize(), convertFromImage(), load() etc.), in bitBlt() for the destination pixmap and in QPainter::begin() on a pixmap.
.PP
It is possible to modify a pixmap without letting Qt know. You can first obtain the system-dependent handle and then call system-specific functions (for instance BitBlt under Windows) that modifies the pixmap contents. In this case, you can call detach() to cut the pixmap loose from other pixmaps that share data with this one.
.PP
detach() returns immediately if there is just a single reference or if the pixmap has not been initialized yet.
.SH "void QPixmap::fill ( const QColor & fillColor = Qt::white )"
Fills the pixmap with the color \fIfillColor.\fR
.SH "void QPixmap::fill ( const QWidget * widget, const QPoint & ofs )"
Fills the pixmap with the widget's background color or pixmap. If the background is empty, nothing is done.
.PP
The \fIofs\fR point is an offset in the widget.
.PP
The point \fIofs\fR is a point in the widget's coordinate system. The pixmap's top left pixel will be mapped to the point \fIofs\fR in the widget. This is significant if the widget has a background pixmap, otherwise the pixmap will simply be filled with the background color of the widget.
.PP
Example:
.PP
.nf
.br
  void CuteWidget::paintEvent( QPaintEvent *e )