QGIS API Documentation  3.4.15-Madeira (e83d02e274)
Classes | Public Slots | Signals | Public Member Functions | Protected Slots | Protected Member Functions | Protected Attributes | Properties | Friends | List of all members
QgsMapCanvas Class Reference

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

#include <qgsmapcanvas.h>

Inheritance diagram for QgsMapCanvas:
Inheritance graph
[legend]

Classes

class  CanvasProperties
 Deprecated to be deleted, stuff from here should be moved elsewhere. More...
 

Public Slots

void layerStateChange ()
 This slot is connected to the visibility change of one or more layers. More...
 
void readProject (const QDomDocument &)
 called to read map canvas settings from project More...
 
void refresh ()
 Repaints the canvas map. More...
 
void refreshAllLayers ()
 Reload all layers, clear the cache and refresh the canvas. More...
 
void saveAsImage (const QString &fileName, QPixmap *QPixmap=nullptr, const QString &="PNG")
 Save the convtents of the map canvas to disk as an image. More...
 
void selectionChangedSlot ()
 Receives signal about selection change, and pass it on with layer info. More...
 
void setMagnificationFactor (double factor)
 Sets the factor of magnification to apply to the map canvas. More...
 
void setRenderFlag (bool flag)
 Sets whether a user has disabled canvas renders via the GUI. More...
 
void setScaleLocked (bool isLocked)
 Lock the scale, so zooming can be performed using magnication. More...
 
void stopRendering ()
 stop rendering (if there is any right now) More...
 
void writeProject (QDomDocument &)
 called to write map canvas settings to project More...
 
void zoomIn ()
 Zoom in with fixed factor. More...
 
void zoomOut ()
 Zoom out with fixed factor. More...
 
void zoomToSelected (QgsVectorLayer *layer=nullptr)
 Zoom to the extent of the selected features of provided (vector) layer. More...
 

Signals

void canvasColorChanged ()
 Emitted when canvas background color changes. More...
 
void currentLayerChanged (QgsMapLayer *layer)
 Emitted when the current layer is changed. More...
 
void destinationCrsChanged ()
 Emitted when map CRS has changed. More...
 
void extentsChanged ()
 Emitted when the extents of the map change. More...
 
void keyPressed (QKeyEvent *e)
 Emit key press event. More...
 
void keyReleased (QKeyEvent *e)
 Emit key release event. More...
 
void layersChanged ()
 Emitted when a new set of layers has been received. More...
 
void layerStyleOverridesChanged ()
 Emitted when the configuration of overridden layer styles changes. More...
 
void magnificationChanged (double)
 Emitted when the scale of the map changes. More...
 
void mapCanvasRefreshed ()
 Emitted when canvas finished a refresh request. More...
 
void mapToolSet (QgsMapTool *newTool, QgsMapTool *oldTool)
 Emit map tool changed with the old tool. More...
 
void messageEmitted (const QString &title, const QString &message, Qgis::MessageLevel=Qgis::Info)
 emit a message (usually to be displayed in a message bar) More...
 
void renderComplete (QPainter *)
 Emitted when the canvas has rendered. More...
 
void renderStarting ()
 Emitted when the canvas is about to be rendered. More...
 
void rotationChanged (double)
 Emitted when the rotation of the map changes. More...
 
void scaleChanged (double)
 Emitted when the scale of the map changes. More...
 
void selectionChanged (QgsVectorLayer *layer)
 Emitted when selection in any layer gets changed. More...
 
void themeChanged (const QString &theme)
 Emitted when the canvas has been assigned a different map theme. More...
 
void transformContextChanged ()
 Emitted when the canvas transform context is changed. More...
 
void xyCoordinates (const QgsPointXY &p)
 Emits current mouse position. More...
 
void zoomLastStatusChanged (bool)
 Emitted when zoom last status changed. More...
 
void zoomNextStatusChanged (bool)
 Emitted when zoom next status changed. More...
 

Public Member Functions

 QgsMapCanvas (QWidget *parent=nullptr)
 Constructor. More...
 
 ~QgsMapCanvas () override
 
QList< QgsMapCanvasAnnotationItem * > annotationItems () const
 Returns a list of all annotation items in the canvas. More...
 
bool annotationsVisible () const
 Returns true if annotations are visible within the map canvas. More...
 
bool antiAliasingEnabled () const
 true if antialising is enabled More...
 
QColor canvasColor () const
 Read property of QColor bgColor. More...
 
QgsPointXY center () const
 Gets map center, in geographical coordinates. More...
 
void clearCache ()
 Make sure to remove any rendered images from cache (does nothing if cache is not enabled) More...
 
void clearExtentHistory ()
 
QgsMapLayercurrentLayer ()
 returns current layer (set by legend widget) More...
 
QgsExpressionContextScopedefaultExpressionContextScope ()
 Creates a new scope which contains default variables and functions relating to the map canvas. More...
 
void enableAntiAliasing (bool flag)
 used to determine if anti-aliasing is enabled or not More...
 
void enableMapTileRendering (bool flag)
 sets map tile rendering flag More...
 
