QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
QgsPaintEffect Class Referenceabstract

Base class for visual effects which can be applied to QPicture drawings. More...

#include <qgspainteffect.h>

Inheritance diagram for QgsPaintEffect:
Inheritance graph
[legend]

Public Types

enum  DrawMode { Modifier , Render , ModifyAndRender }
 Drawing modes for effects. More...
 

Public Member Functions

 QgsPaintEffect ()=default
 Constructor for QgsPaintEffect. More...
 
 QgsPaintEffect (const QgsPaintEffect &other)
 
virtual ~QgsPaintEffect ()
 
virtual void begin (QgsRenderContext &context)
 Begins intercepting paint operations to a render context. More...
 
virtual QgsPaintEffectclone () const =0
 Duplicates an effect by creating a deep copy of the effect. More...
 
DrawMode drawMode () const
 Returns the draw mode for the effect. More...
 
bool enabled () const
 Returns whether the effect is enabled. More...
 
virtual void end (QgsRenderContext &context)
 Ends interception of paint operations to a render context, and draws the result to the render context after being modified by the effect. More...
 
virtual QVariantMap properties () const =0
 Returns the properties describing the paint effect encoded in a string format. More...
 
virtual bool readProperties (const QDomElement &element)
 Restores the effect to the state described by a DOM element. More...
 
virtual void readProperties (const QVariantMap &props)=0
 Reads a string map of an effect's properties and restores the effect to the state described by the properties map. More...
 
virtual void render (QPicture &picture, QgsRenderContext &context)
 Renders a picture using the effect. More...
 
virtual bool saveProperties (QDomDocument &doc, QDomElement &element) const
 Saves the current state of the effect to a DOM element. More...
 
void setDrawMode (DrawMode drawMode)
 Sets the draw mode for the effect. More...
 
void setEnabled (bool enabled)
 Sets whether the effect is enabled. More...
 
virtual QString type () const =0
 Returns the effect type. More...
 

Protected Member Functions

virtual QRectF boundingRect (const QRectF &rect, const QgsRenderContext &context) const
 Returns the bounding rect required for drawing the effect. More...
 
virtual void draw (QgsRenderContext &context)=0
 Handles drawing of the effect's result on to the specified render context. More...
 
void drawSource (QPainter &painter)
 Draws the source QPicture onto the specified painter. More...
 
void fixQPictureDpi (QPainter *painter) const
 Applies a workaround to a QPainter to avoid an issue with incorrect scaling when drawing QPictures. More...
 
QPointF imageOffset (const QgsRenderContext &context) const
 Returns the offset which should be used when drawing the source image on to a destination render context. More...
 
const QPicture * source () const
 Returns the source QPicture. More...
 
QImage * sourceAsImage (QgsRenderContext &context)
 Returns the source QPicture rendered to a new QImage. More...
 

Protected Attributes

DrawMode mDrawMode = ModifyAndRender
 
bool mEnabled = true
 
bool requiresQPainterDpiFix = true
 

Friends

class QgsEffectStack
 

Detailed Description

Base class for visual effects which can be applied to QPicture drawings.

QgsPaintEffect objects can be used to modify QPicture drawings prior to rendering them with a QPainter operation. There are two methods for drawing using an effect, either drawing a picture directly, or by intercepting drawing operations to a render context.

To directly draw a picture, use the render() method with a source QPicture and destination render context.

Intercepting drawing operations to a render context is achieved by first calling the begin() method, passing a render context. Any drawing operations performed on the render context will not directly affect the context's paint device. When the drawing operations have been completed, call the end() method. This will perform the paint effect on the intercepted drawing operations and render the result to the render context's paint device.

See also
QgsPaintEffectRegistry

Definition at line 51 of file qgspainteffect.h.

Member Enumeration Documentation

◆ DrawMode

Drawing modes for effects.

These modes are used only when effects are drawn as part of an effects stack

See also
QgsEffectStack
Enumerator
Modifier 

The result of the effect is not rendered, but is passed on to following effects in the stack.

Render 

The result of the effect is rendered on the destination, but does not affect subsequent effects in the stack.

ModifyAndRender 

The result of the effect is both rendered and passed on to subsequent effects in the stack.

Definition at line 102 of file qgspainteffect.h.

Constructor & Destructor Documentation

◆ QgsPaintEffect() [1/2]

QgsPaintEffect::QgsPaintEffect ( )
default

Constructor for QgsPaintEffect.

◆ QgsPaintEffect() [2/2]

QgsPaintEffect::QgsPaintEffect ( const QgsPaintEffect other)

Definition at line 28 of file qgspainteffect.cpp.

◆ ~QgsPaintEffect()

QgsPaintEffect::~QgsPaintEffect ( )
virtual

Definition at line 35 of file qgspainteffect.cpp.

Member Function Documentation

◆ begin()

void QgsPaintEffect::begin ( QgsRenderContext context)
virtual

Begins intercepting paint operations to a render context.

When the corresponding end() member is called all intercepted paint operations will be drawn to the render context after being modified by the effect.

Parameters
contextdestination render context
See also
end
render

Definition at line 90 of file qgspainteffect.cpp.

◆ boundingRect()

QRectF QgsPaintEffect::boundingRect ( const QRectF &  rect,
const QgsRenderContext context 
) const
protectedvirtual

Returns the bounding rect required for drawing the effect.

This method can be used to expand the bounding rect of a source picture to account for offset or blurring effects.

Parameters
rectoriginal source bounding rect
contextdestination render context
Returns
modified bounding rect
See also
sourceAsImage

Reimplemented in QgsTransformEffect, QgsShadowEffect, QgsGlowEffect, and QgsBlurEffect.

Definition at line 175 of file qgspainteffect.cpp.

◆ clone()

virtual QgsPaintEffect* QgsPaintEffect::clone ( ) const
pure virtual

Duplicates an effect by creating a deep copy of the effect.

Returns
clone of paint effect

Implemented in QgsTransformEffect, QgsInnerShadowEffect, QgsDropShadowEffect, QgsDrawSourceEffect, QgsInnerGlowEffect, QgsOuterGlowEffect, QgsEffectStack, QgsColorEffect, and QgsBlurEffect.

◆ draw()

virtual void QgsPaintEffect::draw ( QgsRenderContext context)
protectedpure virtual

Handles drawing of the effect's result on to the specified render context.

Derived classes must reimplement this method to apply any transformations to the source QPicture and draw the result using the context's painter.

Parameters
contextdestination render context
See also
drawSource

Implemented in QgsTransformEffect, QgsShadowEffect, QgsDrawSourceEffect, QgsGlowEffect, QgsEffectStack, QgsColorEffect, and QgsBlurEffect.

◆ drawMode()

DrawMode QgsPaintEffect::drawMode ( ) const
inline

Returns the draw mode for the effect.

This property only has an effect if the paint effect is used in a QgsEffectStack.

Returns
draw mode for effect
See also
setDrawMode

Definition at line 211 of file qgspainteffect.h.

◆ drawSource()

void QgsPaintEffect::drawSource ( QPainter &  painter)
protected

Draws the source QPicture onto the specified painter.

Handles scaling of the picture to account for the destination painter's DPI.

Parameters
painterdestination painter
See also
source
sourceAsImage

Definition at line 131 of file qgspainteffect.cpp.

◆ enabled()

bool QgsPaintEffect::enabled ( ) const
inline

Returns whether the effect is enabled.

Returns
true if effect is enabled
See also
setEnabled

Definition at line 196 of file qgspainteffect.h.

◆ end()

void QgsPaintEffect::end ( QgsRenderContext context)
virtual

Ends interception of paint operations to a render context, and draws the result to the render context after being modified by the effect.

Parameters
contextdestination render context
See also
begin

Definition at line 105 of file qgspainteffect.cpp.

◆ fixQPictureDpi()

void QgsPaintEffect::fixQPictureDpi ( QPainter *  painter) const
protected

Applies a workaround to a QPainter to avoid an issue with incorrect scaling when drawing QPictures.

This may need to be called by derived classes prior to rendering results onto a painter.

Parameters
painterdestination painter

Definition at line 181 of file qgspainteffect.cpp.

◆ imageOffset()

QPointF QgsPaintEffect::imageOffset ( const QgsRenderContext context) const
protected

Returns the offset which should be used when drawing the source image on to a destination render context.

Parameters
contextdestination render context
Returns
point offset for image top left corner
See also
sourceAsImage

Definition at line 170 of file qgspainteffect.cpp.

◆ properties()

virtual QVariantMap QgsPaintEffect::properties ( ) const
pure virtual

Returns the properties describing the paint effect encoded in a string format.

