class QRegion#

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

Synopsis#

Methods#

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description#

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

QRegion is used with 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:

def paintEvent(self, arg__0):

    QRegion r1(QRect(100, 100, 200, 80), // r1: elliptic region
               QRegion.Ellipse)
    QRegion r2(QRect(100, 120, 90, 30)) # r2: rectangular region
    r3 = r1.intersected(r2) # r3: intersection
    painter = QPainter(self)
    painter.setClipRegion(r3)
    # ...                                  // paint clipped graphics
class RegionType#

Specifies the shape of the region to be created.

Constant

Description

QRegion.Rectangle

the region covers the entire rectangle.

QRegion.Ellipse

the region is an ellipse inside the rectangle.

__init__(bitmap)#
Parameters:

bitmapQBitmap

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

__init__()

Constructs an empty region.

See also

isEmpty()

__init__(x, y, w, h[, t=QRegion.RegionType.Rectangle])
Parameters:
  • x – int

  • y – int

  • w – int

  • h – int

  • tRegionType

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

__init__(region)
Parameters:

regionQRegion

Constructs a new region which is equal to region r.

__init__(pa[, fillRule=Qt.OddEvenFill])
Parameters:

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.

__init__(r[, t=QRegion.RegionType.Rectangle])
Parameters:

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

RegionType

__getitem__()#
__len__()#
begin()#
Return type:

QRect

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

boundingRect()#
Return type:

QRect

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

cbegin()#
Return type:

QRect

Same as begin() .

cend()#
Return type:

QRect

Same as end() .

contains(r)#
Parameters:

rQRect

Return type:

bool

This is an overloaded function.

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

contains(p)
Parameters:

pQPoint

Return type:

bool

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

end()#
Return type:

QRect

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

intersected(r)#
Parameters:

rQRect

Return type:

QRegion

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

intersected(r)
Parameters:

rQRegion

Return type:

QRegion

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

../../_images/rintersect.png

The figure shows the intersection of two elliptical regions.

intersects(r)#
Parameters:

rQRect

Return type:

bool

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

intersects(r)
Parameters:

rQRegion

Return type:

bool

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

isEmpty()#
Return type:

bool

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

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

Example:

r1 = QRegion(10, 10, 20, 20)
r1.isEmpty() # false
r3 = QRegion()
r3.isEmpty() # true
r2 = QRegion(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
isNull()#
Return type:

bool

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

__ne__(r)#
Parameters:

rQRegion

Return type:

bool

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

__and__(r)#
Parameters:

rQRegion

Return type:

QRegion

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

See also

intersected()

__and__(r)
Parameters:

rQRect

Return type:

QRegion

This is an overloaded function.

__mul__(m)#
Parameters:

mQTransform

Return type:

QRegion

__add__(r)#
Parameters:

rQRect

Return type:

QRegion

This is an overloaded function.

__add__(r)
Parameters:

rQRegion

Return type:

QRegion

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

See also

united() operator|()

__iadd__(r)#
Parameters:

rQRect

Return type:

QRegion

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

See also

united()

__iadd__(r)
Parameters:

rQRegion

Return type:

QRegion

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

__sub__(r)#
Parameters:

rQRegion

Return type:

QRegion

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

See also

subtracted()

__isub__(r)#
Parameters:

rQRegion

Return type:

QRegion

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

__eq__(r)#
Parameters:

rQRegion

Return type:

bool

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

__xor__(r)#
Parameters:

rQRegion

Return type:

QRegion

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

See also

xored()

__ixor__(r)#
Parameters:

rQRegion

Return type:

QRegion

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

__or__(r)#
Parameters:

rQRegion

Return type:

QRegion

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

See also

united() operator+()

__ior__(r)#
Parameters:

rQRegion

Return type:

QRegion

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

rectCount()#
Return type:

int

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

setRects(rect, num)#
Parameters:
  • rectQRect

  • num – int

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.

subtracted(r)#
Parameters:

rQRegion

Return type:

QRegion

Returns a region which is r subtracted from this region.

../../_images/rsubtract.png

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

swap(other)#
Parameters:

otherQRegion

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

translate(p)#
Parameters:

pQPoint

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.

translate(dx, dy)
Parameters:
  • dx – int

  • dy – int

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

translated(p)#
Parameters:

pQPoint

Return type:

QRegion

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

translated(dx, dy)
Parameters:
  • dx – int

  • dy – int

Return type:

QRegion

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

united(r)#
Parameters:

rQRect

Return type:

QRegion

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

united(r)
Parameters:

rQRegion

Return type:

QRegion

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

../../_images/runion.png

The figure shows the union of two elliptical regions.

xored(r)#
Parameters:

rQRegion

Return type:

QRegion

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

../../_images/rxor.png

The figure shows the exclusive or of two elliptical regions.