A layout multiframe subclass for HTML content. More...

#include <qgslayoutitemhtml.h>

Inheritance diagram for QgsLayoutItemHtml:

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

Public Types inherited from QgsLayoutMultiFrame
enum	ResizeMode { UseExistingFrames = 0, ExtendToNextPage, RepeatOnEveryPage, RepeatUntilFinished }
	Specifies the behavior for creating new frames to fit the multiframe's content. More...

enum	UndoCommand { UndoHtmlBreakDistance, UndoHtmlSource, UndoHtmlStylesheet, UndoTableCellStyle, UndoTableMaximumFeatures, UndoTableMargin, UndoTableHeaderFontColor, UndoTableContentFontColor, UndoTableGridStrokeWidth, UndoTableGridColor, UndoTableBackgroundColor, UndoNone = -1 }
	Multiframe item undo commands, used for collapsing undo commands. More...

Public Types inherited from QgsLayoutObject
enum	DataDefinedProperty { NoProperty = 0, AllProperties, TestProperty, PresetPaperSize, PaperWidth, PaperHeight, NumPages, PaperOrientation, PageNumber, PositionX, PositionY, ItemWidth, ItemHeight, ItemRotation, Transparency, Opacity, BlendMode, ExcludeFromExports, FrameColor, BackgroundColor, MapRotation, MapScale, MapXMin, MapYMin, MapXMax, MapYMax, MapAtlasMargin, MapLayers, MapStylePreset, PictureSource, PictureSvgBackgroundColor, PictureSvgStrokeColor, PictureSvgStrokeWidth, SourceUrl, LegendTitle, LegendColumnCount, ScalebarFillColor, ScalebarFillColor2, ScalebarLineColor, ScalebarLineWidth, AttributeTableSourceLayer }
	Data defined properties for different item types. More...

enum	PropertyValueType { EvaluatedValue = 0, OriginalValue }
	Specifies whether the value returned by a function should be the original, user set value, or the current evaluated value for the property. More...

Public Slots
void	loadHtml (bool useCache=false, const QgsExpressionContext *context=nullptr)
	Reloads the html source from the url and redraws the item. More...

void	recalculateFrameSizes () override
	Recalculates the frame sizes for the current viewport dimensions. More...

void	refreshDataDefinedProperty (QgsLayoutObject::DataDefinedProperty property=QgsLayoutObject::AllProperties) override

Public Slots inherited from QgsLayoutMultiFrame
void	recalculateFrameRects ()
	Forces a recalculation of all the associated frame's scene rectangles. More...

virtual void	recalculateFrameSizes ()
	Recalculates the portion of the multiframe item which is shown in each of its component frames. More...

void	refresh () override
	Refreshes the multiframe, causing a recalculation of any property overrides. More...

virtual void	refreshDataDefinedProperty (QgsLayoutObject::DataDefinedProperty property=QgsLayoutObject::AllProperties)
	Refreshes a data defined property for the multi frame by reevaluating the property's value and redrawing the item with this new value. More...

void	update ()
	Forces a redraw of all child frames. More...

Public Slots inherited from QgsLayoutObject
virtual void	refresh ()
	Refreshes the object, causing a recalculation of any property overrides. More...

Public Member Functions
	QgsLayoutItemHtml (QgsLayout *layout)
	Constructor for QgsLayoutItemHtml, with the specified parent layout. More...

	~QgsLayoutItemHtml () override

ContentMode	contentMode () const
	Returns the source mode for item's HTML content. More...

QString	displayName () const override
	Returns the multiframe display name. More...

bool	evaluateExpressions () const
	Returns whether html item will evaluate QGIS expressions prior to rendering the HTML content. More...

double	findNearbyPageBreak (double yPos) override
	Finds the optimal position to break a frame at. More...

QString	html () const
	Returns the HTML source displayed in the item if the item is using the QgsLayoutItemHtml::ManualHtml mode. More...

QIcon	icon () const override
	Returns the item's icon. More...

