Class: QgsLayoutItemHtml

class qgis.core.QgsLayoutItemHtml

Bases: QgsLayoutMultiFrame

A layout multiframe subclass for HTML content.

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

Ownership is transferred to the layout.

Methods

childEvent

connectNotify

contentMode

Returns the source mode for item's HTML content.

create

Returns a new QgsLayoutItemHtml for the specified parent layout.

createFromLabel

Returns a new QgsLayoutItemHtml matching the content and rendering of a given label.

customEvent

disconnectNotify

displayName

rtype:

str

evaluateExpressions

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

findNearbyPageBreak

param yPos:

html

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

icon

rtype:

QIcon

isSignalConnected

loadHtml

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

maxBreakDistance

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

readObjectPropertiesFromElement

Sets object properties from a DOM element

readPropertiesFromElement

param itemElem:

recalculateFrameSizes

Recalculates the frame sizes for the current viewport dimensions

receivers

refreshDataDefinedProperty

param property:

render

param context:

sender

senderSignalIndex

setContentMode

Sets the source mode for item's HTML content.

setEvaluateExpressions

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

setHtml

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

setMaxBreakDistance

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

setUrl

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

setUseSmartBreaks

Sets whether the html item should use smart breaks.

setUserStylesheet

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

setUserStylesheetEnabled

Sets whether user stylesheets are enabled for the HTML content.

timerEvent

totalSize

rtype:

QSizeF

type

rtype:

int

url

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

useSmartBreaks

Returns whether html item is using smart breaks.

userStylesheet

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

userStylesheetEnabled

Returns whether user stylesheets are enabled for the HTML content.

writeObjectPropertiesToElement

Stores object properties within an XML DOM element.

writePropertiesToElement

param elem:

Attributes

ManualHtml

Url

class ContentMode

Bases: int

ManualHtml = 1
Url = 0
childEvent(self, QChildEvent)
connectNotify(self, QMetaMethod)
contentMode(self) QgsLayoutItemHtml.ContentMode

Returns the source mode for item’s HTML content.

See also

setContentMode()

See also

url()

See also

html()

Return type:

QgsLayoutItemHtml.ContentMode

create(layout: QgsLayout) QgsLayoutItemHtml

Returns a new QgsLayoutItemHtml for the specified parent layout.

Parameters:

layout (QgsLayout) –

Return type:

QgsLayoutItemHtml

createFromLabel(label: QgsLayoutItemLabel) QgsLayoutItemHtml

Returns a new QgsLayoutItemHtml matching the content and rendering of a given label.

New in version 3.32.

Parameters:

label (QgsLayoutItemLabel) –

Return type:

QgsLayoutItemHtml

customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
displayName(self) str
Return type:

str

evaluateExpressions(self) bool

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.

Return type:

bool

findNearbyPageBreak(self, yPos: float) float
Parameters:

yPos (float) –

Return type:

float

html(self) str

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

See also

setHtml()

See also

contentMode()

Return type:

str

icon(self) QIcon
Return type:

QIcon

isSignalConnected(self, QMetaMethod) bool
loadHtml(self, useCache: bool = False, context: QgsExpressionContext = None)

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

Parameters:
  • useCache (bool = False) – set to True to use a cached copy of remote html content

  • context (QgsExpressionContext = None) – expression context for evaluating data defined urls and expressions in html

See also

setUrl()

See also

url()

maxBreakDistance(self) float

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.

See also

useSmartBreaks()

Return type:

float

readObjectPropertiesFromElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Sets object properties from a DOM element

Parameters:
  • parentElement – is the parent DOM element for the object

  • document – DOM document

  • context – read write context

Returns:

True if read was successful

readPropertiesFromElement(self, itemElem: QDomElement, doc: QDomDocument, context: QgsReadWriteContext) bool
Parameters:
Return type:

bool

recalculateFrameSizes(self)

Recalculates the frame sizes for the current viewport dimensions

receivers(self, PYQT_SIGNAL) int
refreshDataDefinedProperty(self, property: QgsLayoutObject.DataDefinedProperty = QgsLayoutObject.DataDefinedProperty.AllProperties)
Parameters:

property (QgsLayoutObject.DataDefinedProperty = QgsLayoutObject.DataDefinedProperty.AllProperties) –

render(self, context: QgsLayoutItemRenderContext, renderExtent: QRectF, frameIndex: int)
Parameters:
sender(self) QObject
senderSignalIndex(self) int
setContentMode(self, mode: QgsLayoutItemHtml.ContentMode)

Sets the source mode for item’s HTML content.

See also

contentMode()

See also

setUrl()

See also

setHtml()

Parameters:

mode (QgsLayoutItemHtml.ContentMode) –

setEvaluateExpressions(self, evaluateExpressions: bool)

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.

Parameters:

evaluateExpressions (bool) –

setHtml(self, html: str)

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.

See also

html()

See also

contentMode()

See also

loadHtml()

Parameters:

html (str) –

setMaxBreakDistance(self, distance: float)

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.

Parameters:

distance (float) –

setUrl(self, url: QUrl)

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.

See also

url()

See also

contentMode()

Parameters:

url (QUrl) –

setUseSmartBreaks(self, useSmartBreaks: bool)

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.

See also

useSmartBreaks()

Parameters:

useSmartBreaks (bool) –

setUserStylesheet(self, stylesheet: str)

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.

See also

userStylesheet()

See also

loadHtml()

Parameters:

stylesheet (str) –

setUserStylesheetEnabled(self, enabled: bool)

Sets whether user stylesheets are enabled for the HTML content.

Parameters:

enabled (bool) –

timerEvent(self, QTimerEvent)
totalSize(self) QSizeF
Return type:

QSizeF

type(self) int
Return type:

int

url(self) QUrl

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

See also

setUrl()

See also

contentMode()

Return type:

QUrl

useSmartBreaks(self) bool

Returns whether html item is using smart breaks. Smart breaks prevent the html frame contents from breaking mid-way though a line of text.

Return type:

bool

userStylesheet(self) str

Returns the user stylesheet CSS rules used while rendering the HTML content. These overriding the styles specified within the HTML source.

Return type:

str

userStylesheetEnabled(self) bool

Returns whether user stylesheets are enabled for the HTML content.

See also

userStylesheet()

Return type:

bool

writeObjectPropertiesToElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Stores object properties within an XML DOM element.

Parameters:
  • parentElement – is the parent DOM element to store the object’s properties in

  • document – DOM document

  • context – read write context

Returns:

True if write was successful

writePropertiesToElement(self, elem: QDomElement, doc: QDomDocument, context: QgsReadWriteContext) bool
Parameters:
Return type:

bool