From befbee33497290b6e5448b1249e4ace83fcda27b Mon Sep 17 00:00:00 2001 From: Andreas Aardal Hanssen Date: Wed, 5 Aug 2009 15:14:25 +0200 Subject: First round of documentation for QGraphicsEffect. Discovered some weaknesses in the API; next round is to discuss and fix these. Reviewed-by: TrustMe --- src/gui/graphicsview/qgraphicseffect.cpp | 179 +++++++++++++++++++++++++++---- src/gui/graphicsview/qgraphicseffect.h | 2 + src/gui/graphicsview/qgraphicsitem.cpp | 1 + 3 files changed, 162 insertions(+), 20 deletions(-) diff --git a/src/gui/graphicsview/qgraphicseffect.cpp b/src/gui/graphicsview/qgraphicseffect.cpp index e63af3c..6f60ab9 100644 --- a/src/gui/graphicsview/qgraphicseffect.cpp +++ b/src/gui/graphicsview/qgraphicseffect.cpp @@ -39,6 +39,61 @@ ** ****************************************************************************/ +/*! + \class QGraphicsEffect + \brief The QGraphicsEffect class is the base class for all graphics effects. + \since 4.6 + \ingroup multimedia + \ingroup graphicsview-api + + 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(); if the effect is disabled, the source is + rendered directly. + + If you want to add a visual effect to a QGraphicsItem, you can either use + one of the standard effects, or create your own effect by making a subclass + of QGraphicsEffect. + + Qt provides several standard effects, including: + + \list + \o QGraphicsGrayScaleEffect - renders the item in shades of gray + \o QGraphicsColorizeEffect - renders the item in shades of any given color + \o QGraphicsPixelizeEffect - pixelizes the item with any pixel size + \o QGraphicsBlurEffect - blurs the item by a given radius + \o QGraphicsBloomEffect - applies a blooming / glowing effect + \o QGraphicsFrameEffect - adds a frame to the item + \o QGraphicsShadowEffect - renders a dropshadow behind the item + \endlist + + If all you want is to add an effect to an item, you should visit the + documentation for the specific effect to learn more about how each effect + can be used. + + If you want to create your own custom effect, you can start by creating a + subclass of QGraphicsEffect (or any of the existing effects), and + reimplement the virtual function draw(). This function is called whenever + the effect needs to redraw. draw() has two arguments: the painter, and a + pointer to the source (QGraphicsEffectSource). The source provides extra + context information, such as a pointer to the item that is rendering the + effect, any cached pixmap data, and the device rect bounds. See the draw() + documentation for more details. You can also get a pointer to the current + source by calling source(). + + If your effect changes, you can call update() to request a redraw. If your + custom effect changes the bounding rectangle of the source (e.g., a radial + glow effect may need to apply an extra margin), you can reimplement the + virtual boundingRectFor() function, and call updateBoundingRect() to notify + the framework whenever this rectangle changes. The virtual + sourceBoundingRectChanged() function is called to notify the effects that + the source's bounding rectangle has changed (e.g., if the source is a + QGraphicsRectItem, then if the rectangle parameters have changed). + + \sa QGraphicsItem::setGraphicsEffect() +*/ + #include "qgraphicseffect_p.h" #ifndef QT_NO_GRAPHICSVIEW @@ -109,44 +164,78 @@ QGraphicsEffectSource::~QGraphicsEffectSource() {} QRect QGraphicsEffectSource::deviceRect() const -{ return d_func()->deviceRect(); } +{ + return d_func()->deviceRect(); +} QRectF QGraphicsEffectSource::boundingRect(Qt::CoordinateSystem system) const -{ return d_func()->boundingRect(system); } +{ + return d_func()->boundingRect(system); +} const QGraphicsItem *QGraphicsEffectSource::graphicsItem() const -{ return d_func()->graphicsItem(); } +{ + return d_func()->graphicsItem(); +} const QStyleOption *QGraphicsEffectSource::styleOption() const -{ return d_func()->styleOption(); } +{ + return d_func()->styleOption(); +} void QGraphicsEffectSource::draw(QPainter *painter) -{ d_func()->draw(painter); } +{ + d_func()->draw(painter); +} void QGraphicsEffectSource::update() -{ d_func()->update(); } +{ + d_func()->update(); +} bool QGraphicsEffectSource::isPixmap() const -{ return d_func()->isPixmap(); } +{ + return d_func()->isPixmap(); +} QPixmap QGraphicsEffectSource::pixmap(Qt::CoordinateSystem system, QPoint *offset) const -{ return d_func()->pixmap(system, offset); } - +{ + return d_func()->pixmap(system, offset); +} +/*! + Constructs a new QGraphicsEffect instance. +*/ QGraphicsEffect::QGraphicsEffect() : QObject(*new QGraphicsEffectPrivate, 0) -{} +{ + // ### parent? +} +/*! + \internal +*/ QGraphicsEffect::QGraphicsEffect(QGraphicsEffectPrivate &dd) : QObject(dd, 0) -{} +{ +} +/*! + Removes the effect from the source, and destroys the graphics effect. +*/ QGraphicsEffect::~QGraphicsEffect() { Q_D(QGraphicsEffect); d->setGraphicsEffectSource(0); } +/*! + Returns the bounding rectangle for this effect (i.e., the bounding + rectangle of the source, adjusted by any margins applied by the effect + itself). + + \sa boundingRectFor(), updateBoundingRect() +*/ QRectF QGraphicsEffect::boundingRect() const { Q_D(const QGraphicsEffect); @@ -155,11 +244,35 @@ QRectF QGraphicsEffect::boundingRect() const return QRectF(); } +/*! + Returns the bounding rectangle for this effect, given the provided source + \a rect. 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. + + \sa boundingRect() +*/ QRectF QGraphicsEffect::boundingRectFor(const QRectF &rect) const { return rect; } +/*! + \property QGraphicsEffect::enabled + \brief whether the effect is enabled or not. + + If an effect is disabled, the source will be rendered with as normal, with + no interference from the effect. If the effect is enabled (default), the + source will be rendered with the effect applied. + + This property is provided so that you can disable certain effects on slow + platforms, in order to ensure that the user interface is responsive. +*/ +bool QGraphicsEffect::isEnabled() const +{ + Q_D(const QGraphicsEffect); + return d->isEnabled; +} void QGraphicsEffect::setEnabled(bool enable) { Q_D(QGraphicsEffect); @@ -172,18 +285,26 @@ void QGraphicsEffect::setEnabled(bool enable) d->source->update(); } -bool QGraphicsEffect::isEnabled() const -{ - Q_D(const QGraphicsEffect); - return d->isEnabled; -} +/*! + Returns a pointer to the source, which provides extra context information + that can be useful for the effect. + \sa draw() +*/ QGraphicsEffectSource *QGraphicsEffect::source() const { Q_D(const QGraphicsEffect); return d->source; } +/*! + This function notifies the effect framework that the effect's bounding + rectangle has changed. As a custom effect author, you must call this + function whenever you change any parameters that will cause the virtual + boundingRectFor() function to return a different value. + + \sa boundingRectFor(), boundingRect() +*/ void QGraphicsEffect::updateBoundingRect() { Q_D(QGraphicsEffect); @@ -191,15 +312,33 @@ void QGraphicsEffect::updateBoundingRect() d->source->update(); } -void QGraphicsEffect::sourceChanged() {} -void QGraphicsEffect::sourceBoundingRectChanged() {} +/*! + 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. +*/ +void QGraphicsEffect::sourceChanged() +{ +} + +/*! + This virtual function is called by QGraphicsEffect to notify the effect + that the source's bounding rectangle has changed. If the effect applies any + cache, then this cache must be purged in order to reflect the new + appearance of the source. +*/ +void QGraphicsEffect::sourceBoundingRectChanged() +{ +} QGraphicsGrayscaleEffect::QGraphicsGrayscaleEffect() : QGraphicsEffect(*new QGraphicsGrayscaleEffectPrivate) -{} +{ +} QGraphicsGrayscaleEffect::~QGraphicsGrayscaleEffect() -{} +{ +} void QGraphicsGrayscaleEffect::draw(QPainter *painter, QGraphicsEffectSource *source) { diff --git a/src/gui/graphicsview/qgraphicseffect.h b/src/gui/graphicsview/qgraphicseffect.h index 79e7c3d..bb79563 100644 --- a/src/gui/graphicsview/qgraphicseffect.h +++ b/src/gui/graphicsview/qgraphicseffect.h @@ -99,6 +99,7 @@ public: QGraphicsEffect(); virtual ~QGraphicsEffect(); + // ### make protected? virtual QRectF boundingRectFor(const QRectF &rect) const; QRectF boundingRect() const; @@ -108,6 +109,7 @@ public: public Q_SLOTS: void setEnabled(bool enable); + // ### add update() slot protected: QGraphicsEffect(QGraphicsEffectPrivate &d); diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp index 78a5410..07a063e 100644 --- a/src/gui/graphicsview/qgraphicsitem.cpp +++ b/src/gui/graphicsview/qgraphicsitem.cpp @@ -2218,6 +2218,7 @@ void QGraphicsItem::setGraphicsEffect(QGraphicsEffect *effect) return; if (d_ptr->graphicsEffect && effect) { + // ### This seems wrong - the effect should automatically be deleted. qWarning("QGraphicsItem::setGraphicsEffect: Attempting to set QGraphicsEffect " "%p on %p, which already has an effect installed", effect, this); return; -- cgit v0.12