[ fromfile: paintevents.xml id: paintevents ]

A widget should perform the appropriate painting inside its paintEvent() method. This is the only place where a QWidget can create a QPainter(this).

As you may have observed, a QPaintEvent can be sent to a QWidget due to a number of reasons:

Example 9.19, defines a custom QWidget that overrides paintEvent().

[ . . . . ]
class LifeWidget : public QWidget
{
    Q_OBJECT
public:
    explicit LifeWidget(QWidget* parent = 0);
    ~LifeWidget();
    QSize sizeHint() const;
    void paintEvent(QPaintEvent* evt);      
public slots:
    void setImage(const QImage& image);
private:
    QImage m_image;
    QSize m_size;
};
[ . . . . ]

Steps to get a QPainter for a QWidget:

Example 9.20 shows a paintEvent() that takes an off-screen QImage and paints it directly onto the QWidget.

[ . . . . ]

void LifeWidget::paintEvent(QPaintEvent* evt) {
    QPainter painter(this);         
    if (!m_image.isNull())
        painter.drawImage(QPoint(0,0), m_image);
}

This program paints successive generations of population maps based on the rules described in Conway's Game of Life. Figure 9.27 shows a snapshot of one generation. In Section 17.2.3 we revisit and parallelize this game.

Figure 9.27.  Conway's Game of Life

Normally, paintEvent() is not called directly, but you can schedule it to be called, synchronously or asynchronously. repaint() does not return until paintEvent() has been called. update() returns immediately after a QPaintEvent is placed on the event queue. Example 9.21 scales the image to the correct size and saves it, before calling update(), ensuring that LifeWidget shows the new image sometime soon.

[ . . . . ]

void LifeWidget::setImage(const QImage& image) {
    m_size = image.size();
    m_image = image.scaled(size());
    update();                       
}