QGIS API Documentation  3.8.0-Zanzibar (11aff65)
Public Types | Public Slots | Signals | Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
QgsLayoutMultiFrame Class Referenceabstract

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

#include <qgslayoutmultiframe.h>

Inheritance diagram for QgsLayoutMultiFrame:
Inheritance graph
[legend]

Public Types

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, 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 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...
 

Signals

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

Public Member Functions

 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...
 
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...
 
virtual QString displayName () const
 Returns the multiframe display name. 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 double findNearbyPageBreak (double yPos)
 Finds the optimal position to break a frame at. 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 QIcon icon () const
 Returns the item's icon. 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...
 
virtual void render (QgsLayoutItemRenderContext &context, const QRectF &renderExtent, int frameIndex)=0
 Renders a portion of the multiframe's content into a render context. 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...
 
virtual QSizeF totalSize () const =0
 Returns the total size of the multiframe's content, in layout units. More...
 
virtual int type () const =0
 Returns unique multiframe type id. 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...
 
const QgsLayoutlayout () const
 Returns the layout the object is attached to. More...
 
QgsLayoutlayout ()
 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...
 

Protected Member Functions

virtual bool readPropertiesFromElement (const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context)
 Sets multiframe state from a DOM element. More...
 
virtual bool writePropertiesToElement (QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context) const
 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...
 

Protected Attributes

QList< QgsLayoutFrame * > mFrameItems
 
ResizeMode mResizeMode = UseExistingFrames
 
- Protected Attributes inherited from QgsLayoutObject
QgsObjectCustomProperties mCustomProperties
 Custom properties for object. More...
 
QgsPropertyCollection mDataDefinedProperties
 
QPointer< QgsLayoutmLayout
 

Friends

class QgsLayout
 
class QgsLayoutFrame
 

Additional Inherited Members

- Static Public Member Functions inherited from QgsLayoutObject
static const QgsPropertiesDefinitionpropertyDefinitions ()
 Returns the layout object property definitions. More...
 

Detailed Description

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

Since
QGIS 3.0

Definition at line 48 of file qgslayoutmultiframe.h.

Member Enumeration Documentation

◆ ResizeMode

Specifies the behavior for creating new frames to fit the multiframe's content.

Enumerator
UseExistingFrames 

Don't automatically create new frames, just use existing frames.

ExtendToNextPage 

Creates new full page frames on the following page(s) until the entire multiframe content is visible.

RepeatOnEveryPage 

Repeats the same frame on every page.

RepeatUntilFinished 

creates new frames with the same position and dimensions as the existing frame on the following page(s), until the entire multiframe content is visible

Definition at line 96 of file qgslayoutmultiframe.h.

◆ UndoCommand

Multiframe item undo commands, used for collapsing undo commands.

Enumerator
UndoHtmlBreakDistance 

HTML page break distance.

UndoHtmlSource 

HTML source.

UndoHtmlStylesheet 

HTML stylesheet.

UndoTableCellStyle 

Table cell style.

UndoTableMaximumFeatures 

Maximum features in table.

UndoTableMargin 

Table margins.

UndoTableHeaderFontColor 

Table header font color.

UndoTableContentFontColor 

Table content font color.

UndoTableGridStrokeWidth 

Table grid stroke width.

UndoTableGridColor 

Table grid color.

UndoTableBackgroundColor 

Table background color.

UndoNone 

No command suppression.

Definition at line 106 of file qgslayoutmultiframe.h.

Constructor & Destructor Documentation

◆ QgsLayoutMultiFrame()

QgsLayoutMultiFrame::QgsLayoutMultiFrame ( QgsLayout layout)

Construct a new multiframe item, attached to the specified layout.

Definition at line 24 of file qgslayoutmultiframe.cpp.

◆ ~QgsLayoutMultiFrame()

QgsLayoutMultiFrame::~QgsLayoutMultiFrame ( )
override

Definition at line 33 of file qgslayoutmultiframe.cpp.

Member Function Documentation

◆ addFrame()

void QgsLayoutMultiFrame::addFrame ( QgsLayoutFrame frame,
bool  recalcFrameSizes = true 
)
virtual

