QGIS API Documentation  3.22.4-Białowieża (ce8e65e95e)
Public Types | Public Slots | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
QgsLayoutItemHtml Class Reference

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

#include <qgslayoutitemhtml.h>

Inheritance diagram for QgsLayoutItemHtml:
Inheritance graph
[legend]

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 , MapLabelMargin , MapGridEnabled , MapGridIntervalX ,
  MapGridIntervalY , MapGridOffsetX , MapGridOffsetY , MapGridFrameSize ,
  MapGridFrameMargin , MapGridLabelDistance , MapGridCrossSize , MapGridFrameLineThickness ,
  MapGridAnnotationDisplayLeft , MapGridAnnotationDisplayRight , MapGridAnnotationDisplayTop , MapGridAnnotationDisplayBottom ,
  MapGridFrameDivisionsLeft , MapGridFrameDivisionsRight , MapGridFrameDivisionsTop , MapGridFrameDivisionsBottom ,
  PictureSource , PictureSvgBackgroundColor , PictureSvgStrokeColor , PictureSvgStrokeWidth ,
  SourceUrl , LegendTitle , LegendColumnCount , ScalebarFillColor ,
  ScalebarFillColor2 , ScalebarLineColor , ScalebarLineWidth , AttributeTableSourceLayer ,
  MapCrs , StartDateTime , EndDateTime
}
 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...
 
QgsAbstractLayoutUndoCommandcreateCommand (const QString &text, int id, QUndoCommand *parent=nullptr) override
 Creates a new layout undo command with the specified text and parent. More...
 
QgsExpressionContext createExpressionContext () const override
 This method needs to be reimplemented in all classes which implement this interface and return an expression context. More...
 
QgsLayoutFramecreateNewFrame (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...
 
QgsLayoutFrameframe (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...
 
QgsPropertyCollectiondataDefinedProperties ()
 Returns a reference to the object's property collection, used for data defined overrides. More...
 
const QgsPropertyCollectiondataDefinedProperties () const
 Returns a reference to the object's property collection, used for data defined overrides. More...
 
QgsLayoutlayout ()
 Returns the layout the object is attached to. More...
 
const QgsLayoutlayout () const
 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 QgsLayoutItemHtmlcreate (QgsLayout *layout)
 Returns a new QgsLayoutItemHtml for the specified parent layout. More...
 
- 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. More...
 
static const QgsPropertiesDefinitionpropertyDefinitions ()
 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< QgsLayoutmLayout
 

Detailed Description

A layout multiframe subclass for HTML content.

Since
QGIS 3.0

Definition at line 36 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 43 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 42 of file qgslayoutitemhtml.cpp.

◆ ~QgsLayoutItemHtml()

QgsLayoutItemHtml::~QgsLayoutItemHtml ( )
override

Definition at line 80 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 80 of file qgslayoutitemhtml.h.

◆ create()

QgsLayoutItemHtml * QgsLayoutItemHtml::create ( QgsLayout layout)
static

Returns a new QgsLayoutItemHtml for the specified parent layout.

Definition at line 95 of file qgslayoutitemhtml.cpp.

◆ displayName()

QString QgsLayoutItemHtml::displayName ( ) const
overridevirtual

Returns the multiframe display name.

Reimplemented from QgsLayoutMultiFrame.

Definition at line 455 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 125 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 341 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 116 of file qgslayoutitemhtml.h.

◆ icon()

QIcon QgsLayoutItemHtml::icon ( ) const
overridevirtual

Returns the item's icon.

Reimplemented from QgsLayoutMultiFrame.

Definition at line 90 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 128 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 170 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 473 of file qgslayoutitemhtml.cpp.

◆ recalculateFrameSizes

void QgsLayoutItemHtml::recalculateFrameSizes ( )
overrideslot

Recalculates the frame sizes for the current viewport dimensions.

Definition at line 241 of file qgslayoutitemhtml.cpp.

◆ refreshDataDefinedProperty

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

Definition at line 551 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 306 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 72 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 121 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 112 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 429 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 100 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 436 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 445 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 422 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 301 of file qgslayoutitemhtml.cpp.

◆ type()

int QgsLayoutItemHtml::type ( ) const
overridevirtual

Returns unique multiframe type id.

Implements QgsLayoutMultiFrame.

Definition at line 85 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 97 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 189 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 203 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 141 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 460 of file qgslayoutitemhtml.cpp.


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