En esta página

QGraphicsEffect Class

La clase QGraphicsEffect es la clase base de todos los efectos gráficos. Más información...

Encabezado: #include <QGraphicsEffect>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: QObject
Heredado por:

QGraphicsBlurEffect, ` QGraphicsColorizeEffect`, ` QGraphicsDropShadowEffect` y QGraphicsOpacityEffect

Tipos públicos

enum ChangeFlag { SourceAttached, SourceDetached, SourceBoundingRectChanged, SourceInvalidated }
flags ChangeFlags
enum PixmapPadMode { NoPad, PadToTransparentBorder, PadToEffectiveBoundingRect }

Propiedades

Funciones públicas

QGraphicsEffect(QObject *parent = nullptr)
virtual ~QGraphicsEffect()
QRectF boundingRect() const
virtual QRectF boundingRectFor(const QRectF &rect) const
bool isEnabled() const

Ranuras públicas

void setEnabled(bool enable)
void update()

Señales

void enabledChanged(bool enabled)

Funciones protegidas

virtual void draw(QPainter *painter) = 0
void drawSource(QPainter *painter)
QRectF sourceBoundingRect(Qt::CoordinateSystem system = Qt::LogicalCoordinates) const
virtual void sourceChanged(QGraphicsEffect::ChangeFlags flags)
bool sourceIsPixmap() const
QPixmap sourcePixmap(Qt::CoordinateSystem system = Qt::LogicalCoordinates, QPoint *offset = nullptr, QGraphicsEffect::PixmapPadMode mode = PadToEffectiveBoundingRect) const
void updateBoundingRect()

Descripción detallada

Los efectos modifican la apariencia de los elementos al integrarse en el proceso de renderizado y actuar entre la fuente (por ejemplo, un ` QGraphicsPixmapItem`) y el dispositivo de destino (por ejemplo, la ventana gráfica de ` QGraphicsView`). Los efectos se pueden desactivar llamando a ` setEnabled(false)`. Si los efectos están desactivados, la fuente se renderiza directamente.

Para añadir un efecto visual a un QGraphicsItem, por ejemplo, puedes utilizar uno de los efectos estándar o, alternativamente, crear tu propio efecto mediante la creación de una subclase de QGraphicsEffect. A continuación, el efecto se puede instalar en el elemento utilizando QGraphicsItem::setGraphicsEffect().

Qt proporciona los siguientes efectos estándar:

Imagen de un pez sin ningún Graphical Effects

Efecto de desenfoque en una imagen de un pez

Efecto de color azul en una imagen de un pez

Efecto de opacidad en una imagen de un pez

Efecto de sombra proyectada en la imagen de un pez

Efectos de sombra proyectada con opacidad aplicados a una aplicación

Para obtener más información sobre cómo utilizar cada efecto, consulta la documentación específica de cada efecto.

Para crear tu propio efecto personalizado, crea una subclase de `QGraphicsEffect` (o de cualquier otro efecto existente) y reimplementa la función virtual ` draw()`. Esta función se invoca cada vez que el efecto necesita volver a dibujarse. La función ` draw()` toma como argumento el «pintor» con el que se va a dibujar. Para obtener más información, consulta la documentación de draw(). En la función draw() puedes llamar a sourcePixmap() para obtener un mapa de píxeles de la fuente del efecto gráfico, que luego podrás procesar.

Si tu efecto cambia, utiliza update() para solicitar un redibujado. Si tu efecto personalizado modifica el rectángulo delimitador de la fuente —por ejemplo, un efecto de resplandor radial podría necesitar aplicar un margen adicional—, puedes reimplementar la función virtual boundingRectFor() y llamar a updateBoundingRect() para notificar al marco de trabajo cada vez que este rectángulo cambie. La función virtual sourceChanged() se invoca para notificar a los efectos que la fuente ha cambiado de alguna manera; por ejemplo, si la fuente es un QGraphicsRectItem y han cambiado sus parámetros de rectángulo.

Véase también « QGraphicsItem::setGraphicsEffect()» y « QWidget::setGraphicsEffect()».

Documentación sobre los tipos de miembro

enum QGraphicsEffect::ChangeFlag
flags QGraphicsEffect::ChangeFlags

Esta enumeración describe los cambios introducidos en QGraphicsEffectSource.

ConstanteValorDescripción
QGraphicsEffect::SourceAttached0x1El efecto se instala en una fuente.
QGraphicsEffect::SourceDetached0x2El efecto se desinstala de una fuente.
QGraphicsEffect::SourceBoundingRectChanged0x4El rectángulo delimitador de la fuente ha cambiado.
QGraphicsEffect::SourceInvalidated0x8Ha cambiado el aspecto visual de la fuente.

El tipo ChangeFlags es un typedef para QFlags<ChangeFlag>. Almacena una combinación OR de valores de ChangeFlag.

enum QGraphicsEffect::PixmapPadMode

Esta enumeración describe cómo debe rellenarse el mapa de píxeles devuelto por ` sourcePixmap `.

ConstanteValorDescripción
QGraphicsEffect::NoPad0El mapa de píxeles no debe recibir ningún relleno adicional.
QGraphicsEffect::PadToTransparentBorder1El mapa de píxeles debe rellenarse para garantizar que tenga un borde completamente transparente.
QGraphicsEffect::PadToEffectiveBoundingRect2El mapa de píxeles debe rellenarse para que coincida con el rectángulo delimitador efectivo del efecto.

Documentación de la propiedad

enabled : bool

Esta propiedad se mantiene independientemente de si el efecto está activado o no.

Si un efecto está desactivado, la fuente se representará con normalidad, sin que el efecto interfiera. Si el efecto está activado, la fuente se representará con el efecto aplicado.

Esta propiedad está activada de forma predeterminada.

Mediante esta propiedad, puedes desactivar determinados efectos en plataformas lentas, con el fin de garantizar que la interfaz de usuario responda con rapidez.

Funciones de acceso:

bool isEnabled() const
void setEnabled(bool enable)

Señal de notificador:

void enabledChanged(bool enabled)

Documentación de funciones de miembro

QGraphicsEffect::QGraphicsEffect(QObject *parent = nullptr)

Crea una nueva instancia de QGraphicsEffect con el ` parent` especificado.

[virtual noexcept] QGraphicsEffect::~QGraphicsEffect()

Elimina el efecto de la fuente y destruye el efecto gráfico.

QRectF QGraphicsEffect::boundingRect() const

Devuelve el rectángulo delimitador efectivo de este efecto, es decir, el rectángulo delimitador de la fuente en coordenadas del dispositivo, ajustado en función de los márgenes que haya aplicado el propio efecto.

Véase también boundingRectFor() y updateBoundingRect().

[virtual] QRectF QGraphicsEffect::boundingRectFor(const QRectF &rect) const

Devuelve el rectángulo delimitador efectivo de este efecto, a partir del « rect » proporcionado en las coordenadas del dispositivo. Al escribir tu propio efecto personalizado, debes llamar a ` updateBoundingRect()` cada vez que se modifique algún parámetro que pueda hacer que esta función devuelva un valor diferente.

Véase también sourceBoundingRect().

[pure virtual protected] void QGraphicsEffect::draw(QPainter *painter)

Esta función virtual pura dibuja el efecto y se invoca cada vez que es necesario dibujar la fuente.

Reimplementa esta función en una subclase de ` QGraphicsEffect ` para proporcionar la implementación de dibujo del efecto, utilizando ` painter`.

Por ejemplo:

void MyGraphicsEffect::draw(QPainter *painter)
{
    //...
    QPoint offset;
    if (sourceIsPixmap()) {
        // No point in drawing in device coordinates (pixmap will be scaled anyways).
        const QPixmap pixmap = sourcePixmap(Qt::LogicalCoordinates, &offset);
        //...
        painter->drawPixmap(offset, pixmap);
    } else {
        // Draw pixmap in device coordinates to avoid pixmap scaling;
        const QPixmap pixmap = sourcePixmap(Qt::DeviceCoordinates, &offset);
        painter->setWorldTransform(QTransform());
        //...
        painter->drawPixmap(offset, pixmap);
    }
    //...
}