QgsExpressionContextScopeexpressionContextScope ()
 Returns a reference to the expression context scope for the map canvas. More...
 
const QgsExpressionContextScopeexpressionContextScope () const
 Returns a const reference to the expression context scope for the map canvas. More...
 
QgsRectangle extent () const
 Returns the current zoom extent of the map canvas. More...
 
void flashFeatureIds (QgsVectorLayer *layer, const QgsFeatureIds &ids, const QColor &startColor=QColor(255, 0, 0, 255), const QColor &endColor=QColor(255, 0, 0, 0), int flashes=3, int duration=500)
 Causes a set of features with matching ids from a vector layer to flash within the canvas. More...
 
void flashGeometries (const QList< QgsGeometry > &geometries, const QgsCoordinateReferenceSystem &crs=QgsCoordinateReferenceSystem(), const QColor &startColor=QColor(255, 0, 0, 255), const QColor &endColor=QColor(255, 0, 0, 0), int flashes=3, int duration=500)
 Causes a set of geometries to flash within the canvas. More...
 
void freeze (bool frozen=true)
 Freeze/thaw the map canvas. More...
 
QgsRectangle fullExtent () const
 Returns the combined extent for all layers on the map canvas. More...
 
const QgsMapToPixelgetCoordinateTransform ()
 Gets the current coordinate transform. More...
 
bool isCachingEnabled () const
 Check whether images of rendered layers are curerently being cached. More...
 
bool isDrawing ()
 Find out whether rendering is in progress. More...
 
bool isFrozen () const
 Returns true if canvas is frozen. More...
 
bool isParallelRenderingEnabled () const
 Check whether the layers are rendered in parallel or sequentially. More...
 
const QgsLabelingEngineSettingslabelingEngineSettings () const
 Returns global labeling engine settings from the internal map settings. More...
 
const QgsLabelingResultslabelingResults () const
 Gets access to the labeling results (may be null) More...
 
QgsMapLayerlayer (int index)
 Returns the map layer at position index in the layer stack. More...
 
int layerCount () const
 Returns number of layers on the map. More...
 
QList< QgsMapLayer * > layers () const
 Returns the list of layers shown within the map canvas. More...
 
QMap< QString, QString > layerStyleOverrides () const
 Returns the stored overrides of styles for layers. More...
 
double magnificationFactor () const
 Returns the magnification factor. More...
 
const QgsMapSettingsmapSettings () const
 Gets access to properties used for map rendering. More...
 
QgsMapToolmapTool ()
 Returns the currently active tool. More...
 
QgsUnitTypes::DistanceUnit mapUnits () const
 Convenience function for returning the current canvas map units. More...
 
double mapUnitsPerPixel () const
 Returns the mapUnitsPerPixel (map units per pixel) for the canvas. More...
 
int mapUpdateInterval () const
 Find out how often map preview should be updated while it is being rendered (in milliseconds) More...
 
QPoint mouseLastXY ()
 returns last position of mouse cursor More...
 
void panAction (QMouseEvent *event)
 Called when mouse is moving and pan is activated. More...
 
void panActionEnd (QPoint releasePoint)
 Ends pan action and redraws the canvas. More...
 
void panToFeatureIds (QgsVectorLayer *layer, const QgsFeatureIds &ids)
 Centers canvas extent to feature ids. More...
 
void panToSelected (QgsVectorLayer *layer=nullptr)
 Pan to the selected features of current (vector) layer keeping same extent. More...
 
bool previewJobsEnabled () const
 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. More...
 
QgsPreviewEffect::PreviewMode previewMode () const
 Returns the current preview mode for the map canvas. More...
 
bool previewModeEnabled () const
 Returns whether a preview mode is enabled for the map canvas. More...
 
bool renderFlag () const
 Returns true if canvas render is disabled as a result of user disabling renders via the GUI. More...
 
double rotation () const
 Gets the current map canvas rotation in clockwise degrees. More...
 
double scale () const
 Returns the last reported scale of the canvas. More...
 
bool scaleLocked () const
 Returns whether the scale is locked, so zooming can be performed using magnication. More...
 
QColor selectionColor () const
 Returns color for selected features. More...
 
void setAnnotationsVisible (bool visible)
 Sets whether annotations are visible in the canvas. More...
 
void setCachingEnabled (bool enabled)
 Set whether to cache images of rendered layers. More...
 
void setCanvasColor (const QColor &_newVal)
 Write property of QColor bgColor. More...
 
void setCenter (const QgsPointXY &center)
 Set the center of the map canvas, in geographical coordinates. More...
 
void setCurrentLayer (QgsMapLayer *layer)
 
void setDestinationCrs (const QgsCoordinateReferenceSystem &crs)
 sets destination coordinate reference system More...
 
void setExpressionContextScope (const QgsExpressionContextScope &scope)
 Sets an expression context scope for the map canvas. More...
 
void setExtent (const QgsRectangle &r, bool magnified=false)
 Sets the extent of the map canvas. More...
 