Adds a frame to the multiframe.

If recalcFrameSizes is set to true, then a recalculation of all existing frame sizes will be forced.

See also
removeFrame()

Definition at line 55 of file qgslayoutmultiframe.cpp.

◆ beginCommand()

void QgsLayoutMultiFrame::beginCommand ( const QString &  commandText,
QgsLayoutMultiFrame::UndoCommand  command = UndoNone 
)

Starts new undo command for this item.

The commandText should be a capitalized, imperative tense description (e.g. "Add Map Item"). If specified, multiple consecutive commands for this item with the same command will be collapsed into a single undo command in the layout history.

See also
endCommand()
cancelCommand()

Definition at line 282 of file qgslayoutmultiframe.cpp.

◆ cancelCommand()

void QgsLayoutMultiFrame::cancelCommand ( )

Cancels the current item command and discards it.

See also
beginCommand()
endCommand()

Definition at line 296 of file qgslayoutmultiframe.cpp.

◆ contentsChanged

void QgsLayoutMultiFrame::contentsChanged ( )
signal

Emitted when the contents of the multi frame have changed and the frames must be redrawn.

◆ createCommand()

QgsAbstractLayoutUndoCommand * QgsLayoutMultiFrame::createCommand ( const QString &  text,
int  id,
QUndoCommand *  parent = nullptr 
)
overridevirtual

Creates a new layout undo command with the specified text and parent.

The id argument can be used to specify an id number for the source event - this is used to determine whether QUndoCommand command compression can apply to the command.

Implements QgsLayoutUndoObjectInterface.

Definition at line 277 of file qgslayoutmultiframe.cpp.

◆ createNewFrame()

QgsLayoutFrame * QgsLayoutMultiFrame::createNewFrame ( QgsLayoutFrame currentFrame,
QPointF  pos,
QSizeF  size 
)

Creates a new frame and adds it to the multi frame and layout.

Parameters
currentFramean existing QgsLayoutFrame from which to copy the size and general frame properties (e.g., frame style, background, rendering settings).
posposition of top-left corner of the new frame, in layout units
sizesize of the new frame, in layout units

Definition at line 246 of file qgslayoutmultiframe.cpp.

◆ deleteFrames()

void QgsLayoutMultiFrame::deleteFrames ( )

Removes and deletes all child frames.

See also
removeFrame()

Definition at line 445 of file qgslayoutmultiframe.cpp.

◆ displayName()

QString QgsLayoutMultiFrame::displayName ( ) const
virtual

Returns the multiframe display name.

Reimplemented in QgsLayoutItemHtml, QgsLayoutItemAttributeTable, and QgsLayoutItemTextTable.

Definition at line 272 of file qgslayoutmultiframe.cpp.

◆ endCommand()

void QgsLayoutMultiFrame::endCommand ( )

Completes the current item command and push it onto the layout's undo stack.

See also
beginCommand()
cancelCommand()

Definition at line 290 of file qgslayoutmultiframe.cpp.

◆ finalizeRestoreFromXml()

void QgsLayoutMultiFrame::finalizeRestoreFromXml ( )
virtual

Called after all pending items have been restored from XML.

Multiframes can use this method to run steps which must take place after all items have been restored to the layout, such as connecting to signals emitted by other items, which may not have existed in the layout at the time readXml() was called. E.g. a scalebar can use this to connect to its linked map item after restoration from XML.

See also
readXml()

Reimplemented in QgsLayoutItemAttributeTable.

Definition at line 302 of file qgslayoutmultiframe.cpp.

◆ findNearbyPageBreak()

double QgsLayoutMultiFrame::findNearbyPageBreak ( double  yPos)
virtual

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 in QgsLayoutItemHtml.

Definition at line 50 of file qgslayoutmultiframe.cpp.

◆ fixedFrameSize()

QSizeF QgsLayoutMultiFrame::fixedFrameSize ( int  frameIndex = -1) const
virtual

Returns the fixed size for a frame, if desired.

If the fixed frame size changes, the sizes of all frames can be recalculated by calling recalculateFrameRects().

