QGIS API Documentation  3.16.0-Hannover (43b64b13f3)
Signals | Public Member Functions | Properties | List of all members
QgsPrintLayout Class Reference

Print layout, a QgsLayout subclass for static or atlas-based layouts. More...

#include <qgsprintlayout.h>

Inheritance diagram for QgsPrintLayout:
Inheritance graph
[legend]

Signals

void nameChanged (const QString &name)
 Emitted when the layout's name is changed. More...
 
- Signals inherited from QgsLayout
void backgroundTaskCountChanged (int total)
 Emitted whenever the total number of background tasks running in items from the layout changes. More...
 
void changed ()
 Emitted when properties of the layout change. More...
 
void refreshed ()
 Emitted when the layout has been refreshed and items should also be refreshed and updated. More...
 
void selectedItemChanged (QgsLayoutItem *selected)
 Emitted whenever the selected item changes. More...
 
void variablesChanged ()
 Emitted whenever the expression variables stored in the layout have been changed. More...
 

Public Member Functions

 QgsPrintLayout (QgsProject *project)
 Constructor for QgsPrintLayout. More...
 
QgsLayoutAtlasatlas ()
 Returns the print layout's atlas. More...
 
QgsPrintLayoutclone () const override
 Creates a clone of the layout. More...
 
QgsExpressionContext createExpressionContext () const override
 Creates an expression context relating to the layout's current state. More...
 
QIcon icon () const override
 Returns an icon for the layout. More...
 
bool layoutAccept (QgsStyleEntityVisitorInterface *visitor) const override
 Accepts the specified style entity visitor, causing it to visit all style entities associated with the layout. More...
 
QgsProjectlayoutProject () const override
 The project associated with the layout. More...
 
QgsMasterLayoutInterface::Type layoutType () const override
 Returns the master layout type. More...
 
QString name () const override
 Returns the layout's name. More...
 
bool readLayoutXml (const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context) override
 Sets the layout's state from a DOM element. More...
 
bool readXml (const QDomElement &layoutElement, const QDomDocument &document, const QgsReadWriteContext &context) override
 Sets the collection's state from a DOM element. More...
 
void setName (const QString &name) override
 Sets the layout's name. More...
 
void updateSettings () override
 Refreshes the layout when global layout related options change. More...
 
QDomElement writeLayoutXml (QDomDocument &document, const QgsReadWriteContext &context) const override
 Returns the layout's state encapsulated in a DOM element. More...
 
QDomElement writeXml (QDomDocument &document, const QgsReadWriteContext &context) const override
 Returns the layout's state encapsulated in a DOM element. More...
 
- Public Member Functions inherited from QgsLayout
 QgsLayout (QgsProject *project)
 Construct a new layout linked to the specified project. More...
 
 ~QgsLayout () override
 
bool accept (QgsStyleEntityVisitorInterface *visitor) const
 Accepts the specified style entity visitor, causing it to visit all style entities associated with the layout. More...
 
QList< QgsLayoutItem * > addItemsFromXml (const QDomElement &parentElement, const QDomDocument &document, const QgsReadWriteContext &context, QPointF *position=nullptr, bool pasteInPlace=false)
 Add items from an XML representation to the layout. More...
 
void addLayoutItem (QgsLayoutItem *item)
 Adds an item to the layout. More...
 
void addMultiFrame (QgsLayoutMultiFrame *multiFrame)
 Adds a multiFrame to the layout. More...
 
void clear ()
 Clears the layout. More...
 
QgsLayoutclone () const
 Creates a clone of the layout. More...
 
QgsLayoutMeasurement convertFromLayoutUnits (double length, QgsUnitTypes::LayoutUnit unit) const
 Converts a length measurement from the layout's native units to a specified target unit. More...
 
QgsLayoutPoint convertFromLayoutUnits (QPointF point, QgsUnitTypes::LayoutUnit unit) const
 Converts a point from the layout's native units to a specified target unit. More...
 
QgsLayoutSize convertFromLayoutUnits (QSizeF size, QgsUnitTypes::LayoutUnit unit) const
 Converts a size from the layout's native units to a specified target unit. More...
 
QPointF convertToLayoutUnits (const QgsLayoutPoint &point) const
 Converts a point into the layout's native units. More...
 
QSizeF convertToLayoutUnits (const QgsLayoutSize &size) const
 Converts a size into the layout's native units. More...
 
double convertToLayoutUnits (QgsLayoutMeasurement measurement) const
 Converts a measurement into the layout's native units. More...
 
