QGIS API Documentation 3.99.0-Master (26c88405ac0)
Loading...
Searching...
No Matches
QgsLayoutItemHtml Class Reference

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 class  DataDefinedProperty : int {
  NoProperty = 0 , AllProperties , TestProperty , PresetPaperSize ,
  PaperWidth , PaperHeight , NumPages , PaperOrientation ,
  PageNumber , PositionX , PositionY , ItemWidth ,
  ItemHeight , ItemRotation , Transparency , Opacity ,
  BlendMode , ExcludeFromExports , FrameColor , BackgroundColor ,
  MarginLeft , MarginTop , MarginRight , MarginBottom ,
  MapRotation , MapScale , MapXMin , MapYMin ,
  MapXMax , MapYMax , MapAtlasMargin , MapLayers ,
  MapStylePreset , MapLabelMargin , MapGridEnabled , MapGridIntervalX ,
  MapGridIntervalY , MapGridOffsetX , MapGridOffsetY , MapGridFrameSize ,
  MapGridFrameMargin , MapGridLabelDistance , MapGridCrossSize , MapGridFrameLineThickness ,
  MapGridAnnotationDisplayLeft , MapGridAnnotationDisplayRight , MapGridAnnotationDisplayTop , MapGridAnnotationDisplayBottom ,
  MapGridFrameDivisionsLeft , MapGridFrameDivisionsRight , MapGridFrameDivisionsTop , MapGridFrameDivisionsBottom ,
  MapCrs , StartDateTime , EndDateTime , MapZRangeLower ,
  MapZRangeUpper , PictureSource , PictureSvgBackgroundColor , PictureSvgStrokeColor ,
  PictureSvgStrokeWidth , SourceUrl , LegendTitle , LegendColumnCount ,
  LegendAutoWrapWidth , ScalebarLeftSegments , ScalebarRightSegments , ScalebarSegmentWidth ,
  ScalebarMinimumWidth , ScalebarMaximumWidth , ScalebarHeight , ScalebarRightSegmentSubdivisions ,
  ScalebarSubdivisionHeight , ScalebarFillColor , ScalebarFillColor2 , ScalebarLineColor ,
  ScalebarLineWidth , AttributeTableSourceLayer , ElevationProfileTolerance , ElevationProfileDistanceMajorInterval ,
  ElevationProfileDistanceMinorInterval , ElevationProfileDistanceLabelInterval , ElevationProfileElevationMajorInterval , ElevationProfileElevationMinorInterval ,
  ElevationProfileElevationLabelInterval , ElevationProfileMinimumDistance , ElevationProfileMaximumDistance , ElevationProfileMinimumElevation ,
  ElevationProfileMaximumElevation
}
 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.
void recalculateFrameSizes () override
 Recalculates the frame sizes for the current viewport dimensions.
void refreshDataDefinedProperty (QgsLayoutObject::DataDefinedProperty property=QgsLayoutObject::DataDefinedProperty::AllProperties) override
Public Slots inherited from QgsLayoutMultiFrame
void recalculateFrameRects ()
 Forces a recalculation of all the associated frame's scene rectangles.
virtual void recalculateFrameSizes ()
 Recalculates the portion of the multiframe item which is shown in each of its component frames.
void refresh () override
 Refreshes the multiframe, causing a recalculation of any property overrides.
virtual void refreshDataDefinedProperty (QgsLayoutObject::DataDefinedProperty property=QgsLayoutObject::DataDefinedProperty::AllProperties)
 Refreshes a data defined property for the multi frame by reevaluating the property's value and redrawing the item with this new value.
void update ()
 Forces a redraw of all child frames.
Public Slots inherited from QgsLayoutObject
virtual void refresh ()
 Refreshes the object, causing a recalculation of any property overrides.

Public Member Functions

 QgsLayoutItemHtml (QgsLayout *layout)
 Constructor for QgsLayoutItemHtml, with the specified parent layout.
 ~QgsLayoutItemHtml () override
ContentMode contentMode () const
 Returns the source mode for item's HTML content.
QString displayName () const override
 Returns the multiframe display name.
bool evaluateExpressions () const
 Returns whether html item will evaluate QGIS expressions prior to rendering the HTML content.
double findNearbyPageBreak (double yPos) override
 Finds the optimal position to break a frame at.
QString html () const
 Returns the HTML source displayed in the item if the item is using the QgsLayoutItemHtml::ManualHtml mode.
