QGIS API Documentation  3.15.0-Master (c0197371fe)
qgsmapcanvas.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgsmapcanvas.h - description
3  -------------------
4  begin : Sun Jun 30 2002
5  copyright : (C) 2002 by Gary E.Sherman
6  email : sherman at mrcc.com
7 ***************************************************************************/
8 
9 /***************************************************************************
10  * *
11  * This program is free software; you can redistribute it and/or modify *
12  * it under the terms of the GNU General Public License as published by *
13  * the Free Software Foundation; either version 2 of the License, or *
14  * (at your option) any later version. *
15  * *
16  ***************************************************************************/
17 
18 #ifndef QGSMAPCANVAS_H
19 #define QGSMAPCANVAS_H
20 
21 #include "qgsconfig.h"
22 #include "qgis_sip.h"
23 
24 #include "qgsexpressioncontext.h"
25 #include "qgsrectangle.h"
26 #include "qgsfeatureid.h"
27 #include "qgsgeometry.h"
28 #include "qgscustomdrophandler.h"
29 #include "qgstemporalrangeobject.h"
31 #include "qgsproject.h"
32 
33 #include <QDomDocument>
34 #include <QGraphicsView>
35 #include <QtCore>
36 
37 #include "qgsmapsettings.h" // TEMPORARY
38 #include "qgsprevieweffect.h" //for QgsPreviewEffect::PreviewMode
39 
40 #include <QGestureEvent>
41 #include "qgis_gui.h"
42 
43 class QWheelEvent;
44 class QPixmap;
45 class QPaintEvent;
46 class QKeyEvent;
47 class ResizeEvent;
48 
49 class QColor;
50 class QDomDocument;
51 class QPaintDevice;
52 class QMouseEvent;
53 class QRubberBand;
54 class QGraphicsScene;
55 
56 class QgsMapToPixel;
57 class QgsMapLayer;
58 class QgsHighlight;
59 class QgsVectorLayer;
60 
61 class QgsLabelingResults;
64 class QgsMapSettings;
65 class QgsMapCanvasMap;
67 class QgsMapTool;
68 class QgsSnappingUtils;
69 class QgsRubberBand;
72 
74 
75 class QMenu;
76 class QgsMapMouseEvent;
77 
78 
84 class GUI_EXPORT QgsMapCanvas : public QGraphicsView
85 {
86 
87 #ifdef SIP_RUN
89  if ( qobject_cast<QgsMapCanvas *>( sipCpp ) != nullptr )
90  sipType = sipType_QgsMapCanvas;
91  else
92  sipType = nullptr;
93  SIP_END
94 #endif
95 
96  Q_OBJECT
97  Q_PROPERTY( QString theme READ theme WRITE setTheme NOTIFY themeChanged )
98  Q_PROPERTY( bool previewJobsEnabled READ previewJobsEnabled WRITE setPreviewJobsEnabled )
99 
100  public:
101 
103  QgsMapCanvas( QWidget *parent SIP_TRANSFERTHIS = nullptr );
104 
105  ~QgsMapCanvas() override;
106 
111  double magnificationFactor() const;
112 
124  void setLayers( const QList<QgsMapLayer *> &layers );
125 
126  void setCurrentLayer( QgsMapLayer *layer );
127 
132  const QgsMapSettings &mapSettings() const SIP_KEEPREFERENCE;
133 
140  void setTemporalController( QgsTemporalController *controller );
141 
148  const QgsTemporalController *temporalController() const;
149 
154  void setDestinationCrs( const QgsCoordinateReferenceSystem &crs );
155 
160  void setMapSettingsFlags( QgsMapSettings::Flags flags );
161 
166  const QgsLabelingResults *labelingResults() const;
167 
172  void setCachingEnabled( bool enabled );
173 
178  bool isCachingEnabled() const;
179 
184  void clearCache();
185 
195  void waitWhileRendering();
196 
201  void setParallelRenderingEnabled( bool enabled );
202 
207  bool isParallelRenderingEnabled() const;
208 
213  void setMapUpdateInterval( int timeMilliseconds );
214 
219  int mapUpdateInterval() const;
220 
225  double scale() const;
226 
228  double mapUnitsPerPixel() const;
229 
231  QgsRectangle extent() const;
233  QgsRectangle fullExtent() const;
234 
246  void setExtent( const QgsRectangle &r, bool magnified = false );
247 
256  bool setReferencedExtent( const QgsReferencedRectangle &extent ) SIP_THROW( QgsCsException );
257 
262  double rotation() const;
263 
268  void setRotation( double degrees );
269 
274  void setCenter( const QgsPointXY &center );
275 
280  QgsPointXY center() const;
281 
283  void zoomToFullExtent();
284 
286  void zoomToPreviousExtent();
287 
289  void zoomToNextExtent();
290 
291  // ! Clears the list of extents and sets current extent as first item
292  void clearExtentHistory();
293 
294 
299  void zoomToFeatureIds( QgsVectorLayer *layer, const QgsFeatureIds &ids );
300 
307  void panToFeatureIds( QgsVectorLayer *layer, const QgsFeatureIds &ids, bool alwaysRecenter = true );
308 
310  void panToSelected( QgsVectorLayer *layer = nullptr );
311 
324  void flashFeatureIds( QgsVectorLayer *layer, const QgsFeatureIds &ids,
325  const QColor &startColor = QColor( 255, 0, 0, 255 ), const QColor &endColor = QColor( 255, 0, 0, 0 ),
326  int flashes = 3, int duration = 500 );
327 
340  void flashGeometries( const QList< QgsGeometry > &geometries, const QgsCoordinateReferenceSystem &crs = QgsCoordinateReferenceSystem(),
341  const QColor &startColor = QColor( 255, 0, 0, 255 ), const QColor &endColor = QColor( 255, 0, 0, 0 ),
342  int flashes = 3, int duration = 500 );
343 
345  void setMapTool( QgsMapTool *mapTool, bool clean = false );
346 
354  void unsetMapTool( QgsMapTool *mapTool );
355 
357  QgsMapTool *mapTool();
358 
364  void setProject( QgsProject *project );
365 
372  QgsProject *project();
373 
375  void setCanvasColor( const QColor &_newVal );
377  QColor canvasColor() const;
378 
383  void setSelectionColor( const QColor &color );
384 
389  QColor selectionColor() const;
390 
392  void updateScale();
393 
395  QgsMapLayer *layer( int index );
396 
398  int layerCount() const;
399 
404  QList<QgsMapLayer *> layers() const;
405 
415  void freeze( bool frozen = true );
416 
424  bool isFrozen() const;
425 
434  bool renderFlag() const { return mRenderFlag; }
435 
440  QgsUnitTypes::DistanceUnit mapUnits() const;
441 
447  QMap<QString, QString> layerStyleOverrides() const;
448 
460  void setLayerStyleOverrides( const QMap<QString, QString> &overrides );
461 
480  void setTheme( const QString &theme );
481 
487  QString theme() const { return mTheme; }
488 
490  const QgsMapToPixel *getCoordinateTransform();
491 
493  bool isDrawing();
494 
496  QgsMapLayer *currentLayer();
497 
499  void setWheelFactor( double factor );
500 
508  void zoomScale( double scale, bool ignoreScaleLock = false );
509 
517  void zoomByFactor( double scaleFactor, const QgsPointXY *center = nullptr, bool ignoreScaleLock = false );
518 
520  void zoomWithCenter( int x, int y, bool zoomIn );
521 
526  void zoomToFeatureExtent( QgsRectangle &rect );
527 
533  bool scaleLocked() const { return mScaleLocked;}
534 
536  void enableAntiAliasing( bool flag );
537 
539  bool antiAliasingEnabled() const { return mSettings.testFlag( QgsMapSettings::Antialiasing ); }
540 
542  void enableMapTileRendering( bool flag );
543 
544  // following 2 methods should be moved elsewhere or changed to private
545  // currently used by pan map tool
547  void panActionEnd( QPoint releasePoint );
548 
549 #ifndef SIP_RUN
550 
556  void panActionStart( QPoint releasePoint );
557 #endif
558 
560  void panAction( QMouseEvent *event );
561 
563  QPoint mouseLastXY();
564 
570  void setPreviewModeEnabled( bool previewEnabled );
571 
578  bool previewModeEnabled() const;
579 
588  void setPreviewMode( QgsPreviewEffect::PreviewMode mode );
589 
597  QgsPreviewEffect::PreviewMode previewMode() const;
598 
607  QgsSnappingUtils *snappingUtils() const;
608 
617  void setSnappingUtils( QgsSnappingUtils *utils );
618 
629  void setExpressionContextScope( const QgsExpressionContextScope &scope ) { mExpressionContextScope = scope; }
630 
639  QgsExpressionContextScope &expressionContextScope() { return mExpressionContextScope; }
640 
648  const QgsExpressionContextScope &expressionContextScope() const { return mExpressionContextScope; } SIP_SKIP
649 
656  QgsExpressionContextScope *defaultExpressionContextScope() SIP_FACTORY;
657 
661  void setSegmentationTolerance( double tolerance );
662 
666  void setSegmentationToleranceType( QgsAbstractGeometry::SegmentationToleranceType type );
667 
672  QList< QgsMapCanvasAnnotationItem *> annotationItems() const;
673 
679  bool annotationsVisible() const { return mAnnotationsVisible; }
680 
686  void setAnnotationsVisible( bool visible );
687 
692  void setLabelingEngineSettings( const QgsLabelingEngineSettings &settings );
693 
698  const QgsLabelingEngineSettings &labelingEngineSettings() const;
699 
708  bool previewJobsEnabled() const;
709 
718  void setPreviewJobsEnabled( bool enabled );
719 
725  void setCustomDropHandlers( const QVector<QPointer<QgsCustomDropHandler >> &handlers ) SIP_SKIP;
726 
737  void setTemporalRange( const QgsDateTimeRange &range );
738 
745  const QgsDateTimeRange &temporalRange() const;
746 
758  void installInteractionBlocker( QgsMapCanvasInteractionBlocker *blocker );
759 
767  void removeInteractionBlocker( QgsMapCanvasInteractionBlocker *blocker );
768 
774  bool allowInteraction( QgsMapCanvasInteractionBlocker::Interaction interaction ) const;
775 
776  public slots:
777 
779  void refresh();
780 
790  void refreshAllLayers();
791 
800  void redrawAllLayers();
801 
803  void selectionChangedSlot();
804 
806  void saveAsImage( const QString &fileName, QPixmap *QPixmap = nullptr, const QString & = "PNG" );
807 
809  void layerStateChange();
810 
818  void setRenderFlag( bool flag );
819 
824  void stopRendering();
825 
827  void readProject( const QDomDocument & );
828 
830  void writeProject( QDomDocument & );
831 
840  void setMagnificationFactor( double factor, const QgsPointXY *center = nullptr );
841 
847  void setScaleLocked( bool isLocked );
848 
850  void zoomIn();
851 
853  void zoomOut();
854 
859  void zoomToSelected( QgsVectorLayer *layer = nullptr );
860 
866  void setZoomResolutions( const QList<double> &resolutions ) { mZoomResolutions = resolutions; }
867 
873  const QList<double> &zoomResolutions() const { return mZoomResolutions; }
874 
875  private slots:
877  void mapToolDestroyed();
878 
880  void rendererJobFinished();
881 
883  void previewJobFinished();
884 
885  void mapUpdateTimeout();
886 
887  void refreshMap();
888 
889  void mapThemeChanged( const QString &theme );
891  void mapThemeRenamed( const QString &theme, const QString &newTheme );
892 
893  signals:
894 
898  void xyCoordinates( const QgsPointXY &p );
899 
901  void scaleChanged( double );
902 
904  void extentsChanged();
905 
910  void rotationChanged( double );
911 
916  void magnificationChanged( double );
917 
922  void canvasColorChanged();
923 
933  // TODO: deprecate when decorations are reimplemented as map canvas items
934 
939  void renderComplete( QPainter * );
940 
941  // ### QGIS 3: renamte to mapRefreshFinished()
943  void mapCanvasRefreshed();
944 
945  // ### QGIS 3: rename to mapRefreshStarted()
947  void renderStarting();
948 
950  void layersChanged();
951 
953  void keyPressed( QKeyEvent *e );
954 
956  void keyReleased( QKeyEvent *e );
957 
962  void mapToolSet( QgsMapTool *newTool, QgsMapTool *oldTool );
963 
964 
966  void selectionChanged( QgsVectorLayer *layer );
967 
969  void zoomLastStatusChanged( bool );
970 
972  void zoomNextStatusChanged( bool );
973 
978  void destinationCrsChanged();
979 
984  void transformContextChanged();
985 
990  void currentLayerChanged( QgsMapLayer *layer );
991 
996  void layerStyleOverridesChanged();
997 
1003  void themeChanged( const QString &theme );
1004 
1006  void messageEmitted( const QString &title, const QString &message, Qgis::MessageLevel = Qgis::Info );
1007 
1015  void renderErrorOccurred( const QString &error, QgsMapLayer *layer );
1016 
1027  void panDistanceBearingChanged( double distance, QgsUnitTypes::DistanceUnit unit, double bearing );
1028 
1033  void tapAndHoldGestureOccurred( const QgsPointXY &mapPoint, QTapAndHoldGesture *gesture );
1034 
1040  void temporalRangeChanged();
1041 
1042  protected:
1043 
1044  bool event( QEvent *e ) override;
1045  void keyPressEvent( QKeyEvent *e ) override;
1046  void keyReleaseEvent( QKeyEvent *e ) override;
1047  void mouseDoubleClickEvent( QMouseEvent *e ) override;
1048  void mouseMoveEvent( QMouseEvent *e ) override;
1049  void mousePressEvent( QMouseEvent *e ) override;
1050  void mouseReleaseEvent( QMouseEvent *e ) override;
1051  void wheelEvent( QWheelEvent *e ) override;
1052  void resizeEvent( QResizeEvent *e ) override;
1053  void paintEvent( QPaintEvent *e ) override;
1054  void dragEnterEvent( QDragEnterEvent *e ) override;
1055 
1057  void moveCanvasContents( bool reset = false );
1058 
1059  void dropEvent( QDropEvent *event ) override;
1060 
1061 
1064 
1066  std::unique_ptr<CanvasProperties> mCanvasProperties;
1067 
1068 #if 0
1069 
1074  void connectNotify( const char *signal ) override;
1075 #endif
1076 
1077  protected slots:
1079  void updateCanvasItemPositions();
1080 
1081  private slots:
1082 
1083  void layerRepaintRequested( bool deferred );
1084 
1085  void autoRefreshTriggered();
1086 
1087  void updateAutoRefreshTimer();
1088 
1089  void projectThemesChanged();
1090 
1091  void startPreviewJob( int number );
1092 
1093  private:
1094 
1096  QgsMapSettings mSettings;
1097 
1099  QgsMapCanvasMap *mMap = nullptr;
1100 
1105  QgsTemporalController *mController = nullptr;
1106 
1108  bool mFrozen = false;
1109 
1111  bool mRefreshScheduled = false;
1112 
1114  bool mRefreshAfterJob = false;
1115 
1117  bool mRenderFlag = true;
1118 
1120  QPointer< QgsMapLayer > mCurrentLayer;
1121 
1123  QGraphicsScene *mScene = nullptr;
1124 
1126  QgsMapTool *mMapTool = nullptr;
1127 
1129  QgsMapTool *mLastNonZoomMapTool = nullptr;
1130 
1132  QgsProject *mProject = nullptr;
1133 
1135  QMenu *mMenu = nullptr;
1136 
1138  QList <QgsRectangle> mLastExtent;
1139  int mLastExtentIndex = -1;
1140 
1142  double mWheelZoomFactor = 2.0;
1143 
1145  QTimer mMapUpdateTimer;
1146 
1148  QgsMapRendererQImageJob *mJob = nullptr;
1149 
1151  bool mJobCanceled = false;
1152 
1154  QgsLabelingResults *mLabelingResults = nullptr;
1155 
1157  bool mUseParallelRendering = false;
1158 
1160  bool mDrawRenderingStats = false;
1161 
1163  QgsMapRendererCache *mCache = nullptr;
1164 
1165  QTimer *mResizeTimer = nullptr;
1166  QTimer *mRefreshTimer = nullptr;
1167 
1168  QgsPreviewEffect *mPreviewEffect = nullptr;
1169 
1170  QgsRectangle imageRect( const QImage &img, const QgsMapSettings &mapSettings );
1171 
1172  QgsSnappingUtils *mSnappingUtils = nullptr;
1173 
1174  QList< QgsMapRendererQImageJob * > mPreviewJobs;
1175 
1177  bool mScaleLocked = false;
1178 
1179  QgsExpressionContextScope mExpressionContextScope;
1180 
1182  QRect mZoomRect;
1183 
1185  bool mZoomDragging = false;
1186 
1188  std::unique_ptr< QgsRubberBand > mZoomRubberBand;
1189 
1190  QCursor mZoomCursor;
1191 
1192  QTimer mAutoRefreshTimer;
1193 
1194  QTimer mPreviewTimer;
1195  QMetaObject::Connection mPreviewTimerConnection;
1196 
1197  QString mTheme;
1198 
1199  QgsPointXY mCursorPoint;
1200 
1201  bool mAnnotationsVisible = true;
1202 
1203  bool mUsePreviewJobs = false;
1204 
1205  QHash< QString, int > mLastLayerRenderTime;
1206 
1207  QVector<QPointer<QgsCustomDropHandler >> mDropHandlers;
1208 
1209  QgsDistanceArea mDa;
1210  QList<double> mZoomResolutions;
1211 
1212  QList< QgsMapCanvasInteractionBlocker * > mInteractionBlockers;
1213 
1218  QgsPointXY cursorPoint() const;
1219 
1224  void updateMapSize();
1225 
1231  void beginZoomRect( QPoint pos );
1232 
1238  void endZoomRect( QPoint pos );
1239 
1247  bool boundingBoxOfFeatureIds( const QgsFeatureIds &ids, QgsVectorLayer *layer, QgsRectangle &bbox, QString &errorMsg ) const;
1248 
1249  void setLayersPrivate( const QList<QgsMapLayer *> &layers );
1250 
1251  void startPreviewJobs();
1252  void stopPreviewJobs();
1253  void schedulePreviewJob( int number );
1254 
1258  bool panOperationInProgress();
1259 
1260  int nextZoomLevel( const QList<double> &resolutions, bool zoomIn = true ) const;
1261  double zoomInFactor() const;
1262  double zoomOutFactor() const;
1263 
1268  void clearTemporalCache();
1269 
1270  void showContextMenu( QgsMapMouseEvent *event );
1271 
1272  friend class TestQgsMapCanvas;
1273 
1274 }; // class QgsMapCanvas
1275 
1276 // clazy:excludeall=qstring-allocations
1277 
1278 #endif
A rectangle specified with double values.
Definition: qgsrectangle.h:41
Base class for all map layer types.
Definition: qgsmaplayer.h:81
std::unique_ptr< CanvasProperties > mCanvasProperties
Handle pattern for implementation object.
QSet< QgsFeatureId > QgsFeatureIds
Definition: qgsfeatureid.h:34
const QList< double > & zoomResolutions() const
Definition: qgsmapcanvas.h:873
Interaction
Available interactions to block.
#define SIP_TRANSFERTHIS
Definition: qgis_sip.h:53
A widget that displays an overview map.
bool annotationsVisible() const
Returns true if annotations are visible within the map canvas.
Definition: qgsmapcanvas.h:679
A class to represent a 2D point.
Definition: qgspointxy.h:43
A QgsMapMouseEvent is the result of a user interaction with the mouse on a QgsMapCanvas.
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:122
SegmentationToleranceType
Segmentation tolerance as maximum angle or maximum difference between approximation and circle...
const QgsCoordinateReferenceSystem & crs
MessageLevel
Level for messages This will be used both for message log and message bar in application.
Definition: qgis.h:88
Map canvas is a class for displaying all GIS data types on a canvas.
Definition: qgsmapcanvas.h:84
A graphics effect which can be applied to a widget to simulate various printing and color blindness m...
The QgsMapSettings class contains configuration for rendering of the map.
Deprecated to be deleted, stuff from here should be moved elsewhere.
Perform transforms between map coordinates and device coordinates.
Definition: qgsmaptopixel.h:37
#define SIP_SKIP
Definition: qgis_sip.h:126
A class for drawing transient features (e.g.
Definition: qgsrubberband.h:49
Enable anti-aliasing for map rendering.
A class for highlight features on the map.
Definition: qgshighlight.h:57
#define SIP_END
Definition: qgis_sip.h:189
Encapsulates a QGIS project, including sets of map layers and their styles, layouts, annotations, canvases, etc.
Definition: qgsproject.h:92
#define SIP_KEEPREFERENCE
Definition: qgis_sip.h:86
void setZoomResolutions(const QList< double > &resolutions)
Set a list of resolutions (map units per pixel) to which to "snap to" when zooming the map...
Definition: qgsmapcanvas.h:866
A QgsRectangle with associated coordinate reference system.
#define SIP_FACTORY
Definition: qgis_sip.h:76
Single scope for storing variables and functions for use within a QgsExpressionContext.
void setExpressionContextScope(const QgsExpressionContextScope &scope)
Sets an expression context scope for the map canvas.
Definition: qgsmapcanvas.h:629
A controller base class for temporal objects, contains a signal for notifying updates of the objects ...
DistanceUnit
Units of distance.
Definition: qgsunittypes.h:67
Abstract base class for all map tools.
Definition: qgsmaptool.h:63
A general purpose distance and area calculator, capable of performing ellipsoid based calculations...
QString theme() const
Returns the map&#39;s theme shown in the canvas, if set.
Definition: qgsmapcanvas.h:487
QgsExpressionContextScope & expressionContextScope()
Returns a reference to the expression context scope for the map canvas.
Definition: qgsmapcanvas.h:639
An interface for objects which block interactions with a QgsMapCanvas.
bool antiAliasingEnabled() const
true if antialiasing is enabled
Definition: qgsmapcanvas.h:539
bool scaleLocked() const
Returns whether the scale is locked, so zooming can be performed using magnication.
Definition: qgsmapcanvas.h:533
const QgsExpressionContextScope & expressionContextScope() const
Returns a const reference to the expression context scope for the map canvas.
Definition: qgsmapcanvas.h:648
Intermediate base class adding functionality that allows client to query the rendered image...
Stores global configuration for labeling engine.
This class represents a coordinate reference system (CRS).
This class has all the configuration of snapping and can return answers to snapping queries...
#define SIP_CONVERT_TO_SUBCLASS_CODE(code)
Definition: qgis_sip.h:172
#define SIP_THROW(name)
Definition: qgis_sip.h:184
Class that stores computed placement from labeling engine.
This class is responsible for keeping cache of rendered images resulting from a map rendering job...
Custom exception class for Coordinate Reference System related exceptions.
Definition: qgsexception.h:65
Represents a vector layer which manages a vector based data sets.
An interactive map canvas item which displays a QgsAnnotation.