QgsAbstractLayoutUndoCommandcreateCommand (const QString &text, int id=0, QUndoCommand *parent=nullptr) override
 Creates a new layout undo command with the specified text and parent. More...
 
QStringList customProperties () const
 Returns list of keys stored in custom properties for the layout. More...
 
QVariant customProperty (const QString &key, const QVariant &defaultValue=QVariant()) const
 Read a custom property from the layout. More...
 
void deselectAll ()
 Clears any selected items in the layout. More...
 
QgsLayoutGridSettingsgridSettings ()
 Returns a reference to the layout's grid settings, which stores settings relating to grid appearance, spacing and offsets. More...
 
const QgsLayoutGridSettingsgridSettings () const
 Returns a reference to the layout's grid settings, which stores settings relating to grid appearance, spacing and offsets. More...
 
QgsLayoutItemGroupgroupItems (const QList< QgsLayoutItem * > &items)
 Creates a new group from a list of layout items and adds the group to the layout. More...
 
QgsLayoutGuideCollectionguides ()
 Returns a reference to the layout's guide collection, which manages page snap guides. More...
 
const QgsLayoutGuideCollectionguides () const
 Returns a reference to the layout's guide collection, which manages page snap guides. More...
 
void initializeDefaults ()
 Initializes an empty layout, e.g. More...
 
QgsLayoutItemitemById (const QString &id) const
 Returns a layout item given its id. More...
 
QgsLayoutItemitemByTemplateUuid (const QString &uuid) const
 Returns the layout item with matching template uuid unique identifier, or nullptr if a matching item could not be found. More...
 
QgsLayoutItemitemByUuid (const QString &uuid, bool includeTemplateUuids=false) const
 Returns the layout item with matching uuid unique identifier, or nullptr if a matching item could not be found. More...
 
QgsLayoutModelitemsModel ()
 Returns the items model attached to the layout. More...
 
QRectF layoutBounds (bool ignorePages=false, double margin=0.0) const
 Calculates the bounds of all non-gui items in the layout. More...
 
QgsLayoutItemlayoutItemAt (QPointF position, bool ignoreLocked=false) const
 Returns the topmost layout item at a specified position. More...
 
QgsLayoutItemlayoutItemAt (QPointF position, const QgsLayoutItem *belowItem, bool ignoreLocked=false) const
 Returns the topmost layout item at a specified position which is below a specified item. More...
 
template<class T >
void layoutItems (QList< T * > &itemList) const
 Returns a list of layout items of a specific type. More...
 
template<class T >
void layoutObjects (QList< T * > &objectList) const
 Returns a list of layout objects (items and multiframes) of a specific type. More...
 
QList< QgsLayoutItem * > loadFromTemplate (const QDomDocument &document, const QgsReadWriteContext &context, bool clearExisting=true, bool *ok=nullptr)
 Load a layout template document. More...
 
bool lowerItem (QgsLayoutItem *item, bool deferUpdate=false)
 Lowers an item down the z-order. More...
 
bool moveItemToBottom (QgsLayoutItem *item, bool deferUpdate=false)
 Lowers an item down to the bottom of the z-order. More...
 
bool moveItemToTop (QgsLayoutItem *item, bool deferUpdate=false)
 Raises an item up to the top of the z-order. More...
 
QgsLayoutMultiFramemultiFrameByUuid (const QString &uuid, bool includeTemplateUuids=false) const
 Returns the layout multiframe with matching uuid unique identifier, or nullptr if a matching multiframe could not be found. More...
 
QList< QgsLayoutMultiFrame * > multiFrames () const
 Returns a list of multi frames contained in the layout. More...
 
QgsLayoutPageCollectionpageCollection ()
 Returns a pointer to the layout's page collection, which stores and manages page items in the layout. More...
 
const QgsLayoutPageCollectionpageCollection () const
 Returns a pointer to the layout's page collection, which stores and manages page items in the layout. More...
 
QRectF pageItemBounds (int page, bool visibleOnly=false) const
 Returns the bounding box of the items contained on a specified page. More...
 
QgsProjectproject () const
 The project associated with the layout. More...
 
bool raiseItem (QgsLayoutItem *item, bool deferUpdate=false)
 Raises an item up the z-order. More...
 
QgsLayoutItemMapreferenceMap () const
 Returns the map item which will be used to generate corresponding world files when the layout is exported. More...
 
void reloadSettings ()
 Refreshes the layout when global layout related options change. More...
 
void removeCustomProperty (const QString &key)
 Remove a custom property from the layout. More...
 
void removeLayoutItem (QgsLayoutItem *item)
 Removes an item from the layout. More...
 
void removeMultiFrame (QgsLayoutMultiFrame *multiFrame)
 Removes a multiFrame from the layout (but does not delete it). More...
 
QgsLayoutRenderContextrenderContext ()
 Returns a reference to the layout's render context, which stores information relating to the current rendering settings for the layout. More...
 
const QgsLayoutRenderContextrenderContext () const
 Returns a reference to the layout's render context, which stores information relating to the current rendering settings for the layout. More...
 
QgsLayoutReportContextreportContext ()
 Returns a reference to the layout's report context, which stores information relating to the current reporting context for the layout. More...
 
const QgsLayoutReportContextreportContext () const
 Returns a reference to the layout's report context, which stores information relating to the current reporting context for the layout. More...
 
bool saveAsTemplate (const QString &path, const QgsReadWriteContext &context) const
 Saves the layout as a template at the given file path. More...
 
QList< QgsLayoutItem * > selectedLayoutItems (bool includeLockedItems=true)
 Returns list of selected layout items. More...
 
void setCustomProperty (const QString &key, const QVariant &value)
 Set a custom property for the layout. More...
 
void setReferenceMap (QgsLayoutItemMap *map)
 Sets the map item which will be used to generate corresponding world files when the layout is exported. More...
 
void setSelectedItem (QgsLayoutItem *item)
 Clears any selected items and sets item as the current selection. More...
 
void setUnits (QgsUnitTypes::LayoutUnit units)
 Sets the native measurement units for the layout. More...
 
QgsLayoutSnappersnapper ()
 Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and snapping points to the nearest matching point. More...
 
const QgsLayoutSnappersnapper () const
 Returns a reference to the layout's snapper, which stores handles layout snap grids and lines and snapping points to the nearest matching point. More...
 
QgsLayoutUndoStackundoStack ()
 Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout and it's associated objects. More...
 
const QgsLayoutUndoStackundoStack () const
 Returns a pointer to the layout's undo stack, which manages undo/redo states for the layout and it's associated objects. More...
 
QList< QgsLayoutItem * > ungroupItems (QgsLayoutItemGroup *group)
 Ungroups items by removing them from an item group and removing the group from the layout. More...
 
QgsUnitTypes::LayoutUnit units () const
 Returns the native units for the layout. More...
 
void updateZValues (bool addUndoCommands=true)
 Resets the z-values of items based on their position in the internal z order list. More...
 
- Public Member Functions inherited from QgsExpressionContextGenerator
virtual ~QgsExpressionContextGenerator ()=default
 
- Public Member Functions inherited from QgsLayoutUndoObjectInterface
virtual ~QgsLayoutUndoObjectInterface ()=default
 Destructor for QgsLayoutUndoObjectInterface. More...
 
- Public Member Functions inherited from QgsMasterLayoutInterface
virtual ~QgsMasterLayoutInterface ()=default
 

Properties

QString name
 

Additional Inherited Members

- Public Types inherited from QgsLayout
enum  UndoCommand { UndoLayoutDpi, UndoNone = -1 }
 Layout undo commands, used for collapsing undo commands. More...
 
enum  ZValues {
  ZPage = 0, ZItem = 1, ZGrid = 9997, ZGuide = 9998,
  ZSmartGuide = 9999, ZMouseHandles = 10000, ZViewTool = 10001, ZSnapIndicator = 10002
}
 Preset item z-values, to ensure correct stacking. More...
 
- Public Types inherited from QgsMasterLayoutInterface
enum  Type { PrintLayout = 0, Report = 1 }
 Master layout type. More...
 
- Public Slots inherited from QgsLayout
void refresh ()
 Forces the layout, and all items contained within it, to refresh. More...
 
void updateBounds ()
 Updates the scene bounds of the layout. More...
 

Detailed Description

Print layout, a QgsLayout subclass for static or atlas-based layouts.

Since
QGIS 3.0

Definition at line 30 of file qgsprintlayout.h.

Constructor & Destructor Documentation

◆ QgsPrintLayout()

QgsPrintLayout::QgsPrintLayout ( QgsProject project)

Constructor for QgsPrintLayout.

Definition at line 23 of file qgsprintlayout.cpp.

Member Function Documentation

◆ atlas()

QgsLayoutAtlas * QgsPrintLayout::atlas ( )

Returns the print layout's atlas.