QIcon icon () const override
 Returns the item's icon.
double maxBreakDistance () const
 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.
QSizeF totalSize () const override
 Returns the total size of the multiframe's content, in layout units.
int type () const override
 Returns unique multiframe type id.
QUrl url () const
 Returns the URL of the content displayed in the item if the item is using the QgsLayoutItemHtml::Url mode.
QString userStylesheet () const
 Returns the user stylesheet CSS rules used while rendering the HTML content.
bool userStylesheetEnabled () const
 Returns whether user stylesheets are enabled for the HTML content.
bool useSmartBreaks () const
 Returns whether html item is using smart breaks.
Public Member Functions inherited from QgsLayoutMultiFrame
 QgsLayoutMultiFrame (QgsLayout *layout)
 Construct a new multiframe item, attached to the specified layout.
 ~QgsLayoutMultiFrame () override
virtual void addFrame (QgsLayoutFrame *frame, bool recalcFrameSizes=true)
 Adds a frame to the multiframe.
void beginCommand (const QString &commandText, UndoCommand command=UndoNone)
 Starts new undo command for this item.
void cancelCommand ()
 Cancels the current item command and discards it.
QgsAbstractLayoutUndoCommandcreateCommand (const QString &text, int id, QUndoCommand *parent=nullptr) override
 Creates a new layout undo command with the specified text and parent.
QgsExpressionContext createExpressionContext () const override
 This method needs to be reimplemented in all classes which implement this interface and return an expression context.
QgsLayoutFramecreateNewFrame (QgsLayoutFrame *currentFrame, QPointF pos, QSizeF size)
 Creates a new frame and adds it to the multi frame and layout.
void deleteFrames ()
 Removes and deletes all child frames.
void endCommand ()
 Completes the current item command and push it onto the layout's undo stack.
virtual void finalizeRestoreFromXml ()
 Called after all pending items have been restored from XML.
virtual QSizeF fixedFrameSize (int frameIndex=-1) const
 Returns the fixed size for a frame, if desired.
QgsLayoutFrameframe (int index) const
 Returns the child frame at a specified index from the multiframe.
int frameCount () const
 Returns the number of frames associated with this multiframe.
int frameIndex (QgsLayoutFrame *frame) const
 Returns the index of a frame within the multiframe.
QList< QgsLayoutFrame * > frames () const
 Returns a list of all child frames for this multiframe.
virtual QSizeF minFrameSize (int frameIndex=-1) const
 Returns the minimum size for a frames, if desired.
bool readXml (const QDomElement &itemElement, const QDomDocument &document, const QgsReadWriteContext &context, bool includeFrames=false)
 Sets the item state from a DOM element.
void removeFrame (int index, bool removeEmptyPages=false)
 Removes a frame by index from the multiframe.
ResizeMode resizeMode () const
 Returns the resize mode for the multiframe.
void setResizeMode (ResizeMode mode)
 Sets the resize mode for the multiframe, and recalculates frame sizes to match.
QString uuid () const
 Returns the multiframe identification string.
bool writeXml (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context, bool includeFrames=false) const
 Stores the multiframe state in a DOM element.
Public Member Functions inherited from QgsLayoutObject
 QgsLayoutObject (QgsLayout *layout)
 Constructor for QgsLayoutObject, with the specified parent layout.
QgsExpressionContext createExpressionContext () const override
 Creates an expression context relating to the objects' current state.
QStringList customProperties () const
 Returns list of keys stored in custom properties for the object.
QVariant customProperty (const QString &key, const QVariant &defaultValue=QVariant()) const
 Read a custom property from the object.
QgsPropertyCollectiondataDefinedProperties ()
 Returns a reference to the object's property collection, used for data defined overrides.
const QgsPropertyCollectiondataDefinedProperties () const
 Returns a reference to the object's property collection, used for data defined overrides.
QgsLayoutlayout ()
 Returns the layout the object is attached to.
const QgsLayoutlayout () const
 Returns the layout the object is attached to.
void removeCustomProperty (const QString &key)
 Remove a custom property from the object.
void setCustomProperty (const QString &key, const QVariant &value)
 Set a custom property for the object.
void setDataDefinedProperties (const QgsPropertyCollection &collection)
 Sets the objects's property collection, used for data defined overrides.