double	maxBreakDistance () const
	Returns the maximum distance allowed when calculating where to place page breaks in the html. More...

void	render (QgsLayoutItemRenderContext &context, const QRectF &renderExtent, int frameIndex) override
	Renders a portion of the multiframe's content into a render context. More...

void	setContentMode (ContentMode mode)
	Sets the source mode for item's HTML content. More...

void	setEvaluateExpressions (bool evaluateExpressions)
	Sets whether the html item will evaluate QGIS expressions prior to rendering the HTML content. More...

void	setHtml (const QString &html)
	Sets the html to display in the item when the item is using the QgsLayoutItemHtml::ManualHtml mode. More...

void	setMaxBreakDistance (double distance)
	Sets the maximum distance allowed when calculating where to place page breaks in the html. More...

void	setUrl (const QUrl &url)
	Sets the url for content to display in the item when the item is using the QgsLayoutItemHtml::Url mode. More...

void	setUserStylesheet (const QString &stylesheet)
	Sets the user stylesheet CSS rules to use while rendering the HTML content. More...

void	setUserStylesheetEnabled (bool enabled)
	Sets whether user stylesheets are enabled for the HTML content. More...

void	setUseSmartBreaks (bool useSmartBreaks)
	Sets whether the html item should use smart breaks. More...

QSizeF	totalSize () const override
	Returns the total size of the multiframe's content, in layout units. More...

int	type () const override
	Returns unique multiframe type id. More...

QUrl	url () const
	Returns the URL of the content displayed in the item if the item is using the QgsLayoutItemHtml::Url mode. More...

QString	userStylesheet () const
	Returns the user stylesheet CSS rules used while rendering the HTML content. More...

bool	userStylesheetEnabled () const
	Returns whether user stylesheets are enabled for the HTML content. More...

bool	useSmartBreaks () const
	Returns whether html item is using smart breaks. More...

Public Member Functions inherited from QgsLayoutMultiFrame
	QgsLayoutMultiFrame (QgsLayout *layout)
	Construct a new multiframe item, attached to the specified layout. More...

	~QgsLayoutMultiFrame () override

virtual void	addFrame (QgsLayoutFrame *frame, bool recalcFrameSizes=true)
	Adds a frame to the multiframe. More...

void	beginCommand (const QString &commandText, UndoCommand command=UndoNone)
	Starts new undo command for this item. More...

void	cancelCommand ()
	Cancels the current item command and discards it. More...

QgsAbstractLayoutUndoCommand *	createCommand (const QString &text, int id, QUndoCommand *parent=nullptr) override
	Creates a new layout undo command with the specified text and parent. More...

QgsLayoutFrame *	createNewFrame (QgsLayoutFrame *currentFrame, QPointF pos, QSizeF size)
	Creates a new frame and adds it to the multi frame and layout. More...

void	deleteFrames ()
	Removes and deletes all child frames. More...

void	endCommand ()
	Completes the current item command and push it onto the layout's undo stack. More...

virtual void	finalizeRestoreFromXml ()
	Called after all pending items have been restored from XML. More...

virtual QSizeF	fixedFrameSize (int frameIndex=-1) const
	Returns the fixed size for a frame, if desired. More...

QgsLayoutFrame *	frame (int index) const
	Returns the child frame at a specified index from the multiframe. More...

int	frameCount () const
	Returns the number of frames associated with this multiframe. More...

int	frameIndex (QgsLayoutFrame *frame) const
	Returns the index of a frame within the multiframe. More...

QList< QgsLayoutFrame * >	frames () const
	Returns a list of all child frames for this multiframe. More...

virtual QSizeF	minFrameSize (int frameIndex=-1) const
	Returns the minimum size for a frames, if desired. More...

bool	readXml (const QDomElement &itemElement, const QDomDocument &document, const QgsReadWriteContext &context, bool includeFrames=false)
	Sets the item state from a DOM element. More...

void	removeFrame (int index, bool removeEmptyPages=false)
	Removes a frame by index from the multiframe. More...

ResizeMode	resizeMode () const
	Returns the resize mode for the multiframe. More...

void	setResizeMode (ResizeMode mode)
	Sets the resize mode for the multiframe, and recalculates frame sizes to match. More...

QString	uuid () const
	Returns the multiframe identification string. More...

bool	writeXml (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context, bool includeFrames=false) const
	Stores the multiframe state in a DOM element. More...

Public Member Functions inherited from QgsLayoutObject
	QgsLayoutObject (QgsLayout *layout)
	Constructor for QgsLayoutObject, with the specified parent layout. More...

QgsExpressionContext	createExpressionContext () const override
	Creates an expression context relating to the objects' current state. More...

QStringList	customProperties () const
	Returns list of keys stored in custom properties for the object. More...

QVariant	customProperty (const QString &key, const QVariant &defaultValue=QVariant()) const
	Read a custom property from the object. More...

QgsPropertyCollection &	dataDefinedProperties ()
	Returns a reference to the object's property collection, used for data defined overrides. More...

const QgsPropertyCollection &	dataDefinedProperties () const
	Returns a reference to the object's property collection, used for data defined overrides. More...

const QgsLayout *	layout () const
	Returns the layout the object is attached to. More...

QgsLayout *	layout ()
	Returns the layout the object is attached to. More...

void	removeCustomProperty (const QString &key)
	Remove a custom property from the object. More...

void	setCustomProperty (const QString &key, const QVariant &value)
	Set a custom property for the object. More...

void	setDataDefinedProperties (const QgsPropertyCollection &collection)
	Sets the objects's property collection, used for data defined overrides. More...

Public Member Functions inherited from QgsExpressionContextGenerator
virtual	~QgsExpressionContextGenerator ()=default

Public Member Functions inherited from QgsLayoutUndoObjectInterface
virtual	~QgsLayoutUndoObjectInterface ()=default
	Destructor for QgsLayoutUndoObjectInterface. More...

Static Public Member Functions
static QgsLayoutItemHtml *	create (QgsLayout *layout)
	Returns a new QgsLayoutItemHtml for the specified parent layout. More...

Static Public Member Functions inherited from QgsLayoutObject
static const QgsPropertiesDefinition &	propertyDefinitions ()
	Returns the layout object property definitions. More...

Protected Member Functions
bool	readPropertiesFromElement (const QDomElement &itemElem, const QDomDocument &doc, const QgsReadWriteContext &context) override
	Sets multiframe state from a DOM element. More...

bool	writePropertiesToElement (QDomElement &elem, QDomDocument &doc, const QgsReadWriteContext &context) const override
	Stores multiframe state within an XML DOM element. More...

Protected Member Functions inherited from QgsLayoutObject
bool	readObjectPropertiesFromElement (const QDomElement &parentElement, const QDomDocument &document, const QgsReadWriteContext &context)
	Sets object properties from a DOM element. More...

bool	writeObjectPropertiesToElement (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context) const
	Stores object properties within an XML DOM element. More...

Additional Inherited Members
Signals inherited from QgsLayoutMultiFrame
void	contentsChanged ()
	Emitted when the contents of the multi frame have changed and the frames must be redrawn. More...

Signals inherited from QgsLayoutObject
void	changed ()
	Emitted when the object's properties change. More...

Protected Attributes inherited from QgsLayoutMultiFrame
QList< QgsLayoutFrame * >	mFrameItems

ResizeMode	mResizeMode = UseExistingFrames

Protected Attributes inherited from QgsLayoutObject
QgsObjectCustomProperties	mCustomProperties
	Custom properties for object. More...

QgsPropertyCollection	mDataDefinedProperties

QPointer< QgsLayout >	mLayout

Detailed Description

A layout multiframe subclass for HTML content.

Since: QGIS 3.0

Definition at line 36 of file qgslayoutitemhtml.h.

Member Enumeration Documentation

enum QgsLayoutItemHtml::ContentMode

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

Enumerator
Url	Using this mode item fetches its content via a url.
ManualHtml	HTML content is manually set for the item.

Definition at line 43 of file qgslayoutitemhtml.h.

Constructor & Destructor Documentation

QgsLayoutItemHtml::QgsLayoutItemHtml ( QgsLayout * layout )

Constructor for QgsLayoutItemHtml, with the specified parent layout.

Ownership is transferred to the layout.

Definition at line 38 of file qgslayoutitemhtml.cpp.

QgsLayoutItemHtml::~QgsLayoutItemHtml ( )

override

Definition at line 76 of file qgslayoutitemhtml.cpp.

Member Function Documentation

ContentMode QgsLayoutItemHtml::contentMode ( ) const

inline

Returns the source mode for item's HTML content.

See also: setContentMode(); url(); html()

Definition at line 80 of file qgslayoutitemhtml.h.

QgsLayoutItemHtml * QgsLayoutItemHtml::create ( QgsLayout * layout )

static

Returns a new QgsLayoutItemHtml for the specified parent layout.

Definition at line 91 of file qgslayoutitemhtml.cpp.

QString QgsLayoutItemHtml::displayName ( ) const

overridevirtual

Returns the multiframe display name.

Reimplemented from QgsLayoutMultiFrame.

Definition at line 452 of file qgslayoutitemhtml.cpp.

bool QgsLayoutItemHtml::evaluateExpressions ( ) const

inline

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.

See also: setEvaluateExpressions()

Definition at line 125 of file qgslayoutitemhtml.h.

double QgsLayoutItemHtml::findNearbyPageBreak ( double yPos )

overridevirtual

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

Reimplemented from QgsLayoutMultiFrame.

Definition at line 338 of file qgslayoutitemhtml.cpp.

QString QgsLayoutItemHtml::html ( ) const

inline

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

See also: setHtml(); contentMode()

Definition at line 116 of file qgslayoutitemhtml.h.

QIcon QgsLayoutItemHtml::icon ( ) const

overridevirtual

Returns the item's icon.

Reimplemented from QgsLayoutMultiFrame.

Definition at line 86 of file qgslayoutitemhtml.cpp.

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

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

See also: setUrl; url

Definition at line 124 of file qgslayoutitemhtml.cpp.

double QgsLayoutItemHtml::maxBreakDistance ( ) const

inline

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: setMaxBreakDistance(); useSmartBreaks()

Definition at line 170 of file qgslayoutitemhtml.h.

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

overrideprotectedvirtual

Sets multiframe state from a DOM element.

Parameters

element	is the DOM element for the multiframe
document	DOM document
context	read write context

See also: writePropertiesToElement()

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().

See also: readXml()

Reimplemented from QgsLayoutMultiFrame.

Definition at line 470 of file qgslayoutitemhtml.cpp.

void QgsLayoutItemHtml::recalculateFrameSizes ( )

overrideslot

Recalculates the frame sizes for the current viewport dimensions.

Definition at line 237 of file qgslayoutitemhtml.cpp.

void QgsLayoutItemHtml::refreshDataDefinedProperty ( QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties )

overrideslot

Definition at line 548 of file qgslayoutitemhtml.cpp.

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

overridevirtual

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

Implements QgsLayoutMultiFrame.

Definition at line 302 of file qgslayoutitemhtml.cpp.

void QgsLayoutItemHtml::setContentMode ( ContentMode mode )

inline

Sets the source mode for item's HTML content.

See also: contentMode(); setUrl(); setHtml()

Definition at line 72 of file qgslayoutitemhtml.h.

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.

See also: evaluateExpressions()

Definition at line 117 of file qgslayoutitemhtml.cpp.

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.

See also: html(); contentMode(); loadHtml()

Definition at line 108 of file qgslayoutitemhtml.cpp.

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.

See also: maxBreakDistance(); setUseSmartBreaks()

Definition at line 426 of file qgslayoutitemhtml.cpp.

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.

See also: url(); contentMode()

Definition at line 96 of file qgslayoutitemhtml.cpp.

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.