Handles rendering and exports of layouts to various formats. More...

#include <qgslayoutexporter.h>

Classes
struct	ImageExportSettings
	Contains settings relating to exporting layouts to raster images. More...

struct	PageExportDetails
	Contains details of a page being exported by the class. More...

struct	PdfExportSettings
	Contains settings relating to exporting layouts to PDF. More...

struct	PrintExportSettings
	Contains settings relating to printing layouts. More...

struct	SvgExportSettings
	Contains settings relating to exporting layouts to SVG. More...

Public Types
enum	ExportResult { Success , Canceled , MemoryError , FileError , PrintError , SvgLayerError , IteratorError }
	Result codes for exporting layouts. More...

Public Member Functions
	QgsLayoutExporter (QgsLayout *layout)
	Constructor for QgsLayoutExporter, for the specified layout.

virtual	~QgsLayoutExporter ()

void	computeWorldFileParameters (const QRectF &region, double &a, double &b, double &c, double &d, double &e, double &f, double dpi=-1) const
	Computes the world file parameters for a specified region of the layout.

void	computeWorldFileParameters (double &a, double &b, double &c, double &d, double &e, double &f, double dpi=-1) const
	Compute world file parameters.

QString	errorFile () const
	Returns the file name corresponding to the last error encountered during an export.

ExportResult	exportToImage (const QString &filePath, const QgsLayoutExporter::ImageExportSettings &settings)
	Exports the layout to the filePath, using the specified export settings.

ExportResult	exportToPdf (const QString &filePath, const QgsLayoutExporter::PdfExportSettings &settings)
	Exports the layout as a PDF to the filePath, using the specified export settings.

ExportResult	exportToSvg (const QString &filePath, const QgsLayoutExporter::SvgExportSettings &settings)
	Exports the layout as an SVG to the filePath, using the specified export settings.

bool	georeferenceOutput (const QString &file, QgsLayoutItemMap *referenceMap=nullptr, const QRectF &exportRegion=QRectF(), double dpi=-1) const
	Georeferences a file (image of PDF) exported from the layout.

QMap< QString, QgsLabelingResults * >	labelingResults ()
	Returns the labeling results for all map items included in the export.

QgsLayout *	layout () const
	Returns the layout linked to this exporter.

ExportResult	print (QPrinter &printer, const QgsLayoutExporter::PrintExportSettings &settings)
	Prints the layout to a printer, using the specified export settings.

void	renderPage (QPainter *painter, int page) const
	Renders a full page to a destination painter.

QImage	renderPageToImage (int page, QSize imageSize=QSize(), double dpi=-1) const
	Renders a full page to an image.

void	renderRegion (QPainter *painter, const QRectF &region) const
	Renders a region from the layout to a painter.

QImage	renderRegionToImage (const QRectF &region, QSize imageSize=QSize(), double dpi=-1) const
	Renders a region of the layout to an image.

QMap< QString, QgsLabelingResults * >	takeLabelingResults ()
	Takes the labeling results for all map items included in the export.

Static Public Member Functions
static bool	containsAdvancedEffects (const QgsLayout *layout)
	Returns `true` if the specified layout contains visible items which have settings such as opacity which will prevent these individual items from being exported as vector artwork.

static ExportResult	exportToImage (QgsAbstractLayoutIterator iterator, const QString &baseFilePath, const QString &extension, const QgsLayoutExporter::ImageExportSettings &settings, QString &error, QgsFeedback feedback=nullptr)
	Exports a layout iterator to raster images, with the specified export settings.

static ExportResult	exportToPdf (QgsAbstractLayoutIterator iterator, const QString &fileName, const QgsLayoutExporter::PdfExportSettings &settings, QString &error, QgsFeedback feedback=nullptr)
	Exports a layout iterator to a single PDF file, with the specified export settings.

static ExportResult	exportToPdfs (QgsAbstractLayoutIterator iterator, const QString &baseFilePath, const QgsLayoutExporter::PdfExportSettings &settings, QString &error, QgsFeedback feedback=nullptr)
	Exports a layout iterator to multiple PDF files, with the specified export settings.

static ExportResult	exportToSvg (QgsAbstractLayoutIterator iterator, const QString &baseFilePath, const QgsLayoutExporter::SvgExportSettings &settings, QString &error, QgsFeedback feedback=nullptr)
	Exports a layout iterator to SVG files, with the specified export settings.

static ExportResult	print (QgsAbstractLayoutIterator iterator, QPrinter &printer, const QgsLayoutExporter::PrintExportSettings &settings, QString &error, QgsFeedback feedback=nullptr)
	Exports a layout iterator to a printer, with the specified export settings.

static bool	requiresRasterization (const QgsLayout *layout)
	Returns `true` if the specified layout contains visible items which have settings that require rasterization of the entire export layout in order to reproduce the desired appearance.

Static Public Attributes
static const QgsSettingsEntryBool *	settingOpenAfterExportingImage = new QgsSettingsEntryBool( QStringLiteral( "open-after-exporting-image" ), QgsSettingsTree::sTreeLayout, false, QObject::tr( "Whether to open the exported image file with the default viewer after exporting a print layout" ) )
	Settings entry - Whether to automatically open images after exporting them.

static const QgsSettingsEntryBool *	settingOpenAfterExportingPdf = new QgsSettingsEntryBool( QStringLiteral( "open-after-exporting-pdf" ), QgsSettingsTree::sTreeLayout, false, QObject::tr( "Whether to open the exported PDF file with the default viewer after exporting a print layout" ) )
	Settings entry - Whether to automatically open pdfs after exporting them.

static const QgsSettingsEntryBool *	settingOpenAfterExportingSvg = new QgsSettingsEntryBool( QStringLiteral( "open-after-exporting-svg" ), QgsSettingsTree::sTreeLayout, false, QObject::tr( "Whether to open the exported SVG file with the default viewer after exporting a print layout" ) )
	Settings entry - Whether to automatically open svgs after exporting them.

Protected Member Functions
virtual QString	generateFileName (const PageExportDetails &details) const
	Generates the file name for a page during export.

Friends
class	TestQgsLayout

class	TestQgsLayoutExporter

Detailed Description

Handles rendering and exports of layouts to various formats.

Since: QGIS 3.0

Definition at line 50 of file qgslayoutexporter.h.

Member Enumeration Documentation

◆ ExportResult

enum QgsLayoutExporter::ExportResult

Result codes for exporting layouts.

Enumerator
Success	Export was successful.
Canceled	Export was canceled.
MemoryError	Unable to allocate memory required to export.
FileError	Could not write to destination file, likely due to a lock held by another application.
PrintError	Could not start printing to destination device.
SvgLayerError	Could not create layered SVG file.
IteratorError	Error iterating over layout.

Definition at line 151 of file qgslayoutexporter.h.

Constructor & Destructor Documentation

◆ QgsLayoutExporter()

QgsLayoutExporter::QgsLayoutExporter ( QgsLayout * layout )

Constructor for QgsLayoutExporter, for the specified layout.

Definition at line 153 of file qgslayoutexporter.cpp.

◆ ~QgsLayoutExporter()

QgsLayoutExporter::~QgsLayoutExporter ( )

virtual

Definition at line 159 of file qgslayoutexporter.cpp.

Member Function Documentation

◆ computeWorldFileParameters() [1/2]

void QgsLayoutExporter::computeWorldFileParameters	(	const QRectF &	region,
		double &	a,
		double &	b,
		double &	c,
		double &	d,
		double &	e,
		double &	f,
		double	dpi = `-1`
	)		const

Computes the world file parameters for a specified region of the layout.

The dpi argument can be set to the actual DPI of exported file, or left as -1 to use the layout's default DPI.

Definition at line 1916 of file qgslayoutexporter.cpp.

◆ computeWorldFileParameters() [2/2]

void QgsLayoutExporter::computeWorldFileParameters	(	double &	a,
		double &	b,
		double &	c,
		double &	d,
		double &	e,
		double &	f,
		double	dpi = `-1`
	)		const

Compute world file parameters.

Assumes the whole page containing the reference map item will be exported.

The dpi argument can be set to the actual DPI of exported file, or left as -1 to use the layout's default DPI.

Definition at line 1897 of file qgslayoutexporter.cpp.

◆ containsAdvancedEffects()

bool QgsLayoutExporter::containsAdvancedEffects ( const QgsLayout * layout )

static

Returns true if the specified layout contains visible items which have settings such as opacity which will prevent these individual items from being exported as vector artwork.

See also: requiresRasterization()

Since: QGIS 3.20

Definition at line 2008 of file qgslayoutexporter.cpp.

◆ errorFile()

QString QgsLayoutExporter::errorFile ( ) const

inline

Returns the file name corresponding to the last error encountered during an export.

