QgsMapRendererTask class

QgsTask task which draws a map to an image file or a painter as a background task.

Reference

This can be used to draw maps without blocking the QGIS interface.

Base classes

class QgsTask: Abstract base class for long running background tasks.

Public types

enum ErrorType { ImageAllocationFail = 1, ImageSaveFail, ImageUnsupportedFormat }: Error type.

Constructors, destructors, conversion operators

QgsMapRendererTask(const QgsMapSettings& ms, const QString& fileName, const QString& fileFormat = QString("PNG"), bool forceRaster = false): Constructor for QgsMapRendererTask to render a map to an image file.
QgsMapRendererTask(const QgsMapSettings& ms, QPainter* p): Constructor for QgsMapRendererTask to render a map to a QPainter object.

Public functions

void addAnnotations(QList<QgsAnnotation*> annotations): Adds annotations to be rendered on the map.
void addDecorations(const QList<QgsMapDecoration*>& decorations): Adds decorations to be rendered on the map.
void cancel() override: Notifies the task that it should terminate.
void setSaveWorldFile(bool save): Sets whether a world file will be created alongside an image file.

Signals

void errorOccurred(int error): Emitted when map rendering failed.
void renderingComplete(): Emitted when the map rendering is successfully completed.

Protected functions

void finished(bool result) override: If the task is managed by a QgsTaskManager, this will be called after the task has finished (whether through successful completion or via early termination).
auto run() -> bool override: Performs the task's operation.

Enum documentation

enum QgsMapRendererTask::ErrorType

Error type.

Enumerators
ImageAllocationFail	Image allocation failure.
ImageSaveFail	Image save failure.
ImageUnsupportedFormat	Format is unsupported on the platform. Since QGIS 3.4

Function documentation

void QgsMapRendererTask::cancel() override

Notifies the task that it should terminate.

Calling this is not guaranteed to immediately end the task, rather it sets the isCanceled() flag which task subclasses can check and terminate their operations at an appropriate time. Any subtasks owned by this task will also be canceled. Derived classes must ensure that the base class implementation is called from any overridden version.

void QgsMapRendererTask::finished(bool result) override protected

If the task is managed by a QgsTaskManager, this will be called after the task has finished (whether through successful completion or via early termination).

The result argument reflects whether the task was successfully completed or not. This method is always called from the main thread, so it is safe to create widgets and perform other operations which require the main thread. However, the GUI will be blocked for the duration of this method so tasks should avoid performing any lengthy operations here.

bool QgsMapRendererTask::run() override protected

Performs the task's operation.

This method will be called when the task commences (ie via calling start() ), and subclasses should implement the operation they wish to perform in the background within this method.

A task must return a boolean value to indicate whether the task was completed successfully or terminated before completion.