qpixmap.3qt

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

.br
  {
.br
    QRect ur = e->rect();               // rectangle to update
.br
.br
    QPixmap  pix( ur.size() );          // Pixmap for double-buffering
.br
.br
    pix.fill( this, ur.topLeft() );     // fill with widget background
.br
.br
    QPainter p( &pix );
.br
    p.translate( -ur.x(), -ur.y() );    // use widget coordinate system
.br
                                        // when drawing on pixmap
.br
    //    ... draw on pixmap ...
.br
.br
    p.end();
.br
.br
    bitBlt( this, ur.topLeft(), &pix );
.br
  }
.fi
.PP
Examples:
.(l
grapher/grapher.cpp xform/xform.cpp desktop/desktop.cpp
.)l
.SH "void QPixmap::fill ( const QWidget * widget, int xofs, int yofs )"
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::grabWindow ( WId window, int x=0, int y=0, int w=-1, int h=-1 ) \fC[static]\fR"
Grabs the contents of a window and makes a pixmap out of it. Returns the pixmap.
.PP
The arguments \fI(x,y)\fR specify the offset in the window, while \fI(w,h)\fR specify the width and height of the area to be copied.
.PP
If \fIw\fR is negative, the function copies everything to the right border of the window. If \fIh\fR is negative, the function copies everything to the bottom of the window.
.PP
Note that grabWindows() grabs pixels from the screen, not from the window. This means that If there is another window partially or entirely over the one you grab, you get pixels from the overlying window too.
.PP
The reason we use a window identifier and not a QWidget is to enable grabbing of windows that are not part of the application.
.PP
\fBWarning:\fR Grabbing an area outside the window, or screen, is not safe in general. This depends on the underlying window system.
.SH "int QPixmap::height () const"
Returns the height of the pixmap.
.PP
See also: width(), size() and rect().
.PP
Examples:
.(l
qtimage/qtimage.cpp xform/xform.cpp desktop/desktop.cpp scrollview/scrollview.cpp movies/main.cpp
.)l
.SH "const char* QPixmap::imageFormat ( const QString & fileName ) \fC[static]\fR"
Returns a string that specifies the image format of the file \fIfileName,\fR or null if the file cannot be read or if the format cannot be recognized.
.PP
The QImageIO documentation lists the supported image formats.
.PP
See also: load() and save().
.SH "bool QPixmap::isNull () const"
Returns TRUE if it is a null pixmap.
.PP
A null pixmap has zero width, zero height and no contents. You cannot draw in a null pixmap or bitBlt() anything to it.
.PP
Resizing an existing pixmap to (0,0) makes a pixmap into a null pixmap.
.PP
See also: resize().
.PP
Examples:
.(l
qmag/qmag.cpp scrollview/scrollview.cpp
.)l
.SH "bool QPixmap::isQBitmap () const"
Returns TRUE if this is a QBitmap, otherwise FALSE.
.SH "bool QPixmap::load ( const QString & fileName, const char * format, int conversion_flags )"
Loads a pixmap from the file \fIfileName.\fR Returns TRUE if successful, or FALSE if the pixmap could not be loaded.
.PP
If \fIformat\fR is specified, the loader attempts to read the pixmap using the specified format. If \fIformat\fR is not specified (default), the loader reads a few bytes from the header to guess the file format.
.PP
See the convertFromImage() documentation for a description of the \fIconversion_flags\fR argument.
.PP
The QImageIO documentation lists the supported image formats and explains how to add extra formats.
.PP
See also: loadFromData(), save(), imageFormat(), QImage::load() and QImageIO.
.PP
Examples:
.(l
xform/xform.cpp scrollview/scrollview.cpp picture/picture.cpp
.)l
.SH "bool QPixmap::load ( const QString & fileName, const char * format=0, 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 "bool QPixmap::loadFromData ( const uchar * buf, uint len, const char * format, int conversion_flags )"
Loads a pixmap from the binary data in \fIbuf\fR (\fIlen\fR bytes). Returns TRUE if successful, or FALSE if the pixmap could not be loaded.
.PP
If \fIformat\fR is specified, the loader attempts to read the pixmap using the specified format. If \fIformat\fR is not specified (default), the loader reads a few bytes from the header to guess the file format.
.PP
See the convertFromImage() documentation for a description of the \fIconversion_flags\fR argument.
.PP
The QImageIO documentation lists the supported image formats and explains how to add extra formats.
.PP
See also: load(), save(), imageFormat(), QImage::loadFromData() and QImageIO.
.SH "bool QPixmap::loadFromData ( const QByteArray & buf, const char * format=0, int conversion_flags=0 )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "bool QPixmap::loadFromData ( const uchar * buf, uint len, const char * format=0, 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 "const QBitmap * QPixmap::mask () const"
Returns the mask bitmap, or null if no mask has been set.
.PP
See also: setMask() and QBitmap.
.SH "int QPixmap::metric ( int m ) const \fC[virtual protected]\fR"
Internal implementation of the virtual QPaintDevice::metric() function.
.PP
Use the QPaintDeviceMetrics class instead.
.PP
Reimplemented from QPaintDevice.
.SH "QPixmap & QPixmap::operator= ( const QImage & image )"
Converts the image \fIimage\fR to a pixmap that is assigned to this pixmap. Returns a reference to the pixmap.
.PP
See also: convertFromImage().
.SH "QPixmap & QPixmap::operator= ( const QPixmap & pixmap )"
Assigns the pixmap \fIpixmap\fR to this pixmap and returns a reference to this pixmap.
.SH "QRect QPixmap::rect () const"
Returns the enclosing rectangle (0,0,width(),height()) of the pixmap.
.PP
See also: width(), height() and size().
.PP
Examples:
.(l
xform/xform.cpp
.)l
.SH "void QPixmap::resize ( int w, int h )"
Resizes the pixmap to \fIw\fR width and \fIh\fR height. If either \fIw\fR or \fIh\fR is less than 1, the pixmap becomes a null pixmap.
.PP
If both \fIw\fR and \fIh\fR are greater than 0, a valid pixmap is created. New pixels will be uninitialized (random) if the pixmap is expanded.
.PP
Examples:
.(l
grapher/grapher.cpp desktop/desktop.cpp
.)l
.SH "void QPixmap::resize ( const QSize & size )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "bool QPixmap::save ( const QString & fileName, const char * format ) const"
Saves the pixmap to the file \fIfileName,\fR using the image file format \fIformat.\fR Returns TRUE if successful, or FALSE if the pixmap could not be saved.
.PP
See also: load(), loadFromData(), imageFormat(), QImage::save() and QImageIO.
.PP
Examples:
.(l
qmag/qmag.cpp
.)l
.SH "bool QPixmap::selfMask () const"
Returns TRUE if the pixmap's mask is identical to the pixmap itself.
.PP
See also: mask().
.SH "int QPixmap::serialNumber () const"
Returns a number that uniquely identifies this QPixmap object. The serial number is very useful for caching.
.PP
See also: QPixmapCache.
.SH "void QPixmap::setDefaultOptimization ( Optimization optimization ) \fC[static]\fR"
Sets the default pixmap optimization.
.PP
All \fInew\fR pixmaps that are created will use this default optimization. You may also set optimization for individual pixmaps using the setOptimization() function.
.PP
The initial default optimization setting is \fCQPixmap::Normal.\fR
.PP
See also: defaultOptimization(), setOptimization() and optimization().
.SH "void QPixmap::setMask ( const QBitmap & newmask )"
Sets a mask bitmap.
.PP
The \fImask\fR bitmap defines the clip mask for this pixmap. Every pixel in \fImask\fR corresponds to a pixel in this pixmap. Pixel value 1 means opaque and pixel value 0 means transparent. The mask must have the same size as this pixmap.
.PP
Setting a null mask resets the mask,
.PP
See also: mask(), createHeuristicMask() and QBitmap.
.SH "void QPixmap::setOptimization ( Optimization optimization )"
Sets pixmap drawing optimization for this pixmap.
.PP
The optimization setting affects pixmap operations, in particular drawing of transparent pixmaps (bitBlt() a pixmap with a mask set) and pixmap transformations (the xForm() function).
.PP
Pixmap optimization involves keeping intermediate results in a cache buffer and use the data in the cache to speed up bitBlt() and xForm(). The cost is more memory consumption, up to twice as much as an unoptimized pixmap.
.PP
The \fIoptimization\fR parameter can be:
.TP
\fCQPixmap::DefaultOptim,\fR sets the default optimization, i.e. QPixmap::defaultOptimization().
.TP
\fCQPixmap::NoOptim,\fR equivalent with MemoryOptim.
.TP
\fCQPixmap::MemoryOptim,\fR use as little memory/resource as possible, with little or no caching. The tradeoff may be unnoticably slower pixmap operations. Read the important note about Windows 95/98 below.
.TP
\fCQPixmap::NormalOptim,\fR normal optimization to make pixmap drawing faster. This option is the default and is suitable for most purposes.
.TP
\fCQPixmap::BestOptim,\fR heavily optimized pixmap drawing, but may consume more memory. Use this option for pixmap drawn extremely frequently, e.g. masked pixmaps/sprites.
.PP
Use the setDefaultOptimization() to change the default optimization for all new pixmaps.
.PP
\fBNote about Windows 95 and 98:\fR On Windows 9x, the system crashes if you create around 1000 pixmaps or more, independent of the size of the pixmaps or installed RAM. The reason is that Windows 9x has a serious resource limitation that comes from the old, 64k segmented memory model. Windows NT does not have this limitation.
.PP
Qt tries to work around the resource limitation. If you set the pixmap optimization to \fCQPixmap::MemoryOptim\fR and the width of your pixmap is less than or equal to 128 pixels, Qt will create a logical pixmap which refers an internal pixmap. This internal pixmap is shared by hundreds of other pixmaps which have the optimization set to \fCQPixmap::MemoryOptim.\fR The result is that your application may use thousands of pixmaps on Windows 9x and spend only a few percent of the system resources.
.PP
When should you set the memory optimization? If your application uses hundreds of pixmaps, e.g. on tool bar buttons, in popup menus, and you plan to run it on Windows 95 or Windows 98.
.PP
Here is an example:
.PP
.nf
.br
    QPixmap::setDefaultOptimization( QPixmap::MemoryOptim );
.br
    while ( ... ) {
.br
      // load tool bar pixmaps etc.
.br
      QPixmap *pixmap = new QPixmap(fileName);
.br
    }
.br
    QPixmap::setDefaultOptimization( QPixmap::NormalOptim );
.fi
.PP
See also: optimization(), setDefaultOptimization() and defaultOptimization().
.PP
Examples:
.(l
desktop/desktop.cpp
.)l
.SH "QSize QPixmap::size () const"
Returns the size of the pixmap.
.PP
See also: width(), height() and rect().
.PP
Examples:
.(l
qtimage/qtimage.cpp movies/main.cpp
.)l
.SH "QWMatrix QPixmap::trueMatrix ( const QWMatrix & matrix, int w, int h ) \fC[static]\fR"
Returns the actual matrix used for transforming a pixmap with \fIw\fR width and \fIh\fR height.
.PP
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.
.PP
This function returns the modified matrix, which maps points correctly from the original pixmap into the new pixmap.
.PP
See also: xForm() and QWMatrix.
.SH "int QPixmap::width () const"
Returns the width of the pixmap.
.PP
See also: height(), size() and rect().
.PP
Examples:
.(l
qtimage/qtimage.cpp xform/xform.cpp desktop/desktop.cpp scrollview/scrollview.cpp movies/main.cpp
.)l
.SH "QPixmap QPixmap::xForm ( const QWMatrix & matrix ) const"
Returns a copy of the pixmap that is transformed using \fImatrix.\fR
.PP
Qt uses this function to implement rotated text on window systems that do not support such complex features.
.PP
Example of how to manually draw a rotated text at (100,200) in a widget:
.PP
.nf
.br
    char    *str = "Trolls R Qt";       // text to be drawn
.br
    QFont    f( "Charter", 24 );        // use Charter 24pt font
.br
    QPixmap  pm( 8, 8 );
.br
    QPainter p;
.br
    QRect    r;                         // text bounding rectangle
.br
    QPoint   bl;                        // text baseline position
.br
.br
    p.begin( &pm );                     // first get the bounding
.br
    p.setFont( f );                     //   text rectangle
.br
    r = p.fontMetrics().boundingRect(str);
.br
    bl = -r.topLeft();                  // get baseline position
.br
    p.end();
.br
.br
    pm.resize( r.size() );              // resize to fit the text
.br
    pm.fill( white );                   // fills pm with white
.br
    p.begin( &pm );                     // begin painting pm
.br
    p.setFont( f );                     // set the font
.br
    p.setPen( blue );                   // set blue text color
.br
    p.drawText( bl, str );              // draw the text
.br
    p.end();                            // painting done
.br
.br
    QWMatrix m;                         // transformation matrix
.br
    m.rotate( -33.4 );                  // rotate coordinate system
.br
    QPixmap rp = pm.xForm( m );         // rp is rotated pixmap
.br
.br
    QWMatrix t = QPixmap::trueMatrix( m, pm.width(), pm.height() );
.br
    int x, y;
.br
    t.map( bl.x(),bl.y(), &x,&y );      // get pm's baseline pos in rp
.br
.br
    bitBlt( myWidget, 100-x, 200-y,     // blt rp into a widget
.br
            &rp, 0, 0, -1, -1 );
.fi
.PP
This example outlines how Qt implements rotated text under X11. The font calculation is the most tedious part. The rotation itself is only 3 lines of code.
.PP
If you want to draw rotated text, you do not have to implement all the code above. The code below does exactly the same thing as the example above, except that it uses a QPainter.
.PP
.nf
.br
    char    *str = "Trolls R Qt";       // text to be drawn
.br
    QFont    f( "Charter", 24 );        // use Charter 24pt font
.br
    QPainter p;
.br
.br
    p.begin( myWidget );
.br
    p.translate( 100, 200 );            // translates coord system
.br
    p.rotate( -33.4 );                  // rotates it counterclockwise
.br
    p.setFont( f );
.br
    p.drawText( 0, 0, str );
.br
    p.end();
.fi
.PP
See also: trueMatrix(), QWMatrix and QPainter::setWorldMatrix().
.PP
Bugs and limitations:
.TP
2 and 4 bits pixmaps are not supported.
.PP
Examples:
.(l
qtimage/qtimage.cpp xform/xform.cpp qmag/qmag.cpp desktop/desktop.cpp movies/main.cpp
.)l
.SH RELATED FUNCTION DOCUMENTATION
.SH "QDataStream & operator>> (QDataStream & s, QPixmap & pixmap)"
Reads a pixmap from the stream.
.PP
See also: QPixmap::load().
.SH "QDataStream & operator<< (QDataStream & s, const QPixmap & pixmap)"
Writes a pixmap to the stream as a PNG image.
.PP
See also:  QPixmap::save().
.SH "SEE ALSO"
.BR http://www.troll.no/qt/qpixmap.html
.SH COPYRIGHT
Copyright 1992-1999 Troll Tech AS.  See the license file included in
the distribution for a complete license statement.
.SH AUTHOR
Generated automatically from the source code.