# QPainter Class Reference

The QPainter class paints on paint devices. More...

`#include <qpainter.h>`

List of all member functions.

## Public Members

- QPainter ()
- QPainter ( const QPaintDevice * )
- QPainter ( const QPaintDevice *, const QWidget * )
- ~QPainter ()
- bool begin ( const QPaintDevice * )
- bool begin ( const QPaintDevice *, const QWidget * )
- bool end ()
- QPaintDevice* device () const
- bool isActive () const
- void flush ()
- void save ()
- void restore ()
- QFontMetrics fontMetrics () const
- QFontInfo fontInfo () const
- const QFont& font () const
- void setFont ( const QFont & )
- const QPen& pen () const
- void setPen ( const QPen & )
- void setPen ( PenStyle )
- void setPen ( const QColor & )
- const QBrush& brush () const
- void setBrush ( const QBrush & )
- void setBrush ( BrushStyle )
- void setBrush ( const QColor & )
- const QColor& backgroundColor () const
- void setBackgroundColor ( const QColor & )
- BGMode backgroundMode () const
- void setBackgroundMode ( BGMode )
- RasterOp rasterOp () const
- void setRasterOp ( RasterOp )
- const QPoint& brushOrigin () const
- void setBrushOrigin ( int x, int y )
- void setBrushOrigin ( const QPoint & )
- void setViewXForm ( bool )
- bool hasViewXForm () const
- QRect window () const
- void setWindow ( const QRect & )
- void setWindow ( int x, int y, int w, int h )
- QRect viewport () const
- void setViewport ( const QRect & )
- void setViewport ( int x, int y, int w, int h )
- void setWorldXForm ( bool )
- bool hasWorldXForm () const
- const QWMatrix& worldMatrix () const
- void setWorldMatrix ( const QWMatrix &, bool combine=FALSE )
- void translate ( float dx, float dy )
- void scale ( float sx, float sy )
- void shear ( float sh, float sv )
- void rotate ( float a )
- void resetXForm ()
- QPoint xForm ( const QPoint & ) const
- QRect xForm ( const QRect & ) const
- QPointArray xForm ( const QPointArray & ) const
- QPointArray xForm ( const QPointArray &, int index, int npoints ) const
- QPoint xFormDev ( const QPoint & ) const
- QRect xFormDev ( const QRect & ) const
- QPointArray xFormDev ( const QPointArray & ) const
- QPointArray xFormDev ( const QPointArray &, int index, int npoints ) const
- void setClipping ( bool )
- bool hasClipping () const
- const QRegion& clipRegion () const
- void setClipRect ( const QRect & )
- void setClipRect ( int x, int y, int w, int h )
- void setClipRegion ( const QRegion & )
- void drawPoint ( int x, int y )
- void drawPoint ( const QPoint & )
- void drawPoints ( const QPointArray & a, int index=0, int npoints=-1 )
- void moveTo ( int x, int y )
- void moveTo ( const QPoint & )
- void lineTo ( int x, int y )
- void lineTo ( const QPoint & )
- void drawLine ( int x1, int y1, int x2, int y2 )
- void drawLine ( const QPoint &, const QPoint & )
- void drawRect ( int x, int y, int w, int h )
- void drawRect ( const QRect & )
- void drawWinFocusRect ( int x, int y, int w, int h )
- void drawWinFocusRect ( int x, int y, int w, int h, const QColor & bgColor )
- void drawWinFocusRect ( const QRect & )
- void drawWinFocusRect ( const QRect &, const QColor & bgColor )
- void drawRoundRect ( int x, int y, int w, int h, int, int )
- void drawRoundRect ( const QRect &, int, int )
- void drawEllipse ( int x, int y, int w, int h )
- void drawEllipse ( const QRect & )
- void drawArc ( int x, int y, int w, int h, int a, int alen )
- void drawArc ( const QRect &, int a, int alen )
- void drawPie ( int x, int y, int w, int h, int a, int alen )
- void drawPie ( const QRect &, int a, int alen )
- void drawChord ( int x, int y, int w, int h, int a, int alen )
- void drawChord ( const QRect &, int a, int alen )
- void drawLineSegments ( const QPointArray &, int index=0, int nlines=-1 )
- void drawPolyline ( const QPointArray &, int index=0, int npoints=-1 )
- void drawPolygon ( const QPointArray &, bool winding=FALSE, int index=0, int npoints=-1 )
- void drawQuadBezier ( const QPointArray &, int index=0 )
- void drawPixmap ( int x, int y, const QPixmap &, int sx=0, int sy=0, int sw=-1, int sh=-1 )
- void drawPixmap ( const QPoint &, const QPixmap &, const QRect & sr )
- void drawPixmap ( const QPoint &, const QPixmap & )
- void drawImage ( int x, int y, const QImage &, int sx=0, int sy=0, int sw=-1, int sh=-1 )
- void drawImage ( const QPoint &, const QImage &, const QRect & sr )
- void drawImage ( const QPoint &, const QImage & )
- void drawTiledPixmap ( int x, int y, int w, int h, const QPixmap &, int sx=0, int sy=0 )
- void drawTiledPixmap ( const QRect &, const QPixmap &, const QPoint & )
- void drawTiledPixmap ( const QRect &, const QPixmap & )
- void drawPicture ( const QPicture & )
- void fillRect ( int x, int y, int w, int h, const QBrush & )
- void fillRect ( const QRect &, const QBrush & )
- void eraseRect ( int x, int y, int w, int h )
- void eraseRect ( const QRect & )
- void drawText ( int x, int y, const char * str, int len = -1 )
- void drawText ( const QPoint &, const char * str, int len = -1 )
- void drawText ( int x, int y, int w, int h, int flags, const char * str, int len = -1, QRect * br=0, char ** internal=0 )
- void drawText ( const QRect &, int flags, const char * str, int len = -1, QRect * br=0, char ** internal=0 )
- QRect boundingRect ( int x, int y, int w, int h, int flags, const char * str, int len = -1, char ** intern=0 )
- QRect boundingRect ( const QRect &, int flags, const char * str, int len = -1, char ** intern=0 )
- int tabStops () const
- void setTabStops ( int )
- int* tabArray () const
- void setTabArray ( int * )
- HANDLE handle () const

## Static Public Members

- void redirect ( QPaintDevice * pdev, QPaintDevice * replacement )
- void initialize ()
- void cleanup ()

## Related Functions

(Note that these are not member functions.)

- void qDrawShadeLine (QPainter * p, int x1, int y1, int x2, int y2, const QColorGroup & g, bool sunken, int lineWidth, int midLineWidth)
- void qDrawShadeRect (QPainter * p, int x, int y, int w, int h, const QColorGroup & g, bool sunken, int lineWidth, int midLineWidth, const QBrush * fill)
- void qDrawShadePanel (QPainter * p, int x, int y, int w, int h, const QColorGroup & g, bool sunken, int lineWidth, const QBrush * fill)
- void qDrawWinButton (QPainter * p, int x, int y, int w, int h, const QColorGroup & g, bool sunken, const QBrush * fill)
- void qDrawWinPanel (QPainter * p, int x, int y, int w, int h, const QColorGroup & g, bool sunken, const QBrush * fill)
- void qDrawPlainRect (QPainter * p, int x, int y, int w, int h, const QColor & c, int lineWidth, const QBrush * fill)

## Detailed Description

The QPainter class paints on paint devices.

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.

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.

The typical use of a painter is:

1. Construct a painter.
2. Set a pen, a brush etc.
3. Draw.
4. Destroy the painter.

This example uses a convenience constructor that calls begin(), and relies on the destructor to call end():

        void MyWidget::paintEvent()
        {
            QPainter paint( this );                 // start painting widget
            paint.setPen( blue );                   // set blue pen
            paint.drawText( rect(),                 // draw a text, centered
                            AlignCenter,            //   in the widget
                            "The Text" );
        }

You can also use the begin() and end() functions to begin and end painting explicitly:

        void MyWidget::paintEvent()
        {
            QPainter paint;
            paint.begin( this );                    // start painting widget
            paint.setPen( blue );                   // set blue pen
            paint.drawText( rect(),                 // draw a text, centered
                            AlignCenter,            //   in the widget
                            "The Text" );
            paint.end();                            // painting done
        }

This is useful since it is not possible to have two painters active on the same paint device at a time.

QPainter is almost never used outside paintEvent(). Any widget must 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.

Note that both painters and some paint devices have attributes such as current font, current foreground colors and so on.

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.

Warning: QPainter::begin() resets all attributes to their default values, from the device, thus setting fonts, brushes, etc, before begin() will have no effect.

See also: QPaintDevice, QWidget and QPixmap.

Examples: qtimage/qtimage.cpp tictac/tictac.cpp table/table.cpp life/life.cpp grapher/grapher.cpp forever/forever.cpp desktop/desktop.cpp connect/connect.cpp trivial/trivial.cpp tooltip/tooltip.cpp drawdemo/drawdemo.cpp hello/hello.cpp movies/main.cpp picture/picture.cpp xform/xform.cpp application/application.cpp aclock/aclock.cpp progress/progress.cpp qmag/qmag.cpp showimg/showimg.cpp

## Member Function Documentation

### QPainter::QPainter ()

Constructs a painter.

Notice that all painter settings (setPen,setBrush etc.) are reset to default values when begin() is called.

See also: begin() and end().

### QPainter::QPainter ( const QPaintDevice * pd )

Constructs a painter that begins painting the paint device pd immediately.

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().

Example using begin() and end():

        void MyWidget::paintEvent( QPaintEvent * )
        {
            QPainter p( this );
            p.drawLine( ... );      // drawing code
        }

Example using this constructor:

        void MyWidget::paintEvent( QPaintEvent * )
        {
            QPainter p( this );
            p.drawLine( ... );      // drawing code
        }

See also: begin() and end().

### QPainter::QPainter ( const QPaintDevice * pd, const QWidget * copyAttributes )

Constructs a painter that begins painting the paint device pd immediately, with the default arguments taken from copyAttributes.

See also: begin().

### QPainter::~QPainter ()

Destroys the painter.

If you called begin() but not end(), the destructor outputs a warning message. Note that there is no need to call end() if you used one of the constructors which takes a paint device argument.

### const QColor & QPainter::backgroundColor () const

Returns the background color currently set.

See also: setBackgroundColor().

### BGMode QPainter::backgroundMode () const

Returns the background mode currently set.

See also: setBackgroundMode().

### bool QPainter::begin ( const QPaintDevice * pd )

Begins painting the paint device pd and returns TRUE if successful, or FALSE if it cannot begin painting. Call end() when you have finished painting.

On the X Window System, paint commands are buffered and may not appear on the screen immediately. The flush() function flushes the buffer.

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.

This function initializes all painter settings:

- The font is set to the default application font, or to the widget's font if pd is a widget.
- The pen is set to QPen(black,0,SolidLine), or to QPen(widget->foreground(), 0,SolidLine) if pd is a widget.
- The brush is set to QBrush(NoBrush).
- The background color is set to white, or to the widget's background color if pd is a widget.
- The background mode is set to `TransparentMode.`
- The raster operation is set to `CopyROP.`
- The brush origin is set to (0,0).
- The view transformation setting is turned off.
- The window is set to the paint device rectangle; (0,0,pd->width(),pd->height()).
- The viewport is set to the paint device rectangle; (0,0,pd->width(),pd->height()).
- The world transformation setting is turned off.
- The world matrix is set to the identify matrix.
- Clipping is disabled.
- The clip region is set to an empty region.

Warning: A paint device can only be painted by one painter at a time.

See also: end(), flush(), setFont(), setPen(), setBrush(), setBackgroundColor(), setBackgroundMode(), setRasterOp(), setBrushOrigin(), setViewXForm(), setWindow(), setViewport(), setWorldXForm(), setWorldMatrix() and setClipRegion().

Examples: desktop/desktop.cpp hello/hello.cpp picture/picture.cpp application/application.cpp

### 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.

This version opens the painter on a paint device pd and sets the initial pen, background color and font from copyAttributes. This is equivalent with:

        QPainter p;
        p.begin( pd );
        p.setPen( copyAttributes->foregroundColor() );
        p.setBackgroundColor( copyAttributes->backgroundColor() );
        p.setFont( copyAttributes->font() );

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.

Example:

        void MyWidget::paintEvent( QPaintEvent * )
        {
            QPixmap pm(rect());
            QPainter p;
            p.begin(&pm, this);
            // ... potential flickering paint operation ...
            p.end();
            bitBlt(this, 0, 0, &pm);
        }

See also: end().

### QRect QPainter::boundingRect ( int x, int y, int w, int h, int tf, const char * 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 len characters from str). The drawing, and hence the bounding rectangle, is constrained to the rectangle (x,y,w,h).

The tf text formatting is the bitwise OR of the following flags:

- `AlignLeft` aligns to the left border.
- `AlignRight` aligns to the right border.
- `AlignHCenter` aligns horizontally centered.
- `AlignTop` aligns to the top border.
- `AlignBottom` aligns to the bottom border.
- `AlignVCenter` aligns vertically centered
- `AlignCenter` (= `AlignHCenter` | `AlignVCenter)`
- `SingleLine` ignores newline characters in the text.
- `ExpandTabs` expands tabulators.
- `ShowPrefix` displays "&x" as "x" underlined.
- `WordBreak` breaks the text to fit the rectangle.

These flags are defined in qwindowdefs.h.

See also: drawText() and fontMetrics().

### QRect QPainter::boundingRect ( const QRect & r, int tf,const char * str, 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.

### const QBrush & QPainter::brush () const

Returns the current painter brush.

See also: QPainter::setBrush().

### const QPoint & QPainter::brushOrigin () const

Returns the brush origin currently set.

See also: setBrushOrigin().

### void QPainter::cleanup () `[static]`

Internal function that cleans up the painter.

### const QRegion & QPainter::clipRegion () const

Returns the clip region currently set. Note that the clip region is given in physical device coordinates and not subject to any coordinate transformation.

See also: setClipRegion(), setClipRect() and setClipping().

### QPaintDevice * QPainter::device () const

Returns the paint device currently active for this painter, or null if begin() has not been called.

See also: QPaintDevice::paintingActive().

### void QPainter::drawArc ( int x, int y, int w, int h, int a, int alen )

Draws an arc defined by the rectangle (x,y,w,h), the start angle a and the arc length alen.

The angles a and alen are 1/16th of a degree, i.e. a full circle equals 5760 (16*360). Positive values of a and alen mean counter-clockwise while negative values mean clockwise direction. Zero degrees is at the 3'o clock position.

Example:

        QPainter p;
        p.begin( myWidget );
        p.drawArc( 10,10, 70,100, 100*16, 160*16 ); // draws a "(" arc
        p.end();

See also: drawPie() and drawChord().

### 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.

### void QPainter::drawChord ( int x, int y, int w, int h, int a, int alen )

Draws a chord defined by the rectangle (x,y,w,h), the start angle a and the arc length alen.

The chord is filled with the current brush.

The angles a and alen are 1/16th of a degree, i.e. a full circle equals 5760 (16*360). Positive values of a and alen mean counter-clockwise while negative values mean clockwise direction. Zero degrees is at the 3'o clock position.

See also: drawArc() and drawPie().

### 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.

### void QPainter::drawEllipse ( int x, int y, int w, int h )

Draws an ellipse with center at (x+w/2,y+h/2) and size (w,h).

Examples: drawdemo/drawdemo.cpp picture/picture.cpp

### 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.

### void QPainter::drawImage ( int x, int y, const QImage & image, int sx=0, int sy=0, int sw=-1, int sh=-1 )

Draws at (x, y) the sw by sh area of pixels from (sx, sy) in image.

This function simply converts image to a QPixmap and draws it.

See also: drawPixmap() and QPixmap::convertFromImage().

### 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.

### 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.

### void QPainter::drawLine ( int x1, int y1, int x2, int y2 )

Draws a line from (x1,y2) to (x2,y2). Both endpoints are drawn.

See also: moveTo() and lineTo().

Examples: table/table.cpp grapher/grapher.cpp connect/connect.cpp aclock/aclock.cpp progress/progress.cpp

### 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.

### void QPainter::drawLineSegments ( const QPointArray & a, int index=0, int nlines=-1 )

Draws nlines separate lines from points defined in a, starting at a[index]. If nlines is -1 all points until the end of the array are used (i.e. (a.size()-index)/2 lines are drawn).

Draws the 1st line from a[index] to a[index+1]. Draws the 2nd line from a[index+2] to a[index+3] etc.

See also: drawPolyline() and drawPolygon().

### void QPainter::drawPicture ( const QPicture & pic )

Replays the picture pic.

This function does exactly the same as QPicture::play().

Examples: picture/picture.cpp

### void QPainter::drawPie ( int x, int y, int w, int h, int a, int alen )

Draws a pie defined by the rectangle (x,y,w,h), the start angle a and the arc length alen.

The pie is filled with the current brush.

The angles a and alen are 1/16th of a degree, i.e. a full circle equals 5760 (16*360). Positive values of a and alen mean counter-clockwise while negative values mean clockwise direction. Zero degrees is at the 3'o clock position.

See also: drawArc() and drawPie().

Examples: grapher/grapher.cpp drawdemo/drawdemo.cpp

### 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.

### 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 (x,y) by copying a part of the pixmap into the paint device.

Arguments:

- (x,y) specify the point in the paint device.
- (sx,sy) specify an offset in the pixmap.
- (sw,sh) 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.

See also: bitBlt() and QPixmap::setMask().

Examples: qtimage/qtimage.cpp grapher/grapher.cpp movies/main.cpp picture/picture.cpp qmag/qmag.cpp showimg/showimg.cpp

### 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.

This version of the call draws the entire pixmap.

### 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.

### void QPainter::drawPoint ( int x, int y )

Draws/plots a single point at (x,y) using the current pen.

Examples: desktop/desktop.cpp connect/connect.cpp

### 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.

### void QPainter::drawPoints ( const QPointArray & a, int index=0, int npoints=-1 )

Draws/plots an array of points using the current pen. The index and npoints arguments allow a subsequence of the array to be drawn.

### void QPainter::drawPolygon ( const QPointArray & a, bool winding=FALSE, int index=0, int npoints=-1 )

Draws the polygon defined by the npoints points in a starting at a[index].

If npoints is -1 all points until the end of the array are used (i.e. a.size()-index line segments define the polygon).

The first point is always connected to the last point.

The polygon is filled with the current brush. If winding is TRUE, the polygon is filled using the winding fill algorithm. If winding is FALSE, the polygon is filled using the even-odd (alternative) fill algorithm.

See also: drawLineSegments() and drawPolyline().

Examples: desktop/desktop.cpp picture/picture.cpp aclock/aclock.cpp

### void QPainter::drawPolyline ( const QPointArray & a, int index=0, int npoints=-1 )

Draws the polyline defined by the npoints points in a starting at a[index].

If npoints is -1 all points until the end of the array are used (i.e. a.size()-index-1 line segments are drawn).

See also: drawLineSegments() and drawPolygon().

Examples: drawdemo/drawdemo.cpp

### void QPainter::drawQuadBezier ( const QPointArray & a, int index=0 )

Draws a cubic Bezier curve defined by the control points in a, starting at a[index].

a must have 4 points or more. The control point a[index+4] and beyond are ignored.

### void QPainter::drawRect ( int x, int y, int w, int h )

Draws a rectangle with upper left corner at (x,y) and with width w and height h.

See also: drawRoundRect().

Examples: table/table.cpp grapher/grapher.cpp forever/forever.cpp trivial/trivial.cpp tooltip/tooltip.cpp drawdemo/drawdemo.cpp picture/picture.cpp

### void QPainter::drawRect ( 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.

### void QPainter::drawRoundRect ( int x, int y, int w, int h, int xRnd, int yRnd )

Draws a rectangle with round corners at (x,y), with width w and height h.

The xRnd and yRnd arguments specify how rounded the corners should be. 0 is angled corners, 99 is maximum roundedness.

The width and height include both lines.

See also: drawRect().

Examples: drawdemo/drawdemo.cpp

### void QPainter::drawRoundRect ( const QRect & r, int xRnd, int yRnd )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

### void QPainter::drawText ( int x, int y, const char * str, int len = -1 )

Draws at most len characters from str at position (x,y).

(x,y) is the base line position. Note that the meaning of y is not the same for the two drawText() varieties.

Examples: table/table.cpp grapher/grapher.cpp desktop/desktop.cpp trivial/trivial.cpp drawdemo/drawdemo.cpp hello/hello.cpp movies/main.cpp picture/picture.cpp application/application.cpp progress/progress.cpp

### void QPainter::drawText ( int x, int y, int w, int h, int tf, const char * str, int len = -1, QRect * brect=0, char ** internal=0 )

Draws at most len characters from str in the rectangle (x,y,w,h).

Note that the meaning of y is not the same for the two drawText() varieties.

This function draws formatted text. The tf text formatting is the bitwise OR of the following flags:

- `AlignLeft` aligns to the left border.
- `AlignRight` aligns to the right border.
- `AlignHCenter` aligns horizontally centered.
- `AlignTop` aligns to the top border.
- `AlignBottom` aligns to the bottom border.
- `AlignVCenter` aligns vertically centered
- `AlignCenter` (= `AlignHCenter` | AlignVCenter)
- `SingleLine` ignores newline characters in the text.
- `DontClip` never clips the text to the rectangle.
- `ExpandTabs` expands tabulators.
- `ShowPrefix` displays "&x" as "x" underlined.
- `WordBreak` breaks the text to fit the rectangle.
- `GrayText` grays out the text.

Horizontal alignment defaults to AlignLeft and vertical alignment defaults to AlignTop.

If several of the horizontal or several of the vertical alignment flags are set, the resulting alignment is undefined.

If ExpandTabs is set and no tab stops or tab array have been set tabs will expand to the closest reasonable tab stop based on the current font. For fixed pitch (fixed width) fonts you are guaranteed that each tab stop will be at a multiple of eight of the width of the characters in the font.

brect (if non-null) is set to the actual bounding rectangle of the output. internal is, yes, internal.

These flags are defined in qwindowdefs.h.

See also: boundingRect().

### void QPainter::drawText ( const QPoint & p, const char * s, int len = -1 )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

### void QPainter::drawText ( const QRect & r, int tf, const char * str, int len = -1, QRect * br=0, 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.

### void QPainter::drawTiledPixmap ( int x, int y, int w, int h, const QPixmap & pixmap, int sx=0, int sy=0 )

Draws a tiled pixmap in the specified rectangle.

Arguments:

- (x,y,w,h) is the rectangle to be filled.
- (sx,sy) spefify an offset in the pixmap.

The pixmap is clipped if a mask has been set.

Calling drawTiledPixmap() is similar to calling drawPixmap() several times to fill (tile) an area with a pixmap.

See also: drawPixmap().

### void QPainter::drawTiledPixmap ( const QRect & r, 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.

### void QPainter::drawTiledPixmap ( const QRect & r, const QPixmap & pm, const QPoint & sp )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

### void QPainter::drawWinFocusRect ( int x, int y, int w, int h )

Draws a Windows focus rectangle with upper left corner at (x,y) and with width w and height h.

This function draws a stippled XOR rectangle that is used to indicate keyboard focus (when the GUI style is `WindowStyle).`

Warning: This function draws nothing if the coordinate system has been rotated or sheared.

See also: drawRect() and QApplication::style().

### void QPainter::drawWinFocusRect ( int x, int y, int w, int h, const QColor & bgColor )

Draws a Windows focus rectangle with upper left corner at (x,y) and with width w and height h using a pen color that contrasts with bgColor.

This function draws a stippled rectangle (XOR is not used) that is used to indicate keyboard focus (when the GUI style is `WindowStyle).`

The pen color used to draw the rectangle is either white or black depending on the grayness of bgColor (see QColor::gray()).

Warning: This function draws nothing if the coordinate system has been rotated or sheared.

See also: drawRect() and QApplication::style().

### void QPainter::drawWinFocusRect ( 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.

### void QPainter::drawWinFocusRect ( const QRect & r, const QColor & bgColor )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

### bool QPainter::end ()

Ends painting. Any resources used while painting are released.

See also: begin().

Examples: desktop/desktop.cpp hello/hello.cpp picture/picture.cpp application/application.cpp

### void QPainter::eraseRect ( int x, int y, int w, int h )

Erases the area inside (x,y,w,h). Equivalent to `fillRect( x, y, w, h, backgroundColor() )`

Examples: life/life.cpp showimg/showimg.cpp

### void QPainter::eraseRect ( 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.

### void QPainter::fillRect ( int x, int y, int w, int h, const QBrush & brush )

Fills the rectangle (x,y,w,h) with the brush.

You can specify a QColor as brush, since there is a QBrush constructor that takes a QColor argument and creates a solid pattern brush.

See also: drawRect().

Examples: progress/progress.cpp

### void QPainter::fillRect ( const QRect & r, const QBrush & brush )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

### void QPainter::flush ()

Flushes any buffered drawing operations.

### const QFont & QPainter::font () const

Returns the current painter font.

See also: setFont() and QFont.

### QFontInfo QPainter::fontInfo () const

Returns the font info for the painter. Font info can only be obtained when the painter is active.

See also: fontMetrics() and isActive().

### QFontMetrics QPainter::fontMetrics () const

Returns the font metrics for the painter. Font metrics can only be obtained when the painter is active.

See also: fontInfo() and isActive().

Examples: desktop/desktop.cpp drawdemo/drawdemo.cpp movies/main.cpp application/application.cpp

### HANDLE QPainter::handle () const

Returns the platform-dependent handle used for drawing.

### bool QPainter::hasClipping () const

Returns TRUE if clipping has been set, otherwise FALSE.

See also: setClipping().

### bool QPainter::hasViewXForm () const

Returns TRUE if view transformation is enabled, otherwise FALSE.

See also: setViewXForm() and xForm().

### bool QPainter::hasWorldXForm () const

Returns TRUE if world transformation is enabled, otherwise FALSE.

See also: setWorldXForm().

### void QPainter::initialize () `[static]`

Internal function that initializes the painter.

### bool QPainter::isActive () const

Returns the TRUE if the painter is active painting, i.e. begin() has been called and end() has not yet been called.

See also: QPaintDevice::paintingActive().

Examples: desktop/desktop.cpp

### void QPainter::lineTo ( int x, int y )

Draws a line from the current point to (x,y) and sets this to the new current point. Both endpoints are are drawn.

See also: moveTo() and drawLine().

### void QPainter::lineTo ( 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.

### void QPainter::moveTo ( int x, int y )

Sets the current point.

See also: lineTo() and drawLine().

### void QPainter::moveTo ( 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.

### const QPen & QPainter::pen () const

Returns the current pen for the painter.

See also: setPen().

Examples: progress/progress.cpp

### RasterOp QPainter::rasterOp () const

Returns the raster operation currently set.

See also: setRasterOp().

### void QPainter::redirect ( QPaintDevice * pdev, QPaintDevice * replacement ) `[static]`

Redirects all paint command for a paint device pdev to another paint device replacement.

A redirected paint device is reset if replacement is 0.

The following example redirects painting of a widget to a pixmap:

        QPixmap pm( myWidget->width(), myWidget->height() );
        pm.fill( myWidget->backgroundColor() );
        QPainter::redirect( myWidget, &pm );
        myWidget->repaint( FALSE );
        QPainter::redirect( myWidget, 0 );

### void QPainter::resetXForm ()

Resets any transformations that were made using translate(), scale(), shear(), rotate(), setWorldMatrix(), setViewport() and setWindow()

See also: worldMatrix(), viewPort() and window().

### void QPainter::restore ()

Restores the current painter state (pops a saved state off the stack).

See also: save().

### void QPainter::rotate ( float a )

Rotates the coordinate system a degrees.

See also: translate(), scale(), shear(), resetXForm(), setWorldMatrix() and xForm().

### void QPainter::save ()

Saves the current painter state (pushes the state onto a stack).

A save() must have a corresponding restore().

See also: restore().

### void QPainter::scale ( float sx, float sy )

Scales the coordinate system by (sx,sy).

See also: translate(), shear(), rotate(), resetXForm(), setWorldMatrix() and xForm().

### void QPainter::setBackgroundColor ( const QColor & c )

Sets the background color of the painter to c.

The background color is the color that is filled in when drawing opaque text, stippled lines and bitmaps. The background color has no effect when transparent background mode is set.

See also: backgroundColor() and setBackgroundMode().

### void QPainter::setBackgroundMode ( BGMode m )

Sets the background mode of the painter to m, which must be one of:

- `TransparentMode` (default)
- `OpaqueMode`

Transparent mode draws stippled lines and text without setting the background pixels. Opaque mode fills these space with the current background color.

In order to draw a bitmap or pixmap transparently, you must use QPixmap::setMask().

See also: backgroundMode() and setBackgroundColor().

Examples: picture/picture.cpp

### void QPainter::setBrush ( BrushStyle style )

Sets a new painter brush with black color and the specified style.

See also: brush() and QBrush.

### void QPainter::setBrush ( const QBrush & brush )

Sets a new painter brush.

The brush defines how to fill shapes.

See also: brush().

Examples: grapher/grapher.cpp forever/forever.cpp desktop/desktop.cpp tooltip/tooltip.cpp drawdemo/drawdemo.cpp picture/picture.cpp aclock/aclock.cpp

### void QPainter::setBrush ( const QColor & color )

Sets a new painter brush with the style `SolidPattern` and the specified color.

See also: brush() and QBrush.

### void QPainter::setBrushOrigin ( int x, int y )

Sets the brush origin to (x,y).

The brush origin specifies the (0,0) coordinate of the painter's brush. This setting is only necessary for pattern brushes or pixmap brushes.

See also: brushOrigin().

### void QPainter::setBrushOrigin ( 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.

### void QPainter::setClipRect ( int x, int y, int w, int h )

Sets the clip region to (x,y,w,h) and enables clipping.

Note that the clip rectangle is given in physical device coordinates and not subject to any coordinate transformation.

See also: setClipRegion(), clipRegion() and setClipping().

Examples: qtimage/qtimage.cpp grapher/grapher.cpp trivial/trivial.cpp progress/progress.cpp showimg/showimg.cpp

### void QPainter::setClipRect ( 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.

### void QPainter::setClipRegion ( const QRegion & rgn )

Sets the clip region to rgn and enables clipping.

Note that the clip region is given in physical device coordinates and not subject to any coordinate transformation.

See also: setClipRect(), clipRegion() and setClipping().

### void QPainter::setClipping ( bool enable )

Enables clipping if enable is TRUE, or disables clipping if enable is FALSE.

See also: hasClipping(), setClipRect() and setClipRegion().

### void QPainter::setFont ( const QFont & font )

Sets a new painter font.

This font is used by all subsequent drawText() functions. The text color is the same as the pen color.

See also: font() and drawText().

Examples: grapher/grapher.cpp drawdemo/drawdemo.cpp hello/hello.cpp movies/main.cpp picture/picture.cpp application/application.cpp

### void QPainter::setPen ( PenStyle style )

Sets a new painter pen with style `style,` width 0 and black color.

See also: pen() and QPen.

### void QPainter::setPen ( const QColor & color )

Sets a new painter pen with style `SolidLine,` width 0 and the specified color.

See also: pen() and QPen.

### void QPainter::setPen ( const QPen & pen )

Sets a new painter pen.

The pen defines how to draw lines and outlines, and it also defines the text color.

See also: pen().

Examples: table/table.cpp grapher/grapher.cpp forever/forever.cpp desktop/desktop.cpp connect/connect.cpp drawdemo/drawdemo.cpp hello/hello.cpp movies/main.cpp progress/progress.cpp

### void QPainter::setRasterOp ( RasterOp r )

Sets the raster operation to r.

The r parameter must be one of:

- `CopyROP:` dst = src.
- `OrROP:` dst = dst OR src.
- `XorROP:` dst = dst XOR src.
- `EraseROP:` dst = (NOT src) AND dst
- `NotCopyROP:` dst = NOT src
- `NotOrROP:` dst = (NOT src) OR dst
- `NotXorROP:` dst = (NOT src) XOR dst
- `NotEraseROP:` dst = src AND dst
- `NotROP:` dst = NOT dst

See also: rasterOp().

### void QPainter::setTabArray ( int * ta )

Set an array containing the tab stops.

Tab stops are used when drawing formatted text with `ExpandTabs` set.

The last tab stop must be 0 (terminates the array).

Notice that setting a tab array overrides any fixed tabulator stop that is set using setTabStops().

See also: tabArray(), setTabStops(), drawText() and fontMetrics().

### void QPainter::setTabStops ( int ts )

Set the number of pixels per tab stop to a fixed number.

Tab stops are used when drawing formatted text with `ExpandTabs` set. This fixed tab stop value has lower precedence than tab array settings.

See also: tabStops(), setTabArray(), drawText() and fontMetrics().

### void QPainter::setViewXForm ( bool enable )

Enables view transformations if enable is TRUE, or disables view transformations if enable is FALSE.

See also: hasViewXForm(), setWindow(), setViewport(), setWorldMatrix(), setWorldXForm() and xForm().

### void QPainter::setViewport ( int x, int y, int w, int h )

Sets the viewport rectangle view transformation for the painter and enables view transformation.

The viewport rectangle is part of the view transformation. The viewport specifies the device coordinate system.

The viewport and the window are initially set to (0,0,width,height), where (width,height) is the pixel size of the paint device.

You can use this method to normalize the coordinate system of the painter when drawing on a part of a paint device. The following example will draw a line from the top left to the bottom right corner of a page, excluding margins:

          QPrinter page;
          int margin, pageWidth, pageHeight;
          ...
          QPainter p( page );
          p.setViewPort( margin, margin, pageWidth - margin, pageHeight - margin );
          p.drawLine( 0, 0, pageWidth - 2*margin, pageHeight - 2*margin );

The setViewPort() method is often used in conjunction with setWindow(), as in this example:

          QPainter p( myWidget );
          p.setWindow( 0, 0, 1000, 2000 );
          p.setViewport( 100,100, 200,200 );
          p.drawPoint( 500, 500 );                  // draws pixel at (150,125)

The preceding example sets up a transformation that maps the logical coordinates (0,0,1000,2000) into a (200,200) rectangle at (100,100).

View transformations can be combined with world transformations. World transformations are applied after the view transformations.

See also: viewport(), setWindow(), setViewXForm(), setWorldMatrix(), setWorldXForm() and xForm().

### void QPainter::setViewport ( 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.

### void QPainter::setWindow ( int x, int y, int w, int h )

Sets the window rectangle view transformation for the painter and enables view transformation.

The window rectangle is part of the view transformation. The window specifies the logical coordinate system.

The window and the viewport are initially set to (0,0,width,height), where (width,height) is the pixel size of the paint device.

You can use this method to normalize the coordinate system of the painter. The following example will draw a vertical line, from top to bottom, at the center of a pixmap, independent of the size of the pixmap:

          int width, height;
          ...
          QPixmap icon( width, height );
          QPainter p( icon );
          p.setWindow( 0, 0, 100, 100 );
          p.drawLine( 50, 0, 50, 100 );             // draw center line

The setWindow() method is often used in conjunction with setViewport(), as in this example:

          QPainter p( myWidget );
          p.setWindow( 0, 0, 1000, 2000 );
          p.setViewport( 100,100, 200,200 );
          p.drawPoint( 500, 500 );                  // draws pixel at (150,125)

The preceding example sets up a transformation that maps the logical coordinates (0,0,1000,2000) into a (200,200) rectangle at (100,100).

View transformations can be combined with world transformations. World transformations are applied after the view transformations.

See also: window(), setViewport(), setViewXForm(), setWorldMatrix() and setWorldXForm().

Examples: forever/forever.cpp drawdemo/drawdemo.cpp

### void QPainter::setWindow ( 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.

### void QPainter::setWorldMatrix ( const QWMatrix & m, bool combine=FALSE )

Sets the world transformation matrix to m and enables world transformation.

If combine is TRUE, then m is combined with the current transformation matrix, otherwise m will replace the current transformation matrix.

World transformations are applied after the view transformations (i.e. window and viewport).

If the matrix set is the identity matrix (m11 and m22 are 1.0 and the rest are 0.0), this function calls setWorldXForm(FALSE).

The following functions can transform the coordinate system without using a QWMatrix:

- translate()
- scale()
- shear()
- rotate()

They operate on the painter's world matrix and are implemented like this:

        void QPainter::rotate( float a )
        {
            wxmat.rotate( a );
            setWorldMatrix( wxmat );
        }

See the QWMatrix documentation for a general discussion on coordinate system transformations.

See also: worldMatrix(), setWorldXForm(), setWindow(), setViewport(), setViewXForm() and xForm().

Examples: drawdemo/drawdemo.cpp aclock/aclock.cpp

### void QPainter::setWorldXForm ( bool enable )

Enables world transformations if enable is TRUE, or disables world transformations if enable is FALSE.

See also: setWorldMatrix(), setWindow(), setViewport(), setViewXForm() and xForm().

### void QPainter::shear ( float sh, float sv )

Shears the coordinate system (sh,sv).

See also: translate(), scale(), rotate(), resetXForm(), setWorldMatrix() and xForm().

### int * QPainter::tabArray () const

Returns the tab stop array currently set.

See also: setTabArray().

### int QPainter::tabStops () const

Returns the tab stop setting.

See also: setTabStops().

### void QPainter::translate ( float dx, float dy )

Translates the coordinate system by (dx,dy).

For example, the following code draws a single vertical line 20 pixels high.

        void MyWidget::paintEvent()
        {
            QPainter paint( this );
            paint.drawLine(10,0,10,20);
            paint.translate(100.0,100.0);
            paint.drawLine(-90,-80,-90,-70);
        }

See also: scale(), shear(), rotate(), resetXForm(), setWorldMatrix() and xForm().

### QRect QPainter::viewport () const

Returns the viewport rectangle.

See also: setViewport() and setViewXForm().

### QRect QPainter::window () const

Returns the window rectangle.

See also: setWindow() and setViewXForm().

### const QWMatrix & QPainter::worldMatrix () const

Returns the world transformation matrix.

See also: setWorldMatrix().

### QPoint QPainter::xForm ( const QPoint & pv ) const

Returns the point pv transformed from user coordinates to device coordinates.

See also: xFormDev() and QWMatrix::xForm().

### QPointArray QPainter::xForm ( const QPointArray & av ) const

Returns the point array av transformed from user coordinates to device coordinates.

See also: xFormDev() and QWMatrix::xForm().

### QPointArray QPainter::xForm ( const QPointArray & av, int index, int npoints ) const

Returns the point array av transformed from user coordinates to device coordinates. The index is the first point in the array and npoints denotes the number of points to be transformed. If npoints is negative, all points from av[index] until the last point in the array are transformed.

The returned point array consists of the number of points that were transformed.

Example:

        QPointArray a(10);
        QPointArray b;
        b = painter.xForm(a,2,4);   // b.size() == 4
        b = painter.xForm(a,2,-1);  // b.size() == 8

See also: xFormDev() and QWMatrix::xForm().

### QRect QPainter::xForm ( const QRect & rv ) const

Returns the rectangle rv transformed from user coordinates to device coordinates.

If world transformation is enabled and rotation or shearing has been specified, then the bounding rectangle is returned.

See also: xFormDev() and QWMatrix::xForm().

### QPoint QPainter::xFormDev ( const QPoint & pd ) const

Returns the point pv transformed from device coordinates to user coordinates.

See also: xForm() and QWMatrix::xForm().

### QPointArray QPainter::xFormDev ( const QPointArray & ad ) const

Returns the point array av transformed from device coordinates to user coordinates.

See also: xForm() and QWMatrix::xForm().

### QPointArray QPainter::xFormDev ( const QPointArray & ad, int index, int npoints ) const

Returns the point array ad transformed from device coordinates to user coordinates. The index is the first point in the array and npoints denotes the number of points to be transformed. If npoints is negative, all points from av[index] until the last point in the array are transformed.

The returned point array consists of the number of points that were transformed.

Example:

        QPointArray a(10);
        QPointArray b;
        b = painter.xFormDev(a,1,3);        // b.size() == 3
        b = painter.xFormDev(a,1,-1);       // b.size() == 9

See also: xForm() and QWMatrix::xForm().

### QRect QPainter::xFormDev ( const QRect & rd ) const

Returns the rectangle rv transformed from device coordinates to user coordinates.

If world transformation is enabled and rotation or shearing is used, then the bounding rectangle is returned.

See also: xForm() and QWMatrix::xForm().

## Related Functions

### void qDrawShadeLine (QPainter * p, int x1, int y1, int x2, int y2, const QColorGroup & g, bool sunken, int lineWidth, int midLineWidth)

Draws a horizontal (y1 == y2) or vertical (x1 == x2) shaded line using the painter p.

Nothing is drawn if y1 != y2 and x1 != x2 (i.e. the line is neither horizontal nor vertical).

The color group argument g specifies the shading colors (light, dark and middle colors).

The line appears sunken if sunken is TRUE, or raised if sunken is FALSE.

The lineWidth argument specifies the line width for each of the lines. It is not the total line width.

The midLineWidth argument specifies the width of a middle line drawn in the QColorGroup::mid() color.

If you want to use a QFrame widget instead, you can make it display a shaded line, for example `QFrame::setFrameStyle( QFrame::HLine | QFrame::Sunken )`.

See also: qDrawShadeRect() and qDrawShadePanel().

### void qDrawShadeRect (QPainter * p, int x, int y, int w, int h, const QColorGroup & g, bool sunken, int lineWidth, int midLineWidth, const QBrush * fill)

Draws a shaded rectangle/box given by (x,y,w,h) using the painter p.

The color group argument g specifies the shading colors (light, dark and middle colors).

The rectangle appears sunken if sunken is TRUE, or raised if sunken is FALSE.

The lineWidth argument specifies the line width for each of the lines. It is not the total line width.

The midLineWidth argument specifies the width of a middle line drawn in the QColorGroup::mid() color.

The rectangle interior is filled with the *fill brush unless fill is null.

If you want to use a QFrame widget instead, you can make it display a shaded rectangle, for example `QFrame::setFrameStyle( QFrame::Box | QFrame::Raised )`.

See also: qDrawShadeLine(), qDrawShadePanel() and qDrawPlainRect().

### void qDrawShadePanel (QPainter * p, int x, int y, int w, int h, const QColorGroup & g, bool sunken, int lineWidth, const QBrush * fill)

Draws a shaded panel given by (x,y,w,h) using the painter p.

The color group argument g specifies the shading colors (light, dark and middle colors).

The panel appears sunken if sunken is TRUE, or raised if sunken is FALSE.

The lineWidth argument specifies the line width.

The panel interior is filled with the *fill brush unless fill is null.

If you want to use a QFrame widget instead, you can make it display a shaded panel, for example `QFrame::setFrameStyle( QFrame::Panel | QFrame::Sunken )`.

See also: qDrawWinPanel(), qDrawShadeLine() and qDrawShadeRect().

Examples: tictac/tictac.cpp life/life.cpp

### void qDrawWinButton (QPainter * p, int x, int y, int w, int h, const QColorGroup & g, bool sunken, const QBrush * fill)

Draws a Windows-style button given by (x,y,w,h) using the painter p.

The color group argument g specifies the shading colors (light, dark and middle colors).

The button appears sunken if sunken is TRUE, or raised if sunken is FALSE.

The line width is 2 pixels.

The button interior is filled with the *fill brush unless fill is null.

See also: qDrawWinPanel().

### void qDrawWinPanel (QPainter * p, int x, int y, int w, int h, const QColorGroup & g, bool sunken, const QBrush * fill)

Draws a Windows-style panel given by (x,y,w,h) using the painter p.

The color group argument g specifies the shading colors.

The panel appears sunken if sunken is TRUE, or raised if sunken is FALSE.

The line width is 2 pixels.

The button interior is filled with the *fill brush unless fill is null.

If you want to use a QFrame widget instead, you can make it display a shaded panel, for example `QFrame::setFrameStyle( QFrame::WinPanel | QFrame::Raised )`.

See also: qDrawShadePanel() and qDrawWinButton().

### void qDrawPlainRect (QPainter * p, int x, int y, int w, int h, const QColor & c, int lineWidth, const QBrush * fill)

Draws a plain rectangle given by (x,y,w,h) using the painter p.

The color argument c specifies the line color.

The lineWidth argument specifies the line width.

The rectangle interior is filled with the *fill brush unless fill is null.

If you want to use a QFrame widget instead, you can make it display a shaded rectangle, for example `QFrame::setFrameStyle( QFrame::Box | QFrame::Plain )`.

See also: qDrawShadeRect().

Search the documentation, FAQ, qt-interest archive and more (uses www.troll.no):

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

It was generated from the following files:

- qpainter.h: 1998/08/21
- qpainter.cpp: 1998/12/15