Class: QgsMapCanvas

Map canvas is a class for displaying all GIS data types on a canvas.

Class Hierarchy

Base classes

QGraphicsView
QAbstractScrollArea
QFrame
QWidget
QObject
QPaintDevice
QgsExpressionContextGenerator	Abstract interface for generating an expression context.

Subclasses

QgsCoordinateBoundsPreviewMapWidget

A widget for showing the bounds of a rectangular region on an interactive map.

class qgis.gui.QgsMapCanvas

Bases: QGraphicsView, QgsExpressionContextGenerator

__init__(parent: QWidget | None = None)

Constructor

Parameters:

parent (Optional[QWidget] = None)

addOverlayWidget(self, widget: QWidget | None, edge: Qt.Edge)

Adds an overlay widget to the layout, which will be bound to the specified edge.

The widget will always float above the map canvas.

Note

Widgets on the left and right edges will always be positioned first, with top and bottom edge widgets expanding to take the remaining horizontal space.

Added in version 3.38.

Parameters:

• widget (Optional[QWidget])

• edge (Qt.Edge)

allowInteraction(self, interaction: QgsMapCanvasInteractionBlocker.Interaction) → bool

Returns True if the specified interaction is currently permitted on the canvas.

Added in version 3.14.

Parameters:

interaction (QgsMapCanvasInteractionBlocker.Interaction)

Return type:

bool

annotationItems(self) → List[QgsMapCanvasAnnotationItem]

Returns a list of all annotation items in the canvas.

Return type:

List[QgsMapCanvasAnnotationItem]

annotationsVisible(self) → bool

Returns True if annotations are visible within the map canvas.

See also

setAnnotationsVisible()

Return type:

bool

antiAliasingEnabled(self) → bool

True if antialiasing is enabled

Return type:

bool

cache(self) → QgsMapRendererCache | None

Returns the map renderer cache, if caching is enabled.

See also

isCachingEnabled()

See also

setCachingEnabled()

Added in version 3.32.

Return type:

Optional[QgsMapRendererCache]

canvasColor(self) → QColor

Read property of QColor bgColor.

Return type:

QColor

signal canvasColorChanged

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.

center(self) → QgsPointXY

Gets map center, in geographical coordinates

Return type:

QgsPointXY

clearCache(self)

Make sure to remove any rendered images from cache (does nothing if cache is not enabled)

clearExtentHistory(self)

Clears the list of extents and sets current extent as first item

signal contextMenuAboutToShow

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.

currentLayer(self) → QgsMapLayer | None

returns current layer (set by legend widget)

Return type:

Optional[QgsMapLayer]

signal currentLayerChanged

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.

defaultExpressionContextScope(self) → QgsExpressionContextScope | None

Creates a new scope which contains default variables and functions relating to the map canvas.

See also

expressionContextScope()

See also

setExpressionContextScope()

Added in version 3.4.

Return type:

Optional[QgsExpressionContextScope]

signal destinationCrsChanged

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.

emitExtentsChanged(self)

Emits the extentsChanged signal when appropriate.

Added in version 3.30.

enableAntiAliasing(self, flag: bool)

used to determine if anti-aliasing is enabled or not

Parameters:

flag (bool)

enableMapTileRendering(self, flag: bool)

sets map tile rendering flag

Parameters:

flag (bool)

expressionContextScope(self) → QgsExpressionContextScope

Returns a reference to the expression context scope for the map canvas. This scope is injected into the expression context used for rendering the map, and can be used to apply specific variable overrides for expression evaluation for the map canvas render.

See also

setExpressionContextScope()

See also

defaultExpressionContextScope()

Return type:

QgsExpressionContextScope

extent(self) → QgsRectangle

Returns the current zoom extent of the map canvas

Return type:

QgsRectangle

signal extentsChanged

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.

flags(self) → Qgis.MapCanvasFlags

Returns flags which control how the map canvas behaves.

See also

setFlags()

Added in version 3.40.

Return type:

Qgis.MapCanvasFlags

flashFeatureIds(self, layer: QgsVectorLayer | None, ids: Any, startColor: QColor | Qt.GlobalColor = QColor(255, 0, 0, 255), endColor: QColor | Qt.GlobalColor = QColor(255, 0, 0, 0), flashes: int = 3, duration: int = 500)

Causes a set of features with matching ids from a vector layer to flash within the canvas.

