CopperSpice API  1.7.2
QGraphicsEffect Class Referenceabstract

The QGraphicsEffect class is the base class for all graphics effects. More...

Inheritance diagram for QGraphicsEffect:
QObject QGraphicsBlurEffect QGraphicsColorizeEffect QGraphicsDropShadowEffect QGraphicsOpacityEffect

Public Types

enum  PixmapPadMode
 

Public Signals

void enabledChanged (bool enabled)
 
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 

Public Slots

void setEnabled (bool enable)
 
void update ()
 
- Public Slots inherited from QObject
void deleteLater ()
 

Public Methods

 QGraphicsEffect (QObject *parent=nullptr)
 
virtual ~QGraphicsEffect ()
 
QRectF boundingRect () const
 
virtual QRectF boundingRectFor (const QRectF &rectF) const
 
bool isEnabled () const
 
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &objName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 

Protected Methods

virtual void draw (QPainter *painter) = 0
 
void drawSource (QPainter *painter)
 
QRectF sourceBoundingRect (Qt::CoordinateSystem system=Qt::LogicalCoordinates) const
 
virtual void sourceChanged (ChangeFlags flags)
 
bool sourceIsPixmap () const
 
QPixmap sourcePixmap (Qt::CoordinateSystem system=Qt::LogicalCoordinates, QPoint *offset=nullptr, PixmapPadMode mode=PadToEffectiveBoundingRect) const
 
void updateBoundingRect ()
 
- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 

Properties

 enabled
 
- Properties inherited from QObject
 objectName
 

Friends

class QGraphicsItem
 
class QWidget
 

Additional Inherited Members

- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 

Detailed Description

The QGraphicsEffect class is the base class for all graphics effects.

Effects alter the appearance of elements by hooking into the rendering pipeline and operating between the source (e.g., a QGraphicsPixmapItem) and the destination device (e.g., QGraphicsView's viewport). Effects can be disabled by calling setEnabled(false). If effects are disabled, the source is rendered directly.

To add a visual effect to a QGraphicsItem, for example, you can use one of the standard effects, or alternately, create your own effect by creating a subclass of QGraphicsEffect. The effect can then be installed on the item using QGraphicsItem::setGraphicsEffect().

CopperSpice provides the following standard effects:

>

For more information on how to use each effect, refer to the specific effect's documentation.

To create your own custom effect, create a subclass of QGraphicsEffect (or any other existing effects) and reimplement the virtual function draw(). This function is called whenever the effect needs to redraw. The draw() function takes the painter with which to draw as an argument. For more information, refer to the documentation for draw(). In the draw() function you can call sourcePixmap() to get a pixmap of the graphics effect source which you can then process.

If your effect changes use update() to request a redraw. If your custom effect changes the bounding rectangle of the source, for example a radial glow effect may need to apply an extra margin, reimplement boundingRectFor(). Then call updateBoundingRect() to notify the QGraphicsEffect object.

The method sourceChanged() is called to notify the effect the source has changed.

See also
QGraphicsItem::setGraphicsEffect(), QWidget::setGraphicsEffect()

Member Enumeration Documentation

This enum describes how the pixmap returned from sourcePixmap should be padded.

ConstantValueDescription
QGraphicsEffect::NoPad0 The pixmap should not receive any additional padding.
QGraphicsEffect::PadToTransparentBorder1 The pixmap should be padded to ensure it has a completely transparent border.
QGraphicsEffect::PadToEffectiveBoundingRect2 The pixmap should be padded to match the effective bounding rectangle of the effect.

Constructor & Destructor Documentation

QGraphicsEffect::QGraphicsEffect ( QObject parent = nullptr)

Constructs a new QGraphicsEffect instance having the specified parent.

QGraphicsEffect::~QGraphicsEffect ( )
virtual

Removes the effect from the source, and destroys the graphics effect.

Method Documentation

QRectF QGraphicsEffect::boundingRect ( ) const

Returns the effective bounding rectangle for this effect, i.e., the bounding rectangle of the source in device coordinates, adjusted by any margins applied by the effect itself.

See also
boundingRectFor(), updateBoundingRect()
QRectF QGraphicsEffect::boundingRectFor ( const QRectF rectF) const
virtual

Returns the effective bounding rectangle for this effect, given the provided rectF in the device coordinates. When writing you own custom effect, you must call updateBoundingRect() whenever any parameters are changed that may cause this this function to return a different value.

See also
sourceBoundingRect()

Reimplemented in QGraphicsDropShadowEffect, and QGraphicsBlurEffect.

void QGraphicsEffect::draw ( QPainter painter)
protectedpure virtual

This pure virtual function draws the effect and is called whenever the source needs to be drawn. Reimplement this function in a QGraphicsEffect subclass to provide the effect's drawing implementation, using painter.

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->drawPixmap(offset, pixmap);
}
...
}