Definition at line 609 of file qgslayoutexporter.h.

◆ exportToImage() [1/2]

PRIVATE QgsLayoutExporter::ExportResult QgsLayoutExporter::exportToImage	(	const QString &	filePath,
		const QgsLayoutExporter::ImageExportSettings &	settings
	)

Exports the layout to the filePath, using the specified export settings.

If the layout is a multi-page layout, then filenames for each page will automatically be generated by appending "_1", "_2", etc to the image file's base name.

Returns a result code indicating whether the export was successful or an error was encountered. If an error code is returned, errorFile() can be called to determine the filename for the export which encountered the error.

Definition at line 375 of file qgslayoutexporter.cpp.

◆ exportToImage() [2/2]

QgsLayoutExporter::ExportResult QgsLayoutExporter::exportToImage	(	QgsAbstractLayoutIterator *	iterator,
		const QString &	baseFilePath,
		const QString &	extension,
		const QgsLayoutExporter::ImageExportSettings &	settings,
		QString &	error,
		QgsFeedback *	feedback = `nullptr`
	)

static

Exports a layout iterator to raster images, with the specified export settings.

The baseFilePath argument gives a base file path, which is modified by the iterator to obtain file paths for each iterator feature.

Returns a result code indicating whether the export was successful or an error was encountered. If an error was obtained then error will be set to the error description.

Definition at line 485 of file qgslayoutexporter.cpp.

◆ exportToPdf() [1/2]

QgsLayoutExporter::ExportResult QgsLayoutExporter::exportToPdf	(	const QString &	filePath,
		const QgsLayoutExporter::PdfExportSettings &	settings
	)

Exports the layout as a PDF to the filePath, using the specified export settings.

Returns a result code indicating whether the export was successful or an error was encountered.

Definition at line 533 of file qgslayoutexporter.cpp.

◆ exportToPdf() [2/2]

QgsLayoutExporter::ExportResult QgsLayoutExporter::exportToPdf	(	QgsAbstractLayoutIterator *	iterator,
		const QString &	fileName,
		const QgsLayoutExporter::PdfExportSettings &	settings,
		QString &	error,
		QgsFeedback *	feedback = `nullptr`
	)

static

Exports a layout iterator to a single PDF file, with the specified export settings.

The fileName argument gives the destination file name for the output PDF.

Returns a result code indicating whether the export was successful or an error was encountered. If an error was obtained then error will be set to the error description.

See also: exportToPdfs()

Definition at line 728 of file qgslayoutexporter.cpp.

◆ exportToPdfs()

QgsLayoutExporter::ExportResult QgsLayoutExporter::exportToPdfs	(	QgsAbstractLayoutIterator *	iterator,
		const QString &	baseFilePath,
		const QgsLayoutExporter::PdfExportSettings &	settings,
		QString &	error,
		QgsFeedback *	feedback = `nullptr`
	)

static

Exports a layout iterator to multiple PDF files, with the specified export settings.

The baseFilePath argument gives a base file path, which is modified by the iterator to obtain file paths for each iterator feature.

Returns a result code indicating whether the export was successful or an error was encountered. If an error was obtained then error will be set to the error description.

See also: exportToPdf()

Definition at line 822 of file qgslayoutexporter.cpp.

◆ exportToSvg() [1/2]

QgsLayoutExporter::ExportResult QgsLayoutExporter::exportToSvg	(	const QString &	filePath,
		const QgsLayoutExporter::SvgExportSettings &	settings
	)

Exports the layout as an SVG to the filePath, using the specified export settings.

Returns a result code indicating whether the export was successful or an error was encountered.

Definition at line 993 of file qgslayoutexporter.cpp.

◆ exportToSvg() [2/2]

QgsLayoutExporter::ExportResult QgsLayoutExporter::exportToSvg	(	QgsAbstractLayoutIterator *	iterator,
		const QString &	baseFilePath,
		const QgsLayoutExporter::SvgExportSettings &	settings,
		QString &	error,
		QgsFeedback *	feedback = `nullptr`
	)

static

Exports a layout iterator to SVG files, with the specified export settings.

The baseFilePath argument gives a base file path, which is modified by the iterator to obtain file paths for each iterator feature.

Returns a result code indicating whether the export was successful or an error was encountered. If an error was obtained then error will be set to the error description.

Definition at line 1167 of file qgslayoutexporter.cpp.

◆ generateFileName()

QString QgsLayoutExporter::generateFileName ( const PageExportDetails & details ) const

protectedvirtual

Generates the file name for a page during export.

Subclasses can override this method to customize page file naming.

Definition at line 2077 of file qgslayoutexporter.cpp.

◆ georeferenceOutput()

bool QgsLayoutExporter::georeferenceOutput	(	const QString &	file,
		QgsLayoutItemMap *	referenceMap = `nullptr`,
		const QRectF &	exportRegion = `QRectF()`,
		double	dpi = `-1`
	)		const

Georeferences a file (image of PDF) exported from the layout.

The referenceMap argument specifies a map item to use for georeferencing. If left as nullptr, the default layout QgsLayout::referenceMap() will be used.

The exportRegion argument can be set to a valid rectangle to indicate that only part of the layout was exported.

Similarly, the dpi can be set to the actual DPI of exported file, or left as -1 to use the layout's default DPI.

The function will return true if the output was successfully georeferenced.

See also: computeWorldFileParameters()

Definition at line 1628 of file qgslayoutexporter.cpp.

◆ labelingResults()

QMap< QString, QgsLabelingResults * > QgsLayoutExporter::labelingResults ( )

Returns the labeling results for all map items included in the export.

Map keys are the item UUIDs (see QgsLayoutItem::uuid()).

Ownership of the results remains with the layout exporter.

Since: QGIS 3.20

Definition at line 1218 of file qgslayoutexporter.cpp.

◆ layout()

QgsLayout * QgsLayoutExporter::layout ( ) const

Returns the layout linked to this exporter.

Definition at line 164 of file qgslayoutexporter.cpp.

◆ print() [1/2]

QgsLayoutExporter::ExportResult QgsLayoutExporter::print	(	QgsAbstractLayoutIterator *	iterator,
		QPrinter &	printer,
		const QgsLayoutExporter::PrintExportSettings &	settings,
		QString &	error,
		QgsFeedback *	feedback = `nullptr`
	)

static

Exports a layout iterator to a printer, with the specified export settings.

Returns a result code indicating whether the export was successful or an error was encountered. If an error was obtained then error will be set to the error description.

Definition at line 911 of file qgslayoutexporter.cpp.

◆ print() [2/2]

QgsLayoutExporter::ExportResult QgsLayoutExporter::print	(	QPrinter &	printer,
		const QgsLayoutExporter::PrintExportSettings &	settings
	)

Prints the layout to a printer, using the specified export settings.

Returns a result code indicating whether the export was successful or an error was encountered.

Definition at line 872 of file qgslayoutexporter.cpp.

◆ renderPage()

void QgsLayoutExporter::renderPage	(	QPainter *	painter,
		int	page
	)		const

Renders a full page to a destination painter.

The page argument specifies the page number to render. Page numbers are 0 based, such that the first page in a layout is page 0.

See also: renderRegion()

Definition at line 169 of file qgslayoutexporter.cpp.

◆ renderPageToImage()

QImage QgsLayoutExporter::renderPageToImage	(	int	page,
		QSize	imageSize = `QSize()`,
		double	dpi = `-1`
	)		const

Renders a full page to an image.

The page argument specifies the page number to render. Page numbers are 0 based, such that the first page in a layout is page 0.

The optional imageSize parameter can specify the target image size, in pixels. It is the caller's responsibility to ensure that the ratio of the target image size matches the ratio of the corresponding layout page size.

The dpi parameter is an optional dpi override. Set to -1 to use the default layout print resolution. This parameter has no effect if imageSize is specified.

Returns the rendered image, or a null QImage if the image does not fit into available memory.

See also: renderPage(); renderRegionToImage()

Definition at line 192 of file qgslayoutexporter.cpp.

◆ renderRegion()

PRIVATE void QgsLayoutExporter::renderRegion	(	QPainter *	painter,
		const QRectF &	region
	)		const

Renders a region from the layout to a painter.

This method can be used to render sections of pages rather than full pages.

See also: renderPage(); renderRegionToImage()

Definition at line 261 of file qgslayoutexporter.cpp.

◆ renderRegionToImage()

QImage QgsLayoutExporter::renderRegionToImage	(	const QRectF &	region,
		QSize	imageSize = `QSize()`,
		double	dpi = `-1`
	)		const

Renders a region of the layout to an image.

This method can be used to render sections of pages rather than full pages.

The optional imageSize parameter can specify the target image size, in pixels. It is the caller's responsibility to ensure that the ratio of the target image size matches the ratio of the specified region of the layout.

The dpi parameter is an optional dpi override. Set to -1 to use the default layout print resolution. This parameter has no effect if imageSize is specified.

Returns the rendered image, or a null QImage if the image does not fit into available memory.

See also: renderRegion(); renderPageToImage()

Definition at line 281 of file qgslayoutexporter.cpp.

◆ requiresRasterization()

bool QgsLayoutExporter::requiresRasterization ( const QgsLayout * layout )

static

Returns true if the specified layout contains visible items which have settings that require rasterization of the entire export layout in order to reproduce the desired appearance.

See also: containsAdvancedEffects()

Since: QGIS 3.20

Definition at line 1991 of file qgslayoutexporter.cpp.

◆ takeLabelingResults()

QMap< QString, QgsLabelingResults * > QgsLayoutExporter::takeLabelingResults ( )

Takes the labeling results for all map items included in the export.

Map keys are the item UUIDs (see QgsLayoutItem::uuid()).

Ownership of the results is transferred to the caller.

Note: Not available in Python bindings

Since: QGIS 3.20

Definition at line 1223 of file qgslayoutexporter.cpp.

Friends And Related Symbol Documentation

◆ TestQgsLayout

friend class TestQgsLayout

friend

Definition at line 771 of file qgslayoutexporter.h.

◆ TestQgsLayoutExporter

friend class TestQgsLayoutExporter

friend

Definition at line 772 of file qgslayoutexporter.h.

Member Data Documentation

◆ settingOpenAfterExportingImage

PRIVATE const QgsSettingsEntryBool * QgsLayoutExporter::settingOpenAfterExportingImage = new QgsSettingsEntryBool( QStringLiteral( "open-after-exporting-image" ), QgsSettingsTree::sTreeLayout, false, QObject::tr( "Whether to open the exported image file with the default viewer after exporting a print layout" ) )

static

Settings entry - Whether to automatically open images after exporting them.

Since: QGIS 3.34

Definition at line 56 of file qgslayoutexporter.h.

◆ settingOpenAfterExportingPdf

const QgsSettingsEntryBool * QgsLayoutExporter::settingOpenAfterExportingPdf = new QgsSettingsEntryBool( QStringLiteral( "open-after-exporting-pdf" ), QgsSettingsTree::sTreeLayout, false, QObject::tr( "Whether to open the exported PDF file with the default viewer after exporting a print layout" ) )

static

Settings entry - Whether to automatically open pdfs after exporting them.

Since: QGIS 3.34

Definition at line 59 of file qgslayoutexporter.h.

◆ settingOpenAfterExportingSvg

const QgsSettingsEntryBool * QgsLayoutExporter::settingOpenAfterExportingSvg = new QgsSettingsEntryBool( QStringLiteral( "open-after-exporting-svg" ), QgsSettingsTree::sTreeLayout, false, QObject::tr( "Whether to open the exported SVG file with the default viewer after exporting a print layout" ) )

static

Settings entry - Whether to automatically open svgs after exporting them.

Since: QGIS 3.34

Definition at line 62 of file qgslayoutexporter.h.

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

/build/qgis-3.34.0+99sid/src/core/layout/qgslayoutexporter.h
/build/qgis-3.34.0+99sid/src/core/layout/qgslayoutexporter.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ ExportResult

Constructor & Destructor Documentation

◆ QgsLayoutExporter()

◆ ~QgsLayoutExporter()

Member Function Documentation

◆ computeWorldFileParameters() [1/2]

◆ computeWorldFileParameters() [2/2]

◆ containsAdvancedEffects()

◆ errorFile()

◆ exportToImage() [1/2]

◆ exportToImage() [2/2]

◆ exportToPdf() [1/2]

◆ exportToPdf() [2/2]

◆ exportToPdfs()

◆ exportToSvg() [1/2]

◆ exportToSvg() [2/2]

◆ generateFileName()

◆ georeferenceOutput()

◆ labelingResults()

◆ layout()

◆ print() [1/2]

◆ print() [2/2]

◆ renderPage()

◆ renderPageToImage()

◆ renderRegion()

◆ renderRegionToImage()

◆ requiresRasterization()

◆ takeLabelingResults()

Friends And Related Symbol Documentation

◆ TestQgsLayout

◆ TestQgsLayoutExporter

Member Data Documentation

◆ settingOpenAfterExportingImage

◆ settingOpenAfterExportingPdf

◆ settingOpenAfterExportingSvg