En esta página

QRegion Class

La clase QRegion define una región de recorte para un pintor. Más información...

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

Tipos públicos

enum RegionType { Rectangle, Ellipse }
const_iterator
const_reverse_iterator

Funciones públicas

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

Miembros públicos estáticos

(since 6.0) QRegion fromHRGN(HRGN hrgn)
QDataStream &operator<<(QDataStream &s, const QRegion &r)
QDataStream &operator>>(QDataStream &s, QRegion &r)

Descripción detallada

QRegion se utiliza con QPainter::setClipRegion() para limitar el área de dibujo a lo que se necesita pintar. También existe una función QWidget::repaint() que toma un parámetro QRegion. QRegion es la mejor herramienta para minimizar la cantidad de área de pantalla que debe actualizarse al volver a dibujar.

Esta clase no es adecuada para construir formas para su representación, especialmente como contornos. Utiliza QPainterPath para crear trazados y formas que se puedan utilizar con QPainter.

QRegion es una clase compartida implícitamente.

Creación y uso de regiones

Se puede crear una región a partir de un rectángulo, una elipse, un polígono o un mapa de bits. Se pueden crear regiones complejas combinando regiones simples mediante united(), intersected(), subtracted() o xored() (OR exclusivo). Se puede mover una región utilizando translate().

Se puede comprobar si una región cumple con isEmpty() o si contains() con QPoint o QRect. El rectángulo delimitador se puede obtener con boundingRect().

La iteración sobre la región (con begin(), end() o bucles «for» de rango) proporciona una descomposición de la región en rectángulos.

Ejemplo de uso de regiones complejas:

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
}

Véase también QPainter::setClipRegion(), QPainter::setClipRect() y QPainterPath.

Documentación sobre tipos de miembros

enum QRegion::RegionType

Especifica la forma de la región que se va a crear.

ConstanteValorDescripción
QRegion::Rectangle0la región cubre todo el rectángulo.
QRegion::Ellipse1La región es una elipse dentro del rectángulo.

QRegion::const_iterator

Un iterador sobre los rectángulos no superpuestos que conforman la región.

La unión de todos los rectángulos es igual a la región original.

QRegion no ofrece iteradores mutables.

Véase también begin() y end().

QRegion::const_reverse_iterator

Un iterador inverso sobre los rectángulos no superpuestos que conforman la región.

La unión de todos los rectángulos es igual a la región original.

QRegion No ofrece iteradores mutables.

Véase también rbegin() y rend().

Documentación de las funciones miembro

QRegion::QRegion()

Crea una región vacía.

Véase también isEmpty().

QRegion::QRegion(const QBitmap &bm)

Crea una región a partir del mapa de bits bm.

La región resultante está formada por los píxeles del mapa de bits bm que cumplen la condición Qt::color1, como si cada píxel fuera un rectángulo de 1 por 1.

Este constructor puede crear regiones complejas que ralentizarán el proceso de dibujo cuando se utilicen. Ten en cuenta que el dibujo de mapas de píxeles enmascarados se puede realizar mucho más rápido utilizando QPixmap::setMask().

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

Crea una región poligonal a partir de la matriz de puntos a con la regla de relleno especificada por fillRule.

Si fillRule es Qt::WindingFill, la región poligonal se define utilizando el algoritmo de enrollamiento; si es Qt::OddEvenFill, se utiliza el algoritmo de relleno par-impar.

Advertencia: Este constructor puede utilizarse para crear regiones complejas que ralentizarán el proceso de dibujo cuando se utilicen.

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

Crea una región rectangular o elíptica.

Si ` t ` es ` Rectangle`, la región es el rectángulo relleno (`x`, ` y`, ` w`, ` h`). Si ` t ` es ` Ellipse`, la región es la elipse rellena con centro en (`x + w / 2`, ` y + h / 2) y tamaño (`w `, `h`).

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

Crea una región basada en el rectángulo r con el tipo de región t.

Si el rectángulo no es válido, se creará una región nula.

Esta es una función sobrecargada.

Véase también QRegion::RegionType.

QRegion::QRegion(const QRegion &r)

Crea una nueva región que es igual a la región r.

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

Crea una nueva región a partir de la región other. Tras la llamada, other es nulo.

Véase también isNull().

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

Devuelve un objeto ` const_iterator ` que apunta al inicio del rango de rectángulos no superpuestos que conforman la región.

La unión de todos los rectángulos es igual a la región original.

Véase también rbegin(), cbegin() y end().

[noexcept] QRect QRegion::boundingRect() const

Devuelve el rectángulo delimitador de esta región. Si la región está vacía, devuelve un rectángulo que es QRect::isNull().

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

Es lo mismo que « begin()».

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

Es lo mismo que « end()».

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

Devuelve ` true ` si la región contiene el punto ` p`; en caso contrario, devuelve ` false`.

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

Devuelve ` true ` si la región se solapa con el rectángulo ` r`; en caso contrario, devuelve ` false`.

Esta es una función sobrecargada.

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

Es lo mismo que « rbegin()».

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

Es lo mismo que « rend()».

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

Devuelve un ` const_iterator ` que apunta a un punto situado justo después del final de los rectángulos no superpuestos que conforman la región.

La unión de todos los rectángulos es igual a la región original.

Véanse también rend(), cend() y begin().

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

Devuelve un ` QRegion ` equivalente al ` hrgn` proporcionado.

Esta función se introdujo en Qt 6.0.

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

Devuelve una región que es la intersección de esta región y la región dada rect.

Véase también subtracted(), united() y xored().

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

Devuelve una región que es la intersección de esta región y r.

Intersección de regiones

La figura muestra la intersección de dos regiones elípticas.

Véanse también subtracted(), united() y xored().

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

Devuelve ` true ` si esta región se cruza con ` rect`; en caso contrario, devuelve ` false`.

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

Devuelve « true » si esta región se cruza con « region »; en caso contrario, devuelve « false ».

bool QRegion::isEmpty() const

Devuelve « true » si la región está vacía; en caso contrario, devuelve « false ». Una región vacía es aquella que no contiene ningún punto.

Ejemplo:

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

Devuelve « true » si la región está vacía; en caso contrario, devuelve « false ». Una región vacía es aquella que no contiene ningún punto. Esta función es idéntica a isEmpty

Véase también isEmpty().

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

Devuelve un objeto ` const_reverse_iterator ` que apunta al inicio del rango de rectángulos no superpuestos que conforman la región.

La unión de todos los rectángulos es igual a la región original.

Véase también begin(), crbegin() y rend().

[noexcept] int QRegion::rectCount() const

Devuelve el número de rectángulos que componen esta región. Es lo mismo que ` end() - begin()`.

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

Devuelve un conjunto de rectángulos no superpuestos que conforman la región. El conjunto sigue siendo válido hasta la siguiente llamada a un método mutante (no const) sobre esta región.

La unión de todos los rectángulos es igual a la región original.

Nota: Esta función también existía en Qt 5, pero devolvía un objeto ` QVector` <QRect>.

Esta función se introdujo en Qt 6.8.

Véase también setRects().

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

Devuelve un objeto ` const_reverse_iterator ` que apunta a una posición situada justo después del final del rango de rectángulos no superpuestos que conforman la región.

La unión de todos los rectángulos es igual a la región original.

Véase también end(), crend() y rbegin().

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

Establece la región utilizando la matriz de rectángulos especificada por « rects ». Los rectángulos deben estar ordenados de forma óptima según Y-X y cumplir las siguientes restricciones:

  • Los rectángulos no deben intersecarse.
  • Todos los rectángulos con una misma coordenada superior deben tener la misma altura.
  • No puede haber dos rectángulos contiguos horizontalmente (en ese caso, deben combinarse en un único rectángulo más ancho).
  • Los rectángulos deben estar ordenados en orden ascendente, con Y como clave de ordenación principal y X como clave de ordenación secundaria.

Nota: Por razones históricas, rects.size() debe ser menor que INT_MAX (véase rectCount()).

Esta función se introdujo en Qt 6.8.

Véase también rects().

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

Devuelve una región que se obtiene restando r de esta región.

Resta de regiones

La figura muestra el resultado al restar la elipse de la derecha de la elipse de la izquierda (left - right).

Véanse también intersected(), united() y xored().

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

Intercambia esta región con other. Esta operación es muy rápida y nunca falla.

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

Devuelve un HRGN equivalente a la región indicada.

Esta función se introdujo en Qt 6.0.

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

Traslada (desplaza) la región dx a lo largo del eje X y dy a lo largo del eje Y.

void QRegion::translate(const QPoint &point)

Traslada la región point.x() a lo largo del eje x y point.y() a lo largo del eje y, con respecto a la posición actual. Los valores positivos desplazan la región hacia la derecha y hacia abajo.

Traslada a la posición indicada point.

Esta es una función sobrecargada.

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

Devuelve una copia de la región desplazada dx a lo largo del eje x y dy a lo largo del eje y, con respecto a la posición actual. Los valores positivos desplazan la región hacia la derecha y hacia abajo.

Véase también translate().

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

Devuelve una copia del rectángulo que se ha desplazado p.x() a lo largo del eje x y p.y() a lo largo del eje y, con respecto a la posición actual. Los valores positivos desplazan el rectángulo hacia la derecha y hacia abajo.

Esta es una función sobrecargada.

Véase también translate().

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

Devuelve una región que es la unión de esta región y la especificada en rect.

Véase también intersected(), subtracted() y xored().

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

Devuelve una región que es la unión de esta región y r.

Unión Regional

La figura muestra la unión de dos regiones elípticas.

Véanse también intersected(), subtracted() y xored().

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

Devuelve una región que es el «o exclusivo» (XOR) de esta región y r.

Región XORed

La figura muestra el OR exclusivo de dos regiones elípticas.

Véanse también intersected(), united() y subtracted().

QRegion::operator QVariant() const

Devuelve la región como un QVariant

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

Devuelve « true » si esta región es diferente de la región « other »; en caso contrario, devuelve « false ».

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

Aplica la función « intersected()» a esta región y « r ». « r1&r2 » es equivalente a « r1.intersected(r2) ».

Véase también intersected().

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

Esta es una función sobrecargada.

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

Aplica la función « intersected()» a esta región y « r », y asigna el resultado a esta región. « r1&=r2 » es equivalente a « r1 = r1.intersected(r2)».

Véase también intersected().

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

Esta es una función sobrecargada.

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

Aplica la función united() a esta región y r. r1+r2 es equivalente a r1.united(r2).

Véase también united() y operator|().

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

Esta es una función sobrecargada.

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

Devuelve una región que es la unión de esta región con la especificada en rect.

Véase también united().

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

Aplica la función « united()» a esta región y « r », y asigna el resultado a esta región. « r1+=r2 » es equivalente a « r1 = r1.united(r2) ».

Véase también intersected().

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

Aplica la función « subtracted()» a esta región y a « r ». « r1-r2 » es equivalente a « r1.subtracted(r2) ».

Véase también subtracted().

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

Aplica la función « subtracted()» a esta región y « r », y asigna el resultado a esta región. « r1-=r2 » es equivalente a « r1 = r1.subtracted(r2) ».

Véase también subtracted().

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

Asigna « other » a esta instancia de « QRegion ».

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

Asigna ` r ` a esta región y devuelve una referencia a la región.

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

Devuelve « true » si la región es igual a « r »; en caso contrario, devuelve «false».

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

Aplica la función xored() a esta región y r. r1^r2 es equivalente a r1.xored(r2).

Véase también xored().

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

Aplica la función « xored()» a esta región y « r », y asigna el resultado a esta región. « r1^=r2 » es equivalente a « r1 = r1.xored(r2) ».

Véase también xored().

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

Aplica la función united() a esta región y r. r1|r2 es equivalente a r1.united(r2).

Véase también united() y operator+().

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

Aplica la función « united()» a esta región y « r », y asigna el resultado a esta región. « r1|=r2 » es equivalente a « r1 = r1.united(r2) ».

Véase también united().

Elementos no miembros relacionados

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

Escribe la región r en el flujo s y devuelve una referencia al flujo.

Véase también el formato de los operadores de QDataStream.

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

Lee una región del flujo s y la almacena en r, y devuelve una referencia al flujo.

Véase también el formato de los operadores de QDataStream.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.