Definition at line 58 of file qgsprintlayout.cpp.

◆ clone()

QgsPrintLayout * QgsPrintLayout::clone ( ) const
overridevirtual

Creates a clone of the layout.

Ownership of the returned layout is transferred to the caller.

Implements QgsMasterLayoutInterface.

Definition at line 29 of file qgsprintlayout.cpp.

◆ createExpressionContext()

QgsExpressionContext QgsPrintLayout::createExpressionContext ( ) const
overridevirtual

Creates an expression context relating to the layout's current state.

The context includes scopes for global, project, layout and layout context properties.

Reimplemented from QgsLayout.

Definition at line 100 of file qgsprintlayout.cpp.

◆ icon()

QIcon QgsPrintLayout::icon ( ) const
overridevirtual

Returns an icon for the layout.

Implements QgsMasterLayoutInterface.

Definition at line 53 of file qgsprintlayout.cpp.

◆ layoutAccept()

bool QgsPrintLayout::layoutAccept ( QgsStyleEntityVisitorInterface visitor) const
overridevirtual

Accepts the specified style entity visitor, causing it to visit all style entities associated with the layout.

Returns true if the visitor should continue visiting other objects, or false if visiting should be canceled.

Since
QGIS 3.10

Reimplemented from QgsMasterLayoutInterface.

Definition at line 117 of file qgsprintlayout.cpp.

◆ layoutProject()

QgsProject * QgsPrintLayout::layoutProject ( ) const
overridevirtual

The project associated with the layout.

Used to get access to layers, map themes, relations and various other bits. It is never nullptr.

Implements QgsMasterLayoutInterface.

Definition at line 48 of file qgsprintlayout.cpp.

◆ layoutType()

QgsMasterLayoutInterface::Type QgsPrintLayout::layoutType ( ) const
overridevirtual

Returns the master layout type.

Implements QgsMasterLayoutInterface.

Definition at line 130 of file qgsprintlayout.cpp.

◆ name()

QString QgsPrintLayout::name ( ) const
inlineoverridevirtual

Returns the layout's name.

See also
setName()

Implements QgsMasterLayoutInterface.

Definition at line 52 of file qgsprintlayout.h.

◆ nameChanged

void QgsPrintLayout::nameChanged ( const QString &  name)
signal

Emitted when the layout's name is changed.

See also
setName()

◆ readLayoutXml()

bool QgsPrintLayout::readLayoutXml ( const QDomElement &  layoutElement,
const QDomDocument &  document,
const QgsReadWriteContext context 
)
overridevirtual

Sets the layout's state from a DOM element.

layoutElement is the DOM node corresponding to the layout.

See also
writeLayoutXml()

Implements QgsMasterLayoutInterface.

Definition at line 95 of file qgsprintlayout.cpp.

◆ readXml()

bool QgsPrintLayout::readXml ( const QDomElement &  layoutElement,
const QDomDocument &  document,
const QgsReadWriteContext context 
)
overridevirtual

Sets the collection's state from a DOM element.

layoutElement is the DOM node corresponding to the layout.

See also
writeXml()

Reimplemented from QgsLayout.

Definition at line 77 of file qgsprintlayout.cpp.

◆ setName()

void QgsPrintLayout::setName ( const QString &  name)
overridevirtual

Sets the layout's name.

See also
name()

Implements QgsMasterLayoutInterface.

Definition at line 63 of file qgsprintlayout.cpp.

◆ updateSettings()

void QgsPrintLayout::updateSettings ( )
overridevirtual

Refreshes the layout when global layout related options change.

Implements QgsMasterLayoutInterface.

Definition at line 112 of file qgsprintlayout.cpp.

◆ writeLayoutXml()

QDomElement QgsPrintLayout::writeLayoutXml ( QDomDocument &  document,
const QgsReadWriteContext context 
) const
overridevirtual

Returns the layout's state encapsulated in a DOM element.

See also
readLayoutXml()

Implements QgsMasterLayoutInterface.

Definition at line 90 of file qgsprintlayout.cpp.

◆ writeXml()

QDomElement QgsPrintLayout::writeXml ( QDomDocument &  document,
const QgsReadWriteContext context 
) const
overridevirtual

Returns the layout's state encapsulated in a DOM element.

See also
readXml()

Reimplemented from QgsLayout.

Definition at line 69 of file qgsprintlayout.cpp.

Property Documentation

◆ name

QString QgsPrintLayout::name
readwrite

Definition at line 1 of file qgsprintlayout.h.


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