Class: QgsMapRendererJob

Abstract base class for map rendering implementations.

The API is designed in a way that rendering is done asynchronously, therefore the caller is not blocked while the rendering is in progress. Non-blocking operation is quite important because the rendering can take considerable amount of time.

Common use case:

1. Prepare QgsMapSettings with rendering configuration (extent, layer, map size, …)

2. Create QgsMapRendererJob subclass with QgsMapSettings instance

3. Connect to job’s finished() signal

4. Call start(). Map rendering will start in background, the function immediately returns

5. At some point, slot connected to finished() signal is called, map rendering is done

It is possible to cancel the rendering job while it is active by calling cancel() function.

The following subclasses are available:

• QgsMapRendererSequentialJob - renders map in one background thread to an image

• QgsMapRendererParallelJob - renders map in multiple background threads to an image

• QgsMapRendererCustomPainterJob - renders map with given QPainter in one background thread

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: cancel(), cancelWithoutBlocking(), isActive(), takeLabelingResults(), usedCachedLabels(), waitForFinished()

Class Hierarchy

Base classes

QObject

Subclasses

QgsMapRendererAbstractCustomPainterJob	Abstract base class for map renderer jobs which use custom painters.
QgsMapRendererQImageJob	Intermediate base class adding functionality that allows a client to query the rendered image.

class qgis.core.QgsMapRendererJob

Bases: QObject

class Error(lid: str | None, msg: str | None)

class Error(a0: QgsMapRendererJob.Error)

Bases: object

layerID

message

abstract cancel(self)

Stop the rendering job - does not return until the job has terminated. Does nothing if the rendering is not active.

abstract cancelWithoutBlocking(self)

Triggers cancellation of the rendering job without blocking. The render job will continue to operate until it is able to cancel, at which stage the finished() signal will be emitted. Does nothing if the rendering is not active.

errors(self) → List[QgsMapRendererJob.Error]

List of errors that happened during the rendering job - available when the rendering has been finished

Return type:

List[QgsMapRendererJob.Error]

featureFilterProvider(self) → QgsFeatureFilterProvider | None

Returns the feature filter provider used by the QgsRenderContext of each LayerRenderJob.

Return type:

Optional[QgsFeatureFilterProvider]

signal finished

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

abstract isActive(self) → bool

Tell whether the rendering job is currently running in background.

Return type:

bool

signal layerRendered

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

signal layerRenderingStarted

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

layersRedrawnFromCache(self) → List[str]

Returns a list of the layer IDs for all layers which were redrawn from cached images.

This method should only be called after the render job is completed.

Added in version 3.22.

Return type:

List[str]

mapSettings(self) → QgsMapSettings

Returns map settings with which this job was started.

Return type:

QgsMapSettings

Returns:

A QgsMapSettings instance with render settings

signal renderingLayersFinished

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

renderingTime(self) → int

Returns the total time it took to finish the job (in milliseconds).

See also

perLayerRenderingTime()

Return type:

int

setCache(self, cache: QgsMapRendererCache | None)

Assign a cache to be used for reading and storing rendered images of individual layers. Does not take ownership of the object.

Parameters:

cache (Optional[QgsMapRendererCache])

setFeatureFilterProvider(self, f: QgsFeatureFilterProvider | None)

Set the feature filter provider used by the QgsRenderContext of each LayerRenderJob. Ownership is not transferred and the provider must not be deleted before the render job.

Parameters:

f (Optional[QgsFeatureFilterProvider])

start(self)

Start the rendering job and immediately return. Does nothing if the rendering is already in progress.

abstract takeLabelingResults(self) → QgsLabelingResults | None

Gets pointer to internal labeling engine (in order to get access to the results). This should not be used if cached labeling was redrawn - see usedCachedLabels().

See also

usedCachedLabels()

Return type:

Optional[QgsLabelingResults]

takeRenderedItemResults(self) → QgsRenderedItemResults | None

Takes the rendered item results from the map render job and returns them.

Ownership is transferred to the caller.

Added in version 3.22.

Return type:

Optional[QgsRenderedItemResults]

abstract usedCachedLabels(self) → bool

Returns True if the render job was able to use a cached labeling solution. If so, any previously stored labeling results (see takeLabelingResults()) should be retained.

See also

takeLabelingResults()

Return type:

bool

abstract waitForFinished(self)

Block until the job has finished.