QgsLayoutExporter class

Handles rendering and exports of layouts to various formats.

Contents

Public types

struct ImageExportSettings
Contains settings relating to exporting layouts to raster images.
struct PageExportDetails
Contains details of a page being exported by the class.
struct PdfExportSettings
Contains settings relating to exporting layouts to PDF.
struct PrintExportSettings
Contains settings relating to printing layouts.
struct SvgExportSettings
Contains settings relating to exporting layouts to SVG.
enum ExportResult { Success, Canceled, MemoryError, FileError, PrintError, SvgLayerError, IteratorError }
Result codes for exporting layouts.

Public static functions

static auto exportToImage(QgsAbstractLayoutIterator* iterator, const QString& baseFilePath, const QString& extension, const QgsLayoutExporter::ImageExportSettings& settings, QString& error, QgsFeedback* feedback = nullptr) -> ExportResult
Exports a layout iterator to raster images, with the specified export settings.
static auto exportToPdf(QgsAbstractLayoutIterator* iterator, const QString& fileName, const QgsLayoutExporter::PdfExportSettings& settings, QString& error, QgsFeedback* feedback = nullptr) -> ExportResult
Exports a layout iterator to a single PDF file, with the specified export settings.
static auto exportToPdfs(QgsAbstractLayoutIterator* iterator, const QString& baseFilePath, const QgsLayoutExporter::PdfExportSettings& settings, QString& error, QgsFeedback* feedback = nullptr) -> ExportResult
Exports a layout iterator to multiple PDF files, with the specified export settings.
static auto exportToSvg(QgsAbstractLayoutIterator* iterator, const QString& baseFilePath, const QgsLayoutExporter::SvgExportSettings& settings, QString& error, QgsFeedback* feedback = nullptr) -> ExportResult
Exports a layout iterator to SVG files, with the specified export settings.
static auto print(QgsAbstractLayoutIterator* iterator, QPrinter& printer, const QgsLayoutExporter::PrintExportSettings& settings, QString& error, QgsFeedback* feedback = nullptr) -> ExportResult
Exports a layout iterator to a printer, with the specified export settings.

Constructors, destructors, conversion operators

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

Public functions

void computeWorldFileParameters(double& a, double& b, double& c, double& d, double& e, double& f, double dpi = -1) const
Compute world file parameters.
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.
auto errorFile() const -> QString
Returns the file name corresponding to the last error encountered during an export.
auto exportToImage(const QString& filePath, const QgsLayoutExporter::ImageExportSettings& settings) -> ExportResult
Exports the layout to the filePath, using the specified export settings.
auto exportToPdf(const QString& filePath, const QgsLayoutExporter::PdfExportSettings& settings) -> ExportResult
Exports the layout as a PDF to the filePath, using the specified export settings.
auto exportToSvg(const QString& filePath, const QgsLayoutExporter::SvgExportSettings& settings) -> ExportResult
Exports the layout as an SVG to the filePath, using the specified export settings.
auto georeferenceOutput(const QString& file, QgsLayoutItemMap* referenceMap = nullptr, const QRectF& exportRegion = QRectF(), double dpi = -1) const -> bool
Georeferences a file (image of PDF) exported from the layout.
auto layout() const -> QgsLayout*
Returns the layout linked to this exporter.
auto print(QPrinter& printer, const QgsLayoutExporter::PrintExportSettings& settings) -> ExportResult
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.
auto renderPageToImage(int page, QSize imageSize = QSize(), double dpi = -1) const -> QImage
Renders a full page to an image.
void renderRegion(QPainter* painter, const QRectF& region) const
Renders a region from the layout to a painter.
auto renderRegionToImage(const QRectF& region, QSize imageSize = QSize(), double dpi = -1) const -> QImage
Renders a region of the layout to an image.

Protected functions

auto generateFileName(const PageExportDetails& details) const -> QString virtual
Generates the file name for a page during export.

Enum documentation

enum QgsLayoutExporter::ExportResult

Result codes for exporting layouts.

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

Function documentation

static ExportResult QgsLayoutExporter::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.

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.

static ExportResult QgsLayoutExporter::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.

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.

static ExportResult QgsLayoutExporter::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.

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.

static ExportResult QgsLayoutExporter::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.

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.

static ExportResult QgsLayoutExporter::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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Generates the file name for a page during export.

Subclasses can override this method to customize page file naming.