void setLabelingEngineSettings (const QgsLabelingEngineSettings &settings)
 Sets global labeling engine settings in the internal map settings. More...
 
void setLayers (const QList< QgsMapLayer * > &layers)
 Sets the list of layers that should be shown in the canvas. More...
 
void setLayerStyleOverrides (const QMap< QString, QString > &overrides)
 Sets the stored overrides of styles for rendering layers. More...
 
void setMapSettingsFlags (QgsMapSettings::Flags flags)
 Resets the flags for the canvas' map settings. More...
 
void setMapTool (QgsMapTool *mapTool, bool clean=false)
 Sets the map tool currently being used on the canvas. More...
 
void setMapUpdateInterval (int timeMilliseconds)
 Set how often map preview should be updated while it is being rendered (in milliseconds) More...
 
void setParallelRenderingEnabled (bool enabled)
 Set whether the layers are rendered in parallel or sequentially. More...
 
void setPreviewJobsEnabled (bool enabled)
 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. More...
 
void setPreviewMode (QgsPreviewEffect::PreviewMode mode)
 Sets a preview mode for the map canvas. More...
 
void setPreviewModeEnabled (bool previewEnabled)
 Enables a preview mode for the map canvas. More...
 
void setRotation (double degrees)
 Set the rotation of the map canvas in clockwise degrees. More...
 
void setSegmentationTolerance (double tolerance)
 Sets the segmentation tolerance applied when rendering curved geometries. More...
 
void setSegmentationToleranceType (QgsAbstractGeometry::SegmentationToleranceType type)
 Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation) More...
 
void setSelectionColor (const QColor &color)
 Set color of selected vector features. More...
 
void setSnappingUtils (QgsSnappingUtils *utils)
 Assign an instance of snapping utils to the map canvas. More...
 
void setTheme (const QString &theme)
 Sets a map theme to show in the canvas. More...
 
void setWheelFactor (double factor)
 Sets wheel zoom factor (should be greater than 1) More...
 
QgsSnappingUtilssnappingUtils () const
 Returns snapping utility class that is associated with map canvas. More...
 
QString theme () const
 Returns the map's theme shown in the canvas, if set. More...
 
void unsetMapTool (QgsMapTool *mapTool)
 Unset the current map tool or last non zoom tool. More...
 
void updateScale ()
 Emits signal scaleChanged to update scale in main window. More...
 
void waitWhileRendering ()
 Blocks until the rendering job has finished. More...
 
void zoomByFactor (double scaleFactor, const QgsPointXY *center=nullptr)
 Zoom with the factor supplied. More...
 
void zoomScale (double scale)
 Zooms the canvas to a specific scale. More...
 
void zoomToFeatureExtent (QgsRectangle &rect)
 Zooms to feature extent. More...
 
void zoomToFeatureIds (QgsVectorLayer *layer, const QgsFeatureIds &ids)
 Set canvas extent to the bounding box of a set of features. More...
 
void zoomToFullExtent ()
 Zoom to the full extent of all layers. More...
 
void zoomToNextExtent ()
 Zoom to the next extent (view) More...
 
void zoomToPreviousExtent ()
 Zoom to the previous extent (view) More...
 
void zoomWithCenter (int x, int y, bool zoomIn)
 Zooms in/out with a given center. More...
 

Protected Slots

void updateCanvasItemPositions ()
 called on resize or changed extent to notify canvas items to change their rectangle More...
 

Protected Member Functions

void dragEnterEvent (QDragEnterEvent *e) override
 Overridden drag enter event. More...
 
bool event (QEvent *e) override
 Overridden standard event to be gestures aware. More...
 
void keyPressEvent (QKeyEvent *e) override
 Overridden key press event. More...
 
void keyReleaseEvent (QKeyEvent *e) override
 Overridden key release event. More...
 
void mouseDoubleClickEvent (QMouseEvent *e) override
 Overridden mouse double-click event. More...
 
void mouseMoveEvent (QMouseEvent *e) override
 Overridden mouse move event. More...
 
void mousePressEvent (QMouseEvent *e) override
 Overridden mouse press event. More...
 
void mouseReleaseEvent (QMouseEvent *e) override
 Overridden mouse release event. More...
 
void moveCanvasContents (bool reset=false)
 called when panning is in action, reset indicates end of panning More...
 
void paintEvent (QPaintEvent *e) override
 Overridden paint event. More...
 
void resizeEvent (QResizeEvent *e) override
 Overridden resize event. More...
 
void wheelEvent (QWheelEvent *e) override
 Overridden mouse wheel event. More...
 

Protected Attributes

std::unique_ptr< CanvasPropertiesmCanvasProperties
 Handle pattern for implementation object. More...
 

Properties

bool previewJobsEnabled
 
QString theme
 

Friends

class TestQgsMapCanvas
 

Detailed Description

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

Definition at line 74 of file qgsmapcanvas.h.

Constructor & Destructor Documentation

QgsMapCanvas::QgsMapCanvas ( QWidget *  parent = nullptr)

Constructor.

Definition at line 103 of file qgsmapcanvas.cpp.

