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:

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

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

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

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

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

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< QgsLayout >	mLayout

Friends
class	QgsLayout

class	QgsLayoutFrame

Additional Inherited Members
Static Public Member Functions inherited from QgsLayoutObject
static const QgsPropertiesDefinition &	propertyDefinitions ()
	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 47 of file qgslayoutmultiframe.h.

Member Enumeration Documentation

enum QgsLayoutMultiFrame::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 95 of file qgslayoutmultiframe.h.

enum QgsLayoutMultiFrame::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 105 of file qgslayoutmultiframe.h.

Constructor & Destructor Documentation

QgsLayoutMultiFrame::QgsLayoutMultiFrame ( QgsLayout * layout )

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

Definition at line 24 of file qgslayoutmultiframe.cpp.

QgsLayoutMultiFrame::~QgsLayoutMultiFrame ( )

override

Definition at line 33 of file qgslayoutmultiframe.cpp.

Member Function Documentation

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.

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.

void QgsLayoutMultiFrame::cancelCommand ( )

Cancels the current item command and discards it.

See also: beginCommand(); endCommand()

Definition at line 296 of file qgslayoutmultiframe.cpp.

void QgsLayoutMultiFrame::contentsChanged ( )

signal

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

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.

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

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

Parameters

currentFrame	an existing QgsLayoutFrame from which to copy the size and general frame properties (e.g., frame style, background, rendering settings).
pos	position of top-left corner of the new frame, in layout units
size	size of the new frame, in layout units

Definition at line 246 of file qgslayoutmultiframe.cpp.

void QgsLayoutMultiFrame::deleteFrames ( )

Removes and deletes all child frames.

See also: removeFrame()

Definition at line 445 of file qgslayoutmultiframe.cpp.

QString QgsLayoutMultiFrame::displayName ( ) const

virtual

Returns the multiframe display name.

Reimplemented in QgsLayoutItemHtml, QgsLayoutItemAttributeTable, and QgsLayoutItemTextTable.

Definition at line 272 of file qgslayoutmultiframe.cpp.

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.

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.

double QgsLayoutMultiFrame::findNearbyPageBreak ( double yPos )

virtual

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

Definition at line 50 of file qgslayoutmultiframe.cpp.

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

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

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.

int QgsLayoutMultiFrame::frameCount ( ) const

inline

Returns the number of frames associated with this multiframe.

See also: frames()

Definition at line 259 of file qgslayoutmultiframe.h.

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.

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.

virtual QIcon QgsLayoutMultiFrame::icon ( ) const

inlinevirtual

Returns the item's icon.

Reimplemented in QgsLayoutItemAttributeTable, and QgsLayoutItemHtml.

Definition at line 148 of file qgslayoutmultiframe.h.

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

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

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

protectedvirtual

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

Definition at line 564 of file qgslayoutmultiframe.cpp.

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

Sets the item state from a DOM element.

Parameters

itemElement	is the DOM node corresponding to item (e.g. 'LayoutItem' element)
document	DOM document
context	read write context
includeFrames	set to true to read state information about child frames from DOM

See also: writeXml()

Definition at line 506 of file qgslayoutmultiframe.cpp.

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.

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.

void QgsLayoutMultiFrame::refresh ( )

overrideslot

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

Definition at line 330 of file qgslayoutmultiframe.cpp.

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.

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.

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

context	destination render painter
renderExtent	visible extent of content to render into the painter.
frameIndex	frame number for content

Implemented in QgsLayoutTable, and QgsLayoutItemHtml.

ResizeMode QgsLayoutMultiFrame::resizeMode ( ) const

inline

Returns the resize mode for the multiframe.

See also: setResizeMode()

Definition at line 227 of file qgslayoutmultiframe.h.

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.

virtual QSizeF QgsLayoutMultiFrame::totalSize ( ) const

pure virtual

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

Implemented in QgsLayoutTable, and QgsLayoutItemHtml.

virtual int QgsLayoutMultiFrame::type ( ) const

pure virtual

Returns unique multiframe type id.

Implemented in QgsLayoutItemAttributeTable, QgsLayoutItemHtml, and QgsLayoutItemTextTable.

void QgsLayoutMultiFrame::update ( )

slot

Forces a redraw of all child frames.

Definition at line 437 of file qgslayoutmultiframe.cpp.

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

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

protectedvirtual

Stores multiframe state within an XML DOM element.

Parameters

element	is the DOM element to store the multiframe's properties in
document	DOM document
context	read write context

See also: writeXml(); readPropertiesFromElement()

Reimplemented in QgsLayoutTable, QgsLayoutItemAttributeTable, and QgsLayoutItemHtml.

Definition at line 559 of file qgslayoutmultiframe.cpp.

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

Stores the multiframe state in a DOM element.

Parameters

parentElement	parent DOM element (e.g. 'Layout' element)
document	DOM document
context	read write context
includeFrames	set 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

friend class QgsLayout

friend

Definition at line 433 of file qgslayoutmultiframe.h.

friend class QgsLayoutFrame

friend

Definition at line 432 of file qgslayoutmultiframe.h.

Member Data Documentation

QList<QgsLayoutFrame *> QgsLayoutMultiFrame::mFrameItems

protected

Definition at line 400 of file qgslayoutmultiframe.h.

ResizeMode QgsLayoutMultiFrame::mResizeMode = UseExistingFrames

protected

Definition at line 402 of file qgslayoutmultiframe.h.

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

/build/qgis-3.4.15+24xenial/src/core/layout/qgslayoutmultiframe.h
/build/qgis-3.4.15+24xenial/src/core/layout/qgslayoutmultiframe.cpp

Public Types

Public Slots

Signals

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation