QgsLayoutItemLabel class

A layout item subclass for text labels.

Reference

Base classes

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

Public types

enum Mode { ModeFont, ModeHtml }: Label modes.

Public static functions

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

Constructors, destructors, conversion operators

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

Public functions

void adjustSizeToText(): Resizes the item so that the label's text fits to the item.
auto currentText() const -> QString: Returns the text as it appears on the label (with evaluated expressions and other dynamic content).
auto displayName() const -> QString override: Gets item display name.
auto font() const -> QFont: Returns the label's current font.
auto fontColor() const -> QColor: Returns the label font color.
auto hAlign() const -> Qt::AlignmentFlag: Returns the horizontal alignment of the label.
auto icon() const -> QIcon override: Returns the item's icon.
auto marginX() const -> double: Returns the horizontal margin between the edge of the frame and the label contents, in layout units.
auto marginY() const -> double: Returns the vertical margin between the edge of the frame and the label contents, in layout units.
auto mode() const -> Mode: Returns the label's current mode.
void setFont(const QFont& font): Sets the label's current font.
void setFontColor(const QColor& color): Sets the label font color.
void setFrameEnabled(bool drawFrame) override: Sets whether this item has a frame drawn around it or not.
void setFrameStrokeWidth(QgsLayoutMeasurement width) override: Sets the frame stroke width.
void setHAlign(Qt::AlignmentFlag alignment): Sets the horizontal alignment of the label.
void setMargin(double margin): Sets the margin between the edge of the frame and the label contents.
void setMarginX(double margin): Sets the horizontal margin between the edge of the frame and the label contents, in layout units.
void setMarginY(double margin): Sets the vertical margin between the edge of the frame and the label contents, in layout units.
void setMode(Mode mode): Sets the label's current mode, allowing the label to switch between font based and HTML based rendering.
void setText(const QString& text): Sets the label's preset text.
void setVAlign(Qt::AlignmentFlag alignment): Sets for the vertical alignment of the label.
auto sizeForText() const -> QSizeF: Returns the required item size (in layout units) for the label's text to fill the item.
auto text() const -> QString: Returns the label's preset text.
auto vAlign() const -> Qt::AlignmentFlag: Returns for the vertical alignment of the label.

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.

Enum documentation

enum QgsLayoutItemLabel::Mode

Label modes.

Enumerators
ModeFont	Label displays text rendered using a single font.
ModeHtml	Label displays rendered HTML content.

Function documentation

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

Returns a new label item for the specified layout.

The caller takes responsibility for deleting the returned object.

void QgsLayoutItemLabel::adjustSizeToText()

Resizes the item so that the label's text fits to the item.

Keeps the top left point stationary.

QString QgsLayoutItemLabel::currentText() const

Returns the text as it appears on the label (with evaluated expressions and other dynamic content).

QString QgsLayoutItemLabel::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.

QFont QgsLayoutItemLabel::font() const

Returns the label's current font.

QColor QgsLayoutItemLabel::fontColor() const

Returns the label font color.

Qt::AlignmentFlag QgsLayoutItemLabel::hAlign() const

Returns the horizontal alignment of the label.

double QgsLayoutItemLabel::marginX() const

Returns the horizontal margin between the edge of the frame and the label contents, in layout units.

double QgsLayoutItemLabel::marginY() const

Returns the vertical margin between the edge of the frame and the label contents, in layout units.

Mode QgsLayoutItemLabel::mode() const

Returns the label's current mode.

void QgsLayoutItemLabel::setFont(const QFont& font)

Sets the label's current font.

void QgsLayoutItemLabel::setFontColor(const QColor& color)

Sets the label font color.

void QgsLayoutItemLabel::setFrameEnabled(bool drawFrame) override

Sets whether this item has a frame drawn around it or not.

void QgsLayoutItemLabel::setFrameStrokeWidth(QgsLayoutMeasurement width) override

Sets the frame stroke width.

void QgsLayoutItemLabel::setHAlign(Qt::AlignmentFlag alignment)

Sets the horizontal alignment of the label.

void QgsLayoutItemLabel::setMargin(double margin)

Sets the margin between the edge of the frame and the label contents.

This method sets both the horizontal and vertical margins to the same value. The margins can be individually controlled using the setMarginX() and setMarginY() methods.

Margins are set using the current layout units.

void QgsLayoutItemLabel::setMarginX(double margin)

Sets the horizontal margin between the edge of the frame and the label contents, in layout units.

void QgsLayoutItemLabel::setMarginY(double margin)

Sets the vertical margin between the edge of the frame and the label contents, in layout units.

void QgsLayoutItemLabel::setMode(Mode mode)

Sets the label's current mode, allowing the label to switch between font based and HTML based rendering.

void QgsLayoutItemLabel::setText(const QString& text)

Sets the label's preset text.

void QgsLayoutItemLabel::setVAlign(Qt::AlignmentFlag alignment)

Sets for the vertical alignment of the label.

QSizeF QgsLayoutItemLabel::sizeForText() const

Returns the required item size (in layout units) for the label's text to fill the item.

QString QgsLayoutItemLabel::text() const

Returns the label's preset text.

Qt::AlignmentFlag QgsLayoutItemLabel::vAlign() const

Returns for the vertical alignment of the label.

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