Class: QgsMapCanvas

class qgis.gui.QgsMapCanvas

Bases: PyQt5.QtWidgets.QGraphicsView, QgsExpressionContextGenerator

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

QgsMapCanvas(parent: QWidget = None) Constructor

Methods

actionEvent

allowInteraction

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

annotationItems

Returns a list of all annotation items in the canvas.

annotationsVisible

Returns True if annotations are visible within the map canvas.

antiAliasingEnabled

True if antialiasing is enabled

canvasColor

Read property of QColor bgColor.

center

Gets map center, in geographical coordinates

changeEvent

childEvent

clearCache

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

clearExtentHistory

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

closeEvent

connectNotify

contextMenuEvent

create

createExpressionContext

rtype

QgsExpressionContext

currentLayer

returns current layer (set by legend widget)

customEvent

defaultExpressionContextScope

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

destroy

disconnectNotify

dragEnterEvent

param e

dragLeaveEvent

dragMoveEvent

drawBackground

drawForeground

drawFrame

dropEvent

param event

enableAntiAliasing

used to determine if anti-aliasing is enabled or not

enableMapTileRendering

sets map tile rendering flag

enterEvent

event

param e

eventFilter

expressionContextScope

Returns a reference to the expression context scope for the map canvas.

extent

Returns the current zoom extent of the map canvas

flashFeatureIds

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

flashGeometries

Causes a set of geometries to flash within the canvas.

focusInEvent

focusNextChild

focusNextPrevChild

focusOutEvent

focusPreviousChild

freeze

Freeze/thaw the map canvas.

fullExtent

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

getCoordinateTransform

Gets the current coordinate transform

hideEvent

initPainter

initStyleOption

inputMethodEvent

installInteractionBlocker

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

isCachingEnabled

Check whether images of rendered layers are curerently being cached

isDrawing

Find out whether rendering is in progress

isFrozen

Returns True if canvas is frozen.

isParallelRenderingEnabled

Check whether the layers are rendered in parallel or sequentially

isSignalConnected

keyPressEvent

param e

keyReleaseEvent

param e

labelingEngineSettings

Returns global labeling engine settings from the internal map settings

labelingResults

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

layer

Returns the map layer at position index in the layer stack

layerCount

Returns number of layers on the map

layerStateChange

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

layerStyleOverrides

Returns the stored overrides of styles for layers.

layers

Returns the list of layers shown within the map canvas.

leaveEvent

magnificationFactor

Returns the magnification factor

mapSettings

Gets access to properties used for map rendering

mapTool

Returns the currently active tool

mapUnits

Convenience function for returning the current canvas map units.

mapUnitsPerPixel

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

mapUpdateInterval

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

metric

mouseDoubleClickEvent

param e

mouseLastXY

returns last position of mouse cursor

mouseMoveEvent

param e

mousePressEvent

param e

mouseReleaseEvent

param e

moveCanvasContents

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

moveEvent

nativeEvent

paintEvent

param e

panAction

Called when mouse is moving and pan is activated

panActionEnd

Ends pan action and redraws the canvas.

panToFeatureIds

Centers canvas extent to feature ids

panToSelected

Pan to the selected features of current (vector) layer keeping same extent.

previewJobsEnabled

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.

previewMode

Returns the current preview mode for the map canvas.

previewModeEnabled

Returns whether a preview mode is enabled for the map canvas

project

Returns the project linked to this canvas.

projectExtent

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

readProject

called to read map canvas settings from project

receivers

redrawAllLayers

Clears all cached images and redraws all layers.

refresh

Repaints the canvas map

refreshAllLayers

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

removeInteractionBlocker

Removes an interaction blocker from the canvas.

renderFlag

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

resizeEvent

param e

rotation

Gets the current map canvas rotation in clockwise degrees

saveAsImage

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

scale

Returns the last reported scale of the canvas.

scaleLocked

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

scrollContentsBy

selectionChangedSlot

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

selectionColor

Returns color for selected features

sender

senderSignalIndex

setAnnotationsVisible

Sets whether annotations are visible in the canvas.

setCachingEnabled

Set whether to cache images of rendered layers

setCanvasColor

Write property of QColor bgColor.

setCenter

Set the center of the map canvas, in geographical coordinates

setCurrentLayer

param layer

setDestinationCrs

Sets destination coordinate reference system

setExpressionContextScope

Sets an expression context scope for the map canvas.

setExtent

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

setLabelingEngineSettings

Sets global labeling engine settings in the internal map settings

setLayerStyleOverrides

Sets the stored overrides of styles for rendering layers.

setLayers

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

setMagnificationFactor

Sets the factor of magnification to apply to the map canvas.

setMapSettingsFlags

Resets the flags for the canvas’ map settings.

setMapTool

Sets the map tool currently being used on the canvas

setMapUpdateInterval

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

setParallelRenderingEnabled

Set whether the layers are rendered in parallel or sequentially

setPreviewJobsEnabled

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.

setPreviewMode

Sets a preview mode for the map canvas.

setPreviewModeEnabled

Enables a preview mode for the map canvas

setProject

Sets the project linked to this canvas.

setReferencedExtent

Sets the canvas to the specified extent.

setRenderFlag

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

setRotation

Set the rotation of the map canvas in clockwise degrees

setScaleLocked

Lock the scale, so zooming can be performed using magnication

setSegmentationTolerance

Sets the segmentation tolerance applied when rendering curved geometries

setSegmentationToleranceType

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

setSelectionColor

Set color of selected vector features

setSnappingUtils

Assign an instance of snapping utils to the map canvas.

setTemporalController

Sets the temporal controller for this canvas.

setTemporalRange

Set datetime range for the map canvas.

setTheme

Sets a map theme to show in the canvas.

setViewportMargins

setViewportMargins(self, QMargins)

setWheelFactor

Sets wheel zoom factor (should be greater than 1)

setZRange

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

setZoomResolutions

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

setupViewport

sharedPainter

showEvent

snappingUtils

Returns snapping utility class that is associated with map canvas.

stopRendering

stop rendering (if there is any right now)

tabletEvent

temporalController

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

temporalRange

Returns map canvas datetime range.

theme

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

timerEvent

unsetMapTool

Unset the current map tool or last non zoom tool

updateCanvasItemPositions

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

updateMicroFocus

updateScale

Emits signal scaleChanged to update scale in main window

viewportEvent

viewportMargins

viewportSizeHint

waitWhileRendering

Blocks until the rendering job has finished.

wheelEvent

param e

writeProject

called to write map canvas settings to project

zRange

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

zoomByFactor

Zoom with the factor supplied.

zoomIn

Zoom in with fixed factor

zoomInFactor

Returns the zoom in factor.

zoomOut

Zoom out with fixed factor

zoomOutFactor

Returns the zoom in factor.

zoomResolutions

rtype

List[float]

zoomScale

Zooms the canvas to a specific scale.

zoomToFeatureExtent

Zooms to feature extent.

zoomToFeatureIds

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

zoomToFullExtent

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

zoomToNextExtent

Zoom to the next extent (view)

zoomToPreviousExtent

Zoom to the previous extent (view)

zoomToProjectExtent

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

zoomToSelected

Zoom to the extent of the selected features of provided (vector) layer.

zoomWithCenter

Zooms in/out with a given center

Signals

canvasColorChanged

Emitted when canvas background color changes

contextMenuAboutToShow

Emitted before the map canvas context menu will be shown.

currentLayerChanged

Emitted when the current layer is changed

destinationCrsChanged

Emitted when map CRS has changed

extentsChanged

Emitted when the extents of the map change [signal]

keyPressed

Emit key press event [signal]

keyReleased

Emit key release event [signal]

layerStyleOverridesChanged

Emitted when the configuration of overridden layer styles changes

layersChanged

Emitted when a new set of layers has been received [signal]

magnificationChanged

Emitted when the scale of the map changes

mapCanvasRefreshed

Emitted when canvas finished a refresh request.

mapRefreshCanceled

Emitted when the pending map refresh has been canceled

mapToolSet

Emit map tool changed with the old tool

messageEmitted

emit a message (usually to be displayed in a message bar) [signal]

panDistanceBearingChanged

Emitted whenever the distance or bearing of an in-progress panning operation is changed.

renderComplete

Emitted when the canvas has rendered.

renderErrorOccurred

Emitted whenever an error is encountered during a map render operation.

renderStarting

Emitted when the canvas is about to be rendered.

rotationChanged

Emitted when the rotation of the map changes

scaleChanged

Emitted when the scale of the map changes [signal]

scaleLockChanged

Emitted when the scale locked state of the map changes

selectionChanged

Emitted when selection in any layer gets changed [signal]

tapAndHoldGestureOccurred

Emitted whenever a tap and hold gesture occurs at the specified map point.

temporalRangeChanged

Emitted when the map canvas temporal range changes.

themeChanged

Emitted when the canvas has been assigned a different map theme.

transformContextChanged

Emitted when the canvas transform context is changed.

xyCoordinates

Emits current mouse position

zRangeChanged

Emitted when the map canvas z (elevation) range changes.

zoomLastStatusChanged

Emitted when zoom last status changed [signal]

zoomNextStatusChanged

Emitted when zoom next status changed [signal]

actionEvent(self, QActionEvent)
allowInteraction(self, interaction: QgsMapCanvasInteractionBlocker.Interaction)bool

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

New 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.

New in version 3.0.

Return type

List[QgsMapCanvasAnnotationItem]

annotationsVisible(self)bool

Returns True if annotations are visible within the map canvas.

New in version 3.0.

Return type

bool

antiAliasingEnabled(self)bool

True if antialiasing is enabled

Return type

bool

canvasColor(self)QColor

Read property of QColor bgColor.

Return type

QColor

canvasColorChanged

Emitted when canvas background color changes

New in version 3.0: [signal]

center(self)QgsPointXY

Gets map center, in geographical coordinates

New in version 2.8.

Return type

QgsPointXY

changeEvent(self, QEvent)
childEvent(self, QChildEvent)
clearCache(self)

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

New in version 2.4.

clearExtentHistory(self)

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

closeEvent(self, QCloseEvent)
connectNotify(self, QMetaMethod)
contextMenuAboutToShow

Emitted before the map canvas context menu will be shown. Can be used to extend the context menu.

New in version 3.16: [signal]

Parameters
contextMenuEvent(self, QContextMenuEvent)
create(self, window: sip.voidptr = 0, initializeWindow: bool = True, destroyOldWindow: bool = True)
createExpressionContext(self)QgsExpressionContext
Return type

QgsExpressionContext

currentLayer(self)QgsMapLayer

returns current layer (set by legend widget)

Return type

QgsMapLayer

currentLayerChanged

Emitted when the current layer is changed

New in version 2.8: [signal]

Parameters

layer (QgsMapLayer) –

customEvent(self, QEvent)
defaultExpressionContextScope(self)QgsExpressionContextScope

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

New in version 3.4.

Return type

QgsExpressionContextScope

destinationCrsChanged

Emitted when map CRS has changed

New in version 2.4: [signal]

destroy(self, destroyWindow: bool = True, destroySubWindows: bool = True)
disconnectNotify(self, QMetaMethod)
dragEnterEvent(self, e: QDragEnterEvent)
Parameters

e (QDragEnterEvent) –

dragLeaveEvent(self, QDragLeaveEvent)
dragMoveEvent(self, QDragMoveEvent)
drawBackground(self, QPainter, QRectF)
drawForeground(self, QPainter, QRectF)
drawFrame(self, QPainter)
dropEvent(self, event: QDropEvent)
Parameters

event (QDropEvent) –

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) –

enterEvent(self, QEvent)
event(self, e: QEvent)bool
Parameters

e (QEvent) –

Return type

bool

eventFilter(self, QObject, QEvent)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.

New in version 2.12.

Return type

QgsExpressionContextScope

extent(self)QgsRectangle

Returns the current zoom extent of the map canvas

Return type

QgsRectangle

extentsChanged

Emitted when the extents of the map change [signal]

flashFeatureIds(self, layer: QgsVectorLayer, ids: object, startColor: Union[QColor, Qt.GlobalColor, QGradient] = QColor(255, 0, 0, 255), endColor: Union[QColor, Qt.GlobalColor, QGradient] = 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.

New in version 3.0.

Parameters
  • layer (QgsVectorLayer) –

  • ids (object) –

  • startColor (Union[QColor) –

  • endColor (Union[QColor) –

  • flashes (int = 3) –

  • duration (int = 500) –

flashGeometries(self, geometries: Iterable[QgsGeometry], crs: QgsCoordinateReferenceSystem = QgsCoordinateReferenceSystem(), startColor: Union[QColor, Qt.GlobalColor, QGradient] = QColor(255, 0, 0, 255), endColor: Union[QColor, Qt.GlobalColor, QGradient] = 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).

New in version 3.0.

Parameters
  • geometries (Iterable[QgsGeometry]) –

  • crs (QgsCoordinateReferenceSystem = QgsCoordinateReferenceSystem()) –

  • startColor (Union[QColor) –

  • endColor (Union[QColor) –

  • flashes (int = 3) –

  • duration (int = 500) –

focusInEvent(self, QFocusEvent)
focusNextChild(self)bool
focusNextPrevChild(self, bool)bool
focusOutEvent(self, QFocusEvent)
focusPreviousChild(self)bool
freeze(self, frozen: bool = True)

Freeze/thaw 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() 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

Gets the current coordinate transform

Return type

QgsMapToPixel

hideEvent(self, QHideEvent)
initPainter(self, QPainter)
initStyleOption(self, QStyleOptionFrame)
inputMethodEvent(self, QInputMethodEvent)
installInteractionBlocker(self, blocker: QgsMapCanvasInteractionBlocker)

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.

New in version 3.14.

Parameters

blocker (QgsMapCanvasInteractionBlocker) –

isCachingEnabled(self)bool

Check whether images of rendered layers are curerently being cached

New in version 2.4.

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

renderFlag()

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

See also

freeze()

Return type

bool

isParallelRenderingEnabled(self)bool

Check whether the layers are rendered in parallel or sequentially

New in version 2.4.

Return type

bool

isSignalConnected(self, QMetaMethod)bool
keyPressEvent(self, e: QKeyEvent)
Parameters

e (QKeyEvent) –

keyPressed

Emit key press event [signal]

Parameters

e (QKeyEvent) –

keyReleaseEvent(self, e: QKeyEvent)
Parameters

e (QKeyEvent) –

keyReleased

Emit key release event [signal]

Parameters

e (QKeyEvent) –

labelingEngineSettings(self)QgsLabelingEngineSettings

Returns global labeling engine settings from the internal map settings

New in version 3.0.

Return type

QgsLabelingEngineSettings

labelingResults(self, allowOutdatedResults: bool = True)QgsLabelingResults

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.

New in version 2.4.

Parameters

allowOutdatedResults (bool = True) –

Return type

QgsLabelingResults

layer(self, index: int)QgsMapLayer

Returns the map layer at position index in the layer stack

Parameters

index (int) –

Return type

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.

New in version 2.12.

Return type

Dict[str, str]

layerStyleOverridesChanged

Emitted when the configuration of overridden layer styles changes

New in version 2.12: [signal]

layers(self)List[QgsMapLayer]

Returns the list of layers shown within the map canvas.

See also

setLayers()

Return type

List[QgsMapLayer]

layersChanged

Emitted when a new set of layers has been received [signal]

leaveEvent(self, QEvent)
magnificationChanged

Emitted when the scale of the map changes

New in version 2.16: [signal]

magnificationFactor(self)float

Returns the magnification factor

New in version 2.16.

Return type

float

mapCanvasRefreshed

Emitted when canvas finished a refresh request. [signal]

mapRefreshCanceled

Emitted when the pending map refresh has been canceled

New in version 3.18: [signal]

mapSettings(self)QgsMapSettings

Gets access to properties used for map rendering

New in version 2.4.

Return type

QgsMapSettings

mapTool(self)QgsMapTool

Returns the currently active tool

Return type

QgsMapTool

mapToolSet

Emit map tool changed with the old tool

New in version 2.3: [signal]

Parameters
mapUnits(self)QgsUnitTypes.DistanceUnit

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

Return type

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

New in version 2.4.

Return type

int

messageEmitted

emit a message (usually to be displayed in a message bar) [signal]

Parameters
  • title (str) –

  • message (str) –

  • a2 (Qgis.MessageLevel = Qgis.MessageLevel.Info) –

metric(self, QPaintDevice.PaintDeviceMetric)int
mouseDoubleClickEvent(self, e: QMouseEvent)
Parameters

e (QMouseEvent) –

mouseLastXY(self)QPoint

returns last position of mouse cursor

Return type

QPoint

mouseMoveEvent(self, e: QMouseEvent)
Parameters

e (QMouseEvent) –

mousePressEvent(self, e: QMouseEvent)
Parameters

e (QMouseEvent) –

mouseReleaseEvent(self, e: QMouseEvent)
Parameters

e (QMouseEvent) –

moveCanvasContents(self, reset: bool = False)

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

Parameters

reset (bool = False) –

moveEvent(self, QMoveEvent)
nativeEvent(self, Union[QByteArray, bytes, bytearray], sip.voidptr)Tuple[bool, int]
paintEvent(self, e: QPaintEvent)
Parameters

e (QPaintEvent) –

panAction(self, event: QMouseEvent)

Called when mouse is moving and pan is activated

Parameters

event (QMouseEvent) –

panActionEnd(self, releasePoint: QPoint)

Ends pan action and redraws the canvas.

Parameters

releasePoint (QPoint) –

panDistanceBearingChanged

Emitted whenever the distance or bearing of an in-progress panning operation is changed.

This signal will be emitted during a pan operation as the user moves the map, giving the total distance and bearing between the map position at the start of the pan and the current pan position.

New in version 3.12: [signal]

Parameters
panToFeatureIds(self, layer: QgsVectorLayer, ids: object, alwaysRecenter: bool = True)

Centers canvas extent to feature ids

Parameters
  • layer (QgsVectorLayer) – the vector layer

  • ids (object) – 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: QgsVectorLayer = None)

Pan to the selected features of current (vector) layer 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

New in version 3.18.

Parameters

layer (QgsVectorLayer = 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.

New in version 3.0.

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

New in version 2.3.

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

previewMode()

New in version 2.3.

project(self)QgsProject

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

New in version 3.14.

Return type

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

New in version 3.20.

Return type

QgsRectangle

readProject(self, QDomDocument)

called to read map canvas settings from project

receivers(self, PYQT_SIGNAL)int
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.

New 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.

New in version 2.9.

removeInteractionBlocker(self, blocker: QgsMapCanvasInteractionBlocker)

Removes an interaction blocker from the canvas.

New in version 3.14.

Parameters

blocker (QgsMapCanvasInteractionBlocker) –

renderComplete

Emitted when the canvas has rendered. Passes a pointer to the painter on which the map was drawn. This is useful for plugins that wish to draw on the map after it has been rendered. Passing the painter allows plugins to work when the map is being rendered onto a pixmap other than the mapCanvas own pixmap member.

  • anything related to rendering progress is not visible outside of map canvas

  • additional drawing shall be done directly within the renderer job or independently as a map canvas item [signal]

renderErrorOccurred

Emitted whenever an error is encountered during a map render operation.

The layer argument indicates the associated map layer, if available.

New in version 3.10.0: [signal]

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

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

Return type

bool

renderStarting

Emitted when the canvas is about to be rendered. [signal]

resizeEvent(self, e: QResizeEvent)
Parameters

e (QResizeEvent) –

rotation(self)float

Gets the current map canvas rotation in clockwise degrees

New in version 2.8.

Return type

float

rotationChanged

Emitted when the rotation of the map changes

New in version 2.8: [signal]

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

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

Parameters
  • fileName (str) –

  • QPixmap (QPixmap = None) –

  • a2 (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

scaleChanged

Emitted when the scale of the map changes [signal]

scaleLockChanged

Emitted when the scale locked state of the map changes

Parameters

locked (bool) – true if the scale is locked

See also

setScaleLocked()

New in version 3.18: [signal]

scaleLocked(self)bool

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

See also

setScaleLocked()

New in version 2.16.

Return type

bool

QgsMapCanvas.scrollContentsBy(self, int, int)
selectionChanged

Emitted when selection in any layer gets changed [signal]

Parameters

layer (QgsVectorLayer) –

selectionChangedSlot(self)

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

selectionColor(self)QColor

Returns color for selected features

New in version 3.0.

Return type

QColor

sender(self)QObject
senderSignalIndex(self)int
setAnnotationsVisible(self, visible: bool)

Sets whether annotations are visible in the canvas.

New in version 3.0.

Parameters

visible (bool) –

setCachingEnabled(self, enabled: bool)

Set whether to cache images of rendered layers

New in version 2.4.

Parameters

enabled (bool) –

setCanvasColor(self, _newVal: Union[QColor, Qt.GlobalColor, QGradient])

Write property of QColor bgColor.

Parameters

_newVal (Union[QColor) –

setCenter(self, center: QgsPointXY)

Set the center of the map canvas, in geographical coordinates

New in version 2.8.

Parameters

center (QgsPointXY) –

setCurrentLayer(self, layer: QgsMapLayer)
Parameters

layer (QgsMapLayer) –

setDestinationCrs(self, crs: QgsCoordinateReferenceSystem)

Sets destination coordinate reference system

New in version 2.4.

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

New in version 2.12.

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
setLabelingEngineSettings(self, settings: QgsLabelingEngineSettings)

Sets global labeling engine settings in the internal map settings

New in version 3.0.

Parameters

settings (QgsLabelingEngineSettings) –

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

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.

New in version 2.12.

Parameters

overrides (Dict[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()

New in version 3.0.

Parameters

layers (Iterable[QgsMapLayer]) –

setMagnificationFactor(self, factor: float, center: QgsPointXY = 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 (QgsPointXY = None) – Optional point to re-center the map

New in version 2.16.

setMapSettingsFlags(self, flags: Union[QgsMapSettings.Flags, QgsMapSettings.Flag])

Resets the flags for the canvas’ map settings.

New in version 3.0.

Parameters

flags (Union[QgsMapSettings.Flags) –

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

Sets the map tool currently being used on the canvas

Parameters
  • mapTool (QgsMapTool) –

  • clean (bool = False) –

setMapUpdateInterval(self, timeMilliseconds: int)

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

New in version 2.4.

Parameters

timeMilliseconds (int) –

setParallelRenderingEnabled(self, enabled: bool)

Set whether the layers are rendered in parallel or sequentially

New in version 2.4.

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.

New in version 3.0.

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

New in version 2.3.

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

New in version 2.3.

setProject(self, project: QgsProject)

Sets the project linked to this canvas.

New in version 3.14.

Parameters

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

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

New in version 2.8.

Parameters

degrees (float) –

setScaleLocked(self, isLocked: bool)

Lock the scale, so zooming can be performed using magnication

See also

scaleLocked()

New in version 2.16.

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: Union[QColor, Qt.GlobalColor, QGradient])

Set color of selected vector features

New in version 2.4.

Parameters

color (Union[QColor) –

setSnappingUtils(self, utils: QgsSnappingUtils)

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

New in version 2.8.

Parameters

utils (QgsSnappingUtils) –

setTemporalController(self, controller: QgsTemporalController)

Sets the temporal controller for this canvas.

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

New in version 3.14.

Parameters

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

New in version 3.14.

Parameters

range (QgsDateTimeRange) –

setTheme(self, theme: str)

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.

See also

theme()

New in version 3.0.

Parameters

theme (str) –

QgsMapCanvas.setViewportMargins(self, int, int, int, int)

setViewportMargins(self, QMargins)

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

New 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

New in version 3.12.

setupViewport(self, QWidget)
sharedPainter(self)QPainter
showEvent(self, QShowEvent)
snappingUtils(self)QgsSnappingUtils

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.

New in version 2.8.

Return type

QgsSnappingUtils

stopRendering(self)

stop rendering (if there is any right now)

New in version 2.4.

tabletEvent(self, QTabletEvent)
tapAndHoldGestureOccurred

Emitted whenever a tap and hold gesture occurs at the specified map point.

New in version 3.12: [signal]

Parameters
  • mapPoint (QgsPointXY) –

  • gesture (QTapAndHoldGesture) –

temporalController(self)QgsTemporalController

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

New in version 3.14.

Return type

QgsTemporalController

temporalRange(self)QgsDateTimeRange

Returns map canvas datetime range.

New in version 3.14.

Return type

QgsDateTimeRange

temporalRangeChanged

Emitted when the map canvas temporal range changes.

New in version 3.14: [signal]

theme(self)str

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

See also

setTheme()

New in version 3.0.

Return type

str

themeChanged

Emitted when the canvas has been assigned a different map theme.

See also

setTheme()

New in version 3.0: [signal]

Parameters

theme (str) –

timerEvent(self, QTimerEvent)
transformContextChanged

Emitted when the canvas transform context is changed.

New in version 3.0: [signal]

unsetMapTool(self, mapTool: QgsMapTool)

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 (QgsMapTool) –

updateCanvasItemPositions(self)

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

updateMicroFocus(self)
updateScale(self)

Emits signal scaleChanged to update scale in main window

viewportEvent(self, QEvent)bool
viewportMargins(self)QMargins
viewportSizeHint(self)QSize
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.

New in version 3.0.

wheelEvent(self, e: QWheelEvent)
Parameters

e (QWheelEvent) –

writeProject(self, QDomDocument)

called to write map canvas settings to project

xyCoordinates

Emits current mouse position

Note

changed in 1.3 [signal]

Parameters

p (QgsPointXY) –

zRange(self)QgsDoubleRange

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

See also

setZRange()

See also

zRangeChanged()

New in version 3.18.

Return type

QgsDoubleRange

zRangeChanged

Emitted when the map canvas z (elevation) range changes.

See also

zRange()

See also

setZRange()

New in version 3.18: [signal]

zoomByFactor(self, scaleFactor: float, center: QgsPointXY = 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 (QgsPointXY = None) –

  • ignoreScaleLock (bool = False) –

zoomIn(self)

Zoom in with fixed factor

zoomInFactor(self)float

Returns the zoom in factor.

Return type

float

zoomLastStatusChanged

Emitted when zoom last status changed [signal]

zoomNextStatusChanged

Emitted when zoom next status changed [signal]

zoomOut(self)

Zoom out with fixed factor

zoomOutFactor(self)float

Returns the zoom in factor.

Return type

float

zoomResolutions(self)List[float]
Return type

List[float]

Returns

List of resolutions to which to “snap to” when zooming the map

New in version 3.12.

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, ids: object)

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

Parameters
  • layer (QgsVectorLayer) – the vector layer

  • ids (object) – the feature ids

zoomToFullExtent(self)

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

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.

New in version 3.20.

zoomToSelected(self, layer: QgsVectorLayer = None)

Zoom to the extent of the selected features of provided (vector) layer.

Parameters

layer (QgsVectorLayer = 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

New 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) –