QRegion Class

 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
 }

Member Function Documentation

QRegion::QRegion()

Constructs an empty region.

See also isEmpty().

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)

This is an overloaded function.

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

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

See also QRegion::RegionType.

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.

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

This is an overloaded function.

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

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

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

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

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

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

Returns true if this region intersects with rect, 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] 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().

void QRegion::setRects(const QRect *rects, int number)

Sets the region using the array of rectangles specified by rects and number. 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.

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 region other with this region. 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)

This is an overloaded function.

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.

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

This is an overloaded function.

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.

See also translate().

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

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

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

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

Move-assigns other to this QRegion instance.

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