Qt logo

QPainter Class Reference


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

#include <qpainter.h>

Inherits Qt.

List of all member functions.

Public Members

Static Public Members

Related Functions

(Note that these are not member functions.)

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( Qt::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( Qt::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: The range of acceptable coordinate values to QPainter's various drawing functions is limited by the capabilities of the drawing engine of the underlying window system. Currently, only Windows NT is able to handle the full 32 bit range; on other platforms, the output may be incorrect when the absolute value of any coordinate (after any set world and/or view transforms have been applied) exceeds some system-dependent value. All systems we have tested were able to correctly handle coordinates up to +/- 2000.

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


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(constQPaintDevice*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(constQPaintDevice*pd, constQWidget*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.

constQColor&QPainter::backgroundColor()const

Returns the background color currently set.

See also: setBackgroundColor().

BGModeQPainter::backgroundMode()const

Returns the background mode currently set.

See also: setBackgroundMode().

boolQPainter::begin(constQPaintDevice*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:

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 picture/picture.cpp

boolQPainter::begin(constQPaintDevice*pd, constQWidget*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(size());
        QPainter p;
        p.begin(&pm, this);
        // ... potential flickering paint operation ...
        p.end();
        bitBlt(this, 0, 0, &pm);
    }

See also: end().

QRectQPainter::boundingRect(intx, inty, intw, inth, inttf, constQString&str, intlen=-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:

These flags are defined in qnamespace.h.

See also: drawText() and fontMetrics().

QRectQPainter::boundingRect(constQRect&r, inttf, constQString&, intlen=-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.

constQBrush&QPainter::brush()const

Returns the current painter brush.

See also: QPainter::setBrush().

constQPoint&QPainter::brushOrigin()const

Returns the brush origin currently set.

See also: setBrushOrigin().

voidQPainter::cleanup() [static]

Internal function that cleans up the painter.

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

voidQPainter::drawArc(intx, inty, intw, inth, inta, intalen)

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

voidQPainter::drawArc(constQRect&r, inta, intalen)

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

voidQPainter::drawChord(intx, inty, intw, inth, inta, intalen)

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

voidQPainter::drawChord(constQRect&r, inta, intalen)

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

voidQPainter::drawEllipse(intx, inty, intw, inth)

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

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

voidQPainter::drawEllipse(constQRect&r)

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

voidQPainter::drawImage(intx, inty, constQImage&image, intsx=0, intsy=0, intsw=-1, intsh=-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().

voidQPainter::drawImage(constQPoint&, constQImage&)

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

voidQPainter::drawImage(constQPoint&, constQImage&, constQRect&sr)

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

voidQPainter::drawLine(intx1, inty1, intx2, inty2)

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

See also: moveTo() and lineTo().

Examples: grapher/grapher.cpp drawlines/connect.cpp progress/progress.cpp splitter/splitter.cpp scrollview/scrollview.cpp

voidQPainter::drawLine(constQPoint&p1, constQPoint&p2)

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

voidQPainter::drawLineSegments(constQPointArray&a, intindex=0, intnlines=-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().

voidQPainter::drawPicture(constQPicture&pic)

Replays the picture pic.

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

Examples: picture/picture.cpp

voidQPainter::drawPie(intx, inty, intw, inth, inta, intalen)

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

voidQPainter::drawPie(constQRect&r, inta, intalen)

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

voidQPainter::drawPixmap(intx, inty, constQPixmap&pixmap, intsx=0, intsy=0, intsw=-1, intsh=-1)

Draws a pixmap at (x,y) by copying a part of the pixmap into the paint device.

Arguments:

The pixmap is clipped if a mask has been set.

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

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

voidQPainter::drawPixmap(constQPoint&p, constQPixmap&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.

voidQPainter::drawPixmap(constQPoint&p, constQPixmap&pm, constQRect&sr)

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

voidQPainter::drawPoint(intx, inty)

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

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

voidQPainter::drawPoint(constQPoint&p)

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

voidQPainter::drawPoints(constQPointArray&a, intindex=0, intnpoints=-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.

voidQPainter::drawPolygon(constQPointArray&a, boolwinding=FALSE, intindex=0, intnpoints=-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

voidQPainter::drawPolyline(constQPointArray&a, intindex=0, intnpoints=-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

voidQPainter::drawQuadBezier(constQPointArray&a, intindex=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.

voidQPainter::drawRect(intx, inty, intw, inth)

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

See also: drawRoundRect().

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

voidQPainter::drawRect(constQRect&r)

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

voidQPainter::drawRoundRect(intx, inty, intw, inth, intxRnd, intyRnd)

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

voidQPainter::drawRoundRect(constQRect&r, intxRnd, intyRnd)

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

voidQPainter::drawText(intx, inty, constQString&str, intlen=-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.

voidQPainter::drawText(intx, inty, intw, inth, inttf, constQString&str, intlen=-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:

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 qnamespace.h.

See also: boundingRect().

Examples: grapher/grapher.cpp drawdemo/drawdemo.cpp progress/progress.cpp desktop/desktop.cpp scrollview/scrollview.cpp trivial/trivial.cpp movies/main.cpp picture/picture.cpp

voidQPainter::drawText(constQPoint&p, constQString&, intlen=-1)

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

voidQPainter::drawText(constQRect&r, inttf, constQString&, intlen=-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.

voidQPainter::drawTiledPixmap(intx, inty, intw, inth, constQPixmap&pixmap, intsx=0, intsy=0)

Draws a tiled pixmap in the specified rectangle.

Arguments:

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

voidQPainter::drawTiledPixmap(constQRect&r, constQPixmap&pm)

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

voidQPainter::drawTiledPixmap(constQRect&r, constQPixmap&pm, constQPoint&sp)

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

voidQPainter::drawWinFocusRect(intx, inty, intw, inth)

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

voidQPainter::drawWinFocusRect(intx, inty, intw, inth, constQColor&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().

voidQPainter::drawWinFocusRect(constQRect&r)

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

voidQPainter::drawWinFocusRect(constQRect&r, constQColor&bgColor)

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

boolQPainter::end()

Ends painting. Any resources used while painting are released.

See also: begin().

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

voidQPainter::eraseRect(intx, inty, intw, inth)

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

voidQPainter::eraseRect(constQRect&r)

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

voidQPainter::fillRect(intx, inty, intw, inth, constQBrush&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 scrollview/scrollview.cpp

voidQPainter::fillRect(constQRect&r, constQBrush&brush)

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

voidQPainter::flush()

Flushes any buffered drawing operations.

constQFont&QPainter::font()const

Returns the current painter font.

See also: setFont() and QFont.

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

QFontMetricsQPainter::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: drawdemo/drawdemo.cpp desktop/desktop.cpp scrollview/scrollview.cpp movies/main.cpp

boolQPainter::hasClipping()const

Returns TRUE if clipping has been set, otherwise FALSE.

See also: setClipping().

boolQPainter::hasViewXForm()const

Returns TRUE if view transformation is enabled, otherwise FALSE.

See also: setViewXForm() and xForm().

boolQPainter::hasWorldXForm()const

Returns TRUE if world transformation is enabled, otherwise FALSE.

See also: setWorldXForm().

voidQPainter::initialize() [static]

Internal function that initializes the painter.

boolQPainter::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

voidQPainter::lineTo(intx, inty)

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

voidQPainter::lineTo(constQPoint&p)

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

voidQPainter::moveTo(intx, inty)

Sets the current point.

See also: lineTo() and drawLine().

voidQPainter::moveTo(constQPoint&p)

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

constQPen&QPainter::pen()const

Returns the current pen for the painter.

See also: setPen().

Examples: progress/progress.cpp

RasterOpQPainter::rasterOp()const

Returns the raster operation currently set.

See also: setRasterOp().

voidQPainter::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 );

voidQPainter::resetXForm()

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

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

voidQPainter::restore()

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

See also: save().

voidQPainter::restoreWorldMatrix()

Restores the current world matrix (pops a saved matrix off the stack).

See also: saveWorldMatrix().

voidQPainter::rotate(doublea)

Rotates the coordinate system a degrees.

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

voidQPainter::save()

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

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

See also: restore().

voidQPainter::saveWorldMatrix()

Saves the current world matrix (pushes the matrix onto a stack).

In sane code a save() has a corresponding restoreWorldMatrix().

See also: restoreWorldMatrix().

voidQPainter::scale(doublesx, doublesy)

Scales the coordinate system by (sx,sy).

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

voidQPainter::setBackgroundColor(constQColor&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().

voidQPainter::setBackgroundMode(BGModem)

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

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

voidQPainter::setBrush(BrushStylestyle)

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

See also: brush() and QBrush.

voidQPainter::setBrush(constQBrush&brush)

Sets a new painter brush.

The brush defines how to fill shapes.

See also: brush().

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

voidQPainter::setBrush(constQColor&color)

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

See also: brush() and QBrush.

voidQPainter::setBrushOrigin(intx, inty)

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

voidQPainter::setBrushOrigin(constQPoint&p)

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

voidQPainter::setClipRect(intx, inty, intw, inth)

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 progress/progress.cpp splitter/splitter.cpp trivial/trivial.cpp

voidQPainter::setClipRect(constQRect&r)

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

voidQPainter::setClipRegion(constQRegion&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().

voidQPainter::setClipping(boolenable)

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

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

voidQPainter::setFont(constQFont&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 scrollview/scrollview.cpp movies/main.cpp picture/picture.cpp

voidQPainter::setPen(PenStylestyle)

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

See also: pen() and QPen.

Examples: grapher/grapher.cpp drawlines/connect.cpp drawdemo/drawdemo.cpp progress/progress.cpp forever/forever.cpp desktop/desktop.cpp scrollview/scrollview.cpp movies/main.cpp

voidQPainter::setPen(constQColor&color)

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

See also: pen() and QPen.

voidQPainter::setPen(constQPen&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().

voidQPainter::setRasterOp(RasterOpr)

Sets the raster operation to r.

The r parameter must be one of:

See also: rasterOp().

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

voidQPainter::setTabStops(intts)

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

voidQPainter::setViewXForm(boolenable)

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

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

voidQPainter::setViewport(intx, inty, intw, inth)

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

voidQPainter::setViewport(constQRect&r)

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

voidQPainter::setWindow(intx, inty, intw, inth)

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: drawdemo/drawdemo.cpp forever/forever.cpp

voidQPainter::setWindow(constQRect&r)

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

voidQPainter::setWorldMatrix(constQWMatrix&m, boolcombine=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:

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

    void QPainter::rotate( double a )
    {
        QWMatrix m;
        m.rotate( a );
        setWorldMatrix( m, TRUE );
    }

Note that you should always use combine when you are drawing into a QPicture. Otherwise the picture may not be completely encapsulated and cannot be replayed with additional transformations. Using the translate(), scale(), etc. functions is safe.

Furthermore, you can easily save and restore the current world transformation matrix with the convenient functions saveWorldMatrix() and restoreWorldMatrix(), respectively. If you need to draw some top-to-bottom text at the position (x y), for instance, but everything else shall remain unrotated, you can easily achieve this with:

    void MyWidget::paintEvent()
    {
        QPainter paint( this );
        ...
        paint.saveWorldMatrix();
        paint.translate( x, y );
        paint.rotate( 90 );
        paint.drawText( 0, 0, "top-to-bottom text" );
        paint.restoreWorldMatrix();
        ....
    }

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

voidQPainter::setWorldXForm(boolenable)

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

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

voidQPainter::shear(doublesh, doublesv)

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

intQPainter::tabStops()const

Returns the tab stop setting.

See also: setTabStops().

voidQPainter::translate(doubledx, doubledy)

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

QRectQPainter::viewport()const

Returns the viewport rectangle.

See also: setViewport() and setViewXForm().

QRectQPainter::window()const

Returns the window rectangle.

See also: setWindow() and setViewXForm().

constQWMatrix&QPainter::worldMatrix()const

Returns the world transformation matrix.

See also: setWorldMatrix().

QPointQPainter::xForm(constQPoint&pv)const

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

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

QPointArrayQPainter::xForm(constQPointArray&av)const

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

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

QPointArrayQPainter::xForm(constQPointArray&av, intindex, intnpoints)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().

QRectQPainter::xForm(constQRect&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().

QPointQPainter::xFormDev(constQPoint&pd)const

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

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

QPointArrayQPainter::xFormDev(constQPointArray&ad)const

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

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

QPointArrayQPainter::xFormDev(constQPointArray&ad, intindex, intnpoints)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().

QRectQPainter::xFormDev(constQRect&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 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().

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

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


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.


Copyright 1999 Troll TechTrademarks
Qt version 2.0.2