El usuario no debe llamar a esta función de forma explícita, ya que está pensada únicamente para su reimplementación.

[protected] void QGraphicsEffect::drawSource(QPainter *painter)

Dibuja la fuente directamente utilizando el ` painter` proporcionado.

Esta función solo debe llamarse desde ` QGraphicsEffect::draw()`.

Por ejemplo:

void MyGraphicsOpacityEffect::draw(QPainter *painter)
{
    // Fully opaque; draw directly without going through a pixmap.
    if (qFuzzyCompare(m_opacity, 1)) {
        drawSource(painter);
        return;
    }
    //...
}

Véase también QGraphicsEffect::draw().

[signal] void QGraphicsEffect::enabledChanged(bool enabled)

Esta señal se emite cada vez que se activa o desactiva el efecto. El parámetro ` enabled ` indica el nuevo estado de activación del efecto.

Nota: Señalde notificación para la propiedad enabled.

Véase también isEnabled().

[protected] QRectF QGraphicsEffect::sourceBoundingRect(Qt::CoordinateSystem system = Qt::LogicalCoordinates) const

Devuelve el rectángulo delimitador de la fuente mapeada a la dirección dada system.

Si se llama a esta función con ` Qt::DeviceCoordinates ` fuera de ` QGraphicsEffect::draw()`, se obtendrán resultados indefinidos, ya que no hay ningún contexto de dispositivo disponible.

Véase también ` draw()`.

[virtual protected] void QGraphicsEffect::sourceChanged(QGraphicsEffect::ChangeFlags flags)

QGraphicsEffect llama a esta función virtual para notificar que el efecto ha cambiado. Si el efecto utiliza alguna caché, esta debe purgarse para reflejar el nuevo aspecto de la fuente.

El ` flags ` describe qué ha cambiado.

[protected] bool QGraphicsEffect::sourceIsPixmap() const

Devuelve « true » si la fuente es, en realidad, un mapa de píxeles (pixmap), por ejemplo, un « QGraphicsPixmapItem ».

Esta función resulta útil con fines de optimización. Por ejemplo, no tiene sentido dibujar la fuente en coordenadas del dispositivo para evitar el escalado del mapa de píxeles si esta función devuelve true, ya que el mapa de píxeles de origen se escalará de todos modos.

[protected] QPixmap QGraphicsEffect::sourcePixmap(Qt::CoordinateSystem system = Qt::LogicalCoordinates, QPoint *offset = nullptr, QGraphicsEffect::PixmapPadMode mode = PadToEffectiveBoundingRect) const

Devuelve un mapa de píxeles con la fuente pintada en él.

El parámetro « system » especifica qué sistema de coordenadas se debe utilizar para la imagen de origen. El parámetro opcional « offset » devuelve el desplazamiento en el que se debe pintar el mapa de píxeles utilizando el pintor actual. Para controlar cómo se rellena el mapa de píxeles, utilice el parámetro « mode ».

El mapa de píxeles devuelto se recorta al rectángulo del dispositivo del pintor actual cuando system es Qt::DeviceCoordinates.

Llamar a esta función con ` Qt::DeviceCoordinates ` fuera de ` QGraphicsEffect::draw()` dará resultados indefinidos, ya que no hay ningún contexto de dispositivo disponible.

Véase también draw() y boundingRect().

[slot] void QGraphicsEffect::update()

Programa un redibujado del efecto. Llama a esta función siempre que sea necesario redibujar el efecto. Esta función no provoca un redibujado de la fuente.

Véase también updateBoundingRect().

[protected] void QGraphicsEffect::updateBoundingRect()

Esta función notifica al marco de efectos cuando ha cambiado el rectángulo delimitador del efecto. Como creador de efectos personalizados, debes llamar a esta función cada vez que modifiques cualquier parámetro que provoque que la función virtual ` boundingRectFor()` devuelva un valor diferente.

Esta función llamará a ` update()` si es necesario.

Véanse también boundingRectFor(), boundingRect() y sourceBoundingRect().

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