QRegion Class | Qt GUI | Qt 6.10.3
Description: The QRegion class specifies a clip region for a painter.

- Qt 6.10
- Qt GUI
- C++ Classes
- QRegion
- Qt 6.10.3 Reference Documentation

# QRegion Class

The QRegion class specifies a clip region for a painter. More...

Header: | `#include <QRegion>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Gui)` `target_link_libraries(mytarget PRIVATE Qt6::Gui)`
qmake: | `QT += gui`

- List of all members, including inherited members
- Deprecated members
- QRegion is part of Painting Classes and Implicitly Shared Classes.

## Public Types

enum | RegionType { Rectangle, Ellipse }
| const_iterator
| const_reverse_iterator

## Public Functions

| QRegion()
| QRegion(const QBitmap &bm)
| QRegion(const QPolygon &a, Qt::FillRule fillRule = Qt::OddEvenFill)
| QRegion(int x, int y, int w, int h, QRegion::RegionType t = Rectangle)
| QRegion(const QRect &r, QRegion::RegionType t = Rectangle)
| QRegion(const QRegion &r)
| QRegion(QRegion &&other)
QRegion::const_iterator | begin() const
QRect | boundingRect() const
QRegion::const_iterator | cbegin() const
QRegion::const_iterator | cend() const
bool | contains(const QPoint &p) const
bool | contains(const QRect &r) const
QRegion::const_reverse_iterator | crbegin() const
QRegion::const_reverse_iterator | crend() const
QRegion::const_iterator | end() const
QRegion | intersected(const QRect &rect) const
QRegion | intersected(const QRegion &r) const
bool | intersects(const QRect &rect) const
bool | intersects(const QRegion &region) const
bool | isEmpty() const
bool | isNull() const
QRegion::const_reverse_iterator | rbegin() const
int | rectCount() const
`(since 6.8)` QSpan<const QRect> | rects() const
QRegion::const_reverse_iterator | rend() const
`(since 6.8)` void | setRects(QSpan<const QRect> rects)
QRegion | subtracted(const QRegion &r) const
void | swap(QRegion &other)
`(since 6.0)` HRGN | toHRGN() const
void | translate(int dx, int dy)
void | translate(const QPoint &point)
QRegion | translated(int dx, int dy) const
QRegion | translated(const QPoint &p) const
QRegion | united(const QRect &rect) const
QRegion | united(const QRegion &r) const
QRegion | xored(const QRegion &r) const
QVariant | operator QVariant() const
bool | operator!=(const QRegion &other) const
QRegion | operator&(const QRegion &r) const
QRegion | operator&(const QRect &r) const
QRegion & | operator&=(const QRegion &r)
QRegion & | operator&=(const QRect &r)
QRegion | operator+(const QRegion &r) const
QRegion | operator+(const QRect &r) const
QRegion & | operator+=(const QRect &rect)
QRegion & | operator+=(const QRegion &r)
QRegion | operator-(const QRegion &r) const
QRegion & | operator-=(const QRegion &r)
QRegion & | operator=(QRegion &&other)
QRegion & | operator=(const QRegion &r)
bool | operator==(const QRegion &r) const
QRegion | operator^(const QRegion &r) const
QRegion & | operator^=(const QRegion &r)
QRegion | operator|(const QRegion &r) const
QRegion & | operator|=(const QRegion &r)

## Static Public Members

`(since 6.0)` QRegion | fromHRGN(HRGN hrgn)

## Related Non-Members

QDataStream & | operator<<(QDataStream &s, const QRegion &r)
QDataStream & | operator>>(QDataStream &s, QRegion &r)

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

See also QPainter::setClipRegion(), QPainter::setClipRect(), and QPainterPath.

## Member Type Documentation

### enum QRegion::RegionType

Specifies the shape of the region to be created.

Constant | Value | Description
--- | --- | ---
`QRegion::Rectangle` | `0` | the region covers the entire rectangle.
`QRegion::Ellipse` | `1` | the region is an ellipse inside the rectangle.

### QRegion::const_iterator

An iterator over the non-overlapping rectangles that make up the region.

The union of all the rectangles is equal to the original region.

QRegion does not offer mutable iterators.

See also begin() and end().

### QRegion::const_reverse_iterator

A reverse iterator over the non-overlapping rectangles that make up the region.

The union of all the rectangles is equal to the original region.

QRegion does not offer mutable iterators.

See also rbegin() and rend().

## Member Function Documentation

### QRegion::QRegion()

Constructs an empty region.

See also isEmpty().

### QRegion::QRegion(const QBitmap &bm)

Constructs a region from the bitmap bm.

The resulting region consists of the pixels in bitmap bm that are Qt::color1, as if each pixel was a 1 by 1 rectangle.

This constructor may create complex regions that will slow down painting when used. Note that drawing masked pixmaps can be done much faster using QPixmap::setMask().

### QRegion::QRegion(const QPolygon &a, Qt::FillRule fillRule = Qt::OddEvenFill)

Constructs a polygon region from the point array a with the fill rule specified by fillRule.

If fillRule is Qt::WindingFill, the polygon region is defined using the winding algorithm; if it is Qt::OddEvenFill, the odd-even fill algorithm is used.

Warning: This constructor can be used to create complex regions that will slow down painting when used.

### QRegion::QRegion(int x, int y, int w, int h, QRegion::RegionType t = Rectangle)

Constructs a rectangular or elliptic region.

If t is `Rectangle`, the region is the filled rectangle (x, y, w, h). If t is `Ellipse`, the region is the filled ellipse with center at (x + w / 2, y + h / 2) and size (w ,h).

### QRegion::QRegion(const QRect &r, QRegion::RegionType t = Rectangle)

Create a region based on the rectangle r with region type t.

If the rectangle is invalid a null region will be created.

This is an overloaded function.

See also QRegion::RegionType.

### QRegion::QRegion(const QRegion &r)

Constructs a new region which is equal to region r.

### `[noexcept]` QRegion::QRegion(QRegion &&other)

Move-constructs a new region from region other. After the call, other is null.

See also isNull().

### `[noexcept]` QRegion::const_iterator QRegion::begin() const

Returns a const_iterator pointing to the beginning of the range of non-overlapping rectangles that make up the region.

The union of all the rectangles is equal to the original region.

See also rbegin(), cbegin(), and end().

### `[noexcept]` QRect QRegion::boundingRect() const

Returns the bounding rectangle of this region. An empty region gives a rectangle that is QRect::isNull().

### `[noexcept]` QRegion::const_iterator QRegion::cbegin() const

Same as begin().

### `[noexcept]` QRegion::const_iterator QRegion::cend() const

Same as end().

### bool QRegion::contains(const QPoint &p) const

Returns `true` if the region contains the point p; otherwise returns `false`.

### bool QRegion::contains(const QRect &r) const

Returns `true` if the region overlaps the rectangle r; otherwise returns `false`.

This is an overloaded function.

### `[noexcept]` QRegion::const_reverse_iterator QRegion::crbegin() const

Same as rbegin().

### `[noexcept]` QRegion::const_reverse_iterator QRegion::crend() const

Same as rend().

### `[noexcept]` QRegion::const_iterator QRegion::end() const

Returns a const_iterator pointing to one past the end of non-overlapping rectangles that make up the region.

The union of all the rectangles is equal to the original region.

See also rend(), cend(), and begin().

### `[static, since 6.0]` QRegion QRegion::fromHRGN(HRGN hrgn)

Returns a QRegion that is equivalent to the given hrgn.

This function was introduced in Qt 6.0.

### QRegion QRegion::intersected(const QRect &rect) const

Returns a region which is the intersection of this region and the given rect.

See also subtracted(), united(), and xored().

### QRegion QRegion::intersected(const QRegion &r) const

Returns a region which is the intersection of this region and r.

The figure shows the intersection of two elliptical regions.

See also subtracted(), united(), and xored().

### bool QRegion::intersects(const QRect &rect) const

Returns `true` if this region intersects with rect, otherwise returns `false`.

### bool QRegion::intersects(const QRegion &region) const

Returns `true` if this region intersects with region, otherwise returns `false`.

### bool QRegion::isEmpty() const

Returns `true` if the region is empty; otherwise returns `false`. An empty region is a region that contains no points.

Example:

     QRegion r1(10, 10, 20, 20);
     r1.isEmpty();               // false

     QRegion r3;
     r3.isEmpty();               // true

     QRegion r2(40, 40, 20, 20);
     r3 = r1.intersected(r2);    // r3: intersection of r1 and r2
     r3.isEmpty();               // true

     r3 = r1.united(r2);         // r3: union of r1 and r2
     r3.isEmpty();               // false

### bool QRegion::isNull() const

Returns `true` if the region is empty; otherwise returns `false`. An empty region is a region that contains no points. This function is the same as isEmpty

See also isEmpty().

### `[noexcept]` QRegion::const_reverse_iterator QRegion::rbegin() const

Returns a const_reverse_iterator pointing to the beginning of the range of non-overlapping rectangles that make up the region.

The union of all the rectangles is equal to the original region.

See also begin(), crbegin(), and rend().

### `[noexcept]` int QRegion::rectCount() const

Returns the number of rectangles that this region is composed of. Same as `end() - begin()`.

### `[noexcept, since 6.8]` QSpan<const QRect> QRegion::rects() const

Returns a span of non-overlapping rectangles that make up the region. The span remains valid until the next call of a mutating (non-const) method on this region.

The union of all the rectangles is equal to the original region.

Note: This functions existed in Qt 5, too, but returned QVector<QRect> instead.

This function was introduced in Qt 6.8.

See also setRects().

### `[noexcept]` QRegion::const_reverse_iterator QRegion::rend() const

Returns a const_reverse_iterator pointing to one past the end of the range of non-overlapping rectangles that make up the region.

The union of all the rectangles is equal to the original region.

See also end(), crend(), and rbegin().

### `[since 6.8]` void QRegion::setRects(QSpan<const QRect> rects)

Sets the region using the array of rectangles specified by rects. The rectangles must be optimally Y-X sorted and follow these restrictions:

- The rectangles must not intersect.
- All rectangles with a given top coordinate must have the same height.
- No two rectangles may abut horizontally (they should be combined into a single wider rectangle in that case).
- The rectangles must be sorted in ascending order, with Y as the major sort key and X as the minor sort key.

Note: For historical reasons, `rects.size()` must be less than `INT_MAX` (see rectCount()).

This function was introduced in Qt 6.8.

See also rects().

### QRegion QRegion::subtracted(const QRegion &r) const

Returns a region which is r subtracted from this region.

The figure shows the result when the ellipse on the right is subtracted from the ellipse on the left (`left - right`).

See also intersected(), united(), and xored().

### `[noexcept]` void QRegion::swap(QRegion &other)

Swaps this region with other. This operation is very fast and never fails.

### `[since 6.0]` HRGN QRegion::toHRGN() const

Returns a HRGN that is equivalent to the given region.

This function was introduced in Qt 6.0.

### void QRegion::translate(int dx, int dy)

Translates (moves) the region dx along the X axis and dy along the Y axis.

### void QRegion::translate(const QPoint &point)

Translates the region point.x() along the x axis and point.y() along the y axis, relative to the current position. Positive values move the region to the right and down.

Translates to the given point.

This is an overloaded function.

### QRegion QRegion::translated(int dx, int dy) const

Returns a copy of the region that is translated dx along the x axis and dy along the y axis, relative to the current position. Positive values move the region to the right and down.

See also translate().

### QRegion QRegion::translated(const QPoint &p) const

Returns a copy of the regtion that is translated p.x() along the x axis and p.y() along the y axis, relative to the current position. Positive values move the rectangle to the right and down.