The startColor and endColor can be specified, along with the number of flashes and duration of each flash (in milliseconds).

Note

If the features or geometries are already available, flashGeometries() is much more efficient.

See also

flashGeometries()

Parameters:

• layer (Optional[QgsVectorLayer])

• ids (Any)

• startColor (Union[QColor, Qt.GlobalColor] = QColor(255, 0, 0, 255))

• endColor (Union[QColor, Qt.GlobalColor] = QColor(255, 0, 0, 0))

• flashes (int = 3)

• duration (int = 500)

flashGeometries(self, geometries: Iterable[QgsGeometry], crs: QgsCoordinateReferenceSystem = QgsCoordinateReferenceSystem(), startColor: QColor | Qt.GlobalColor = QColor(255, 0, 0, 255), endColor: QColor | Qt.GlobalColor = QColor(255, 0, 0, 0), flashes: int = 3, duration: int = 500)

Causes a set of geometries to flash within the canvas.

If crs is a valid coordinate reference system, the geometries will be automatically transformed from this CRS to the canvas CRS.

The startColor and endColor can be specified, along with the number of flashes and duration of each flash (in milliseconds).

See also

flashFeatureIds()

Parameters:

• geometries (Iterable[QgsGeometry])

• crs (QgsCoordinateReferenceSystem = QgsCoordinateReferenceSystem())

• startColor (Union[QColor, Qt.GlobalColor] = QColor(255, 0, 0, 255))

• endColor (Union[QColor, Qt.GlobalColor] = QColor(255, 0, 0, 0))

• flashes (int = 3)

• duration (int = 500)

freeze(self, frozen: bool = True)

Freezes/thaws the map canvas. This is used to prevent the canvas from responding to events while layers are being added/removed etc.

Parameters:

frozen (bool = True) – Boolean specifying if the canvas should be frozen (True) or thawed (False). Default is True.

See also

isFrozen()

See also

setRenderFlag()

Note

freeze() should be used to programmatically halt map updates, while setRenderFlag() should only be used when users disable rendering via GUI.

fullExtent(self) → QgsRectangle

Returns the combined extent for all layers on the map canvas.

This method returns the combined extent for all layers which are currently visible in the map canvas. The returned extent will be in the same CRS as the map canvas.

See also

projectExtent()

Return type:

QgsRectangle

getCoordinateTransform(self) → QgsMapToPixel | None

Gets the current coordinate transform

Return type:

Optional[QgsMapToPixel]

installInteractionBlocker(self, blocker: QgsMapCanvasInteractionBlocker | None)

Installs an interaction blocker onto the canvas, which may prevent certain map canvas interactions from occurring.

The caller retains ownership of blocker, and must correctly call removeInteractionBlocker() before deleting the object.

See also

allowInteraction()

See also

removeInteractionBlocker()

Added in version 3.14.

Parameters:

blocker (Optional[QgsMapCanvasInteractionBlocker])

isCachingEnabled(self) → bool

Check whether images of rendered layers are curerently being cached

See also

setCachingEnabled()

See also

cache()

Return type:

bool

isDrawing(self) → bool

Find out whether rendering is in progress

Return type:

bool

isFrozen(self) → bool

Returns True if canvas is frozen.

See also

freeze()

See also

renderFlag()

Note

isFrozen() should be used to determine whether map updates have been halted programmatically, while renderFlag() should be used to determine whether a user has disabled rendering via GUI.

Return type:

bool

isParallelRenderingEnabled(self) → bool

Check whether the layers are rendered in parallel or sequentially

Return type:

bool

signal keyPressed

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 keyReleased

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.

labelingEngineSettings(self) → QgsLabelingEngineSettings

Returns global labeling engine settings from the internal map settings

Return type:

QgsLabelingEngineSettings

labelingResults(self, allowOutdatedResults: bool = True) → QgsLabelingResults | None

Gets access to the labeling results (may be None).

Since QGIS 3.20, if the allowOutdatedResults flag is False then outdated labeling results (e.g. as a result of an ongoing canvas render) will not be returned, and instead None will be returned.

Parameters:

allowOutdatedResults (bool = True)

Return type:

Optional[QgsLabelingResults]

layer(self, index: int) → QgsMapLayer | None

Returns the map layer at position index in the layer stack

layer(self, id: Optional[str]) -> Optional[QgsMapLayer] Returns the map layer with the matching ID, or None if no layers could be found.

