QRegion Class

Detailed Description

QRegion is used with QPainter::setClipRegion() to limit the paint area to what needs to be painted. There is also a QWidget::repaint() function that takes a QRegion parameter. QRegion is the best tool for minimizing the amount of screen area to be updated by a repaint.

This class is not suitable for constructing shapes for rendering, especially as outlines. Use QPainterPath to create paths and shapes for use with QPainter.

QRegion is an implicitly shared class.

Creating and Using Regions

A region can be created from a rectangle, an ellipse, a polygon or a bitmap. Complex regions may be created by combining simple regions using united(), intersected(), subtracted(), or xored() (exclusive or). You can move a region using translate().

You can test whether a region isEmpty() or if it contains() a QPoint or QRect. The bounding rectangle can be found with boundingRect().

Iteration over the region (with begin(), end(), or C++11 ranged-for loops) gives a decomposition of the region into rectangles.

Example of using complex regions:

 void MyWidget::paintEvent(QPaintEvent *)
 {
     QRegion r1(QRect(100, 100, 200, 80),    // r1: elliptic region
                QRegion::Ellipse);
     QRegion r2(QRect(100, 120, 90, 30));    // r2: rectangular region
     QRegion r3 = r1.intersected(r2);        // r3: intersection

     QPainter painter(this);
     painter.setClipRegion(r3);
     ...                                     // paint clipped graphics
 }