Public Member Functions inherited from QgsExpressionContextGenerator
virtual ~QgsExpressionContextGenerator ()=default
Public Member Functions inherited from QgsLayoutUndoObjectInterface
virtual ~QgsLayoutUndoObjectInterface ()=default

Static Public Member Functions

static QgsLayoutItemHtmlcreate (QgsLayout *layout)
 Returns a new QgsLayoutItemHtml for the specified parent layout.
static QgsLayoutItemHtmlcreateFromLabel (QgsLayoutItemLabel *label)
 Returns a new QgsLayoutItemHtml matching the content and rendering of a given label.
Static Public Member Functions inherited from QgsLayoutObject
static bool propertyAssociatesWithParentMultiframe (DataDefinedProperty property)
 Returns true if the specified property key is normally associated with the parent QgsLayoutMultiFrame object instead of a child QgsLayoutFrame object.
static const QgsPropertiesDefinitionpropertyDefinitions ()
 Returns the layout object property definitions.

Protected Member Functions

bool readPropertiesFromElement (const QDomElement &itemElem, const QDomDocument &doc, const QgsReadWriteContext &context) override
 Sets multiframe state from a DOM element.
bool writePropertiesToElement (QDomElement &elem, QDomDocument &doc, const QgsReadWriteContext &context) const override
 Stores multiframe state within an XML DOM element.
Protected Member Functions inherited from QgsLayoutObject
bool readObjectPropertiesFromElement (const QDomElement &parentElement, const QDomDocument &document, const QgsReadWriteContext &context)
 Sets object properties from a DOM element.
bool writeObjectPropertiesToElement (QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context) const
 Stores object properties within an XML DOM element.

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.
Signals inherited from QgsLayoutObject
void changed ()
 Emitted when the object's properties change.
Protected Attributes inherited from QgsLayoutMultiFrame
QList< QgsLayoutFrame * > mFrameItems
ResizeMode mResizeMode = UseExistingFrames
Protected Attributes inherited from QgsLayoutObject
QgsObjectCustomProperties mCustomProperties
 Custom properties for object.
QgsPropertyCollection mDataDefinedProperties
QPointer< QgsLayoutmLayout

Detailed Description

A layout multiframe subclass for HTML content.

Definition at line 37 of file qgslayoutitemhtml.h.

Member Enumeration Documentation

◆ 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 44 of file qgslayoutitemhtml.h.

Constructor & Destructor Documentation

◆ QgsLayoutItemHtml()

QgsLayoutItemHtml::QgsLayoutItemHtml ( QgsLayout * layout)

Constructor for QgsLayoutItemHtml, with the specified parent layout.

Ownership is transferred to the layout.

Definition at line 49 of file qgslayoutitemhtml.cpp.

◆ ~QgsLayoutItemHtml()

QgsLayoutItemHtml::~QgsLayoutItemHtml ( )
override

Definition at line 87 of file qgslayoutitemhtml.cpp.

Member Function Documentation

◆ contentMode()

ContentMode QgsLayoutItemHtml::contentMode ( ) const
inline

Returns the source mode for item's HTML content.

See also
setContentMode()
url()
html()

Definition at line 88 of file qgslayoutitemhtml.h.

◆ create()

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

Returns a new QgsLayoutItemHtml for the specified parent layout.

Definition at line 102 of file qgslayoutitemhtml.cpp.

◆ createFromLabel()

QgsLayoutItemHtml * QgsLayoutItemHtml::createFromLabel ( QgsLayoutItemLabel * label)
static

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

Since
QGIS 3.32

Definition at line 107 of file qgslayoutitemhtml.cpp.

◆ displayName()

QString QgsLayoutItemHtml::displayName ( ) const
overridevirtual

Returns the multiframe display name.

Reimplemented from QgsLayoutMultiFrame.

Definition at line 525 of file qgslayoutitemhtml.cpp.

◆ evaluateExpressions()

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 133 of file qgslayoutitemhtml.h.

◆ findNearbyPageBreak()

double QgsLayoutItemHtml::findNearbyPageBreak ( double yPos)
overridevirtual

Finds the optimal position to break a frame at.

Parameters
yPosmaximum 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 411 of file qgslayoutitemhtml.cpp.

◆ html()

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 124 of file qgslayoutitemhtml.h.

◆ icon()

QIcon QgsLayoutItemHtml::icon ( ) const
overridevirtual

Returns the item's icon.

Reimplemented from QgsLayoutMultiFrame.

Definition at line 97 of file qgslayoutitemhtml.cpp.

◆ loadHtml

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

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

Parameters
useCacheset to true to use a cached copy of remote html content
contextexpression context for evaluating data defined urls and expressions in html
See also
setUrl
url

Definition at line 162 of file qgslayoutitemhtml.cpp.

◆ maxBreakDistance()

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 178 of file qgslayoutitemhtml.h.

◆ readPropertiesFromElement()

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

Sets multiframe state from a DOM element.

Parameters
elementis the DOM element for the multiframe
documentDOM document
contextread 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 543 of file qgslayoutitemhtml.cpp.

◆ recalculateFrameSizes

void QgsLayoutItemHtml::recalculateFrameSizes ( )
overrideslot

Recalculates the frame sizes for the current viewport dimensions.

Definition at line 277 of file qgslayoutitemhtml.cpp.

◆ refreshDataDefinedProperty

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

Definition at line 621 of file qgslayoutitemhtml.cpp.

◆ render()

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

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

Parameters
contextdestination render painter
renderExtentvisible extent of content to render into the painter.
frameIndexframe number for content

Implements QgsLayoutMultiFrame.

Definition at line 342 of file qgslayoutitemhtml.cpp.

◆ setContentMode()

void QgsLayoutItemHtml::setContentMode ( ContentMode mode)
inline

Sets the source mode for item's HTML content.

See also
contentMode()
setUrl()
setHtml()

Definition at line 80 of file qgslayoutitemhtml.h.

◆ setEvaluateExpressions()

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 155 of file qgslayoutitemhtml.cpp.

◆ setHtml()

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 146 of file qgslayoutitemhtml.cpp.

◆ setMaxBreakDistance()

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 499 of file qgslayoutitemhtml.cpp.

◆ setUrl()

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 134 of file qgslayoutitemhtml.cpp.

◆ setUserStylesheet()

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.

See also
userStylesheet()
setUserStylesheetEnabled()
loadHtml()

Definition at line 506 of file qgslayoutitemhtml.cpp.

◆ setUserStylesheetEnabled()

void QgsLayoutItemHtml::setUserStylesheetEnabled ( bool enabled)

Sets whether user stylesheets are enabled for the HTML content.

See also
userStylesheetEnabled()
setUserStylesheet()

Definition at line 515 of file qgslayoutitemhtml.cpp.

◆ setUseSmartBreaks()

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.

See also
useSmartBreaks()

Definition at line 492 of file qgslayoutitemhtml.cpp.

◆ totalSize()

QSizeF QgsLayoutItemHtml::totalSize ( ) const
overridevirtual

Returns the total size of the multiframe's content, in layout units.

Implements QgsLayoutMultiFrame.

Definition at line 337 of file qgslayoutitemhtml.cpp.

◆ type()

int QgsLayoutItemHtml::type ( ) const
overridevirtual

Returns unique multiframe type id.

Implements QgsLayoutMultiFrame.

Definition at line 92 of file qgslayoutitemhtml.cpp.

◆ url()

QUrl QgsLayoutItemHtml::url ( ) const
inline

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

See also
setUrl()
contentMode()

Definition at line 105 of file qgslayoutitemhtml.h.

◆ userStylesheet()

QString QgsLayoutItemHtml::userStylesheet ( ) const
inline

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

These overriding the styles specified within the HTML source.

See also
setUserStylesheet()
userStylesheetEnabled()

Definition at line 197 of file qgslayoutitemhtml.h.

◆ userStylesheetEnabled()

bool QgsLayoutItemHtml::userStylesheetEnabled ( ) const
inline

Returns whether user stylesheets are enabled for the HTML content.

See also
setUserStylesheetEnabled()
userStylesheet()

Definition at line 211 of file qgslayoutitemhtml.h.

◆ useSmartBreaks()

bool QgsLayoutItemHtml::useSmartBreaks ( ) const
inline

Returns whether html item is using smart breaks.

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

See also
setUseSmartBreaks()

Definition at line 149 of file qgslayoutitemhtml.h.

◆ writePropertiesToElement()

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

Stores multiframe state within an XML DOM element.

Parameters
elementis the DOM element to store the multiframe's properties in
documentDOM document
contextread write context
See also
writeXml()
readPropertiesFromElement()

Reimplemented from QgsLayoutMultiFrame.

Definition at line 530 of file qgslayoutitemhtml.cpp.


The documentation for this class was generated from the following files: