QgsLayoutItemLegend class

A layout item subclass for map legends.

Reference

Base classes

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

Public static functions

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

Constructors, destructors, conversion operators

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

Public functions

void adjustBoxSize(): Sets the legend's item bounds to fit the whole legend content.
auto autoUpdateModel() const -> bool: Returns whether the legend content should auto update to reflect changes in the project's layer tree.
auto boxSpace() const -> double: Returns the legend box space.
auto columnCount() const -> int: Returns the legend column count.
auto columnSpace() const -> double: Returns the legend column spacing.
auto displayName() const -> QString override: Gets item display name.
auto drawRasterStroke() const -> bool: Returns whether a stroke will be drawn around raster symbol items.
auto equalColumnWidth() const -> bool: Returns whether column widths should be equalized.
void finalizeRestoreFromXml() override: Called after all pending items have been restored from XML.
auto fontColor() const -> QColor: Returns the legend font color.
auto icon() const -> QIcon override: Returns the item's icon.
auto itemFlags() const -> QgsLayoutItem::Flags override: Returns the item's flags, which indicate how the item behaves.
auto legendFilterByMapEnabled() const -> bool: Find out whether legend items are filtered to show just the ones visible in the associated map.
auto legendFilterOutAtlas() const -> bool: Returns whether to filter out legend elements outside of the current atlas feature.
auto legendSettings() const -> const QgsLegendSettings&: Returns the legend's renderer settings object.
auto lineSpacing() const -> double: Returns the spacing in-between lines in layout units.
auto linkedMap() const -> QgsLayoutItemMap*: Returns the associated map.
auto model() -> QgsLegendModel*: Returns the legend model.
auto rasterStrokeColor() const -> QColor: Returns the stroke color for the stroke drawn around raster symbol items.
auto rasterStrokeWidth() const -> double: Returns the stroke width (in layout units) for the stroke drawn around raster symbol items.
auto resizeToContents() const -> bool: Returns whether the legend should automatically resize to fit its contents.
auto rstyle(QgsLegendStyle::Style s) -> QgsLegendStyle&: Returns reference to modifiable legend style.
void setAutoUpdateModel(bool autoUpdate): Sets whether the legend content should auto update to reflect changes in the project's layer tree.
void setBoxSpace(double space): Sets the legend box space.
void setColumnCount(int count): Sets the legend column count.
void setColumnSpace(double spacing): Sets the legend column spacing.
void setDrawRasterStroke(bool enabled): Sets whether a stroke will be drawn around raster symbol items.
void setEqualColumnWidth(bool equalize): Sets whether column widths should be equalized.
void setFontColor(const QColor& color): Sets the legend font color.
void setLegendFilterByMapEnabled(bool enabled): Set whether legend items should be filtered to show just the ones visible in the associated map.
void setLegendFilterOutAtlas(bool doFilter): When set to true, during an atlas rendering, it will filter out legend elements where features are outside the current atlas feature.
void setLineSpacing(double spacing): Sets the spacing in-between multiple lines.
void setLinkedMap(QgsLayoutItemMap* map): Sets the map to associate with the legend.
void setRasterStrokeColor(const QColor& color): Sets the stroke color for the stroke drawn around raster symbol items.
void setRasterStrokeWidth(double width): Sets the stroke width for the stroke drawn around raster symbol items.
void setResizeToContents(bool enabled): Sets whether the legend should automatically resize to fit its contents.
void setSplitLayer(bool enabled): Sets whether the legend items from a single layer can be split over multiple columns.
void setStyle(QgsLegendStyle::Style component, const QgsLegendStyle& style): Sets the style of component to style for the legend.
void setStyleFont(QgsLegendStyle::Style component, const QFont& font): Sets the style font for a legend component.
void setStyleMargin(QgsLegendStyle::Style component, double margin): Set the margin for a legend component.
void setStyleMargin(QgsLegendStyle::Style component, QgsLegendStyle::Side side, double margin): Set the margin for a particular side of a legend component.
void setSymbolHeight(double height): Sets the legend symbol height.
void setSymbolWidth(double width): Sets the legend symbol width.
void setTitle(const QString& title): Sets the legend title.
void setTitleAlignment(Qt::AlignmentFlag alignment): Sets the alignment of the legend title.
void setWmsLegendHeight(double height): Sets the WMS legend height.
void setWmsLegendWidth(double width): Sets the WMS legend width.
void setWrapString(const QString& string): Sets the legend text wrapping string.
auto splitLayer() const -> bool: Returns whether the legend items from a single layer can be split over multiple columns.
auto style(QgsLegendStyle::Style s) const -> QgsLegendStyle: Returns legend style.
auto styleFont(QgsLegendStyle::Style component) const -> QFont: Returns the font settings for a legend component.
auto symbolHeight() const -> double: Returns the legend symbol height.
auto symbolWidth() const -> double: Returns the legend symbol width.
auto title() const -> QString: Returns the legend title.
auto titleAlignment() const -> Qt::AlignmentFlag: Returns the alignment of the legend title.
void updateFilterByMap(bool redraw = true): Updates the legend content when filtered by map.
void updateLegend(): Updates the model and all legend entries.
auto wmsLegendHeight() const -> double: Returns the WMS legend height.
auto wmsLegendWidth() const -> double: Returns the WMS legend width.
auto wrapString() const -> QString: Returns the legend text wrapping string.

Protected functions

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.

Function documentation

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

Returns a new legend item for the specified layout.

The caller takes responsibility for deleting the returned object.

bool QgsLayoutItemLegend::autoUpdateModel() const

Returns whether the legend content should auto update to reflect changes in the project's layer tree.

double QgsLayoutItemLegend::boxSpace() const

Returns the legend box space.

int QgsLayoutItemLegend::columnCount() const

Returns the legend column count.

double QgsLayoutItemLegend::columnSpace() const

Returns the legend column spacing.

QString QgsLayoutItemLegend::displayName() const override

Gets item display name.

This is the item's id if set, and if not, a user-friendly string identifying item type.

bool QgsLayoutItemLegend::drawRasterStroke() const

Returns whether a stroke will be drawn around raster symbol items.

bool QgsLayoutItemLegend::equalColumnWidth() const

Returns whether column widths should be equalized.

void QgsLayoutItemLegend::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.

QColor QgsLayoutItemLegend::fontColor() const

Returns the legend font color.

QgsLayoutItem::Flags QgsLayoutItemLegend::itemFlags() const override

Returns the item's flags, which indicate how the item behaves.

bool QgsLayoutItemLegend::legendFilterByMapEnabled() const

Find out whether legend items are filtered to show just the ones visible in the associated map.

bool QgsLayoutItemLegend::legendFilterOutAtlas() const

Returns whether to filter out legend elements outside of the current atlas feature.

double QgsLayoutItemLegend::lineSpacing() const

Returns the spacing in-between lines in layout units.

QgsLayoutItemMap* QgsLayoutItemLegend::linkedMap() const

Returns the associated map.

QColor QgsLayoutItemLegend::rasterStrokeColor() const

Returns the stroke color for the stroke drawn around raster symbol items.

The stroke is only drawn if drawRasterStroke() is true.

double QgsLayoutItemLegend::rasterStrokeWidth() const

Returns the stroke width (in layout units) for the stroke drawn around raster symbol items.

The stroke is only drawn if drawRasterStroke() is true.

bool QgsLayoutItemLegend::resizeToContents() const

Returns whether the legend should automatically resize to fit its contents.

void QgsLayoutItemLegend::setAutoUpdateModel(bool autoUpdate)

Sets whether the legend content should auto update to reflect changes in the project's layer tree.

void QgsLayoutItemLegend::setBoxSpace(double space)