This function should not be called explicitly by the user, since it is meant for reimplementation purposes only.

Implemented in QGraphicsOpacityEffect, QGraphicsDropShadowEffect, QGraphicsBlurEffect, and QGraphicsColorizeEffect.

void QGraphicsEffect::drawSource ( QPainter painter)
protected

Draws the source directly using the given painter.

This function should only be called from QGraphicsEffect::draw().

For example:

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

This signal is emitted whenever the effect is enabled or disabled. The enabled parameter holds the effect's new enabled state.

See also
isEnabled()
bool QGraphicsEffect::isEnabled ( ) const

Property documentation pending.

void QGraphicsEffect::setEnabled ( bool  enable)
slot

Property documentation pending.

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

Returns the bounding rectangle of the source mapped to the given system. Calling this function with Qt::DeviceCoordinates outside of QGraphicsEffect::draw() will give undefined behavior, as there is no device context available.

See also
draw()
void QGraphicsEffect::sourceChanged ( ChangeFlags  flags)
protectedvirtual

This virtual function is called by QGraphicsEffect to notify the effect that the source has changed. If the effect applies any cache, then this cache must be purged in order to reflect the new appearance of the source.

The flags describes what has changed.

bool QGraphicsEffect::sourceIsPixmap ( ) const
protected

Returns true if the source effectively is a pixmap, e.g., a QGraphicsPixmapItem.

This function is useful for optimization purposes. For instance, there's no point in drawing the source in device coordinates to avoid pixmap scaling if this function returns true - the source pixmap will be scaled anyways.

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

Returns a pixmap with the source painted into it. The system specifies which coordinate system to be used for the source. The optional offset parameter returns the offset where the pixmap should be painted at using the current painter. For control on how the pixmap is padded use the mode parameter. The returned pixmap is clipped to the current painter's device rectangle when system is Qt::DeviceCoordinates.

Calling this method with Qt::DeviceCoordinates outside of QGraphicsEffect::draw() will give undefined behavior, as there is no device context available.

See also
draw(), boundingRect()
void QGraphicsEffect::update ( )
slot

Schedules a redraw of the effect. Call this method whenever the effect needs to be redrawn. Does not trigger a redraw of the source.

See also
updateBoundingRect()
void QGraphicsEffect::updateBoundingRect ( )
protected

Notifies the effect the bounding rectangle has changed. As a custom effect author you must call this method whenever you change any parameters that will cause boundingRectFor() to return a different value. This method will call update() if necessary.

See also
boundingRectFor(), boundingRect(), sourceBoundingRect()

Property Documentation

QGraphicsEffect::enabled

This property holds whether the effect is enabled or not. This property is enabled by default.

If an effect is disabled, the source will be rendered with as normal, with no interference from the effect. If the effect is enabled, the source will be rendered with the effect applied. Using this property, you can disable certain effects on slow platforms, in order to ensure that the user interface is responsive.

PropertiesClass Methods
read isEnabled
write setEnabled
notify enabledChanged