QGIS API Documentation  2.18.21-Las Palmas (9fba24a)
Public Types | Public Slots | Signals | Public Member Functions | Protected Slots | Protected Attributes | List of all members
QgsComposerMultiFrame Class Referenceabstract

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

#include <qgscomposermultiframe.h>

Inheritance diagram for QgsComposerMultiFrame:
Inheritance graph
[legend]

Public Types

enum  ResizeMode { UseExistingFrames = 0, ExtendToNextPage, RepeatOnEveryPage, RepeatUntilFinished }
 Specifies the behaviour for creating new frames to fit the multiframe's content. More...
 
- Public Types inherited from QgsComposerObject
enum  DataDefinedProperty {
  NoProperty = 0, AllProperties, TestProperty, PresetPaperSize,
  PaperWidth, PaperHeight, NumPages, PaperOrientation,
  PageNumber, PositionX, PositionY, ItemWidth,
  ItemHeight, ItemRotation, Transparency, BlendMode,
  ExcludeFromExports, MapRotation, MapScale, MapXMin,
  MapYMin, MapXMax, MapYMax, MapAtlasMargin,
  MapLayers, MapStylePreset, PictureSource, SourceUrl
}
 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 it's component frames. More...
 
void update ()
 Forces a redraw of all child frames. More...
 
- Public Slots inherited from QgsComposerObject
virtual void refreshDataDefinedProperty (const DataDefinedProperty property=AllProperties, const QgsExpressionContext *context=nullptr)
 Refreshes a data defined property for the item by reevaluating the property's value and redrawing the item with this new value. More...
 
virtual void repaint ()
 Triggers a redraw for the item. More...
 

Signals

void changed ()
 Emitted when the properties of a multi frame have changed, and the GUI item widget must be updated. More...
 
void contentsChanged ()
 Emitted when the contents of the multi frame have changed and the frames must be redrawn. More...
 
- Signals inherited from QgsComposerObject
void itemChanged ()
 Emitted when the item changes. More...
 

Public Member Functions

 QgsComposerMultiFrame (QgsComposition *c, bool createUndoCommands)
 Construct a new multiframe item. More...
 
virtual ~QgsComposerMultiFrame ()
 
bool _readXML (const QDomElement &itemElem, const QDomDocument &doc, bool ignoreFrames=false)
 Restores state information about base multiframe object from a DOM element. More...
 
bool _writeXML (QDomElement &elem, QDomDocument &doc, bool ignoreFrames=false) const
 Stores state information about base multiframe object in DOM element. More...
 
virtual void addFrame (QgsComposerFrame *frame, bool recalcFrameSizes=true)=0
 Adds a frame to the multiframe. More...
 
QgsCompositioncomposition ()
 Returns the parent composition for the multiframe. More...
 
QgsComposerFramecreateNewFrame (QgsComposerFrame *currentFrame, QPointF pos, QSizeF size)
 Creates a new frame and adds it to the multi frame and composition. More...
 
bool createUndoCommands () const
 Returns whether undo commands should be created for interactions with the multiframe. More...
 
void deleteFrames ()
 Removes and deletes all child frames. More...
 
virtual QString displayName () const
 Get multiframe display name. More...
 
virtual double findNearbyPageBreak (double yPos)
 Finds the optimal position to break a frame at. More...
 
virtual QSizeF fixedFrameSize (const int frameIndex=-1) const
 Returns the fixed size for a frame, if desired. More...
 
QgsComposerFrameframe (int i) const
 Returns a child frame from the multiframe. More...
 
int frameCount () const
 Returns the number of frames associated with this multiframe. More...
 
int frameIndex (QgsComposerFrame *frame) const
 Returns the index of a frame within the multiframe. More...
 
virtual QSizeF minFrameSize (const int frameIndex=-1) const
 Returns the minimum size for a frames, if desired. More...
 
virtual bool readXML (const QDomElement &itemElem, const QDomDocument &doc, bool ignoreFrames=false)=0
 Reads multiframe state information from a DOM element. More...
 
void removeFrame (int i, const bool removeEmptyPages=false)
 Removes a frame from the multiframe. More...
 
virtual Q_DECL_DEPRECATED void render (QPainter *p, const QRectF &renderExtent)
 Renders a portion of the multiframe's content into a painter. More...
 
virtual void render (QPainter *painter, const QRectF &renderExtent, const int frameIndex)
 Renders a portion of the multiframe's content into a painter. More...
 
ResizeMode resizeMode () const
 Returns the resize mode for the multiframe. More...
 
void setCreateUndoCommands (bool enabled)
 Sets whether undo commands should be created for interactions with 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. More...
 
virtual bool writeXML (QDomElement &elem, QDomDocument &doc, bool ignoreFrames=false) const =0
 Stores state information about multiframe in DOM element. More...
 
- Public Member Functions inherited from QgsComposerObject
 QgsComposerObject (QgsComposition *composition)
 Constructor. More...
 
virtual ~QgsComposerObject ()
 
const QgsCompositioncomposition () const
 Returns the composition the item is attached to. More...
 
QgsCompositioncomposition ()
 
virtual QgsExpressionContextcreateExpressionContext () const
 Creates an expression context relating to the objects' current state. More...
 
QStringList customProperties () const
 Return 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...
 
QgsDataDefineddataDefinedProperty (const DataDefinedProperty property) const
 Returns a reference to the data defined settings for one of the item's data defined properties. More...
 
virtual bool readXML (const QDomElement &itemElem, const QDomDocument &doc)
 Sets item state from DOM element. 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 setDataDefinedProperty (const DataDefinedProperty property, const bool active, const bool useExpression, const QString &expression, const QString &field)
 Sets parameters for a data defined property for the item. More...
 
virtual bool writeXML (QDomElement &elem, QDomDocument &doc) const
 Stores item state in DOM element. More...
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
 QObject (QObject *parent, const char *name)
 
virtual ~QObject ()
 
bool blockSignals (bool block)
 
QObjectchild (const char *objName, const char *inheritsClass, bool recursiveSearch) const
 
const QObjectList & children () const
 
const char * className () const
 
bool connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const QObject *receiver, const char *method)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method)
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QByteArraydynamicPropertyNames () const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name) const
 
QList< T > findChildren (const QRegExp &regExp) const
 
QList< T > findChildren (const QString &name) const
 
bool inherits (const char *className) const
 
void insertChild (QObject *object)
 
void installEventFilter (QObject *filterObj)
 
bool isA (const char *className) const
 
bool isWidgetType () const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
const char * name () const
 
const char * name (const char *defaultName) const
 
QString objectName () const
 
QObjectparent () const
 
QVariant property (const char *name) const
 
void removeChild (QObject *object)
 
void removeEventFilter (QObject *obj)
 
void setName (const char *name)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval)
 
QThreadthread () const
 

Protected Slots

void handleFrameRemoval (QgsComposerItem *item)
 Called before a frame is going to be removed. More...
 
void handlePageChange ()
 Adapts to changed number of composition pages if resize type is RepeatOnEveryPage. More...
 

Protected Attributes

bool mCreateUndoCommands
 True: creates QgsMultiFrameCommands on internal changes (e.g. More...
 
QList< QgsComposerFrame * > mFrameItems
 
ResizeMode mResizeMode
 
- Protected Attributes inherited from QgsComposerObject
QgsCompositionmComposition
 
QgsObjectCustomProperties mCustomProperties
 Custom properties for object. More...
 
QMap< QgsComposerObject::DataDefinedProperty, QStringmDataDefinedNames
 Map of data defined properties for the item to string name to use when exporting item to xml. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from QObject
bool connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
bool connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Protected Member Functions inherited from QgsComposerObject
bool dataDefinedEvaluate (const QgsComposerObject::DataDefinedProperty property, QVariant &expressionValue, const QgsExpressionContext &context=QgsExpressionContext()) const
 Evaluate a data defined property and return the calculated value. More...
 
- Protected Member Functions inherited from QObject
bool checkConnectArgs (const char *signal, const QObject *object, const char *method)
 
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const char *signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const char *signal)
 
int receivers (const char *signal) const
 
QObjectsender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 
- Static Protected Member Functions inherited from QObject
QByteArray normalizeSignalSlot (const char *signalSlot)
 
- Properties inherited from QObject
 objectName
 

Detailed Description

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

Definition at line 39 of file qgscomposermultiframe.h.

Member Enumeration Documentation

◆ ResizeMode

Specifies the behaviour 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 47 of file qgscomposermultiframe.h.

Constructor & Destructor Documentation

◆ QgsComposerMultiFrame()

QgsComposerMultiFrame::QgsComposerMultiFrame ( QgsComposition c,
bool  createUndoCommands 
)

Construct a new multiframe item.

Parameters
cparent composition
createUndoCommands

Definition at line 21 of file qgscomposermultiframe.cpp.

◆ ~QgsComposerMultiFrame()

QgsComposerMultiFrame::~QgsComposerMultiFrame ( )
virtual

Definition at line 39 of file qgscomposermultiframe.cpp.

Member Function Documentation

◆ _readXML()

bool QgsComposerMultiFrame::_readXML ( const QDomElement itemElem,
const QDomDocument doc,
bool  ignoreFrames = false 
)

Restores state information about base multiframe object from a DOM element.

Implementations of readXML should call this method.

Parameters
itemElemis DOM element
docis the DOM document
ignoreFramesset to false to avoid reading state information about child frames from DOM
See also
readXML

Definition at line 374 of file qgscomposermultiframe.cpp.

◆ _writeXML()

bool QgsComposerMultiFrame::_writeXML ( QDomElement elem,
QDomDocument doc,
bool  ignoreFrames = false 
) const

Stores state information about base multiframe object in DOM element.

Implementations of writeXML should call this method.

Parameters
elemis DOM element
docis the DOM document
ignoreFramesset to false to avoid writing state information about child frames into DOM
See also
writeXML

Definition at line 359 of file qgscomposermultiframe.cpp.

◆ addFrame()

virtual void QgsComposerMultiFrame::addFrame ( QgsComposerFrame frame,
bool  recalcFrameSizes = true 
)
pure virtual

Adds a frame to the multiframe.

Parameters
frameframe to add
recalcFrameSizesset to true to force recalculation of all existing frame sizes
See also
removeFrame

Implemented in QgsComposerHtml, QgsComposerTextTableV2, and QgsComposerAttributeTableV2.

◆ changed

void QgsComposerMultiFrame::changed ( )
signal

Emitted when the properties of a multi frame have changed, and the GUI item widget must be updated.

◆ composition()

QgsComposition* QgsComposerMultiFrame::composition ( )
inline

Returns the parent composition for the multiframe.

Returns
composition

Definition at line 188 of file qgscomposermultiframe.h.

◆ contentsChanged

void QgsComposerMultiFrame::contentsChanged ( )
signal

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

◆ createNewFrame()

QgsComposerFrame * QgsComposerMultiFrame::createNewFrame ( QgsComposerFrame currentFrame,
QPointF  pos,
QSizeF  size 
)

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

Parameters
currentFramean existing QgsComposerFrame from which to copy the size and general frame properties (eg frame style, background, rendering settings).
posposition of top-left corner of the new frame
sizesize of the new frame
Returns
new QgsComposerFrame
Note
added in version 2.3

Definition at line 199 of file qgscomposermultiframe.cpp.

◆ createUndoCommands()

bool QgsComposerMultiFrame::createUndoCommands ( ) const
inline

Returns whether undo commands should be created for interactions with the multiframe.

Returns
true if undo commands should be created
See also
setCreateUndoCommands

Definition at line 194 of file qgscomposermultiframe.h.

◆ deleteFrames()

void QgsComposerMultiFrame::deleteFrames ( )

Removes and deletes all child frames.

See also
removeFrame

Definition at line 330 of file qgscomposermultiframe.cpp.

◆ displayName()

QString QgsComposerMultiFrame::displayName ( ) const
virtual

Get multiframe display name.

Returns
display name for item
Note
added in version 2.5

Reimplemented in QgsComposerHtml, and QgsComposerAttributeTableV2.

Definition at line 225 of file qgscomposermultiframe.cpp.

◆ findNearbyPageBreak()

virtual double QgsComposerMultiFrame::findNearbyPageBreak ( double  yPos)
inlinevirtual

Finds the optimal position to break a frame at.

Parameters
yPosmaximum vertical position for break
Returns
the optimal breakable position which occurs in the multi frame close to and before the specified yPos
Note
added in version 2.3

Reimplemented in QgsComposerHtml.

Definition at line 121 of file qgscomposermultiframe.h.

◆ fixedFrameSize()

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

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.
Note
added in version 2.5
See also
minFrameSize
recalculateFrameRects

Reimplemented in QgsComposerTableV2.

Definition at line 79 of file qgscomposermultiframe.h.

◆ frame()

QgsComposerFrame * QgsComposerMultiFrame::frame ( int  i) const

Returns a child frame from the multiframe.

Parameters
iindex of frame
Returns
child frame if found
See also
frameIndex

Definition at line 345 of file qgscomposermultiframe.cpp.

◆ frameCount()

int QgsComposerMultiFrame::frameCount ( ) const
inline

Returns the number of frames associated with this multiframe.

Returns
number of child frames

Definition at line 205 of file qgscomposermultiframe.h.

◆ frameIndex()

int QgsComposerMultiFrame::frameIndex ( QgsComposerFrame frame) const

Returns the index of a frame within the multiframe.

Parameters
frameframe to find index of
Returns
index for frame if found, -1 if frame not found in multiframe
Note
added in version 2.5
See also
frame

Definition at line 354 of file qgscomposermultiframe.cpp.

◆ handleFrameRemoval

void QgsComposerMultiFrame::handleFrameRemoval ( QgsComposerItem item)
protectedslot

Called before a frame is going to be removed.

Updates frame list and recalculates content of remaining frames.

Definition at line 230 of file qgscomposermultiframe.cpp.

◆ handlePageChange

void QgsComposerMultiFrame::handlePageChange ( )
protectedslot

Adapts to changed number of composition pages if resize type is RepeatOnEveryPage.

Definition at line 257 of file qgscomposermultiframe.cpp.

◆ minFrameSize()

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

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.
Note
added in version 2.5
See also
fixedFrameSize
recalculateFrameRects

Reimplemented in QgsComposerTableV2.

Definition at line 91 of file qgscomposermultiframe.h.

◆ readXML()

virtual bool QgsComposerMultiFrame::readXML ( const QDomElement itemElem,
const QDomDocument doc,
bool  ignoreFrames = false 
)
pure virtual

Reads multiframe state information from a DOM element.

Implementations of readXML should also call the _readXML method to restore general multiframe properties.

Parameters
itemElemis DOM element
docis the DOM document
ignoreFramesset to false to avoid read state information about child frames from DOM
See also
_readXML

Implemented in QgsComposerTableV2, QgsComposerHtml, and QgsComposerAttributeTableV2.

◆ recalculateFrameRects

void QgsComposerMultiFrame::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.

Note
added in version 2.5
See also
minFrameSize()
fixedFrameSize()
recalculateFrameSizes

Definition at line 184 of file qgscomposermultiframe.cpp.

◆ recalculateFrameSizes

void QgsComposerMultiFrame::recalculateFrameSizes ( )
virtualslot

Recalculates the portion of the multiframe item which is shown in each of it's 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 70 of file qgscomposermultiframe.cpp.

◆ removeFrame()

void QgsComposerMultiFrame::removeFrame ( int  i,
const bool  removeEmptyPages = false 
)

Removes a frame from the multiframe.

This method automatically removes the frame from the composition.

Parameters
iindex of frame to remove
removeEmptyPagesset to true to remove pages which are empty after the frame is removed
See also
addFrame
deleteFrames

Definition at line 298 of file qgscomposermultiframe.cpp.

◆ render() [1/2]

void QgsComposerMultiFrame::render ( QPainter p,
const QRectF renderExtent 
)
virtual

Renders a portion of the multiframe's content into a painter.

Parameters
pdestination painter
renderExtentvisible extent of content to render into the painter.
Deprecated:
use render( QPainter* painter, const QRectF& renderExtent, const int frameIndex ) instead

Definition at line 44 of file qgscomposermultiframe.cpp.

◆ render() [2/2]

void QgsComposerMultiFrame::render ( QPainter painter,
const QRectF renderExtent,
const int  frameIndex 
)
virtual

Renders a portion of the multiframe's content into a painter.

Parameters
painterdestination painter
renderExtentvisible extent of content to render into the painter.
frameIndexframe number for content
Note
added in version 2.5

Reimplemented in QgsComposerTableV2, and QgsComposerHtml.

Definition at line 51 of file qgscomposermultiframe.cpp.

◆ resizeMode()

ResizeMode QgsComposerMultiFrame::resizeMode ( ) const
inline

Returns the resize mode for the multiframe.

Returns
resize mode
See also
setResizeMode

Definition at line 147 of file qgscomposermultiframe.h.

◆ setCreateUndoCommands()

void QgsComposerMultiFrame::setCreateUndoCommands ( bool  enabled)
inline

Sets whether undo commands should be created for interactions with the multiframe.

Parameters
enabledset to true if undo commands should be created
See also
createUndoCommands

Definition at line 200 of file qgscomposermultiframe.h.

◆ setResizeMode()

void QgsComposerMultiFrame::setResizeMode ( ResizeMode  mode)

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

Parameters
moderesize mode
See also
resizeMode

Definition at line 60 of file qgscomposermultiframe.cpp.

◆ totalSize()

virtual QSizeF QgsComposerMultiFrame::totalSize ( ) const
pure virtual

Returns the total size of the multiframe's content.

Returns
total size required for content

Implemented in QgsComposerTableV2, and QgsComposerHtml.

◆ update

void QgsComposerMultiFrame::update ( )
slot

Forces a redraw of all child frames.

Definition at line 322 of file qgscomposermultiframe.cpp.

◆ writeXML()

virtual bool QgsComposerMultiFrame::writeXML ( QDomElement elem,
QDomDocument doc,
bool  ignoreFrames = false 
) const
pure virtual

Stores state information about multiframe in DOM element.

Implementations of writeXML should also call the _writeXML method to save general multiframe properties.

Parameters
elemis DOM element
docis the DOM document
ignoreFramesset to false to avoid writing state information about child frames into DOM
See also
_writeXML

Implemented in QgsComposerTableV2, QgsComposerHtml, and QgsComposerAttributeTableV2.

Member Data Documentation

◆ mCreateUndoCommands

bool QgsComposerMultiFrame::mCreateUndoCommands
protected

True: creates QgsMultiFrameCommands on internal changes (e.g.

changing frames )

Definition at line 281 of file qgscomposermultiframe.h.

◆ mFrameItems

QList<QgsComposerFrame*> QgsComposerMultiFrame::mFrameItems
protected

Definition at line 276 of file qgscomposermultiframe.h.

◆ mResizeMode

ResizeMode QgsComposerMultiFrame::mResizeMode
protected

Definition at line 278 of file qgscomposermultiframe.h.


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