qpainter.3qt

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

.SH DESCRIPTION
The QPainter class paints on paint devices.
.PP
The painter provides efficient graphics rendering on any QPaintDevice object. QPainter can draw everything from simple lines to complex shapes like pies and chords. It can also draw aligned text and pixmaps.
.PP
Graphics can be transformed using view transformation, world transformation or a combination of these two. View transformation is a window/viewport transformation with translation and scaling. World transformation is a full 2D transformation including rotation and shearing.
.PP
The typical use of a painter is:
.IP 1
Construct a painter.
.IP 2
Set a pen, a brush etc.
.IP 3
Draw.
.IP 4
Destroy the painter.
.PP
This example uses a convenience constructor that calls begin(), and relies on the destructor to call end():
.PP
.nf
.br
    void MyWidget::paintEvent()
.br
    {
.br
        QPainter paint( this );                 // start painting widget
.br
        paint.setPen( Qt::blue );               // set blue pen
.br
        paint.drawText( rect(),                 // draw a text, centered
.br
                        AlignCenter,            //   in the widget
.br
                        "The Text" );
.br
    }
.fi
.PP
You can also use the begin() and end() functions to begin and end painting explicitly:
.PP
.nf
.br
    void MyWidget::paintEvent()
.br
    {
.br
        QPainter paint;
.br
        paint.begin( this );                    // start painting widget
.br
        paint.setPen( Qt::blue );               // set blue pen
.br
        paint.drawText( rect(),                 // draw a text, centered
.br
                        AlignCenter,            //   in the widget
.br
                        "The Text" );
.br
        paint.end();                            // painting done
.br
    }
.fi
.PP
This is useful since it is not possible to have two painters active on the same paint device at a time.
.PP
QPainter is almost never used outside paintEvent(). Any widget \fImust\fR be able to repaint itself at any time via paintEvent(), therefore it's almost always best to design the widget so that it does all the painting in paintEvent() and use either QWidget::update() or QWidget::repaint() force a paint event as necessary.
.PP
Note that both painters and some paint devices have attributes such as current font, current foreground colors and so on.
.PP
QPainter::begin() copies these attributes from the paint device, and changing a paint device's attributes will have effect only the next time a painter is opened on it.
.PP
\fBWarning:\fR QPainter::begin() resets all attributes to their default values, from the device, thus setting fonts, brushes, etc, before begin() will have \fIno\fR effect.
.PP
See also: QPaintDevice, QWidget and QPixmap.
.PP
Examples:
.(l
qtimage/qtimage.cpp grapher/grapher.cpp drawlines/connect.cpp xform/xform.cpp drawdemo/drawdemo.cpp progress/progress.cpp qmag/qmag.cpp splitter/splitter.cpp forever/forever.cpp desktop/desktop.cpp scrollview/scrollview.cpp trivial/trivial.cpp movies/main.cpp picture/picture.cpp
.)l
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QPainter::QPainter ()"
Constructs a painter.
.PP
Notice that all painter settings (setPen,setBrush etc.) are reset to default values when begin() is called.
.PP
See also: begin() and end().
.SH "QPainter::QPainter ( const QPaintDevice * pd )"
Constructs a painter that begins painting the paint device \fIpd\fR immediately.
.PP
This constructor is convenient for short-lived painters, e.g. in a paint event and should be used only once. The constructor calls begin() for you and the QPainter destructor automatically calls end().
.PP
Example using begin() and end():
.PP
.nf
.br
    void MyWidget::paintEvent( QPaintEvent * )
.br
    {
.br
        QPainter p( this );
.br
        p.drawLine( ... );      // drawing code
.br
    }
.fi
.PP
Example using this constructor:
.PP
.nf
.br
    void MyWidget::paintEvent( QPaintEvent * )
.br
    {
.br
        QPainter p( this );
.br
        p.drawLine( ... );      // drawing code
.br
    }
.fi
.PP
See also: begin() and end().
.SH "QPainter::QPainter ( const QPaintDevice * pd, const QWidget * copyAttributes )"
Constructs a painter that begins painting the paint device \fIpd\fR immediately, with the default arguments taken from \fIcopyAttributes.\fR
.PP
See also: begin().
.SH "QPainter::~QPainter ()"
Destroys the painter.
.SH "const QColor & QPainter::backgroundColor () const"
Returns the background color currently set.
.PP
See also: setBackgroundColor().
.SH "BGMode QPainter::backgroundMode () const"
Returns the background mode currently set.
.PP
See also: setBackgroundMode().
.SH "bool QPainter::begin ( const QPaintDevice * pd )"
Begins painting the paint device \fIpd\fR and returns TRUE if successful, or FALSE if it cannot begin painting. Call end() when you have finished painting.
.PP
On the X Window System, paint commands are buffered and may not appear on the screen immediately. The flush() function flushes the buffer.
.PP
As an alternative to calling begin() and end(), you can use the QPainter constructor that takes a paint device argument. This is for short-lived painters, for example in paint events.
.PP
This function initializes all painter settings:
.TP
The font is set to the default application font, or to the widget's font if \fIpd\fR is a widget.
.TP
The pen is set to QPen(black,0,SolidLine), or to QPen(widget->foreground(), 0,SolidLine) if \fIpd\fR is a widget.
.TP
The brush is set to QBrush(NoBrush).
.TP
The background color is set to white, or to the widget's background color if \fIpd\fR is a widget.
.TP
The background mode is set to \fCTransparentMode.\fR
.TP
The raster operation is set to \fCCopyROP.\fR
.TP
The brush origin is set to (0,0).
.TP
The view transformation setting is turned off.
.TP
The window is set to the paint device rectangle; (0,0,pd->width(),pd->height()).
.TP
The viewport is set to the paint device rectangle; (0,0,pd->width(),pd->height()).
.TP
The world transformation setting is turned off.
.TP
The world matrix is set to the identify matrix.
.TP
Clipping is disabled.
.TP
The clip region is set to an empty region.
.PP
\fBWarning:\fR A paint device can only be painted by one painter at a time.
.PP
See also: end(), flush(), setFont(), setPen(), setBrush(), setBackgroundColor(), setBackgroundMode(), setRasterOp(), setBrushOrigin(), setViewXForm(), setWindow(), setViewport(), setWorldXForm(), setWorldMatrix() and setClipRegion().
.PP
Examples:
.(l
desktop/desktop.cpp picture/picture.cpp
.)l
.SH "bool QPainter::begin ( const QPaintDevice * pd, const QWidget * copyAttributes )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.PP
This version opens the painter on a paint device \fIpd\fR and sets the initial pen, background color and font from \fIcopyAttributes.\fR This is equivalent with:
.PP
.nf
.br
    QPainter p;
.br
    p.begin( pd );
.br
    p.setPen( copyAttributes->foregroundColor() );
.br
    p.setBackgroundColor( copyAttributes->backgroundColor() );
.br
    p.setFont( copyAttributes->font() );
.fi
.PP
This begin function is convenient for double buffering. When you draw in a pixmap instead of directly in a widget (to later bitBlt the pixmap into the widget) you will need to set the widgets's font etc. This function does exactly that.
.PP
Example:
.PP
.nf
.br
    void MyWidget::paintEvent( QPaintEvent * )
.br
    {
.br
        QPixmap pm(size());
.br
        QPainter p;
.br
        p.begin(&pm, this);
.br
        // ... potential flickering paint operation ...
.br
        p.end();
.br
        bitBlt(this, 0, 0, &pm);
.br
    }
.fi
.PP
See also: end().
.SH "QRect QPainter::boundingRect ( int x, int y, int w, int h, int tf, const QString & str, int len = -1, char ** internal=0 )"
Returns the bounding rectangle of the aligned text that would be printed with the corresponding drawText() function (the first \fIlen\fR characters from \fIstr).\fR The drawing, and hence the bounding rectangle, is constrained to the rectangle \fI(x,y,w,h).\fR
.PP
The \fItf\fR text formatting is the bitwise OR of the following flags:
.TP
\fCAlignLeft\fR aligns to the left border.
.TP
\fCAlignRight\fR aligns to the right border.
.TP
\fCAlignHCenter\fR aligns horizontally centered.
.TP
\fCAlignTop\fR aligns to the top border.
.TP
\fCAlignBottom\fR aligns to the bottom border.
.TP
\fCAlignVCenter\fR aligns vertically centered
.TP
\fCAlignCenter\fR (= \fCAlignHCenter\fR | \fCAlignVCenter)\fR
.TP
\fCSingleLine\fR ignores newline characters in the text.
.TP
\fCExpandTabs\fR expands tabulators.
.TP
\fCShowPrefix\fR displays "&x" as "x" underlined.
.TP
\fCWordBreak\fR breaks the text to fit the rectangle.
.PP
These flags are defined in qwindowdefs.h.
.PP
See also: drawText() and fontMetrics().
.SH "QRect QPainter::boundingRect ( const QRect & r, int tf, const QString &, int len = -1, char ** i=0 )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "const QBrush & QPainter::brush () const"
Returns the current painter brush.
.PP
See also: QPainter::setBrush().
.SH "const QPoint & QPainter::brushOrigin () const"
Returns the brush origin currently set.
.PP
See also: setBrushOrigin().
.SH "void QPainter::cleanup () \fC[static]\fR"
Internal function that cleans up the painter.
.SH "const QRegion & QPainter::clipRegion () const"
Returns the clip region currently set. Note that the clip region is given in physical device coordinates and \fInot\fR subject to any coordinate transformation.
.PP
See also: setClipRegion(), setClipRect() and setClipping().
.SH "QPaintDevice * QPainter::device () const"
Returns the paint device currently active for this painter, or null if begin() has not been called.
.PP
See also: QPaintDevice::paintingActive().
.SH "void QPainter::drawArc ( int x, int y, int w, int h, int a, int alen )"
Draws an arc defined by the rectangle \fI(x,y,w,h),\fR the start angle \fIa\fR and the arc length \fIalen.\fR
.PP
The angles \fIa\fR and \fIalen\fR are 1/16th of a degree, i.e. a full circle equals 5760 (16*360). Positive values of \fIa\fR and \fIalen\fR mean counter-clockwise while negative values mean clockwise direction. Zero degrees is at the 3'o clock position.
.PP
Example:
.PP
.nf
.br
    QPainter p;
.br
    p.begin( myWidget );
.br
    p.drawArc( 10,10, 70,100, 100*16, 160*16 ); // draws a "(" arc
.br
    p.end();
.fi
.PP
See also: drawPie() and drawChord().
.SH "void QPainter::drawArc ( const QRect & r, int a, int alen )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "void QPainter::drawChord ( int x, int y, int w, int h, int a, int alen )"
Draws a chord defined by the rectangle \fI(x,y,w,h),\fR the start angle \fIa\fR and the arc length \fIalen.\fR
.PP
The chord is filled with the current brush.
.PP
The angles \fIa\fR and \fIalen\fR are 1/16th of a degree, i.e. a full circle equals 5760 (16*360). Positive values of \fIa\fR and \fIalen\fR mean counter-clockwise while negative values mean clockwise direction. Zero degrees is at the 3'o clock position.
.PP
See also: drawArc() and drawPie().
.SH "void QPainter::drawChord ( const QRect & r, int a, int alen )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "void QPainter::drawEllipse ( int x, int y, int w, int h )"
Draws an ellipse with center at \fI(x+w/2,y+h/2)\fR and size \fI(w,h).\fR
.PP
Examples:
.(l
drawdemo/drawdemo.cpp picture/picture.cpp
.)l
.SH "void QPainter::drawEllipse ( const QRect & r )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "void QPainter::drawImage ( int x, int y, const QImage & image, int sx=0, int sy=0, int sw=-1, int sh=-1 )"
Draws at (\fIx, y)\fR the \fIsw\fR by \fIsh\fR area of pixels from (\fIsx, sy)\fR in \fIimage.\fR
.PP
This function simply converts \fIimage\fR to a QPixmap and draws it.
.PP
See also: drawPixmap() and QPixmap::convertFromImage().
.SH "void QPainter::drawImage ( const QPoint &, const QImage & )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "void QPainter::drawImage ( const QPoint &, const QImage &, const QRect & sr )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "void QPainter::drawLine ( int x1, int y1, int x2, int y2 )"
Draws a line from \fI(x1,y2)\fR to \fI(x2,y2).\fR Both endpoints are drawn.
.PP
See also: moveTo() and lineTo().
.PP
Examples:
.(l
grapher/grapher.cpp drawlines/connect.cpp progress/progress.cpp splitter/splitter.cpp scrollview/scrollview.cpp
.)l
.SH "void QPainter::drawLine ( const QPoint & p1, const QPoint & p2 )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "void QPainter::drawLineSegments ( const QPointArray & a, int index=0, int nlines=-1 )"
Draws \fInlines\fR separate lines from points defined in \fIa,\fR starting at a[\fIindex].\fR If \fInlines\fR is -1 all points until the end of the array are used (i.e. (a.size()-index)/2 lines are drawn).
.PP
Draws the 1st line from \fIa[index]\fR to \fIa[index+1].\fR Draws the 2nd line from \fIa[index+2]\fR to \fIa[index+3]\fR etc.
.PP
See also: drawPolyline() and drawPolygon().
.SH "void QPainter::drawPicture ( const QPicture & pic )"
Replays the picture \fIpic.\fR
.PP
This function does exactly the same as QPicture::play().
.PP
Examples:
.(l
picture/picture.cpp
.)l
.SH "void QPainter::drawPie ( int x, int y, int w, int h, int a, int alen )"
Draws a pie defined by the rectangle \fI(x,y,w,h),\fR the start angle \fIa\fR and the arc length \fIalen.\fR
.PP
The pie is filled with the current brush.
.PP
The angles \fIa\fR and \fIalen\fR are 1/16th of a degree, i.e. a full circle equals 5760 (16*360). Positive values of \fIa\fR and \fIalen\fR mean counter-clockwise while negative values mean clockwise direction. Zero degrees is at the 3'o clock position.
.PP
See also: drawArc() and drawPie().
.PP
Examples:
.(l
grapher/grapher.cpp drawdemo/drawdemo.cpp
.)l
.SH "void QPainter::drawPie ( const QRect & r, int a, int alen )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "void QPainter::drawPixmap ( int x, int y, const QPixmap & pixmap, int sx=0, int sy=0, int sw=-1, int sh=-1 )"
Draws a pixmap at \fI(x,y)\fR by copying a part of the pixmap into the paint device.
.PP
Arguments:
.TP
\fI(x,y)\fR specify the point in the paint device.
.TP
\fI(sx,sy)\fR specify an offset in the pixmap.
.TP
\fI(sw,sh)\fR specify the area of the area of the pixmap to be copied. The value -1 means to the right/bottom of the pixmap. The pixmap is clipped if a mask has been set.
.PP
See also: bitBlt() and QPixmap::setMask().
.PP
Examples:
.(l
qtimage/qtimage.cpp grapher/grapher.cpp qmag/qmag.cpp scrollview/scrollview.cpp movies/main.cpp picture/picture.cpp
.)l
.SH "void QPainter::drawPixmap ( const QPoint & p, const QPixmap & pm )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.PP
This version of the call draws the entire pixmap.
.SH "void QPainter::drawPixmap ( const QPoint & p, const QPixmap & pm, const QRect & sr )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "void QPainter::drawPoint ( int x, int y )"
Draws/plots a single point at \fI(x,y)\fR using the current pen.
.PP
Examples:
.(l
drawlines/connect.cpp desktop/desktop.cpp
.)l
.SH "void QPainter::drawPoint ( const QPoint & p )"
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
.SH "void QPainter::drawPoints ( const QPointArray & a, int index=0, int npoints=-1 )"
Draws/plots an array of points using the current pen. The \fIindex\fR and \fInpoints\fR arguments allow a subsequence of the array to be drawn.
.SH "void QPainter::drawPolygon ( const QPointArray & a, bool winding=FALSE, int index=0, int npoints=-1 )"
Draws the polygon defined by the \fInpoints\fR points in \fIa\fR starting at \fIa[index].\fR
.PP
If \fInpoints\fR is -1 all points until the end of the array are used (i.e. a.size()-index line segments define the polygon).
.PP
The first point is always connected to the last point.
.PP
The polygon is filled with the current brush. If \fIwinding\fR is TRUE, the polygon is filled using the winding fill algorithm. If \fIwinding\fR is FALSE, the polygon is filled using the even-odd (alternative) fill algorithm.
.PP
See also: drawLineSegments() and drawPolyline().