Sets the legend box space.

void QgsLayoutItemLegend::setColumnCount(int count)

Sets the legend column count.

void QgsLayoutItemLegend::setColumnSpace(double spacing)

Sets the legend column spacing.

void QgsLayoutItemLegend::setDrawRasterStroke(bool enabled)

Sets whether a stroke will be drawn around raster symbol items.

Parameters
enabled	set to true to draw borders

void QgsLayoutItemLegend::setEqualColumnWidth(bool equalize)

Sets whether column widths should be equalized.

void QgsLayoutItemLegend::setFontColor(const QColor& color)

Sets the legend font color.

void QgsLayoutItemLegend::setLegendFilterByMapEnabled(bool enabled)

Set whether legend items should be filtered to show just the ones visible in the associated map.

void QgsLayoutItemLegend::setLegendFilterOutAtlas(bool doFilter)

When set to true, during an atlas rendering, it will filter out legend elements where features are outside the current atlas feature.

void QgsLayoutItemLegend::setLineSpacing(double spacing)

Sets the spacing in-between multiple lines.

void QgsLayoutItemLegend::setLinkedMap(QgsLayoutItemMap* map)

Sets the map to associate with the legend.

void QgsLayoutItemLegend::setRasterStrokeColor(const QColor& color)

Sets the stroke color for the stroke drawn around raster symbol items.

The stroke is only drawn if drawRasterStroke() is true.

void QgsLayoutItemLegend::setRasterStrokeWidth(double width)

Sets the stroke width for the stroke drawn around raster symbol items.

The stroke is only drawn if drawRasterStroke() is true.

void QgsLayoutItemLegend::setResizeToContents(bool enabled)

Sets whether the legend should automatically resize to fit its contents.

Parameters
enabled	set to false to disable automatic resizing. The legend frame will not be expanded to fit legend items, and items may be cropped from display.

void QgsLayoutItemLegend::setSplitLayer(bool enabled)

Sets whether the legend items from a single layer can be split over multiple columns.

void QgsLayoutItemLegend::setStyleFont(QgsLegendStyle::Style component, const QFont& font)

Sets the style font for a legend component.

void QgsLayoutItemLegend::setSymbolHeight(double height)

Sets the legend symbol height.

void QgsLayoutItemLegend::setSymbolWidth(double width)

Sets the legend symbol width.

void QgsLayoutItemLegend::setTitle(const QString& title)

Sets the legend title.

void QgsLayoutItemLegend::setTitleAlignment(Qt::AlignmentFlag alignment)

Sets the alignment of the legend title.

void QgsLayoutItemLegend::setWmsLegendHeight(double height)

Sets the WMS legend height.

void QgsLayoutItemLegend::setWmsLegendWidth(double width)

Sets the WMS legend width.

void QgsLayoutItemLegend::setWrapString(const QString& string)

Sets the legend text wrapping string.

bool QgsLayoutItemLegend::splitLayer() const

Returns whether the legend items from a single layer can be split over multiple columns.

QFont QgsLayoutItemLegend::styleFont(QgsLegendStyle::Style component) const

Returns the font settings for a legend component.

double QgsLayoutItemLegend::symbolHeight() const

Returns the legend symbol height.

double QgsLayoutItemLegend::symbolWidth() const

Returns the legend symbol width.

QString QgsLayoutItemLegend::title() const

Returns the legend title.

Qt::AlignmentFlag QgsLayoutItemLegend::titleAlignment() const

Returns the alignment of the legend title.

double QgsLayoutItemLegend::wmsLegendHeight() const

Returns the WMS legend height.

double QgsLayoutItemLegend::wmsLegendWidth() const

Returns the WMS legend width.

QString QgsLayoutItemLegend::wrapString() const

Returns the legend text wrapping string.

void QgsLayoutItemLegend::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 QgsLayoutItemLegend::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 QgsLayoutItemLegend::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