This method searches both layers associated with the map canvas (see layers()) and layers from the QgsProject associated with the canvas (which is current the QgsProject.instance()). It can be used to resolve layer IDs to layers which may be visible in the canvas, but not associated with a QgsProject.

Added in version 3.22.

Parameters:

index (int)

Return type:

Optional[QgsMapLayer]

layerCount(self) → int

Returns number of layers on the map.

Return type:

int

layerStateChange(self)

This slot is connected to the visibility change of one or more layers

layerStyleOverrides(self) → Dict[str, str]

Returns the stored overrides of styles for layers.

See also

setLayerStyleOverrides()

Return type:

Dict[str, str]

signal layerStyleOverridesChanged

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.

layers(self, expandGroupLayers: bool = False) → List[QgsMapLayer]

Returns the list of layers shown within the map canvas.

Since QGIS 3.24, if the expandGroupLayers option is True then group layers will be converted to all their child layers.

See also

setLayers()

Parameters:

expandGroupLayers (bool = False)

Return type:

List[QgsMapLayer]

signal layersChanged

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 magnificationChanged

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.

magnificationFactor(self) → float

Returns the magnification factor

Return type:

float

signal mapCanvasRefreshed

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 mapRefreshCanceled

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.

mapSettings(self) → QgsMapSettings

Gets access to properties used for map rendering

Return type:

QgsMapSettings

mapTool(self) → QgsMapTool | None

Returns the currently active tool

Return type:

Optional[QgsMapTool]

signal mapToolSet

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.

mapUnits(self) → Qgis.DistanceUnit

Convenience function for returning the current canvas map units. The map units are dictated by the canvas’ destinationCrs() map units.

Return type:

Qgis.DistanceUnit

mapUnitsPerPixel(self) → float

Returns the mapUnitsPerPixel (map units per pixel) for the canvas

Return type:

float

mapUpdateInterval(self) → int

Find out how often map preview should be updated while it is being rendered (in milliseconds)

Return type:

int

signal messageEmitted

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.

mouseLastXY(self) → QPoint

returns last position of mouse cursor

Return type:

QPoint

moveCanvasContents(self, reset: bool = False)

called when panning is in action, reset indicates end of panning

Parameters:

reset (bool = False)

panAction(self, event: QMouseEvent | None)

Called when mouse is moving and pan is activated

Parameters:

event (Optional[QMouseEvent])

panActionEnd(self, releasePoint: QPoint)

Ends pan action and redraws the canvas.

Parameters:

releasePoint (QPoint)

signal panDistanceBearingChanged

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.

panToFeatureIds(self, layer: QgsVectorLayer | None, ids: Any, alwaysRecenter: bool = True)

Centers canvas extent to feature ids

Parameters:

• layer (Optional[QgsVectorLayer]) – the vector layer

• ids (Any) – the feature ids

• alwaysRecenter (bool = True) – if False, the canvas is recentered only if the bounding box is not contained within the current extent

panToSelected(self, layer: QgsMapLayer | None = None)

Pan to the selected features of current ayer keeping same extent.

panToSelected(self, layers: Iterable[QgsMapLayer]) Pan to the combined extent of the selected features of all provided (vector) layers.

Parameters:

layers – A list of layers

Added in version 3.18.

Parameters:

layer (Optional[QgsMapLayer] = None)

previewJobsEnabled(self) → bool

Returns True if canvas map preview jobs (low priority render jobs which render portions of the view just outside of the canvas extent, to allow preview of these out-of-canvas areas when panning or zooming out the map) are enabled for the canvas.

See also

setPreviewJobsEnabled()

Return type:

bool

previewMode(self) → QgsPreviewEffect.PreviewMode

Returns the current preview mode for the map canvas. This setting only has an effect if previewModeEnabled is True.

Return type:

QgsPreviewEffect.PreviewMode

Returns:

preview mode for map canvas

See also

setPreviewMode()

See also

previewModeEnabled()

previewModeEnabled(self) → bool

Returns whether a preview mode is enabled for the map canvas

Return type:

bool

Returns:

True if a preview mode is currently enabled

See also

setPreviewModeEnabled()

See also

previewMode()

project(self) → QgsProject | None

Returns the project linked to this canvas. The returned value may be None.

Added in version 3.14.

Return type:

Optional[QgsProject]

projectExtent(self) → QgsRectangle

Returns the associated project’s full extent, in the canvas’ CRS.

