QgsPaintEffect class

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

Reference

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.

Derived classes

class QgsBlurEffect: A paint effect which blurs a source picture, using a number of different blur methods.
class QgsColorEffect: A paint effect which alters the colors (e.g., brightness, contrast) in a source picture.
class QgsDrawSourceEffect: A paint effect which draws the source picture with minor or no alterations.
class QgsEffectStack: A paint effect which consists of a stack of other chained paint effects.
class QgsGlowEffect: Base class for paint effect which draw a glow inside or outside a picture.
class QgsShadowEffect: Base class for paint effects which offset, blurred shadows.
class QgsTransformEffect: A paint effect which applies transformations (such as move, scale and rotate) to a picture.

Public types

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

Constructors, destructors, conversion operators

QgsPaintEffect() defaulted: Constructor for QgsPaintEffect.

Public functions

void begin(QgsRenderContext& context) virtual: Begins intercepting paint operations to a render context.
auto clone() const -> QgsPaintEffect* pure virtual: Duplicates an effect by creating a deep copy of the effect.
auto drawMode() const -> DrawMode: Returns the draw mode for the effect.
auto enabled() const -> bool: Returns whether the effect is enabled.
void 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.
auto properties() const -> QgsStringMap pure virtual: Returns the properties describing the paint effect encoded in a string format.
void readProperties(const QgsStringMap& props) pure virtual: Reads a string map of an effect's properties and restores the effect to the state described by the properties map.
auto readProperties(const QDomElement& element) -> bool virtual: Restores the effect to the state described by a DOM element.
void render(QPicture& picture, QgsRenderContext& context) virtual: Renders a picture using the effect.
auto saveProperties(QDomDocument& doc, QDomElement& element) const -> bool virtual: Saves the current state of the effect to a DOM element.
void setDrawMode(DrawMode drawMode): Sets the draw mode for the effect.
void setEnabled(bool enabled): Sets whether the effect is enabled.
auto type() const -> QString pure virtual: Returns the effect type.

Protected functions

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

Enum documentation

enum QgsPaintEffect::DrawMode

Drawing modes for effects.

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

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

Function documentation

void QgsPaintEffect::begin(QgsRenderContext& context) virtual

Begins intercepting paint operations to a render context.

Parameters
context	destination 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.

QgsPaintEffect* QgsPaintEffect::clone() const pure virtual

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

Returns	clone of paint effect

DrawMode QgsPaintEffect::drawMode() const

Returns the draw mode for the effect.

Returns	draw mode for effect

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

bool QgsPaintEffect::enabled() const

Returns whether the effect is enabled.

Returns	true if effect is enabled

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
context	destination render context

QgsStringMap 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

void QgsPaintEffect::readProperties(const QgsStringMap& 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
props	effect properties encoded in a string map

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

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

Parameters
element	DOM element describing an effect's state
Returns	true if read was successful

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

Renders a picture using the effect.

Parameters
picture	source QPicture to render
context	destination render context

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

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

Parameters
doc	destination DOM document
element	destination DOM element
Returns	true if save was successful

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

void QgsPaintEffect::setDrawMode(DrawMode drawMode)

Sets the draw mode for the effect.

Parameters
drawMode	draw mode for effect

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

void QgsPaintEffect::setEnabled(bool enabled)

Sets whether the effect is enabled.

Parameters
enabled	set to false to disable the effect

QString QgsPaintEffect::type() const pure virtual

Returns the effect type.

Returns	unique string representation of the effect type

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

Returns the bounding rect required for drawing the effect.

Parameters
rect	original source bounding rect
context	destination render context
Returns	modified bounding rect

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

void QgsPaintEffect::draw(QgsRenderContext& context) pure virtual protected

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

Parameters
context	destination 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.

void QgsPaintEffect::drawSource(QPainter& painter) protected

Draws the source QPicture onto the specified painter.

Parameters
painter	destination painter

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

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

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

Parameters
painter	destination painter

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

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
context	destination render context
Returns	point offset for image top left corner

const QPicture* QgsPaintEffect::source() const protected

Returns the source QPicture.

Returns	source QPicture

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

QImage* QgsPaintEffect::sourceAsImage(QgsRenderContext& context) protected

Returns the source QPicture rendered to a new QImage.

Returns	source QPicture rendered to an image

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.