QgsMapCanvas::~QgsMapCanvas ( )
override

Definition at line 211 of file qgsmapcanvas.cpp.

Member Function Documentation

QList< QgsMapCanvasAnnotationItem * > QgsMapCanvas::annotationItems ( ) const

Returns a list of all annotation items in the canvas.

Since
QGIS 3.0

Definition at line 2258 of file qgsmapcanvas.cpp.

bool QgsMapCanvas::annotationsVisible ( ) const
inline

Returns true if annotations are visible within the map canvas.

See also
setAnnotationsVisible()
Since
QGIS 3.0

Definition at line 600 of file qgsmapcanvas.h.

bool QgsMapCanvas::antiAliasingEnabled ( ) const
inline

true if antialising is enabled

Definition at line 470 of file qgsmapcanvas.h.

QColor QgsMapCanvas::canvasColor ( ) const

Read property of QColor bgColor.

Definition at line 1792 of file qgsmapcanvas.cpp.

void QgsMapCanvas::canvasColorChanged ( )
signal

Emitted when canvas background color changes.

Since
QGIS 3.0
QgsPointXY QgsMapCanvas::center ( ) const

Gets map center, in geographical coordinates.

Since
QGIS 2.8

Definition at line 891 of file qgsmapcanvas.cpp.

void QgsMapCanvas::clearCache ( )

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

Since
QGIS 2.4

Definition at line 450 of file qgsmapcanvas.cpp.

void QgsMapCanvas::clearExtentHistory ( )

Definition at line 972 of file qgsmapcanvas.cpp.

QgsMapLayer * QgsMapCanvas::currentLayer ( )

returns current layer (set by legend widget)

Definition at line 477 of file qgsmapcanvas.cpp.

void QgsMapCanvas::currentLayerChanged ( QgsMapLayer layer)
signal

Emitted when the current layer is changed.

Since
QGIS 2.8
QgsExpressionContextScope * QgsMapCanvas::defaultExpressionContextScope ( )

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

See also
expressionContextScope()
setExpressionContextScope()
Since
QGIS 3.4

Definition at line 482 of file qgsmapcanvas.cpp.

void QgsMapCanvas::destinationCrsChanged ( )
signal

Emitted when map CRS has changed.

Since
QGIS 2.4
void QgsMapCanvas::dragEnterEvent ( QDragEnterEvent *  e)
overrideprotected

Overridden drag enter event.

Definition at line 2191 of file qgsmapcanvas.cpp.

void QgsMapCanvas::enableAntiAliasing ( bool  flag)

used to determine if anti-aliasing is enabled or not

Definition at line 277 of file qgsmapcanvas.cpp.

void QgsMapCanvas::enableMapTileRendering ( bool  flag)

sets map tile rendering flag

Definition at line 282 of file qgsmapcanvas.cpp.

bool QgsMapCanvas::event ( QEvent *  e)
overrideprotected

Overridden standard event to be gestures aware.

Definition at line 2205 of file qgsmapcanvas.cpp.

QgsExpressionContextScope& QgsMapCanvas::expressionContextScope ( )
inline

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()
defaultExpressionContextScope()
Since
QGIS 2.12

Definition at line 560 of file qgsmapcanvas.h.

const QgsExpressionContextScope& QgsMapCanvas::expressionContextScope ( ) const
inline

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

See also
setExpressionContextScope()
defaultExpressionContextScope()
Note
not available in Python bindings
Since
QGIS 2.12

Definition at line 569 of file qgsmapcanvas.h.

QgsRectangle QgsMapCanvas::extent ( ) const

Returns the current zoom extent of the map canvas.

Definition at line 815 of file qgsmapcanvas.cpp.

void QgsMapCanvas::extentsChanged ( )
signal

Emitted when the extents of the map change.

void QgsMapCanvas::flashFeatureIds ( QgsVectorLayer layer,
const QgsFeatureIds ids,
const QColor &  startColor = QColor( 255, 0, 0, 255 ),
const QColor &  endColor = QColor( 255, 0, 0, 0 ),
int  flashes = 3,
int  duration = 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()
Since
QGIS 3.0

Definition at line 1161 of file qgsmapcanvas.cpp.

void QgsMapCanvas::flashGeometries ( const QList< QgsGeometry > &  geometries,
const QgsCoordinateReferenceSystem crs = QgsCoordinateReferenceSystem(),
const QColor &  startColor = QColor( 255, 0, 0, 255 ),
const QColor &  endColor = QColor( 255, 0, 0, 0 ),
int  flashes = 3,
int  duration = 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()
Since
QGIS 3.0

Definition at line 1184 of file qgsmapcanvas.cpp.

void QgsMapCanvas::freeze ( bool  frozen = 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
frozenBoolean specifying if the canvas should be frozen (true) or thawed (false). Default is true.
See also
isFrozen()
setRenderFlag(). freeze() should be used to programmatically halt map updates, while setRenderFlag() should only be used when users disable rendering via GUI.

Definition at line 1824 of file qgsmapcanvas.cpp.

QgsRectangle QgsMapCanvas::fullExtent ( ) const

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

Definition at line 820 of file qgsmapcanvas.cpp.

const QgsMapToPixel * QgsMapCanvas::getCoordinateTransform ( )

Gets the current coordinate transform.

Definition at line 317 of file qgsmapcanvas.cpp.

bool QgsMapCanvas::isCachingEnabled ( ) const

Check whether images of rendered layers are curerently being cached.

Since
QGIS 2.4

Definition at line 445 of file qgsmapcanvas.cpp.

bool QgsMapCanvas::isDrawing ( )

Find out whether rendering is in progress.

Definition at line 310 of file qgsmapcanvas.cpp.

bool QgsMapCanvas::isFrozen ( ) const

Returns true if canvas is frozen.

See also
renderFlag(). 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.
freeze()

Definition at line 1829 of file qgsmapcanvas.cpp.

bool QgsMapCanvas::isParallelRenderingEnabled ( ) const

Check whether the layers are rendered in parallel or sequentially.

Since
QGIS 2.4

Definition at line 461 of file qgsmapcanvas.cpp.

void QgsMapCanvas::keyPressed ( QKeyEvent *  e)
signal

Emit key press event.

void QgsMapCanvas::keyPressEvent ( QKeyEvent *  e)
overrideprotected

Overridden key press event.

Definition at line 1261 of file qgsmapcanvas.cpp.

void QgsMapCanvas::keyReleased ( QKeyEvent *  e)
signal

Emit key release event.

void QgsMapCanvas::keyReleaseEvent ( QKeyEvent *  e)
overrideprotected

Overridden key release event.

Definition at line 1355 of file qgsmapcanvas.cpp.

const QgsLabelingEngineSettings & QgsMapCanvas::labelingEngineSettings ( ) const

Returns global labeling engine settings from the internal map settings.

Since
QGIS 3.0

Definition at line 2289 of file qgsmapcanvas.cpp.

const QgsLabelingResults * QgsMapCanvas::labelingResults ( ) const

Gets access to the labeling results (may be null)

Since
QGIS 2.4

Definition at line 418 of file qgsmapcanvas.cpp.

QgsMapLayer * QgsMapCanvas::layer ( int  index)

Returns the map layer at position index in the layer stack.

Definition at line 287 of file qgsmapcanvas.cpp.

int QgsMapCanvas::layerCount ( ) const

Returns number of layers on the map.

Definition at line 1807 of file qgsmapcanvas.cpp.

QList< QgsMapLayer * > QgsMapCanvas::layers ( ) const

Returns the list of layers shown within the map canvas.

See also
setLayers()

Definition at line 1813 of file qgsmapcanvas.cpp.

void QgsMapCanvas::layersChanged ( )
signal

Emitted when a new set of layers has been received.

void QgsMapCanvas::layerStateChange ( )
slot

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

Definition at line 1818 of file qgsmapcanvas.cpp.

QMap< QString, QString > QgsMapCanvas::layerStyleOverrides ( ) const

Returns the stored overrides of styles for layers.

See also
setLayerStyleOverrides().
Since
QGIS 2.12

Definition at line 1844 of file qgsmapcanvas.cpp.

void QgsMapCanvas::layerStyleOverridesChanged ( )
signal

Emitted when the configuration of overridden layer styles changes.

Since
QGIS 2.12
void QgsMapCanvas::magnificationChanged ( double  )
signal

Emitted when the scale of the map changes.

Since
QGIS 2.16
double QgsMapCanvas::magnificationFactor ( ) const

Returns the magnification factor.

Since
QGIS 2.16

Definition at line 272 of file qgsmapcanvas.cpp.

void QgsMapCanvas::mapCanvasRefreshed ( )
signal

Emitted when canvas finished a refresh request.

const QgsMapSettings & QgsMapCanvas::mapSettings ( ) const

Gets access to properties used for map rendering.

Since
QGIS 2.4

Definition at line 371 of file qgsmapcanvas.cpp.

QgsMapTool * QgsMapCanvas::mapTool ( )

Returns the currently active tool.

Definition at line 1954 of file qgsmapcanvas.cpp.

void QgsMapCanvas::mapToolSet ( QgsMapTool newTool,
QgsMapTool oldTool 
)
signal

Emit map tool changed with the old tool.

Since
QGIS 2.3
QgsUnitTypes::DistanceUnit QgsMapCanvas::mapUnits ( ) const

Convenience function for returning the current canvas map units.

The map units are dictated by the canvas' destinationCrs() map units.

Definition at line 1839 of file qgsmapcanvas.cpp.

double QgsMapCanvas::mapUnitsPerPixel ( ) const

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

Definition at line 1834 of file qgsmapcanvas.cpp.

int QgsMapCanvas::mapUpdateInterval ( ) const

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

Since
QGIS 2.4

Definition at line 471 of file qgsmapcanvas.cpp.

void QgsMapCanvas::messageEmitted ( const QString &  title,
const QString &  message,
Qgis::MessageLevel  = Qgis::Info 
)
signal

emit a message (usually to be displayed in a message bar)

void QgsMapCanvas::mouseDoubleClickEvent ( QMouseEvent *  e)
overrideprotected

Overridden mouse double-click event.

Definition at line 1387 of file qgsmapcanvas.cpp.

QPoint QgsMapCanvas::mouseLastXY ( )

returns last position of mouse cursor

Definition at line 1995 of file qgsmapcanvas.cpp.

void QgsMapCanvas::mouseMoveEvent ( QMouseEvent *  e)
overrideprotected

Overridden mouse move event.

Definition at line 1684 of file qgsmapcanvas.cpp.

void QgsMapCanvas::mousePressEvent ( QMouseEvent *  e)
overrideprotected

Overridden mouse press event.

Definition at line 1442 of file qgsmapcanvas.cpp.

void QgsMapCanvas::mouseReleaseEvent ( QMouseEvent *  e)
overrideprotected

Overridden mouse release event.

Definition at line 1480 of file qgsmapcanvas.cpp.

void QgsMapCanvas::moveCanvasContents ( bool  reset = false)
protected

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

Definition at line 1986 of file qgsmapcanvas.cpp.

void QgsMapCanvas::paintEvent ( QPaintEvent *  e)
overrideprotected

Overridden paint event.

Definition at line 1570 of file qgsmapcanvas.cpp.

void QgsMapCanvas::panAction ( QMouseEvent *  event)

Called when mouse is moving and pan is activated.

Definition at line 1978 of file qgsmapcanvas.cpp.

void QgsMapCanvas::panActionEnd ( QPoint  releasePoint)

Ends pan action and redraws the canvas.

Definition at line 1959 of file qgsmapcanvas.cpp.

void QgsMapCanvas::panToFeatureIds ( QgsVectorLayer layer,
const QgsFeatureIds ids 
)

Centers canvas extent to feature ids.

Parameters
layerthe vector layer
idsthe feature ids

Definition at line 1081 of file qgsmapcanvas.cpp.

void QgsMapCanvas::panToSelected ( QgsVectorLayer layer = nullptr)

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

Definition at line 1138 of file qgsmapcanvas.cpp.

bool QgsMapCanvas::previewJobsEnabled ( ) const

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()
Since
QGIS 3.0
QgsPreviewEffect::PreviewMode QgsMapCanvas::previewMode ( ) const

Returns the current preview mode for the map canvas.

This setting only has an effect if previewModeEnabled is true.

Returns
preview mode for map canvas
See also
setPreviewMode
previewModeEnabled
Since
QGIS 2.3

Definition at line 2030 of file qgsmapcanvas.cpp.

bool QgsMapCanvas::previewModeEnabled ( ) const

Returns whether a preview mode is enabled for the map canvas.

Returns
true if a preview mode is currently enabled
See also
setPreviewModeEnabled
previewMode
Since
QGIS 2.3

Definition at line 2010 of file qgsmapcanvas.cpp.

void QgsMapCanvas::readProject ( const QDomDocument &  doc)
slot

called to read map canvas settings from project

Definition at line 2056 of file qgsmapcanvas.cpp.

void QgsMapCanvas::refresh ( )
slot

Repaints the canvas map.

Definition at line 490 of file qgsmapcanvas.cpp.

void QgsMapCanvas::refreshAllLayers ( )
slot

Reload all layers, clear the cache and refresh the canvas.

Since
QGIS 2.9

Definition at line 2223 of file qgsmapcanvas.cpp.

void QgsMapCanvas::renderComplete ( QPainter *  )
signal

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. 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
bool QgsMapCanvas::renderFlag ( ) const
inline

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

See also
setRenderFlag()
isFrozen(). 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.

Definition at line 371 of file qgsmapcanvas.h.

void QgsMapCanvas::renderStarting ( )
signal

Emitted when the canvas is about to be rendered.

void QgsMapCanvas::resizeEvent ( QResizeEvent *  e)
overrideprotected

Overridden resize event.

Definition at line 1541 of file qgsmapcanvas.cpp.

double QgsMapCanvas::rotation ( ) const

Gets the current map canvas rotation in clockwise degrees.

Since
QGIS 2.8

Definition at line 902 of file qgsmapcanvas.cpp.

void QgsMapCanvas::rotationChanged ( double  )
signal

Emitted when the rotation of the map changes.

Since
QGIS 2.8
void QgsMapCanvas::saveAsImage ( const QString &  fileName,
QPixmap *  QPixmap = nullptr,
const QString &  format = "PNG" 
)
slot

Save the convtents of the map canvas to disk as an image.

Definition at line 745 of file qgsmapcanvas.cpp.

double QgsMapCanvas::scale ( ) const

Returns the last reported scale of the canvas.

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

Definition at line 305 of file qgsmapcanvas.cpp.

void QgsMapCanvas::scaleChanged ( double  )
signal

Emitted when the scale of the map changes.

bool QgsMapCanvas::scaleLocked ( ) const
inline

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

See also
setScaleLocked()
Since
QGIS 2.16

Definition at line 464 of file qgsmapcanvas.h.

void QgsMapCanvas::selectionChanged ( QgsVectorLayer layer)
signal

Emitted when selection in any layer gets changed.

void QgsMapCanvas::selectionChangedSlot ( )
slot

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

Definition at line 2180 of file qgsmapcanvas.cpp.

QColor QgsMapCanvas::selectionColor ( ) const

Returns color for selected features.

Since
QGIS 3.0

Definition at line 1802 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setAnnotationsVisible ( bool  visible)

Sets whether annotations are visible in the canvas.

See also
annotationsVisible()
Since
QGIS 3.0

Definition at line 2275 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setCachingEnabled ( bool  enabled)

Set whether to cache images of rendered layers.

Since
QGIS 2.4

Definition at line 423 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setCanvasColor ( const QColor &  _newVal)

Write property of QColor bgColor.

Definition at line 1769 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setCenter ( const QgsPointXY center)

Set the center of the map canvas, in geographical coordinates.

Since
QGIS 2.8

Definition at line 877 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setCurrentLayer ( QgsMapLayer layer)

Definition at line 296 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setDestinationCrs ( const QgsCoordinateReferenceSystem crs)

sets destination coordinate reference system

Since
QGIS 2.4

Definition at line 376 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setExpressionContextScope ( const QgsExpressionContextScope scope)
inline

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
scopenew expression context scope
See also
expressionContextScope()
defaultExpressionContextScope()
Since
QGIS 2.12

Definition at line 550 of file qgsmapcanvas.h.

void QgsMapCanvas::setExtent ( const QgsRectangle r,
bool  magnified = false 
)

Sets the extent of the map canvas.

Definition at line 826 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setLabelingEngineSettings ( const QgsLabelingEngineSettings settings)

Sets global labeling engine settings in the internal map settings.

Since
QGIS 3.0

Definition at line 2284 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setLayers ( const QList< QgsMapLayer * > &  layers)

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()
Since
QGIS 3.0

Definition at line 322 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setLayerStyleOverrides ( const QMap< QString, QString > &  overrides)

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()
Since
QGIS 2.12

Definition at line 1849 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setMagnificationFactor ( double  factor)
slot

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.

Since
QGIS 2.16

Definition at line 256 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setMapSettingsFlags ( QgsMapSettings::Flags  flags)

Resets the flags for the canvas' map settings.

Since
QGIS 3.0

Definition at line 411 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setMapTool ( QgsMapTool mapTool,
bool  clean = false 
)

Sets the map tool currently being used on the canvas.

Definition at line 1713 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setMapUpdateInterval ( int  timeMilliseconds)

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

Since
QGIS 2.4

Definition at line 466 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setParallelRenderingEnabled ( bool  enabled)

Set whether the layers are rendered in parallel or sequentially.

Since
QGIS 2.4

Definition at line 456 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setPreviewJobsEnabled ( bool  enabled)

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()
Since
QGIS 3.0

Definition at line 716 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setPreviewMode ( QgsPreviewEffect::PreviewMode  mode)

Sets a preview mode for the map canvas.

This setting only has an effect if previewModeEnabled is true.

Parameters
modepreview mode for the canvas
See also
previewMode
setPreviewModeEnabled
previewModeEnabled
Since
QGIS 2.3

Definition at line 2020 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setPreviewModeEnabled ( bool  previewEnabled)

Enables a preview mode for the map canvas.

Parameters
previewEnabledset to true to enable a preview mode
See also
setPreviewMode
Since
QGIS 2.3

Definition at line 2000 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setRenderFlag ( bool  flag)
slot

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

Parameters
flagset to false to indicate that user has disabled renders
See also
renderFlag()
freeze(). freeze() should be used to programmatically halt map updates, while setRenderFlag() should only be used when users disable rendering via GUI.

Definition at line 1880 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setRotation ( double  degrees)

Set the rotation of the map canvas in clockwise degrees.

Since
QGIS 2.8

Definition at line 907 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setScaleLocked ( bool  isLocked)
slot

Lock the scale, so zooming can be performed using magnication.

See also
scaleLocked()
Since
QGIS 2.16

Definition at line 1679 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setSegmentationTolerance ( double  tolerance)

Sets the segmentation tolerance applied when rendering curved geometries.

Parameters
tolerancethe segmentation tolerance

Definition at line 2248 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setSegmentationToleranceType ( QgsAbstractGeometry::SegmentationToleranceType  type)

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

Parameters
typethe segmentation tolerance typename

Definition at line 2253 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setSelectionColor ( const QColor &  color)

Set color of selected vector features.

Since
QGIS 2.4

Definition at line 1797 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setSnappingUtils ( QgsSnappingUtils utils)

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

Since
QGIS 2.8

Definition at line 2051 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setTheme ( const QString &  theme)

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()
Since
QGIS 3.0

Definition at line 1859 of file qgsmapcanvas.cpp.

void QgsMapCanvas::setWheelFactor ( double  factor)

Sets wheel zoom factor (should be greater than 1)

Definition at line 1638 of file qgsmapcanvas.cpp.

QgsSnappingUtils * QgsMapCanvas::snappingUtils ( ) const

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.

Since
QGIS 2.8

Definition at line 2040 of file qgsmapcanvas.cpp.

void QgsMapCanvas::stopRendering ( )
slot

stop rendering (if there is any right now)

Since
QGIS 2.4

Definition at line 730 of file qgsmapcanvas.cpp.

QString QgsMapCanvas::theme ( ) const
inline

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

See also
setTheme()
Since
QGIS 3.0

Definition at line 424 of file qgsmapcanvas.h.

void QgsMapCanvas::themeChanged ( const QString &  theme)
signal

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

See also
setTheme()
Since
QGIS 3.0
void QgsMapCanvas::transformContextChanged ( )
signal

Emitted when the canvas transform context is changed.

Since
QGIS 3.0
void QgsMapCanvas::unsetMapTool ( QgsMapTool mapTool)

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.

Definition at line 1753 of file qgsmapcanvas.cpp.

void QgsMapCanvas::updateCanvasItemPositions ( )
protectedslot

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

Definition at line 1577 of file qgsmapcanvas.cpp.

void QgsMapCanvas::updateScale ( )

Emits signal scaleChanged to update scale in main window.

Definition at line 920 of file qgsmapcanvas.cpp.

void QgsMapCanvas::waitWhileRendering ( )

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.

Since
QGIS 3.0

Definition at line 2240 of file qgsmapcanvas.cpp.

void QgsMapCanvas::wheelEvent ( QWheelEvent *  e)
overrideprotected

Overridden mouse wheel event.

Definition at line 1595 of file qgsmapcanvas.cpp.

void QgsMapCanvas::writeProject ( QDomDocument &  doc)
slot

called to write map canvas settings to project

Definition at line 2107 of file qgsmapcanvas.cpp.

void QgsMapCanvas::xyCoordinates ( const QgsPointXY p)
signal

Emits current mouse position.

Note
changed in 1.3
void QgsMapCanvas::zoomByFactor ( double  scaleFactor,
const QgsPointXY center = nullptr 
)

Zoom with the factor supplied.

Factor > 1 zooms out, interval (0,1) zooms in If point is given, re-center on it

Definition at line 2164 of file qgsmapcanvas.cpp.

void QgsMapCanvas::zoomIn ( )
slot

Zoom in with fixed factor.

Definition at line 1643 of file qgsmapcanvas.cpp.

void QgsMapCanvas::zoomLastStatusChanged ( bool  )
signal

Emitted when zoom last status changed.

void QgsMapCanvas::zoomNextStatusChanged ( bool  )
signal

Emitted when zoom next status changed.

void QgsMapCanvas::zoomOut ( )
slot

Zoom out with fixed factor.

Definition at line 1649 of file qgsmapcanvas.cpp.

void QgsMapCanvas::zoomScale ( double  scale)

Zooms the canvas to a specific scale.

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

Definition at line 1655 of file qgsmapcanvas.cpp.

void QgsMapCanvas::zoomToFeatureExtent ( QgsRectangle rect)

Zooms to feature extent.

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

Definition at line 1037 of file qgsmapcanvas.cpp.

void QgsMapCanvas::zoomToFeatureIds ( QgsVectorLayer layer,
const QgsFeatureIds ids 
)

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

Parameters
layerthe vector layer
idsthe feature ids

Definition at line 1061 of file qgsmapcanvas.cpp.

void QgsMapCanvas::zoomToFullExtent ( )

Zoom to the full extent of all layers.

Definition at line 926 of file qgsmapcanvas.cpp.

void QgsMapCanvas::zoomToNextExtent ( )

Zoom to the next extent (view)

Definition at line 957 of file qgsmapcanvas.cpp.

void QgsMapCanvas::zoomToPreviousExtent ( )

Zoom to the previous extent (view)

Definition at line 941 of file qgsmapcanvas.cpp.

void QgsMapCanvas::zoomToSelected ( QgsVectorLayer layer = nullptr)
slot

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

Parameters
layeroptionally specify different than current layer

Definition at line 982 of file qgsmapcanvas.cpp.

void QgsMapCanvas::zoomWithCenter ( int  x,
int  y,
bool  zoomIn 
)

Zooms in/out with a given center.

Definition at line 1660 of file qgsmapcanvas.cpp.

Friends And Related Function Documentation

friend class TestQgsMapCanvas
friend

Definition at line 1053 of file qgsmapcanvas.h.

Member Data Documentation

std::unique_ptr<CanvasProperties> QgsMapCanvas::mCanvasProperties
protected

Handle pattern for implementation object.

Definition at line 883 of file qgsmapcanvas.h.

Property Documentation

bool QgsMapCanvas::previewJobsEnabled
readwrite

Definition at line 88 of file qgsmapcanvas.h.

QString QgsMapCanvas::theme
readwrite

Definition at line 87 of file qgsmapcanvas.h.


The documentation for this class was generated from the following files: