Class: QgsMapRendererJob

class qgis.core.QgsMapRendererJob

Bases: PyQt5.QtCore.QObject

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:

New in version 2.4:

Methods

cancel

Stop the rendering job - does not return until the job has terminated.

cancelWithoutBlocking

Triggers cancellation of the rendering job without blocking.

errors

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

featureFilterProvider

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

isActive

Tell whether the rendering job is currently running in background.

layersRedrawnFromCache

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

mapSettings

Returns map settings with which this job was started.

renderingTime

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

setCache

Assign a cache to be used for reading and storing rendered images of individual layers.

setFeatureFilterProvider

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

start

Start the rendering job and immediately return.

takeLabelingResults

Gets pointer to internal labeling engine (in order to get access to the results).

takeRenderedItemResults

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

usedCachedLabels

Returns True if the render job was able to use a cached labeling solution.

waitForFinished

Block until the job has finished.

Signals

finished

emitted when asynchronous rendering is finished (or canceled).

layerRendered

Emitted when a layer has completed rendering.

layerRenderingStarted

Emitted just before rendering starts for a particular layer.

renderingLayersFinished

Emitted when the layers are rendered.

class Error(lid: str, msg: str)
class Error(QgsMapRendererJob.Error)

Bases: sip.wrapper

layerID
message
cancel(self)

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

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

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

New in version 3.0.

Return type

QgsFeatureFilterProvider

finished

emitted when asynchronous rendering is finished (or canceled). [signal]

isActive(self) bool

Tell whether the rendering job is currently running in background.

Return type

bool

layerRendered

Emitted when a layer has completed rendering.

Note

the QgsMapRendererParallelJob subclass does not emit this signal.

New in version 3.24: [signal]

Parameters

layerId (str) –

layerRenderingStarted

Emitted just before rendering starts for a particular layer.

Note

the QgsMapRendererParallelJob subclass does not emit this signal.

New in version 3.24: [signal]

Parameters

layerId (str) –

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.

New 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

New in version 2.8.

renderingLayersFinished

Emitted when the layers are rendered. Rendering labels is not yet done. If the fully rendered layer including labels is required use finished() instead.

New in version 3.0: [signal]

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)

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

Parameters

cache (QgsMapRendererCache) –

setFeatureFilterProvider(self, f: QgsFeatureFilterProvider)

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.

New in version 3.0.

Parameters

f (QgsFeatureFilterProvider) –

start(self)

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

takeLabelingResults(self) QgsLabelingResults

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().

Return type

QgsLabelingResults

takeRenderedItemResults(self) QgsRenderedItemResults

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

Ownership is transferred to the caller.

New in version 3.22.

Return type

QgsRenderedItemResults

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.

New in version 3.0.

Return type

bool

waitForFinished(self)

Block until the job has finished.