Class: QgsMapCanvas¶
-
class
qgis.gui.
QgsMapCanvas
(parent: QWidget = None)¶ Bases:
PyQt5.QtWidgets.QGraphicsView
Constructor
Map canvas is a class for displaying all GIS data types on a canvas.
- Parameters
parent –
-
actionEvent
()¶
-
annotationItems
(self) → object¶ Returns a list of all annotation items in the canvas.
New in version 3.0.
- Return type
object
-
annotationsVisible
(self) → bool¶ Returns true if annotations are visible within the map canvas.
See also
New in version 3.0.
- Return type
bool
-
antiAliasingEnabled
(self) → bool¶ true if antialising 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
-
changeEvent
()¶
-
childEvent
()¶
-
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)¶
-
closeEvent
()¶
-
connectNotify
()¶
-
contextMenuEvent
()¶
-
create
()¶
-
currentLayer
(self) → QgsMapLayer¶ returns current layer (set by legend widget)
- Return type
-
currentLayerChanged
¶ Emitted when the current layer is changed
New in version 2.8: [signal]
-
customEvent
()¶
-
defaultExpressionContextScope
(self) → QgsExpressionContextScope¶ Creates a new scope which contains default variables and functions relating to the map canvas.
See also
See also
New in version 3.4.
- Return type
-
destinationCrsChanged
¶ Emitted when map CRS has changed
New in version 2.4: [signal]
-
destroy
()¶
-
disconnectNotify
()¶
-
dragEnterEvent
(self, e: QDragEnterEvent)¶ Overridden drag enter event
- Parameters
e (QDragEnterEvent) –
-
dragLeaveEvent
()¶
-
dragMoveEvent
()¶
-
drawBackground
()¶
-
drawForeground
()¶
-
drawFrame
()¶
-
dropEvent
()¶
-
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
()¶
-
event
(self, e: QEvent) → bool¶ Overridden standard event to be gestures aware
- Parameters
e (QEvent) –
- Return type
bool
-
eventFilter
()¶
-
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
See also
New in version 2.12.
- Return type
-
extent
(self) → QgsRectangle¶ Returns the current zoom extent of the map canvas
- Return type
-
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 vectorlayer
to flash within the canvas.The
startColor
andendColor
can be specified, along with the number offlashes
andduration
of each flash (in milliseconds).Note
If the features or geometries are already available, flashGeometries() is much more efficient.
See also
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: object, 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
andendColor
can be specified, along with the number offlashes
andduration
of each flash (in milliseconds).See also
New in version 3.0.
- Parameters
geometries (object) –
crs (
QgsCoordinateReferenceSystem
= QgsCoordinateReferenceSystem()) –startColor (Union[QColor) –
endColor (Union[QColor) –
flashes (int = 3) –
duration (int = 500) –
-
focusInEvent
()¶
-
focusNextChild
()¶
-
focusNextPrevChild
()¶
-
focusOutEvent
()¶
-
focusPreviousChild
()¶
-
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
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
- Return type
-
getCoordinateTransform
(self) → QgsMapToPixel¶ Gets the current coordinate transform
- Return type
-
hideEvent
()¶
-
initPainter
()¶
-
initStyleOption
()¶
-
inputMethodEvent
()¶
-
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
have been halted programmatically, while renderFlag() should be used to determine whether a user has disabled rendering via GUI.
See also
- 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
()¶
-
keyPressEvent
(self, e: QKeyEvent)¶ Overridden key press event
- Parameters
e (QKeyEvent) –
-
keyPressed
¶ Emit key press event [signal]
-
keyReleaseEvent
(self, e: QKeyEvent)¶ Overridden key release event
- Parameters
e (QKeyEvent) –
-
keyReleased
¶ Emit key release event [signal]
-
labelingEngineSettings
(self) → QgsLabelingEngineSettings¶ Returns global labeling engine settings from the internal map settings
New in version 3.0.
- Return type
-
labelingResults
(self) → QgsLabelingResults¶ Gets access to the labeling results (may be null)
New in version 2.4.
- Return type
-
layer
(self, index: int) → QgsMapLayer¶ Returns the map layer at position index in the layer stack
- Parameters
index (int) –
- Return type
-
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
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
- Return type
List[QgsMapLayer]
-
layersChanged
¶ Emitted when a new set of layers has been received [signal]
-
leaveEvent
()¶
-
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]
-
mapSettings
(self) → QgsMapSettings¶ Gets access to properties used for map rendering
New in version 2.4.
- Return type
-
mapTool
(self) → QgsMapTool¶ Returns the currently active tool
- Return type
-
mapToolSet
¶ Emit map tool changed with the old tool
New in version 2.3: [signal]
-
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
-
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]
-
metric
()¶
-
mouseDoubleClickEvent
(self, e: QMouseEvent)¶ Overridden mouse double-click event
- Parameters
e (QMouseEvent) –
-
mouseLastXY
(self) → QPoint¶ returns last position of mouse cursor
- Return type
QPoint
-
mouseMoveEvent
(self, e: QMouseEvent)¶ Overridden mouse move event
- Parameters
e (QMouseEvent) –
-
mousePressEvent
(self, e: QMouseEvent)¶ Overridden mouse press event
- Parameters
e (QMouseEvent) –
-
mouseReleaseEvent
(self, e: QMouseEvent)¶ Overridden mouse release event
- Parameters
e (QMouseEvent) –
-
moveCanvasContents
(self, reset: bool = False)¶ called when panning is in action, reset indicates end of panning
- Parameters
reset (bool = False) –
-
moveEvent
()¶
-
nativeEvent
()¶
-
paintEvent
(self, e: QPaintEvent)¶ Overridden paint event
- 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) –
-
panToFeatureIds
(self, layer: QgsVectorLayer, ids: object)¶ Centers canvas extent to feature ids
- Parameters
layer (QgsVectorLayer) – the vector layer
ids (object) – the feature ids*
-
panToSelected
(self, layer: QgsVectorLayer = None)¶ Pan to the selected features of current (vector) layer keeping same extent.
- 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.
See also
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
- Returns
preview mode for map canvas
See also
See also
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
See also
New in version 2.3.
-
readProject
(self, QDomDocument)¶ called to read map canvas settings from project
-
receivers
()¶
-
refresh
(self)¶ Repaints the canvas map
-
refreshAllLayers
(self)¶ Reload all layers, clear the cache and refresh the canvas
New in version 2.9.
-
renderComplete
¶ TODO: deprecate when decorations are reimplemented as map canvas items - 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]
-
renderFlag
(self) → bool¶ Returns true if canvas render is disabled as a result of user disabling renders via the GUI.
See also
See also
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)¶ Overridden resize event
- 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 convtents 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]
-
scaleLocked
(self) → bool¶ Returns whether the scale is locked, so zooming can be performed using magnication.
See also
New in version 2.16.
- Return type
bool
-
scrollContentsBy
()¶
-
selectionChanged
¶ Emitted when selection in any layer gets changed [signal]
-
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
()¶
-
senderSignalIndex
()¶
-
setAnnotationsVisible
(self, visible: bool)¶ Sets whether annotations are
visible
in the canvas.See also
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
See also
See also
New in version 2.12.
-
setExtent
(self, r: QgsRectangle, magnified: bool = False)¶ Sets the extent of the map canvas
- Parameters
r (QgsRectangle) –
magnified (bool = False) –
-
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.
See also
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
New in version 3.0.
- Parameters
layers (Iterable[QgsMapLayer]) –
-
setMagnificationFactor
(self, factor: float)¶ 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.
New in version 2.16.
- Parameters
factor (float) –
-
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.See also
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
See also
See also
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
New in version 2.3.
-
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
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
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) –
-
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’sQgsMapThemeCollection
.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 viaQgsLayerTreeMapCanvasBridge
.If an empty string is passed then the current theme association will be cleared.
See also
New in version 3.0.
- Parameters
theme (str) –
-
setViewportMargins
()¶
-
setWheelFactor
(self, factor: float)¶ Sets wheel zoom factor (should be greater than 1)
- Parameters
factor (float) –
-
setupViewport
()¶
-
showEvent
()¶
-
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
-
stopRendering
(self)¶ stop rendering (if there is any right now)
New in version 2.4.
-
tabletEvent
()¶
-
theme
(self) → str¶ Returns the map’s theme shown in the canvas, if set.
See also
New in version 3.0.
- Return type
str
-
themeChanged
¶ Emitted when the canvas has been assigned a different map theme.
See also
New in version 3.0: [signal]
-
timerEvent
()¶
-
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
()¶
-
updateScale
(self)¶ Emits signal scaleChanged to update scale in main window
-
viewportEvent
()¶
-
viewportMargins
()¶
-
viewportSizeHint
()¶
-
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)¶ Overridden mouse wheel event
- 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]
-
zoomByFactor
(self, scaleFactor: float, center: QgsPointXY = None)¶ Zoom with the factor supplied. Factor > 1 zooms out, interval (0,1) zooms in If point is given, re-center on it
- Parameters
scaleFactor (float) –
center (
QgsPointXY
= None) –
-
zoomIn
(self)¶ Zoom in with fixed factor
-
zoomLastStatusChanged
¶ Emitted when zoom last status changed [signal]
-
zoomNextStatusChanged
¶ Emitted when zoom next status changed [signal]
-
zoomOut
(self)¶ Zoom out with fixed factor
-
zoomScale
(self, scale: float)¶ Zooms the canvas to a specific
scale
. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.- Parameters
scale (float) –
-
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
-
zoomToNextExtent
(self)¶ Zoom to the next extent (view)
-
zoomToPreviousExtent
(self)¶ Zoom to the previous extent (view)
-
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
-
zoomWithCenter
(self, x: int, y: int, zoomIn: bool)¶ Zooms in/out with a given center
- Parameters
x (int) –
y (int) –
zoomIn (bool) –