Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
QRegion Class Reference

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

#include <qregion.h>

Collaboration diagram for QRegion:

Public Types

enum  RegionType { Rectangle , Ellipse }
 Specifies the shape of the region to be created. More...
typedef const QRectconst_iterator
typedef std::reverse_iterator< const_iteratorconst_reverse_iterator

Public Member Functions

 QRegion ()
 Constructs an empty region.
 QRegion (int x, int y, int w, int h, RegionType t=Rectangle)
 Constructs a rectangular or elliptic region.
 QRegion (const QRect &r, RegionType t=Rectangle)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Create a region based on the rectangle r with region type t.
 QRegion (const QPolygon &pa, Qt::FillRule fillRule=Qt::OddEvenFill)
 Constructs a polygon region from the point array a with the fill rule specified by fillRule.
 QRegion (const QRegion &region)
 Constructs a new region which is equal to region r.
 QRegion (QRegion &&other) noexcept
 QRegion (const QBitmap &bitmap)
 Constructs a region from the bitmap bm.
 ~QRegion ()
QRegionoperator= (const QRegion &)
 Assigns r to this region and returns a reference to the region.
void swap (QRegion &other) noexcept
bool isEmpty () const
 Returns true if the region is empty; otherwise returns false.
bool isNull () const
const_iterator begin () const noexcept
const_iterator cbegin () const noexcept
const_iterator end () const noexcept
const_iterator cend () const noexcept
const_reverse_iterator rbegin () const noexcept
const_reverse_iterator crbegin () const noexcept
const_reverse_iterator rend () const noexcept
const_reverse_iterator crend () const noexcept
bool contains (const QPoint &p) const
 Returns true if the region contains the point p; otherwise returns false.
bool contains (const QRect &r) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns true if the region overlaps the rectangle r; otherwise returns false.
void translate (int dx, int dy)
 Translates (moves) the region dx along the X axis and dy along the Y axis.
void translate (const QPoint &p)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Translates the region {point}{.x()} along the x axis and {point}{.y()} along the y axis, relative to the current position.
QRegion translated (int dx, int dy) const
QRegion translated (const QPoint &p) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
QRegion united (const QRegion &r) const
QRegion united (const QRect &r) const
QRegion intersected (const QRegion &r) const
QRegion intersected (const QRect &r) const
QRegion subtracted (const QRegion &r) const
QRegion xored (const QRegion &r) const
bool intersects (const QRegion &r) const
bool intersects (const QRect &r) const
QRect boundingRect () const noexcept
 Returns the bounding rectangle of this region.
void setRects (const QRect *rect, int num)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. \obsolete Use the QSpan overload instead.
void setRects (QSpan< const QRect > r)
QSpan< const QRectrects () const noexcept
int rectCount () const noexcept
QRegion operator| (const QRegion &r) const
 Applies the united() function to this region and r.
QRegion operator+ (const QRegion &r) const
 Applies the united() function to this region and r.
QRegion operator+ (const QRect &r) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
QRegion operator& (const QRegion &r) const
 Applies the intersected() function to this region and r.
QRegion operator& (const QRect &r) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
QRegion operator- (const QRegion &r) const
 Applies the subtracted() function to this region and r.
QRegion operator^ (const QRegion &r) const
 Applies the xored() function to this region and r.
QRegionoperator|= (const QRegion &r)
 Applies the united() function to this region and r and assigns the result to this region.
QRegionoperator+= (const QRegion &r)
 Applies the united() function to this region and r and assigns the result to this region.
QRegionoperator+= (const QRect &r)
 Returns a region that is the union of this region with the specified rect.
QRegionoperator&= (const QRegion &r)
 Applies the intersected() function to this region and r and assigns the result to this region.
QRegionoperator&= (const QRect &r)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
QRegionoperator-= (const QRegion &r)
 Applies the subtracted() function to this region and r and assigns the result to this region.
QRegionoperator^= (const QRegion &r)
 Applies the xored() function to this region and r and assigns the result to this region.
bool operator== (const QRegion &r) const
 Returns true if the region is equal to r; otherwise returns false.
bool operator!= (const QRegion &r) const
 Returns true if this region is different from the other region; otherwise returns false.
 operator QVariant () const
 Returns the region as a QVariant.

Friends

struct QRegionPrivate
Q_GUI_EXPORT QDataStreamoperator<< (QDataStream &, const QRegion &)
 Writes the region r to the stream s and returns a reference to the stream.
Q_GUI_EXPORT QDataStreamoperator>> (QDataStream &, QRegion &)
 Reads a region from the stream s into r and returns a reference to the stream.
Q_GUI_EXPORT friend bool qt_region_strictContains (const QRegion &region, const QRect &rect)

Detailed Description

The QRegion class specifies a clip region for a painter.

