Class: QgsPaintEffect

class qgis.core.QgsPaintEffect

Bases: sip.wrapper

Constructor for QgsPaintEffect.

QgsPaintEffect(other: QgsPaintEffect)

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.

New in version 2.9:

Methods

begin

Begins intercepting paint operations to a render context.

boundingRect

Returns the bounding rect required for drawing the effect.

clone

Duplicates an effect by creating a deep copy of the effect

draw

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

drawMode

Returns the draw mode for the effect.

drawSource

Draws the source QPicture onto the specified painter.

enabled

Returns whether the effect is enabled

end

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

fixQPictureDpi

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

imageOffset

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

properties

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

readProperties

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

render

Renders a picture using the effect.

saveProperties

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

setDrawMode

Sets the draw mode for the effect.

setEnabled

Sets whether the effect is enabled

source

Returns the source QPicture.

sourceAsImage

Returns the source QPicture rendered to a new QImage.

type

Returns the effect type.

Attributes

Modifier

ModifyAndRender

Render

class DrawMode

Bases: int

Modifier = 0
ModifyAndRender = 2
Render = 1
begin(self, context: QgsRenderContext)

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

context (QgsRenderContext) – destination render context

See also

end()

See also

render()

boundingRect(self, rect: QRectF, context: QgsRenderContext) QRectF

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
  • rect (QRectF) – original source bounding rect

  • context (QgsRenderContext) – destination render context

Return type

QRectF

Returns

modified bounding rect

See also

sourceAsImage()

clone(self) QgsPaintEffect

Duplicates an effect by creating a deep copy of the effect

Return type

QgsPaintEffect

Returns

clone of paint effect

draw(self, context: QgsRenderContext)

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

context (QgsRenderContext) – destination render context

See also

drawSource()

drawMode(self) QgsPaintEffect.DrawMode

Returns the draw mode for the effect. This property only has an effect if the paint effect is used in a QgsEffectStack.

Return type

QgsPaintEffect.DrawMode

Returns

draw mode for effect

See also

setDrawMode()

drawSource(self, painter: QPainter)

Draws the source QPicture onto the specified painter. Handles scaling of the picture to account for the destination painter’s DPI.

Parameters

painter (QPainter) – destination painter

See also

source()

See also

sourceAsImage()

enabled(self) bool

Returns whether the effect is enabled

Return type

bool

Returns

True if effect is enabled

See also

setEnabled()

end(self, context: QgsRenderContext)

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 (QgsRenderContext) – destination render context

See also

begin()

fixQPictureDpi(self, painter: QPainter)

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

painter (QPainter) – destination painter

imageOffset(self, context: QgsRenderContext) QPointF

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

Parameters

context (QgsRenderContext) – destination render context

Return type

QPointF

Returns

point offset for image top left corner

See also

sourceAsImage()

properties(self) Dict[str, str]

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

Return type

Dict[str, str]

Returns

string map of properties, in the form property key, value

See also

readProperties()

See also

saveProperties()

readProperties(self, props: Dict[str, str])

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

Parameters

props (Dict[str) – effect properties encoded in a string map

See also

properties()

readProperties(self, element: QDomElement) -> bool 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

See also

saveProperties()

render(self, picture: QPicture, context: QgsRenderContext)

Renders a picture using the effect.

Parameters
  • picture (QPicture) – source QPicture to render

  • context (QgsRenderContext) – destination render context

See also

begin()

saveProperties(self, doc: QDomDocument, element: QDomElement) bool

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
  • doc (QDomDocument) – destination DOM document

  • element (QDomElement) – destination DOM element

Return type

bool

Returns

True if save was successful

See also

readProperties()

setDrawMode(self, drawMode: QgsPaintEffect.DrawMode)

Sets the draw mode for the effect. This property only has an effect if the paint effect is used in a QgsEffectStack.

Parameters

drawMode (QgsPaintEffect.DrawMode) – draw mode for effect

See also

drawMode()

setEnabled(self, enabled: bool)

Sets whether the effect is enabled

Parameters

enabled (bool) – set to False to disable the effect

See also

enabled()

source(self) QPicture

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

Return type

QPicture

Returns

source QPicture

See also

drawSource()

See also

sourceAsImage()

sourceAsImage(self, context: QgsRenderContext) QImage

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.

Return type

QImage

Returns

source QPicture rendered to an image

See also

drawSource()

See also

source()

See also

imageOffset()

See also

boundingRect()

Parameters

context (QgsRenderContext) –

type(self) str

Returns the effect type.

Return type

str

Returns

unique string representation of the effect type