QgsLayoutItemPicture class

A layout item subclass that displays SVG files or raster format images (jpg, png, ...).

Reference

Base classes

class QgsLayoutItem: Base class for graphical items within a QgsLayout.

Public types

enum Format { FormatSVG, FormatRaster, FormatUnknown }: Format of source image.
enum NorthMode { GridNorth = 0, TrueNorth }: Method for syncing rotation to a map's North direction.
enum ResizeMode { Zoom, Stretch, Clip, ZoomResizeFrame, FrameToImageSize }: Controls how pictures are scaled within the item's frame.

Public static functions

static auto create(QgsLayout* layout) -> QgsLayoutItemPicture*: Returns a new picture item for the specified layout.

Constructors, destructors, conversion operators

QgsLayoutItemPicture(QgsLayout* layout): Constructor for QgsLayoutItemPicture, with the specified parent layout.

Public functions

void finalizeRestoreFromXml() override: Called after all pending items have been restored from XML.
auto icon() const -> QIcon override: Returns the item's icon.
auto linkedMap() const -> QgsLayoutItemMap*: Returns the linked rotation map, if set.
auto mode() const -> Format: Returns the current picture mode (image format).
auto northMode() const -> NorthMode: Returns the mode used to align the picture to a map's North.
auto northOffset() const -> double: Returns the offset added to the picture's rotation from a map's North.
auto pictureAnchor() const -> QgsLayoutItem::ReferencePoint: Returns the picture's current anchor, which controls how it is placed within the picture item's frame.
auto picturePath() const -> QString: Returns the path of the source image.
auto pictureRotation() const -> double: Returns the rotation used for drawing the picture within the item's frame, in degrees clockwise.
auto resizeMode() const -> ResizeMode: Returns the resize mode used for drawing the picture within the composer item's frame.
void setLinkedMap(QgsLayoutItemMap* map): Sets the map object for rotation.
void setNorthMode(NorthMode mode): Sets the mode used to align the picture to a map's North.
void setNorthOffset(double offset): Sets the offset added to the picture's rotation from a map's North.
void setPictureAnchor(QgsLayoutItem::ReferencePoint anchor): Sets the picture's anchor point, which controls how it is placed within the picture item's frame.
void setPicturePath(const QString& path): Sets the source path of the image (may be svg or a raster format).
void setSvgFillColor(const QColor& color): Sets the fill color used for parametrized SVG files.
void setSvgStrokeColor(const QColor& color): Sets the stroke color used for parametrized SVG files.
void setSvgStrokeWidth(double width): Sets the stroke width (in layout units) used for parametrized SVG files.
auto svgFillColor() const -> QColor: Returns the fill color used for parametrized SVG files.
auto svgStrokeColor() const -> QColor: Returns the stroke color used for parametrized SVG files.
auto svgStrokeWidth() const -> double: Returns the stroke width (in layout units) used for parametrized SVG files.

Signals

void pictureRotationChanged(double newRotation): Is emitted on picture rotation change.

Public slots

void recalculateSize(): Forces a recalculation of the picture's frame size.
void refreshPicture(const QgsExpressionContext* context = nullptr): Recalculates the source image (if using an expression for picture's source) and reloads and redraws the picture.
void setPictureRotation(double rotation): Sets the picture rotation within the item bounds, in degrees clockwise.
void setResizeMode(QgsLayoutItemPicture::ResizeMode mode): Sets the resize mode used for drawing the picture within the item bounds.

Protected functions

auto applyItemSizeConstraint(QSizeF targetSize) -> QSizeF override: Applies any item-specific size constraint handling to a given targetSize in layout units.
void draw(QgsLayoutItemRenderContext& context) override: Draws the item's contents using the specified item render context.
auto readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) -> bool override: Sets item state from a DOM element.
auto writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const -> bool override: Stores item state within an XML DOM element.

Enum documentation

enum QgsLayoutItemPicture::Format

Format of source image.

Enumerators
FormatSVG	SVG image.
FormatRaster	Raster image.
FormatUnknown	Invalid or unknown image type.

enum QgsLayoutItemPicture::NorthMode

Method for syncing rotation to a map's North direction.

Enumerators
GridNorth	Align to grid north.
TrueNorth	Align to true north.

enum QgsLayoutItemPicture::ResizeMode

Controls how pictures are scaled within the item's frame.

Enumerators
Zoom	Enlarges image to fit frame while maintaining aspect ratio of picture.
Stretch	Stretches image to fit frame, ignores aspect ratio.
Clip	Draws image at original size and clips any portion which falls outside frame.
ZoomResizeFrame	Enlarges image to fit frame, then resizes frame to fit resultant image.
FrameToImageSize	Sets size of frame to match original size of image without scaling.

Function documentation

static QgsLayoutItemPicture* QgsLayoutItemPicture::create(QgsLayout* layout)

Returns a new picture item for the specified layout.

The caller takes responsibility for deleting the returned object.

void QgsLayoutItemPicture::finalizeRestoreFromXml() override

Called after all pending items have been restored from XML.

Items can use this method to run steps which must take place after all items have been restored to the layout, such as connecting to signals emitted by other items, which may not have existed in the layout at the time readXml() was called. E.g. a scalebar can use this to connect to its linked map item after restoration from XML.

QgsLayoutItemMap* QgsLayoutItemPicture::linkedMap() const

Returns the linked rotation map, if set.

An nullptr means map rotation is disabled. If this is set then the picture is rotated by the same amount as the specified map object.

NorthMode QgsLayoutItemPicture::northMode() const

Returns the mode used to align the picture to a map's North.

double QgsLayoutItemPicture::northOffset() const

Returns the offset added to the picture's rotation from a map's North.

QgsLayoutItem::ReferencePoint QgsLayoutItemPicture::pictureAnchor() const

Returns the picture's current anchor, which controls how it is placed within the picture item's frame.

QString QgsLayoutItemPicture::picturePath() const

Returns the path of the source image.

Returns	path for the source image

Data defined picture source may override this value. The path can either be a local path or a remote (http) path.

double QgsLayoutItemPicture::pictureRotation() const

Returns the rotation used for drawing the picture within the item's frame, in degrees clockwise.

ResizeMode QgsLayoutItemPicture::resizeMode() const

Returns the resize mode used for drawing the picture within the composer item's frame.

void QgsLayoutItemPicture::setLinkedMap(QgsLayoutItemMap* map)

Sets the map object for rotation.

If this is set then the picture will be rotated by the same amount as the specified map object. This is useful especially for syncing north arrows with a map item.

void QgsLayoutItemPicture::setNorthMode(NorthMode mode)

Sets the mode used to align the picture to a map's North.

void QgsLayoutItemPicture::setNorthOffset(double offset)

Sets the offset added to the picture's rotation from a map's North.

void QgsLayoutItemPicture::setPictureAnchor(QgsLayoutItem::ReferencePoint anchor)

Sets the picture's anchor point, which controls how it is placed within the picture item's frame.

void QgsLayoutItemPicture::setPicturePath(const QString& path)

Sets the source path of the image (may be svg or a raster format).

Data defined picture source may override this value. The path can either be a local path or a remote (http) path.

void QgsLayoutItemPicture::setSvgFillColor(const QColor& color)

Sets the fill color used for parametrized SVG files.

void QgsLayoutItemPicture::setSvgStrokeColor(const QColor& color)

Sets the stroke color used for parametrized SVG files.

Parameters
color	stroke color.

void QgsLayoutItemPicture::setSvgStrokeWidth(double width)

Sets the stroke width (in layout units) used for parametrized SVG files.

QColor QgsLayoutItemPicture::svgFillColor() const

Returns the fill color used for parametrized SVG files.

QColor QgsLayoutItemPicture::svgStrokeColor() const

Returns the stroke color used for parametrized SVG files.

double QgsLayoutItemPicture::svgStrokeWidth() const

Returns the stroke width (in layout units) used for parametrized SVG files.

void QgsLayoutItemPicture::refreshPicture(const QgsExpressionContext* context = nullptr) public slot

Recalculates the source image (if using an expression for picture's source) and reloads and redraws the picture.

Parameters
context	expression context for evaluating data defined picture sources

void QgsLayoutItemPicture::setPictureRotation(double rotation) public slot

Sets the picture rotation within the item bounds, in degrees clockwise.

This does not affect the item's frame, only the way the picture is drawn within the item.

void QgsLayoutItemPicture::setResizeMode(QgsLayoutItemPicture::ResizeMode mode) public slot

Sets the resize mode used for drawing the picture within the item bounds.

Parameters
mode	ResizeMode to use for image file

QSizeF QgsLayoutItemPicture::applyItemSizeConstraint(QSizeF targetSize) override protected

Applies any item-specific size constraint handling to a given targetSize in layout units.

Subclasses can override this method if they need to apply advanced logic regarding item sizes, which cannot be covered by setFixedSize() or setMinimumSize(). Item size constraints are applied after fixed, minimum and data defined size constraints.

void QgsLayoutItemPicture::draw(QgsLayoutItemRenderContext& context) override protected

Draws the item's contents using the specified item render context.

Note that the context's painter has been scaled so that painter units are pixels. Use the QgsRenderContext methods to convert from millimeters or other units to the painter's units.

bool QgsLayoutItemPicture::readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) override protected

Sets item state from a DOM element.

Parameters
element	is the DOM element for the item
document	DOM document
context	read write context

Note that item subclasses should not rely on all other items being present in the layout at the time this method is called. Instead, any connections and links to other items must be made in the finalizeRestoreFromXml() method. E.g. when restoring a scalebar, the connection to the linked map's signals should be implemented in finalizeRestoreFromXml(), not readPropertiesFromElement().

bool QgsLayoutItemPicture::writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const override protected

Stores item state within an XML DOM element.

Parameters
element	is the DOM element to store the item's properties in
document	DOM document
context	read write context