QgsLayoutItemHtml class

A layout multiframe subclass for HTML content.

Contents

Base classes

class QgsLayoutMultiFrame
Abstract base class for layout items with the ability to distribute the content to several frames (QgsLayoutFrame items).

Public types

enum ContentMode { Url, ManualHtml }
Source modes for the HTML content to render in the item.

Public static functions

static auto create(QgsLayout* layout) -> QgsLayoutItemHtml*
Returns a new QgsLayoutItemHtml for the specified parent layout.

Constructors, destructors, conversion operators

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

Public functions

auto contentMode() const -> ContentMode
Returns the source mode for item's HTML content.
auto displayName() const -> QString override
Returns the multiframe display name.
auto evaluateExpressions() const -> bool
Returns whether html item will evaluate QGIS expressions prior to rendering the HTML content.
auto findNearbyPageBreak(double yPos) -> double override
Finds the optimal position to break a frame at.
auto html() const -> QString
Returns the HTML source displayed in the item if the item is using the QgsLayoutItemHtml::ManualHtml mode.
auto icon() const -> QIcon override
Returns the item's icon.
auto maxBreakDistance() const -> double
Returns the maximum distance allowed when calculating where to place page breaks in the html.
void render(QgsLayoutItemRenderContext& context, const QRectF& renderExtent, int frameIndex) override
Renders a portion of the multiframe's content into a render context.
void setContentMode(ContentMode mode)
Sets the source mode for item's HTML content.
void setEvaluateExpressions(bool evaluateExpressions)
Sets whether the html item will evaluate QGIS expressions prior to rendering the HTML content.
void setHtml(const QString& html)
Sets the html to display in the item when the item is using the QgsLayoutItemHtml::ManualHtml mode.
void setMaxBreakDistance(double distance)
Sets the maximum distance allowed when calculating where to place page breaks in the html.
void setUrl(const QUrl& url)
Sets the url for content to display in the item when the item is using the QgsLayoutItemHtml::Url mode.
void setUserStylesheet(const QString& stylesheet)
Sets the user stylesheet CSS rules to use while rendering the HTML content.
void setUserStylesheetEnabled(bool enabled)
Sets whether user stylesheets are enabled for the HTML content.
void setUseSmartBreaks(bool useSmartBreaks)
Sets whether the html item should use smart breaks.
auto totalSize() const -> QSizeF override
Returns the total size of the multiframe's content, in layout units.
auto type() const -> int override
Returns unique multiframe type id.
auto url() const -> QUrl
Returns the URL of the content displayed in the item if the item is using the QgsLayoutItemHtml::Url mode.
auto userStylesheet() const -> QString
Returns the user stylesheet CSS rules used while rendering the HTML content.
auto userStylesheetEnabled() const -> bool
Returns whether user stylesheets are enabled for the HTML content.
auto useSmartBreaks() const -> bool
Returns whether html item is using smart breaks.

Public slots

void loadHtml(bool useCache = false, const QgsExpressionContext* context = nullptr)
Reloads the html source from the url and redraws the item.
void recalculateFrameSizes() override
Recalculates the frame sizes for the current viewport dimensions.

Protected functions

auto readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) -> bool override
Sets multiframe state from a DOM element.
auto writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const -> bool override
Stores multiframe state within an XML DOM element.

Enum documentation

enum QgsLayoutItemHtml::ContentMode

Source modes for the HTML content to render in the item.

Enumerators
Url

Using this mode item fetches its content via a url.
ManualHtml

HTML content is manually set for the item.

Function documentation

QgsLayoutItemHtml::QgsLayoutItemHtml(QgsLayout* layout)

Constructor for QgsLayoutItemHtml, with the specified parent layout.

Ownership is transferred to the layout.

ContentMode QgsLayoutItemHtml::contentMode() const

Returns the source mode for item's HTML content.

bool QgsLayoutItemHtml::evaluateExpressions() const

Returns whether html item will evaluate QGIS expressions prior to rendering the HTML content.

If set, any content inside [% %] tags will be treated as a QGIS expression and evaluated against the current atlas feature.

double QgsLayoutItemHtml::findNearbyPageBreak(double yPos) override

Finds the optimal position to break a frame at.

Parameters
yPos maximum vertical position for break, in layout units.
Returns the optimal breakable position which occurs in the multi frame close to and before the specified yPos

QString QgsLayoutItemHtml::html() const

Returns the HTML source displayed in the item if the item is using the QgsLayoutItemHtml::ManualHtml mode.

double QgsLayoutItemHtml::maxBreakDistance() const

Returns the maximum distance allowed when calculating where to place page breaks in the html.

This distance is the maximum amount of empty space allowed at the bottom of a frame after calculating the optimum break location. This setting is only effective if useSmartBreaks is true.

void QgsLayoutItemHtml::render(QgsLayoutItemRenderContext& context, const QRectF& renderExtent, int frameIndex) override

Renders a portion of the multiframe's content into a render context.

Parameters
context destination render painter
renderExtent visible extent of content to render into the painter.
frameIndex frame number for content

void QgsLayoutItemHtml::setContentMode(ContentMode mode)

Sets the source mode for item's HTML content.

void QgsLayoutItemHtml::setEvaluateExpressions(bool evaluateExpressions)

Sets whether the html item will evaluate QGIS expressions prior to rendering the HTML content.

If set, any content inside [% %] tags will be treated as a QGIS expression and evaluated against the current atlas feature.

void QgsLayoutItemHtml::setHtml(const QString& html)

Sets the html to display in the item when the item is using the QgsLayoutItemHtml::ManualHtml mode.

Setting the HTML using this function does not automatically refresh the item's contents. Call loadHtml to trigger a refresh of the item after setting the HTML content.

void QgsLayoutItemHtml::setMaxBreakDistance(double distance)

Sets the maximum distance allowed when calculating where to place page breaks in the html.

This distance is the maximum amount of empty space allowed at the bottom of a frame after calculating the optimum break location. Setting a larger value will result in better choice of page break location, but more wasted space at the bottom of frames. This setting is only effective if useSmartBreaks is true.

void QgsLayoutItemHtml::setUrl(const QUrl& url)

Sets the url for content to display in the item when the item is using the QgsLayoutItemHtml::Url mode.

Content is automatically fetched and the HTML item refreshed after calling this function.

void QgsLayoutItemHtml::setUserStylesheet(const QString& stylesheet)

Sets the user stylesheet CSS rules to use while rendering the HTML content.

These allow for overriding the styles specified within the HTML source. Setting the stylesheet using this function does not automatically refresh the item's contents. Call loadHtml to trigger a refresh of the item after setting the stylesheet rules.

void QgsLayoutItemHtml::setUserStylesheetEnabled(bool enabled)

Sets whether user stylesheets are enabled for the HTML content.

void QgsLayoutItemHtml::setUseSmartBreaks(bool useSmartBreaks)

Sets whether the html item should use smart breaks.

Smart breaks prevent the html frame contents from breaking mid-way though a line of text.

QUrl QgsLayoutItemHtml::url() const

Returns the URL of the content displayed in the item if the item is using the QgsLayoutItemHtml::Url mode.

QString QgsLayoutItemHtml::userStylesheet() const

Returns the user stylesheet CSS rules used while rendering the HTML content.

These overriding the styles specified within the HTML source.

bool QgsLayoutItemHtml::userStylesheetEnabled() const

Returns whether user stylesheets are enabled for the HTML content.

bool QgsLayoutItemHtml::useSmartBreaks() const

Returns whether html item is using smart breaks.

Smart breaks prevent the html frame contents from breaking mid-way though a line of text.

void QgsLayoutItemHtml::loadHtml(bool useCache = false, const QgsExpressionContext* context = nullptr) public slot

Reloads the html source from the url and redraws the item.

Parameters
useCache set to true to use a cached copy of remote html content
context expression context for evaluating data defined urls and expressions in html

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

Sets multiframe state from a DOM element.

Parameters
element is the DOM element for the multiframe
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 QgsLayoutItemHtml::writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const override protected

Stores multiframe state within an XML DOM element.

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