This method returns the full extent for the project associated with this canvas. Unlike fullExtent(), this method does NOT consider which layers are actually visible in the map canvas.

See also

fullExtent()

Added in version 3.20.

Return type:

QgsRectangle

readProject(self, a0: QDomDocument)

called to read map canvas settings from project

Parameters:

a0 (QDomDocument)

redrawAllLayers(self)

Clears all cached images and redraws all layers.

Note

Unlike refreshAllLayers(), this does NOT reload layers themselves, and accordingly is more “lightweight”. Use this method when only an update of the layer’s renderers is required.

Added in version 3.10.

refresh(self)

Repaints the canvas map

refreshAllLayers(self)

Reload all layers (including refreshing layer properties from their data sources), clears the cache and refreshes the canvas.

Note

Consider using the less expensive redrawAllLayers() method if a layer reload from the data provider is not required.

removeInteractionBlocker(self, blocker: QgsMapCanvasInteractionBlocker | None)

Removes an interaction blocker from the canvas.

See also

allowInteraction()

See also

installInteractionBlocker()

Added in version 3.14.

Parameters:

blocker (Optional[QgsMapCanvasInteractionBlocker])

signal renderComplete

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 renderErrorOccurred

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.

renderFlag(self) → bool

Returns True if canvas render is disabled as a result of user disabling renders via the GUI.

See also

setRenderFlag()

See also

isFrozen()

Note

isFrozen() should be used to determine whether map updates have been halted programmatically, while renderFlag() should be used to determine whether a user has disabled rendering via GUI.

Return type:

bool

signal renderStarting

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.

renderedItemResults(self, allowOutdatedResults: bool = True) → QgsRenderedItemResults | None

Gets access to the rendered item results (may be None), which includes the results of rendering annotation items in the canvas map.

If the allowOutdatedResults flag is False then outdated rendered item results (e.g. as a result of an ongoing canvas render) will not be returned, and instead None will be returned.

Added in version 3.22.

Parameters:

allowOutdatedResults (bool = True)

Return type:

Optional[QgsRenderedItemResults]

rotation(self) → float

Gets the current map canvas rotation in clockwise degrees

Return type:

float

signal rotationChanged

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.

saveAsImage(self, fileName: str | None, QPixmap: QPixmap | None = None, a2: str | None = '')

Save the contents of the map canvas to disk as an image

Parameters:

• fileName (Optional[str])

• QPixmap (Optional[QPixmap] = None)

• a2 (Optional[str] = '')

scale(self) → float

Returns the last reported scale of the canvas. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.

Return type:

float

signal scaleChanged

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 scaleLockChanged

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.

scaleLocked(self) → bool

Returns whether the scale is locked, so zooming can be performed using magnication.

See also

setScaleLocked()

Return type:

bool

signal selectionChanged

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.

selectionChangedSlot(self)

Receives signal about selection change, and pass it on with layer info

selectionColor(self) → QColor

Returns color for selected features

Return type:

QColor

setAnnotationsVisible(self, visible: bool)

Sets whether annotations are visible in the canvas.

See also

annotationsVisible()

Parameters:

visible (bool)

setCachingEnabled(self, enabled: bool)

Set whether to cache images of rendered layers

See also

isCachingEnabled()

See also

cache()

Parameters:

enabled (bool)

setCanvasColor(self, _newVal: QColor | Qt.GlobalColor)

Write property of QColor bgColor.

Parameters:

_newVal (Union[QColor, Qt.GlobalColor])

setCenter(self, center: QgsPointXY)

Set the center of the map canvas, in geographical coordinates

Parameters:

center (QgsPointXY)

setCurrentLayer(self, layer: QgsMapLayer | None)

Parameters:

layer (Optional[QgsMapLayer])

setDestinationCrs(self, crs: QgsCoordinateReferenceSystem)

Sets destination coordinate reference system

Parameters:

crs (QgsCoordinateReferenceSystem)

setExpressionContextScope(self, scope: QgsExpressionContextScope)

Sets an expression context scope for the map canvas. This scope is injected into the expression context used for rendering the map, and can be used to apply specific variable overrides for expression evaluation for the map canvas render. This method will overwrite the existing expression context scope for the canvas.

Parameters:

scope (QgsExpressionContextScope) – new expression context scope

See also

expressionContextScope()

See also

defaultExpressionContextScope()

setExtent(self, r: QgsRectangle, magnified: bool = False)

Sets the extent of the map canvas to the specified rectangle.

The magnified argument dictates whether existing canvas constraints such as a scale lock should be respected or not during the operation. If magnified is True then an existing scale lock constraint will be applied. This means that the final visible canvas extent may not match the specified extent.

If magnified is False then scale lock settings will be ignored, and the specified rectangle will ALWAYS be visible in the canvas.

Parameters:

• r (QgsRectangle)

• magnified (bool = False)

setFlags(self, flags: Qgis.MapCanvasFlags | Qgis.MapCanvasFlag)

Sets flags which control how the map canvas behaves.

See also

flags()

Added in version 3.40.

Parameters:

flags (Union[Qgis.MapCanvasFlags, Qgis.MapCanvasFlag])

setLabelingEngineSettings(self, settings: QgsLabelingEngineSettings)

Sets global labeling engine settings in the internal map settings

Parameters:

settings (QgsLabelingEngineSettings)

setLayerStyleOverrides(self, overrides: Dict[str | None, str | None])

Sets the stored overrides of styles for rendering layers.

If the map canvas has been associated with a map theme via a call to setTheme(), then any calls to setLayerStyleOverrides() are ignored. It is necessary to first clear the theme association by calling setTheme() with an empty string before setLayerStyleOverrides() calls can be made.

See also

layerStyleOverrides()

Parameters:

overrides (Dict[Optional[str], Optional[str]])

setLayers(self, layers: Iterable[QgsMapLayer])

Sets the list of layers that should be shown in the canvas.

If the map canvas has been associated with a map theme via a call to setTheme(), then any calls to setLayers() are ignored. It is necessary to first clear the theme association by calling setTheme() with an empty string before setLayers() calls can be made.

See also

layers()

Parameters:

layers (Iterable[QgsMapLayer])

setMagnificationFactor(self, factor: float, center: QgsPointXY | None = None)

Sets the factor of magnification to apply to the map canvas. Indeed, we increase/decrease the DPI of the map settings according to this factor in order to render marker point, labels, … bigger.

Parameters:

• factor (float) – The factor of magnification

• center (Optional[QgsPointXY] = None) – Optional point to re-center the map

setMapController(self, controller: QgsAbstract2DMapController | None)

Sets the input controller device to use for controlling the canvas.

Ownership of controller is transferred to the canvas.

Added in version 3.34.

Parameters:

controller (Optional[QgsAbstract2DMapController])

setMapSettingsFlags(self, flags: Qgis.MapSettingsFlags | Qgis.MapSettingsFlag)

Resets the flags for the canvas’ map settings.

Parameters:

flags (Union[Qgis.MapSettingsFlags, Qgis.MapSettingsFlag])

setMapTool(self, mapTool: QgsMapTool | None, clean: bool = False)

Sets the map tool currently being used on the canvas

Parameters:

• mapTool (Optional[QgsMapTool])

• clean (bool = False)

setMapUpdateInterval(self, timeMilliseconds: int)

Set how often map preview should be updated while it is being rendered (in milliseconds)

Parameters:

timeMilliseconds (int)

setParallelRenderingEnabled(self, enabled: bool)

Set whether the layers are rendered in parallel or sequentially

Parameters:

enabled (bool)

setPreviewJobsEnabled(self, enabled: bool)

Sets whether canvas map preview jobs (low priority render jobs which render portions of the view just outside of the canvas extent, to allow preview of these out-of-canvas areas when panning or zooming out the map) are enabled for the canvas.

See also

previewJobsEnabled()

Parameters:

enabled (bool)

setPreviewMode(self, mode: QgsPreviewEffect.PreviewMode)

Sets a preview mode for the map canvas. This setting only has an effect if previewModeEnabled is True.

Parameters:

mode (QgsPreviewEffect.PreviewMode) – preview mode for the canvas

See also

previewMode()

See also

setPreviewModeEnabled()

See also

previewModeEnabled()

setPreviewModeEnabled(self, previewEnabled: bool)

Enables a preview mode for the map canvas

Parameters:

previewEnabled (bool) – set to True to enable a preview mode

See also

setPreviewMode()

setProject(self, project: QgsProject | None)

Sets the project linked to this canvas.

Added in version 3.14.

Parameters:

project (Optional[QgsProject])

setReferencedExtent(self, extent: QgsReferencedRectangle) → bool

Sets the canvas to the specified extent.

Return type:

bool

Returns:

True if the zoom was successful.

Raises:

QgsCsException – if a transformation error occurred.

Added in version 3.10.

Parameters:

extent (QgsReferencedRectangle)

setRenderFlag(self, flag: bool)

Sets whether a user has disabled canvas renders via the GUI.

Parameters:

flag (bool) – set to False to indicate that user has disabled renders

See also

renderFlag()

See also

freeze()

Note

freeze() should be used to programmatically halt map updates, while setRenderFlag() should only be used when users disable rendering via GUI.

setRotation(self, degrees: float)

Set the rotation of the map canvas in clockwise degrees

Parameters:

degrees (float)

setScaleLocked(self, isLocked: bool)

Lock the scale, so zooming can be performed using magnication

See also

scaleLocked()

Parameters:

isLocked (bool)

setSegmentationTolerance(self, tolerance: float)

Sets the segmentation tolerance applied when rendering curved geometries

Parameters:

tolerance (float) – the segmentation tolerance

setSegmentationToleranceType(self, type: QgsAbstractGeometry.SegmentationToleranceType)

Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)

Parameters:

type (QgsAbstractGeometry.SegmentationToleranceType) – the segmentation tolerance typename

setSelectionColor(self, color: QColor | Qt.GlobalColor)

Set color of selected vector features

Parameters:

color (Union[QColor, Qt.GlobalColor])

setSnappingUtils(self, utils: QgsSnappingUtils | None)

Assign an instance of snapping utils to the map canvas. The instance is not owned by the canvas, so it is possible to use one instance in multiple canvases.

For main canvas in QGIS, do not associate a different instance from the existing one (it is updated from the project’s snapping configuration).

Parameters:

utils (Optional[QgsSnappingUtils])

setTemporalController(self, controller: QgsTemporalController | None)

Sets the temporal controller for this canvas.

The controller will be used to update the canvas’ temporal range.

Added in version 3.14.

Parameters:

controller (Optional[QgsTemporalController])

setTemporalRange(self, range: QgsDateTimeRange)

Set datetime range for the map canvas.

The temporalRangeChanged() signal will be emitted if the temporal range has been changed.

Note

Calling setTemporalRange() does not automatically trigger a map refresh.

See also

temporalRange()

Added in version 3.14.

Parameters:

range (QgsDateTimeRange)

setTheme(self, theme: str | None)

Sets a map theme to show in the canvas. The theme name must match a theme present in the associated project’s QgsMapThemeCollection.

When the canvas is associated to a map theme, it will automatically follow the layer selection and layer styles from that theme. Calls to setLayers() or setLayerStyleOverrides() will have no effect, and canvases associated with a QgsLayerTreeMapCanvasBridge will no longer synchronize their state with the layer tree. In these cases it is necessary to call setTheme() with an empty string to clear the theme association and allow map updates with setLayers(), setLayerStyleOverrides(), or via QgsLayerTreeMapCanvasBridge.

If an empty string is passed then the current theme association will be cleared.

To set a theme and simultaneously update the layer tree, use QgsMapThemeCollection.applyTheme().

See also

theme()

Parameters:

theme (Optional[str])

setWheelFactor(self, factor: float)

Sets wheel zoom factor (should be greater than 1)

Parameters:

factor (float)

setZRange(self, range: QgsDoubleRange)

Sets the range of z-values which will be visible in the map.

See also

zRange()

See also

zRangeChanged()

Added in version 3.18.

Parameters:

range (QgsDoubleRange)

setZoomResolutions(self, resolutions: Iterable[float])

Set a list of resolutions (map units per pixel) to which to “snap to” when zooming the map

Parameters:

resolutions (Iterable[float]) – A list of resolutions

Added in version 3.12.

snappingUtils(self) → QgsSnappingUtils | None

Returns snapping utility class that is associated with map canvas. If no snapping utils instance has been associated previously, an internal will be created for convenience (so map tools do not need to test for existence of the instance).

Main canvas in QGIS returns an instance which is always up-to-date with the project’s snapping configuration.

Return type:

Optional[QgsSnappingUtils]

stopRendering(self)

stop rendering (if there is any right now)

signal tapAndHoldGestureOccurred

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.

temporalController(self) → QgsTemporalController | None

Gets access to the temporal controller that will be used to update the canvas temporal range.

Added in version 3.14.

Return type:

Optional[QgsTemporalController]

temporalRange(self) → QgsDateTimeRange

Returns map canvas datetime range.

See also

setTemporalRange()

Added in version 3.14.

Return type:

QgsDateTimeRange

signal temporalRangeChanged

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.

theme(self) → str

Returns the map’s theme shown in the canvas, if set.

See also

setTheme()

Return type:

str

signal themeChanged

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 transformContextChanged

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.

unsetMapTool(self, mapTool: QgsMapTool | None)

Unset the current map tool or last non zoom tool

This is called from destructor of map tools to make sure that this map tool won’t be used any more. You don’t have to call it manually, QgsMapTool takes care of it.

Parameters:

mapTool (Optional[QgsMapTool])

updateCanvasItemPositions(self)

called on resize or changed extent to notify canvas items to change their rectangle

updateScale(self)

Emits signal scaleChanged to update scale in main window

waitWhileRendering(self)

Blocks until the rendering job has finished.

In almost all cases you do NOT want to call this, as it will hang the UI until the rendering job is complete. It’s included in API solely for unit testing and standalone Python scripts.

writeProject(self, a0: QDomDocument)

called to write map canvas settings to project

Parameters:

a0 (QDomDocument)

signal xyCoordinates

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.

zRange(self) → QgsDoubleRange

Returns the range of z-values which will be visible in the map.

See also

setZRange()

See also

zRangeChanged()

Added in version 3.18.

Return type:

QgsDoubleRange

signal zRangeChanged

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.

zoomByFactor(self, scaleFactor: float, center: QgsPointXY | None = None, ignoreScaleLock: bool = False)

Zoom with the factor supplied. Factor > 1 zooms out, interval (0,1) zooms in If point is given, re-center on it.

If ignoreScaleLock is set to True, then any existing constraint on the map scale of the canvas will be ignored during the zoom operation.

Parameters:

• scaleFactor (float)

• center (Optional[QgsPointXY] = None)

• ignoreScaleLock (bool = False)

zoomIn(self)

Zoom in with fixed factor

zoomInFactor(self) → float

Returns the zoom in factor.

Return type:

float

signal zoomLastStatusChanged

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 zoomNextStatusChanged

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.

zoomOut(self)

Zoom out with fixed factor

zoomOutFactor(self) → float

Returns the zoom in factor.

Return type:

float

zoomResolutions(self) → List[float]

Returns the list of resolutions to which to “snap to” when zooming the map.

See also

setZoomResolutions()

Added in version 3.12.

Return type:

List[float]

zoomScale(self, scale: float, ignoreScaleLock: bool = False)

Zooms the canvas to a specific scale. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.

If ignoreScaleLock is set to True, then any existing constraint on the map scale of the canvas will be ignored during the zoom operation.

Parameters:

• scale (float)

• ignoreScaleLock (bool = False)

zoomToFeatureExtent(self, rect: QgsRectangle)

Zooms to feature extent. Adds a small margin around the extent and does a pan if rect is empty (point extent)

Parameters:

rect (QgsRectangle)

zoomToFeatureIds(self, layer: QgsVectorLayer | None, ids: Any)

Set canvas extent to the bounding box of a set of features

Parameters:

• layer (Optional[QgsVectorLayer]) – the vector layer

• ids (Any) – the feature ids

zoomToFullExtent(self)

Zoom to the full extent of all layers currently visible in the canvas.

See also

zoomToProjectExtent()

zoomToNextExtent(self)

Zoom to the next extent (view)

zoomToPreviousExtent(self)

Zoom to the previous extent (view)

zoomToProjectExtent(self)

Zoom to the full extent the project associated with this canvas.

This method zooms to the full extent for the project associated with this canvas. Unlike zoomToFullExtent(), this method does NOT consider which layers are actually visible in the map canvas.

Added in version 3.20.

zoomToSelected(self, layer: QgsMapLayer | None = None)

Zoom to the extent of the selected features of provided map layer.

Parameters:

layer (Optional[QgsMapLayer] = None) – optionally specify different than current layer

zoomToSelected(self, layers: Iterable[QgsMapLayer]) Zoom to the combined extent of the selected features of all provided (vector) layers.

Parameters:

layers – A list of layers

Added in version 3.18.

zoomWithCenter(self, x: int, y: int, zoomIn: bool)

Zooms in/out with a given center

Parameters:

• x (int)

• y (int)

• zoomIn (bool)