\inmodule QtGui

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 \l{implicitly shared} class.

Definition at line 26 of file qregion.h.

Member Typedef Documentation

◆ const_iterator

Since
5.8

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(), end()

Definition at line 46 of file qregion.h.

◆ const_reverse_iterator

typedef std::reverse_iterator<const_iterator> QRegion::const_reverse_iterator
Since
5.8

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(), rend()

Definition at line 47 of file qregion.h.

Member Enumeration Documentation

◆ RegionType

Specifies the shape of the region to be created.

\value Rectangle the region covers the entire rectangle. \value Ellipse the region is an ellipse inside the rectangle.

Enumerator
Rectangle 
Ellipse 

Definition at line 29 of file qregion.h.

Constructor & Destructor Documentation

◆ QRegion() [1/7]

QRegion::QRegion ( )

Constructs an empty region.

See also
isEmpty()

Definition at line 3793 of file qregion.cpp.

◆ QRegion() [2/7]

QRegion::QRegion ( int x,
int y,
int w,
int h,
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).

Definition at line 160 of file qregion.cpp.

◆ QRegion() [3/7]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.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

Definition at line 3798 of file qregion.cpp.

◆ QRegion() [4/7]

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 \l{Qt::WindingFill}, the polygon region is defined using the winding algorithm; if it is \l{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.

Definition at line 3815 of file qregion.cpp.

◆ QRegion() [5/7]

QRegion::QRegion ( const QRegion & region)

Constructs a new region which is equal to region r.

Definition at line 3831 of file qregion.cpp.

◆ QRegion() [6/7]

QRegion::QRegion ( QRegion && other)
inlinenoexcept
Since
5.7

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

See also
isNull()

Definition at line 36 of file qregion.h.

◆ QRegion() [7/7]

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

Definition at line 3838 of file qregion.cpp.

◆ ~QRegion()

QRegion::~QRegion ( )

Destroys the region.

Definition at line 3854 of file qregion.cpp.

Member Function Documentation

◆ begin()

QRegion::const_iterator QRegion::begin ( ) const
noexcept
Since
5.8

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(), end()

Definition at line 4202 of file qregion.cpp.

◆ boundingRect()

QRect QRegion::boundingRect ( ) const
noexcept

Returns the bounding rectangle of this region.

An empty region gives a rectangle that is QRect::isNull().

Definition at line 4158 of file qregion.cpp.

◆ cbegin()

const_iterator QRegion::cbegin ( ) const
inlinenoexcept
Since
5.8

Same as begin().

Definition at line 50 of file qregion.h.

◆ cend()

const_iterator QRegion::cend ( ) const
inlinenoexcept
Since
5.8

Same as end().

Definition at line 52 of file qregion.h.

◆ contains() [1/2]

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

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

Definition at line 3899 of file qregion.cpp.

◆ contains() [2/2]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns true if the region overlaps the rectangle r; otherwise returns false.

Definition at line 3904 of file qregion.cpp.

◆ crbegin()

const_reverse_iterator QRegion::crbegin ( ) const
inlinenoexcept
Since
5.8

Same as rbegin().

Definition at line 54 of file qregion.h.

◆ crend()

const_reverse_iterator QRegion::crend ( ) const
inlinenoexcept
Since
5.8

Same as rend().

Definition at line 56 of file qregion.h.

◆ end()

QRegion::const_iterator QRegion::end ( ) const
noexcept
Since
5.8

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(), begin()

Definition at line 4207 of file qregion.cpp.

◆ intersected() [1/2]

QRegion QRegion::intersected ( const QRect & rect) const
nodiscard
Since
4.4

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

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

Definition at line 4089 of file qregion.cpp.

◆ intersected() [2/2]

QRegion QRegion::intersected ( const QRegion & r) const
nodiscard
Since
4.2

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

Region Intersection

The figure shows the intersection of two elliptical regions.

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

Definition at line 4044 of file qregion.cpp.

◆ intersects() [1/2]

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

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

Definition at line 4302 of file qregion.cpp.

◆ intersects() [2/2]

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

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

Definition at line 605 of file qregion.cpp.

◆ isEmpty()

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

Definition at line 3889 of file qregion.cpp.

◆ isNull()

bool QRegion::isNull ( ) const
Since
5.0

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

Definition at line 3894 of file qregion.cpp.

◆ operator QVariant()

QRegion::operator QVariant ( ) const

Returns the region as a QVariant.

Definition at line 541 of file qregion.cpp.

◆ operator!=()

bool QRegion::operator!= ( const QRegion & r) const
inline

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

Definition at line 99 of file qregion.h.

◆ operator&() [1/2]

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

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

Since
4.4

Definition at line 431 of file qregion.cpp.

◆ operator&() [2/2]

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

Definition at line 424 of file qregion.cpp.

◆ operator&=() [1/2]

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

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

Since
4.4

Definition at line 503 of file qregion.cpp.

◆ operator&=() [2/2]

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

Definition at line 490 of file qregion.cpp.

◆ operator+() [1/2]

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

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

Since
4.4

Definition at line 415 of file qregion.cpp.

◆ operator+() [2/2]

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(), operator|()

Definition at line 408 of file qregion.cpp.

◆ operator+=() [1/2]

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

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

See also
united()

Definition at line 4015 of file qregion.cpp.

◆ operator+=() [2/2]

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

Definition at line 3953 of file qregion.cpp.

◆ operator-()

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

Definition at line 442 of file qregion.cpp.

◆ operator-=()

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

Definition at line 518 of file qregion.cpp.

◆ operator=()

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

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

Move-assigns other to this QRegion instance.

Since
5.2

Definition at line 3861 of file qregion.cpp.

◆ operator==()

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

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

Definition at line 4289 of file qregion.cpp.

◆ operator^()

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

Definition at line 451 of file qregion.cpp.

◆ operator^=()

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

Definition at line 528 of file qregion.cpp.

◆ operator|()

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(), operator+()

Definition at line 399 of file qregion.cpp.

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

Definition at line 461 of file qregion.cpp.

◆ rbegin()

const_reverse_iterator QRegion::rbegin ( ) const
inlinenoexcept
Since
5.8

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(), rend()

Definition at line 53 of file qregion.h.

◆ rectCount()

int QRegion::rectCount ( ) const
noexcept
Since
4.6

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

Definition at line 4284 of file qregion.cpp.

◆ rects()

QSpan< const QRect > QRegion::rects ( ) const
noexcept
Since
6.8

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.
See also
setRects()

Definition at line 4279 of file qregion.cpp.

◆ rend()

const_reverse_iterator QRegion::rend ( ) const
inlinenoexcept
Since
5.8

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(), rbegin()

Definition at line 55 of file qregion.h.

◆ setRects() [1/2]

void QRegion::setRects ( const QRect * rect,
int num )

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

Definition at line 4218 of file qregion.cpp.

◆ setRects() [2/2]

void QRegion::setRects ( QSpan< const QRect > rects)
Since
6.8

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

\list

  • 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. \endlist \omit Only some platforms have these restrictions (Qt for Embedded Linux, X11 and \macos). \endomit
Note
For historical reasons, {rects.size()} must be less than {INT_MAX} (see rectCount()).
See also
rects()

Definition at line 4227 of file qregion.cpp.

◆ subtracted()

QRegion QRegion::subtracted ( const QRegion & r) const
nodiscard
Since
4.2

Returns a region which is r subtracted from this region.

Region Subtraction

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(), xored()

Definition at line 4115 of file qregion.cpp.

◆ swap()

void QRegion::swap ( QRegion & other)
inlinenoexcept
Since
4.8 \memberswap{region}

Definition at line 42 of file qregion.h.

◆ translate() [1/2]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.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.

Definition at line 62 of file qregion.h.

◆ translate() [2/2]

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

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

Definition at line 3911 of file qregion.cpp.

◆ translated() [1/2]

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

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

Since
4.1

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

Definition at line 64 of file qregion.h.

◆ translated() [2/2]

QRegion QRegion::translated ( int dx,
int dy ) const
nodiscard
Since
4.1

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

Definition at line 585 of file qregion.cpp.

◆ united() [1/2]

QRegion QRegion::united ( const QRect & rect) const
nodiscard
Since
4.4

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

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

Definition at line 3983 of file qregion.cpp.

◆ united() [2/2]

QRegion QRegion::united ( const QRegion & r) const
nodiscard
Since
4.2

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

Region Union

The figure shows the union of two elliptical regions.

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

Definition at line 3920 of file qregion.cpp.

◆ xored()

QRegion QRegion::xored ( const QRegion & r) const
nodiscard
Since
4.2

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

Region XORed

The figure shows the exclusive or of two elliptical regions.

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

Definition at line 4140 of file qregion.cpp.

◆ operator<<

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

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

See also
{Serializing Qt Data Types}{Format of the QDataStream operators}

Definition at line 311 of file qregion.cpp.

◆ operator>>

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

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

See also
{Serializing Qt Data Types}{Format of the QDataStream operators}

Definition at line 345 of file qregion.cpp.

◆ QRegionPrivate

friend struct QRegionPrivate
friend

Definition at line 118 of file qregion.h.

◆ qt_region_strictContains

Q_GUI_EXPORT friend bool qt_region_strictContains ( const QRegion & region,
const QRect & rect )
friend

Returns true if rect is guaranteed to be fully contained in region. A false return value does not guarantee the opposite.

Definition at line 4170 of file qregion.cpp.


The documentation for this class was generated from the following files: