QGIS API Documentation 3.41.0-Master (d5b93354e9c)
|
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 ®ion, 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. | |
QString | errorMessage () const |
Returns a string describing 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. | |
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 ®ion) const |
Renders a region from the layout to a painter. | |
QImage | renderRegionToImage (const QRectF ®ion, 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 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 QgsSettingsEntryInteger * | settingImageQuality = new QgsSettingsEntryInteger( QStringLiteral( "image-quality" ), QgsSettingsTree::sTreeLayout, 90, QObject::tr( "Image quality for lossy formats (e.g. JPEG)" ) ) |
Settings entry - Image quality for lossy formats. | |
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 |
Handles rendering and exports of layouts to various formats.
Definition at line 51 of file qgslayoutexporter.h.
Result codes for exporting layouts.
Definition at line 155 of file qgslayoutexporter.h.
QgsLayoutExporter::QgsLayoutExporter | ( | QgsLayout * | layout | ) |
Constructor for QgsLayoutExporter, for the specified layout.
Definition at line 160 of file qgslayoutexporter.cpp.
|
virtual |
Definition at line 166 of file qgslayoutexporter.cpp.
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 2033 of file qgslayoutexporter.cpp.
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 2014 of file qgslayoutexporter.cpp.
|
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.
Definition at line 2125 of file qgslayoutexporter.cpp.
|
inline |
Returns the file name corresponding to the last error encountered during an export.
Definition at line 620 of file qgslayoutexporter.h.
|
inline |
Returns a string describing the last error encountered during an export.
Definition at line 627 of file qgslayoutexporter.h.
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 385 of file qgslayoutexporter.cpp.
|
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 495 of file qgslayoutexporter.cpp.
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 545 of file qgslayoutexporter.cpp.
|
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.
Definition at line 758 of file qgslayoutexporter.cpp.
|
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.
Definition at line 856 of file qgslayoutexporter.cpp.
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 1030 of file qgslayoutexporter.cpp.
|
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 1209 of file qgslayoutexporter.cpp.
|
protectedvirtual |
Generates the file name for a page during export.
Subclasses can override this method to customize page file naming.
Definition at line 2194 of file qgslayoutexporter.cpp.
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.
Definition at line 1720 of file qgslayoutexporter.cpp.
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.
Definition at line 1262 of file qgslayoutexporter.cpp.
QgsLayout * QgsLayoutExporter::layout | ( | ) | const |
Returns the layout linked to this exporter.
Definition at line 171 of file qgslayoutexporter.cpp.
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.
Definition at line 176 of file qgslayoutexporter.cpp.
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.
Definition at line 199 of file qgslayoutexporter.cpp.
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.
Definition at line 268 of file qgslayoutexporter.cpp.
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.
Definition at line 288 of file qgslayoutexporter.cpp.
|
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.
Definition at line 2108 of file qgslayoutexporter.cpp.
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.
Definition at line 1267 of file qgslayoutexporter.cpp.
|
friend |
Definition at line 800 of file qgslayoutexporter.h.
|
friend |
Definition at line 801 of file qgslayoutexporter.h.
|
static |
Settings entry - Image quality for lossy formats.
Definition at line 66 of file qgslayoutexporter.h.
|
static |
Settings entry - Whether to automatically open images after exporting them.
Definition at line 57 of file qgslayoutexporter.h.
|
static |
Settings entry - Whether to automatically open pdfs after exporting them.
Definition at line 60 of file qgslayoutexporter.h.
|
static |
Settings entry - Whether to automatically open svgs after exporting them.
Definition at line 63 of file qgslayoutexporter.h.