QGIS API Documentation  3.9.0-Master (04f0879ed5)
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
QgsLayoutExporter Class Reference

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

Static Public Member Functions

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

Protected Member Functions

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

Friends

class TestQgsLayout
 
class TestQgsLayoutExporter
 

Detailed Description

Handles rendering and exports of layouts to various formats.

Since
QGIS 3.0

Definition at line 44 of file qgslayoutexporter.h.

Member Enumeration Documentation

◆ 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 136 of file qgslayoutexporter.h.

Constructor & Destructor Documentation

◆ QgsLayoutExporter()

PRIVATE QgsLayoutExporter::QgsLayoutExporter ( QgsLayout layout)

Constructor for QgsLayoutExporter, for the specified layout.

Definition at line 143 of file qgslayoutexporter.cpp.

◆ ~QgsLayoutExporter()

virtual QgsLayoutExporter::~QgsLayoutExporter ( )
virtualdefault

Member Function Documentation

◆ computeWorldFileParameters() [1/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 1759 of file qgslayoutexporter.cpp.

◆ computeWorldFileParameters() [2/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 1778 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 551 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 352 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 455 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 503 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 669 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 761 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 926 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 1099 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 1905 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 1490 of file qgslayoutexporter.cpp.

◆ layout()

QgsLayout * QgsLayoutExporter::layout ( ) const

Returns the layout linked to this exporter.

Definition at line 149 of file qgslayoutexporter.cpp.

◆ print() [1/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 810 of file qgslayoutexporter.cpp.

◆ print() [2/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 847 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 154 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 177 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 244 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 264 of file qgslayoutexporter.cpp.

Friends And Related Function Documentation

◆ TestQgsLayout

friend class TestQgsLayout
friend

Definition at line 668 of file qgslayoutexporter.h.

◆ TestQgsLayoutExporter

friend class TestQgsLayoutExporter
friend

Definition at line 669 of file qgslayoutexporter.h.


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