QPainter

NAME

SYNOPSIS

Inherits Qt.

Inherited by QDirectPainter.

Public Members

Static Public Members

RELATED FUNCTION DOCUMENTATION

DESCRIPTION

The painter provides highly optimized functions to do most of the drawing GUI programs require. QPainter can draw everything from simple lines to complex shapes like pies and chords. It can also draw aligned text and pixmaps. Normally, it draws in a "natural" coordinate system, but it can also do view and world transformation.

The typical use of a painter is:

Construct a painter.

Set a pen, a brush etc.

Draw.

Destroy the painter.

Mostly, all this is done inside a paint event. (In fact, 99% of all QPainter use is in a reimplementation of QWidget::paintEvent(), and the painter is heavily optimized for such use.) Here's one very simple example:

    void SimpleExampleWidget::paintEvent()


    {


        QPainter paint( this );


        paint.setPen( Qt::blue );


        paint.drawText( rect(), AlignCenter, "The Text" );


    }

Usage is simple, and there are many settings you can use:

font() is the currently set font. If you set a font that isn't available, Qt finds a close match. In fact font() returns what you set using setFont() and fontInfo() returns the font actually being used (which may be the same).

brush() is the currently set brush; the color or pattern that's used for filling e.g. circles.

pen() is the currently set pen; the color or stipple that's used for drawing lines or boundaries.

backgroundMode() is Opaque or Transparent, i.e. whether backgroundColor() is used or not.

backgroundColor() only applies when backgroundMode() is Opaque and pen() is a stipple. In that case, it describes the color of the background pixels in the stipple.

rasterOp() is how pixels drawn interact with the pixels already there.

brushOrigin() is the origin of the tiled brushes, normally the origin of the window.

viewport(), window(), worldMatrix() and many more make up the painter's coordinate transformation system. See The Coordinate System for an explanation of this, or see below for a very brief overview of the functions.

hasClipping() is whether the painter clips at all. (The paint device clips, too.) If the painter clips, it clips to clipRegion().

pos() is the current position, set by moveTo() and used by lineTo().

Note that some of these settings mirror settings in some paint devices, e.g. QWidget::font(). QPainter::begin() (or the QPainter constructor) copies these attributes from the paint device. Calling, for example, QWidget::setFont() doesn't take effect until the next time a painter begins painting on it.

save() saves all of these settings on an internal stack, restore() pops them back.

The core functionality of QPainter is drawing, and there are functions to draw most primitives: drawPoint(), drawPoints(), drawLine(), drawRect(), drawWinFocusRect(), drawRoundRect(), drawEllipse(), drawArc(), drawPie(), drawChord(), drawLineSegments(), drawPolyline(), drawPolygon(), drawConvexPolygon() and drawCubicBezier(). All of these functions take integer coordinates; there are no floating-point versions since we want drawing to be as fast as possible.

There are functions to draw pixmaps/images, namely drawPixmap(), drawImage() and drawTiledPixmap(). drawPixmap() and drawImage() produce the same result, except that drawPixmap() is faster on-screen and drawImage() faster and sometimes better on QPrinter and QPicture.

Text drawing is done using drawText(), and when you need fine-grained positioning, boundingRect() tells you where a given drawText() command would draw.

There is a drawPicture() function that draws the contents of an entire QPicture using this painter. drawPicture() is the only function that disregards all the painter's settings: the QPicture has its own settings.

Normally, the QPainter operates on the device's own coordinate system (usually pixels), but QPainter has good support for coordinate transformation. See The Coordinate System for a more general overview and a simple example.

The most common functions used are scale(), rotate(), translate() and shear(), all of which operate on the worldMatrix(). setWorldMatrix() can replace or add to the currently set worldMatrix().

setViewport() sets the rectangle on which QPainter operates. The default is the entire device, which is usually fine, except on printers. setWindow() sets the coordinate system, that is, the rectangle that maps to viewport(). What's drawn inside the window() ends up being inside the viewport(). The window's default is the same as the viewport, and if you don't use the transformations, they are optimized away, gaining another little bit of speed.

After all the coordinate transformation is done, QPainter can clip the drawing to an arbitrary rectangle or region. hasClipping() is TRUE if QPainter clips, and clipRegion() returns the clip region. You can set it using either setClipRegion() or setClipRect(). Note that the clipping can be slow. It's all system-dependent, but as a rule of thumb, you can assume that drawing speed is inversely proportional to the number of rectangles in the clip region.

After QPainter's clipping, the paint device may also clip. For example, most widgets clip away the pixels used by child widgets, and most printers clip away an area near the edges of the paper. This additional clipping is not reflected by the return value of clipRegion() or hasClipping().

QPainter also includes some less-used functions that are very useful on those occasions when they're needed.

isActive() indicates whether the painter is active. begin() (and the most usual constructor) makes it active. end() (and the destructor) deactivates it. If the painter is active, device() returns the paint device on which the painter paints.

Sometimes it is desirable to make someone else paint on an unusual QPaintDevice. QPainter supports a static function to do this, redirect(). We recommend not using it, but for some hacks it's perfect.

setTabStops() and setTabArray() can change where the tab stops are, but these are very seldomly used.

Warning: Note that QPainter does not attempt to work around coordinate limitations in the underlying window system. Some platforms may behave incorrectly with coordinates as small as +/-4000.

See also QPaintDevice, QWidget, QPixmap, QPrinter, QPicture, Application Walkthrough, Coordinate System Overview, Graphics Classes, and Image Processing Classes.  

Member Type Documentation

QPainter::CoordinateMode

QPainter::CoordDevice

QPainter::CoordPainter

See also clipRegion().  

QPainter::TextDirection

QPainter::Auto

QPainter::RTL - right to left

QPainter::LTR - left to right

See also drawText().  

MEMBER FUNCTION DOCUMENTATION

QPainter::QPainter ()

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, bool unclipped = FALSE )

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

Here's an example using begin() and end():

        void MyWidget::paintEvent( QPaintEvent * )


        {


            QPainter p;


            p.begin( this );


            p.drawLine( ... );  // drawing code


            p.end();


        }

The same example using this constructor:

        void MyWidget::paintEvent( QPaintEvent * )


        {


            QPainter p( this );


            p.drawLine( ... );  // drawing code


        }

Since the constructor cannot provide feedback when the initialization of the painter failed you should rather use begin() and end() to paint on external devices, e.g. printers.

See also begin() and end().  

QPainter::QPainter ( const QPaintDevice * pd, const QWidget * copyAttributes, bool unclipped = FALSE )