Parameters
frameIndexframe number
Returns
fixed size for frame. If the size has a width or height of 0, then the frame size is not fixed in that direction and frames can have variable width or height accordingly.
See also
minFrameSize()
recalculateFrameRects()

Reimplemented in QgsLayoutTable.

Definition at line 38 of file qgslayoutmultiframe.cpp.

◆ frame()

QgsLayoutFrame * QgsLayoutMultiFrame::frame ( int  index) const

Returns the child frame at a specified index from the multiframe.

See also
frameIndex()

Definition at line 461 of file qgslayoutmultiframe.cpp.

◆ frameCount()

int QgsLayoutMultiFrame::frameCount ( ) const
inline

Returns the number of frames associated with this multiframe.

See also
frames()

Definition at line 260 of file qgslayoutmultiframe.h.

◆ frameIndex()

int QgsLayoutMultiFrame::frameIndex ( QgsLayoutFrame frame) const

Returns the index of a frame within the multiframe.

Returns
index for frame if found, -1 if frame not found in multiframe
See also
frame()

Definition at line 470 of file qgslayoutmultiframe.cpp.

◆ frames()

QList< QgsLayoutFrame * > QgsLayoutMultiFrame::frames ( ) const

Returns a list of all child frames for this multiframe.

See also
frameCount()

Definition at line 90 of file qgslayoutmultiframe.cpp.

◆ icon()

virtual QIcon QgsLayoutMultiFrame::icon ( ) const
inlinevirtual

Returns the item's icon.

Reimplemented in QgsLayoutItemHtml, and QgsLayoutItemAttributeTable.

Definition at line 149 of file qgslayoutmultiframe.h.

◆ minFrameSize()

QSizeF QgsLayoutMultiFrame::minFrameSize ( int  frameIndex = -1) const
virtual

Returns the minimum size for a frames, if desired.

If the minimum size changes, the sizes of all frames can be recalculated by calling recalculateFrameRects().

Parameters
frameIndexframe number
Returns
minimum size for frame. If the size has a width or height of 0, then the frame size has no minimum in that direction.
See also
fixedFrameSize()
recalculateFrameRects()

Reimplemented in QgsLayoutTable.

Definition at line 44 of file qgslayoutmultiframe.cpp.

◆ readPropertiesFromElement()

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

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 in QgsLayoutTable, QgsLayoutItemAttributeTable, and QgsLayoutItemHtml.

Definition at line 564 of file qgslayoutmultiframe.cpp.

◆ readXml()

bool QgsLayoutMultiFrame::readXml ( const QDomElement &  itemElement,
const QDomDocument &  document,
const QgsReadWriteContext context,
bool  includeFrames = false 
)

Sets the item state from a DOM element.

Parameters
itemElementis the DOM node corresponding to item (e.g. 'LayoutItem' element)
documentDOM document
contextread write context
includeFramesset to true to read state information about child frames from DOM
See also
writeXml()

Definition at line 506 of file qgslayoutmultiframe.cpp.

◆ recalculateFrameRects

void QgsLayoutMultiFrame::recalculateFrameRects ( )
slot

Forces a recalculation of all the associated frame's scene rectangles.

This method is useful for multiframes which implement a minFrameSize() or fixedFrameSize() method.

See also
minFrameSize()
fixedFrameSize()
recalculateFrameSizes

Definition at line 226 of file qgslayoutmultiframe.cpp.

◆ recalculateFrameSizes

void QgsLayoutMultiFrame::recalculateFrameSizes ( )
virtualslot

Recalculates the portion of the multiframe item which is shown in each of its component frames.

If the resize mode is set to anything but UseExistingFrames then this may cause new frames to be added or frames to be removed, in order to fit the current size of the multiframe's content.

See also
recalculateFrameRects()

Definition at line 95 of file qgslayoutmultiframe.cpp.

◆ refresh

void QgsLayoutMultiFrame::refresh ( )
overrideslot

Refreshes the multiframe, causing a recalculation of any property overrides.

Definition at line 330 of file qgslayoutmultiframe.cpp.

◆ refreshDataDefinedProperty

void QgsLayoutMultiFrame::refreshDataDefinedProperty ( QgsLayoutObject::DataDefinedProperty  property = QgsLayoutObject::AllProperties)
virtualslot

Refreshes a data defined property for the multi frame by reevaluating the property's value and redrawing the item with this new value.

If property is set to QgsLayoutObject::AllProperties then all data defined properties for the item will be refreshed.

Reimplemented in QgsLayoutItemAttributeTable.

Definition at line 241 of file qgslayoutmultiframe.cpp.

◆ removeFrame()

void QgsLayoutMultiFrame::removeFrame ( int  index,
bool  removeEmptyPages = false 
)

Removes a frame by index from the multiframe.

This method automatically removes the frame from the layout too.

If removeEmptyPages is set to true, then pages which are empty after the frame is removed will also be removed from the layout.

See also
addFrame()
deleteFrames()

Definition at line 411 of file qgslayoutmultiframe.cpp.

◆ render()

virtual void QgsLayoutMultiFrame::render ( QgsLayoutItemRenderContext context,
const QRectF &  renderExtent,
int  frameIndex 
)
pure virtual

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

Implemented in QgsLayoutTable, and QgsLayoutItemHtml.

◆ resizeMode()

ResizeMode QgsLayoutMultiFrame::resizeMode ( ) const
inline

Returns the resize mode for the multiframe.

See also
setResizeMode()

Definition at line 228 of file qgslayoutmultiframe.h.

◆ setResizeMode()

void QgsLayoutMultiFrame::setResizeMode ( ResizeMode  mode)

Sets the resize mode for the multiframe, and recalculates frame sizes to match.

See also
resizeMode()

Definition at line 78 of file qgslayoutmultiframe.cpp.

◆ totalSize()

virtual QSizeF QgsLayoutMultiFrame::totalSize ( ) const
pure virtual

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

Implemented in QgsLayoutTable, and QgsLayoutItemHtml.

◆ type()

virtual int QgsLayoutMultiFrame::type ( ) const
pure virtual

Returns unique multiframe type id.

Implemented in QgsLayoutItemHtml, QgsLayoutItemAttributeTable, and QgsLayoutItemTextTable.

◆ update

void QgsLayoutMultiFrame::update ( )
slot

Forces a redraw of all child frames.

Definition at line 437 of file qgslayoutmultiframe.cpp.

◆ uuid()

QString QgsLayoutMultiFrame::uuid ( ) const
inline

Returns the multiframe identification string.

This is a unique random string set for the multiframe upon creation.

Note
There is no corresponding setter for the uuid - it's created automatically.

Definition at line 134 of file qgslayoutmultiframe.h.

◆ writePropertiesToElement()

bool QgsLayoutMultiFrame::writePropertiesToElement ( QDomElement &  element,
QDomDocument &  document,
const QgsReadWriteContext context 
) const
protectedvirtual

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 in QgsLayoutTable, QgsLayoutItemAttributeTable, and QgsLayoutItemHtml.

Definition at line 559 of file qgslayoutmultiframe.cpp.

◆ writeXml()

bool QgsLayoutMultiFrame::writeXml ( QDomElement &  parentElement,
QDomDocument &  document,
const QgsReadWriteContext context,
bool  includeFrames = false 
) const

Stores the multiframe state in a DOM element.

Parameters
parentElementparent DOM element (e.g. 'Layout' element)
documentDOM document
contextread write context
includeFramesset to true to write state information about child frames into DOM
See also
readXml()

Definition at line 475 of file qgslayoutmultiframe.cpp.

Friends And Related Function Documentation

◆ QgsLayout

friend class QgsLayout
friend

Definition at line 434 of file qgslayoutmultiframe.h.

◆ QgsLayoutFrame

friend class QgsLayoutFrame
friend

Definition at line 433 of file qgslayoutmultiframe.h.

Member Data Documentation

◆ mFrameItems

QList<QgsLayoutFrame *> QgsLayoutMultiFrame::mFrameItems
protected

Definition at line 401 of file qgslayoutmultiframe.h.

◆ mResizeMode

ResizeMode QgsLayoutMultiFrame::mResizeMode = UseExistingFrames
protected

Definition at line 403 of file qgslayoutmultiframe.h.


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