This is an overloaded function.

See also translate().

### QRegion QRegion::united(const QRect &rect) const

Returns a region which is the union of this region and the given rect.

See also intersected(), subtracted(), and xored().

### QRegion QRegion::united(const QRegion &r) const

Returns a region which is the union of this region and r.

The figure shows the union of two elliptical regions.

See also intersected(), subtracted(), and xored().

### QRegion QRegion::xored(const QRegion &r) const

Returns a region which is the exclusive or (XOR) of this region and r.

The figure shows the exclusive or of two elliptical regions.

See also intersected(), united(), and subtracted().

### QVariant QRegion::operator QVariant() const

Returns the region as a QVariant

### bool QRegion::operator!=(const QRegion &other) const

Returns `true` if this region is different from the other region; otherwise returns `false`.

### QRegion QRegion::operator&(const QRegion &r) const

Applies the intersected() function to this region and r. `r1&r2` is equivalent to `r1.intersected(r2)`.

See also intersected().

### QRegion QRegion::operator&(const QRect &r) const

This is an overloaded function.

### QRegion &QRegion::operator&=(const QRegion &r)

Applies the intersected() function to this region and r and assigns the result to this region. `r1&=r2` is equivalent to `r1` = r1.intersected(r2).

See also intersected().

### QRegion &QRegion::operator&=(const QRect &r)

This is an overloaded function.

### QRegion QRegion::operator+(const QRegion &r) const

Applies the united() function to this region and r. `r1+r2` is equivalent to `r1.united(r2)`.

See also united() and operator|().

### QRegion QRegion::operator+(const QRect &r) const

This is an overloaded function.

### QRegion &QRegion::operator+=(const QRect &rect)

Returns a region that is the union of this region with the specified rect.

See also united().

### QRegion &QRegion::operator+=(const QRegion &r)

Applies the united() function to this region and r and assigns the result to this region. `r1+=r2` is equivalent to `r1 = r1.united(r2)`.

See also intersected().

### QRegion QRegion::operator-(const QRegion &r) const

Applies the subtracted() function to this region and r. `r1-r2` is equivalent to `r1.subtracted(r2)`.

See also subtracted().

### QRegion &QRegion::operator-=(const QRegion &r)

Applies the subtracted() function to this region and r and assigns the result to this region. `r1-=r2` is equivalent to `r1 = r1.subtracted(r2)`.

See also subtracted().

### `[noexcept]` QRegion &QRegion::operator=(QRegion &&other)

Move-assigns other to this QRegion instance.

### QRegion &QRegion::operator=(const QRegion &r)

Assigns r to this region and returns a reference to the region.

### bool QRegion::operator==(const QRegion &r) const

Returns `true` if the region is equal to r; otherwise returns false.

### QRegion QRegion::operator^(const QRegion &r) const

Applies the xored() function to this region and r. `r1^r2` is equivalent to `r1.xored(r2)`.

See also xored().

### QRegion &QRegion::operator^=(const QRegion &r)

Applies the xored() function to this region and r and assigns the result to this region. `r1^=r2` is equivalent to `r1 = r1.xored(r2)`.

See also xored().

### QRegion QRegion::operator|(const QRegion &r) const

Applies the united() function to this region and r. `r1|r2` is equivalent to `r1.united(r2)`.

See also united() and operator+().

### QRegion &QRegion::operator|=(const QRegion &r)

Applies the united() function to this region and r and assigns the result to this region. `r1|=r2` is equivalent to `r1 = r1.united(r2)`.

See also united().

## Related Non-Members

### QDataStream &operator<<(QDataStream &s, const QRegion &r)

Writes the region r to the stream s and returns a reference to the stream.

See also Format of the QDataStream operators.

### QDataStream &operator>>(QDataStream &s, QRegion &r)

Reads a region from the stream s into r and returns a reference to the stream.

See also Format of the QDataStream operators.