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:

Prepare QgsMapSettings with rendering configuration (extent, layer, map size, …)
Create QgsMapRendererJob subclass with QgsMapSettings instance
Connect to job’s finished() signal
Call start(). Map rendering will start in background, the function immediately returns
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.

Abstract Methods

`cancel`	Stop the rendering job - does not return until the job has terminated.
`cancelWithoutBlocking`	Triggers cancellation of the rendering job without blocking.
`isActive`	Tell whether the rendering job is currently running in background.
`takeLabelingResults`	Gets pointer to internal labeling engine (in order to get access to the results).
`usedCachedLabels`	Returns `True` if the render job was able to use a cached labeling solution.
`waitForFinished`	Block until the job has finished.

Methods

`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.
`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.
`takeRenderedItemResults`	Takes the rendered item results from the map render job and returns them.

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 qgis.core.QgsMapRendererJob[source]¶

Bases: QObject

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

class Error(a0: QgsMapRendererJob.Error)

Bases: object

layerID¶

message¶

abstract cancel(self)[source]¶: Stop the rendering job - does not return until the job has terminated. Does nothing if the rendering is not active.

abstract cancelWithoutBlocking(self)[source]¶: 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][source]¶

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[source]¶

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

Return type:: Optional[QgsFeatureFilterProvider]

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

abstract isActive(self) → bool[source]¶

Tell whether the rendering job is currently running in background.

Return type:: bool

signal layerRendered(layerId: str)[source]¶

Emitted when a layer has completed rendering.

Note

the QgsMapRendererParallelJob subclass does not emit this signal.

Added in version 3.24.

Parameters:: layerId (str)

signal layerRenderingStarted(layerId: str)[source]¶

Emitted just before rendering starts for a particular layer.

Note

the QgsMapRendererParallelJob subclass does not emit this signal.

Added in version 3.24.

Parameters:: layerId (str)

layersRedrawnFromCache(self) → List[str][source]¶

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[source]¶: Emitted when the layers are rendered. Rendering labels is not yet done. If the fully rendered layer including labels is required use finished() instead.

renderingTime(self) → int[source]¶

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