Returns
string map of properties, in the form property key, value
See also
readProperties
saveProperties

Implemented in QgsTransformEffect, QgsShadowEffect, QgsDrawSourceEffect, QgsGlowEffect, QgsEffectStack, QgsColorEffect, and QgsBlurEffect.

◆ readProperties() [1/2]

bool QgsPaintEffect::readProperties ( const QDomElement &  element)
virtual

Restores the effect to the state described by a DOM element.

Parameters
elementDOM element describing an effect's state
Returns
true if read was successful
See also
saveProperties

Reimplemented in QgsEffectStack.

Definition at line 68 of file qgspainteffect.cpp.

◆ readProperties() [2/2]

virtual void QgsPaintEffect::readProperties ( const QVariantMap &  props)
pure virtual

Reads a string map of an effect's properties and restores the effect to the state described by the properties map.

Parameters
propseffect properties encoded in a string map
See also
properties

Implemented in QgsTransformEffect, QgsShadowEffect, QgsDrawSourceEffect, QgsGlowEffect, QgsEffectStack, QgsColorEffect, and QgsBlurEffect.

◆ render()

void QgsPaintEffect::render ( QPicture &  picture,
QgsRenderContext context 
)
virtual

Renders a picture using the effect.

Parameters
picturesource QPicture to render
contextdestination render context
See also
begin

Definition at line 80 of file qgspainteffect.cpp.

◆ saveProperties()

bool QgsPaintEffect::saveProperties ( QDomDocument &  doc,
QDomElement &  element 
) const
virtual

Saves the current state of the effect to a DOM element.

The default behavior is to save the properties string map returned by properties().

Parameters
docdestination DOM document
elementdestination DOM element
Returns
true if save was successful
See also
readProperties

Reimplemented in QgsEffectStack.

Definition at line 55 of file qgspainteffect.cpp.

◆ setDrawMode()

void QgsPaintEffect::setDrawMode ( const QgsPaintEffect::DrawMode  drawMode)

Sets the draw mode for the effect.

This property only has an effect if the paint effect is used in a QgsEffectStack.

Parameters
drawModedraw mode for effect
See also
drawMode

Definition at line 50 of file qgspainteffect.cpp.

◆ setEnabled()

void QgsPaintEffect::setEnabled ( bool  enabled)

Sets whether the effect is enabled.

Parameters
enabledset to false to disable the effect
See also
enabled

Definition at line 45 of file qgspainteffect.cpp.

◆ source()

const QPicture* QgsPaintEffect::source ( ) const
inlineprotected

Returns the source QPicture.

The draw() member can utilize this when drawing the effect.

Returns
source QPicture
See also
drawSource
sourceAsImage

Definition at line 252 of file qgspainteffect.h.

◆ sourceAsImage()

QImage * QgsPaintEffect::sourceAsImage ( QgsRenderContext context)
protected

Returns the source QPicture rendered to a new QImage.

The draw() member can utilize this when drawing the effect. The image will be padded or cropped from the original source QPicture by the results of the boundingRect() method. The result is cached to speed up subsequent calls to sourceAsImage.

Returns
source QPicture rendered to an image
See also
drawSource
source
imageOffset
boundingRect

Definition at line 145 of file qgspainteffect.cpp.

◆ type()

virtual QString QgsPaintEffect::type ( ) const
pure virtual

Returns the effect type.

Returns
unique string representation of the effect type

Implemented in QgsTransformEffect, QgsInnerShadowEffect, QgsDropShadowEffect, QgsDrawSourceEffect, QgsInnerGlowEffect, QgsOuterGlowEffect, QgsEffectStack, QgsColorEffect, and QgsBlurEffect.

Friends And Related Function Documentation

◆ QgsEffectStack

friend class QgsEffectStack
friend

Definition at line 307 of file qgspainteffect.h.

Member Data Documentation

◆ mDrawMode

DrawMode QgsPaintEffect::mDrawMode = ModifyAndRender
protected

Definition at line 224 of file qgspainteffect.h.

◆ mEnabled

bool QgsPaintEffect::mEnabled = true
protected

Definition at line 223 of file qgspainteffect.h.

◆ requiresQPainterDpiFix

bool QgsPaintEffect::requiresQPainterDpiFix = true
protected

Definition at line 225 of file qgspainteffect.h.


The documentation for this class was generated from the following files: