QGIS API Documentation  3.21.0-Master (56b4176581)
qgslayoutitemmap.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgslayoutitemmap.h
3  -------------------
4  begin : July 2017
5  copyright : (C) 2017 by Nyall Dawson
6  email : nyall dot dawson at gmail dot com
7  ***************************************************************************/
8 /***************************************************************************
9  * *
10  * This program is free software; you can redistribute it and/or modify *
11  * it under the terms of the GNU General Public License as published by *
12  * the Free Software Foundation; either version 2 of the License, or *
13  * (at your option) any later version. *
14  * *
15  ***************************************************************************/
16 
17 #ifndef QGSLAYOUTITEMMAP_H
18 #define QGSLAYOUTITEMMAP_H
19 
20 #include "qgis_core.h"
21 #include "qgslayoutitem.h"
22 #include "qgslayoutitemregistry.h"
23 #include "qgsmaplayerref.h"
25 #include "qgslayoutitemmapgrid.h"
28 #include "qgstemporalrangeobject.h"
29 
30 class QgsAnnotation;
32 
39 class CORE_EXPORT QgsLayoutItemMapAtlasClippingSettings : public QObject
40 {
41  Q_OBJECT
42 
43  public:
44 
49 
55  bool enabled() const;
56 
62  void setEnabled( bool enabled );
63 
69  QgsMapClippingRegion::FeatureClippingType featureClippingType() const;
70 
76  void setFeatureClippingType( QgsMapClippingRegion::FeatureClippingType type );
77 
83  bool forceLabelsInsideFeature() const;
84 
90  void setForceLabelsInsideFeature( bool forceInside );
91 
98  bool restrictToLayers() const;
99 
106  void setRestrictToLayers( bool enabled );
107 
116  QList< QgsMapLayer * > layersToClip() const;
117 
126  void setLayersToClip( const QList< QgsMapLayer * > &layers );
127 
133  bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
134 
140  bool readXml( const QDomElement &element, const QDomDocument &doc, const QgsReadWriteContext &context );
141 
142  signals:
143 
147  void changed();
148 
149  private slots:
150  void layersAboutToBeRemoved( const QList<QgsMapLayer *> &layers );
151 
152  private:
153 
154  QgsLayoutItemMap *mMap = nullptr;
155  bool mClipToAtlasFeature = false;
156  bool mRestrictToLayers = false;
157  QList< QgsMapLayerRef > mLayersToClip;
159  bool mForceLabelsInsideFeature = false;
160 };
161 
162 
169 class CORE_EXPORT QgsLayoutItemMapItemClipPathSettings : public QObject
170 {
171  Q_OBJECT
172 
173  public:
174 
179 
186  bool isActive() const;
187 
193  bool enabled() const;
194 
200  void setEnabled( bool enabled );
201 
207  QgsGeometry clippedMapExtent() const;
208 
218  QgsGeometry clipPathInMapItemCoordinates() const;
219 
223  QgsMapClippingRegion toMapClippingRegion() const;
224 
232  void setSourceItem( QgsLayoutItem *item );
233 
240  QgsLayoutItem *sourceItem();
241 
247  QgsMapClippingRegion::FeatureClippingType featureClippingType() const;
248 
254  void setFeatureClippingType( QgsMapClippingRegion::FeatureClippingType type );
255 
261  bool forceLabelsInsideClipPath() const;
262 
268  void setForceLabelsInsideClipPath( bool forceInside );
269 
275  bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
276 
283  bool readXml( const QDomElement &element, const QDomDocument &doc, const QgsReadWriteContext &context );
284 
289  void finalizeRestoreFromXml();
290 
291  signals:
292 
296  void changed();
297 
298  private:
299 
300  QgsLayoutItemMap *mMap = nullptr;
301  bool mEnabled = false;
303  bool mForceLabelsInsideClipPath = false;
304 
305  QPointer< QgsLayoutItem > mClipPathSource;
306  QString mClipPathUuid;
307 
308 };
309 
310 
317 class CORE_EXPORT QgsLayoutItemMap : public QgsLayoutItem, public QgsTemporalRangeObject
318 {
319 
320  Q_OBJECT
321 
322  public:
323 
328  {
330 
338 
344  Auto
345  };
346 
352  {
353  ShowPartialLabels = 1 << 0,
354  ShowUnplacedLabels = 1 << 1,
355  };
356  Q_DECLARE_FLAGS( MapItemFlags, MapItemFlag )
357 
358 
361  explicit QgsLayoutItemMap( QgsLayout *layout );
362  ~QgsLayoutItemMap() override;
363 
364  int type() const override;
365  QIcon icon() const override;
366  QgsLayoutItem::Flags itemFlags() const override;
367 
373  QgsLayoutItemMap::MapItemFlags mapFlags() const;
374 
380  void setMapFlags( QgsLayoutItemMap::MapItemFlags flags );
381 
385  void assignFreeId();
386 
387  //overridden to show "Map 1" type names
388  QString displayName() const override;
389 
395  static QgsLayoutItemMap *create( QgsLayout *layout ) SIP_FACTORY;
396 
397  // for now, map items behave a bit differently and don't implement draw. TODO - see if we can avoid this
398  void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget ) override;
399  Q_DECL_DEPRECATED int numberExportLayers() const override SIP_DEPRECATED;
400  void startLayeredExport() override;
401  void stopLayeredExport() override;
402  bool nextExportPart() override;
403  ExportLayerBehavior exportLayerBehavior() const override;
404  QgsLayoutItem::ExportLayerDetail exportLayerDetails() const override;
405  void setFrameStrokeWidth( QgsLayoutMeasurement width ) override;
406 
412  double scale() const;
413 
421  void setScale( double scale, bool forceUpdate = true );
422 
430  void setExtent( const QgsRectangle &extent );
431 
439  void zoomToExtent( const QgsRectangle &extent );
440 
446  QgsRectangle extent() const;
447 
448 
456  QPolygonF visibleExtentPolygon() const;
457 
467 
476  QgsCoordinateReferenceSystem presetCrs() const { return mCrs; }
477 
485  void setCrs( const QgsCoordinateReferenceSystem &crs );
486 
495  bool keepLayerSet() const { return mKeepLayerSet; }
496 
505  void setKeepLayerSet( bool enabled ) { mKeepLayerSet = enabled; }
506 
513  QList<QgsMapLayer *> layers() const;
514 
524  void setLayers( const QList<QgsMapLayer *> &layers );
525 
530  bool keepLayerStyles() const { return mKeepLayerStyles; }
531 
536  void setKeepLayerStyles( bool enabled ) { mKeepLayerStyles = enabled; }
537 
542  QMap<QString, QString> layerStyleOverrides() const { return mLayerStyleOverrides; }
543 
548  void setLayerStyleOverrides( const QMap<QString, QString> &overrides );
549 
553  void storeCurrentLayerStyles();
554 
565  bool followVisibilityPreset() const { return mFollowVisibilityPreset; }
566 
570  void setFollowVisibilityPreset( bool follow );
571 
579  QString followVisibilityPresetName() const { return mFollowVisibilityPresetName; }
580 
587  void setFollowVisibilityPresetName( const QString &name );
588 
589  void moveContent( double dx, double dy ) override;
590  void setMoveContentPreviewOffset( double dx, double dy ) override;
591 
592  void zoomContent( double factor, QPointF point ) override;
593 
594 
596  bool containsWmsLayer() const;
597 
598  bool requiresRasterization() const override;
599  bool containsAdvancedEffects() const override;
600 
607  void setMapRotation( double rotation );
608 
617  double mapRotation( QgsLayoutObject::PropertyValueType valueType = QgsLayoutObject::EvaluatedValue ) const;
618 
623  void setDrawAnnotations( bool draw ) { mDrawAnnotations = draw; }
624 
629  bool drawAnnotations() const { return mDrawAnnotations; }
630 
631 
638  bool atlasDriven() const { return mAtlasDriven; }
639 
646  void setAtlasDriven( bool enabled );
647 
657  AtlasScalingMode atlasScalingMode() const { return mAtlasScalingMode; }
658 
668  void setAtlasScalingMode( AtlasScalingMode mode ) { mAtlasScalingMode = mode; }
669 
681 
689  void setAtlasMargin( double margin ) { mAtlasMargin = margin; }
690 
696  QgsLayoutItemMapGridStack *grids() { return mGridStack.get(); }
697 
702  QgsLayoutItemMapGrid *grid();
703 
710  QgsLayoutItemMapOverviewStack *overviews() { return mOverviewStack.get(); }
711 
717  QgsLayoutItemMapOverview *overview();
718 
729  QgsLayoutMeasurement labelMargin() const;
730 
741  void setLabelMargin( const QgsLayoutMeasurement &margin );
742 
743  QgsExpressionContext createExpressionContext() const override;
744 
750  double mapUnitsToLayoutUnits() const;
751 
759  QgsMapSettings mapSettings( const QgsRectangle &extent, QSizeF size, double dpi, bool includeLayerSettings ) const;
760 
761  void finalizeRestoreFromXml() override;
762 
767  QList<QgsMapLayer *> layersToRender( const QgsExpressionContext *context = nullptr ) const;
768 
780  void addLabelBlockingItem( QgsLayoutItem *item );
781 
793  void removeLabelBlockingItem( QgsLayoutItem *item );
794 
806  bool isLabelBlockingItem( QgsLayoutItem *item ) const;
807 
812  QgsMapRendererJob::Errors renderingErrors() const { return mRenderingErrors; }
813 
821  QgsLabelingResults *previewLabelingResults() const;
822 
823  bool accept( QgsStyleEntityVisitorInterface *visitor ) const override;
824 
837  void addRenderedFeatureHandler( QgsRenderedFeatureHandlerInterface *handler );
838 
845  void removeRenderedFeatureHandler( QgsRenderedFeatureHandlerInterface *handler );
846 
850  QTransform layoutToMapCoordsTransform() const;
851 
857  QgsLayoutItemMapAtlasClippingSettings *atlasClippingSettings() { return mAtlasClippingSettings; }
858 
864  QgsLayoutItemMapItemClipPathSettings *itemClippingSettings() { return mItemClippingSettings; }
865 
866  protected:
867 
868  void draw( QgsLayoutItemRenderContext &context ) override;
869  bool writePropertiesToElement( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const override;
870  bool readPropertiesFromElement( const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context ) override;
871  QPainterPath framePath() const override;
872 
874  bool isDrawing() const {return mDrawing;}
875 
876  // In case of annotations, the bounding rectangle can be larger than the map item rectangle
877  QRectF boundingRect() const override;
878 
880  QPolygonF transformedMapPolygon() const;
881 
883  QPointF mapToItemCoords( QPointF mapCoords ) const;
884 
888  QgsRectangle requestedExtent() const;
889 
890  signals:
891 
898 
904  void mapRotationChanged( double newRotation );
905 
908 
914 
923  void themeChanged( const QString &theme );
924 
930  void crsChanged();
931 
938 
939  public slots:
940 
941  void refresh() override;
942 
943  void invalidateCache() override;
944 
946  void updateBoundingRect();
947 
948  void refreshDataDefinedProperty( QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties ) override;
949 
950  private slots:
951  void layersAboutToBeRemoved( const QList<QgsMapLayer *> &layers );
952 
953  void painterJobFinished();
954 
955  void shapeChanged();
956 
957  void mapThemeChanged( const QString &theme );
958 
960  void currentMapThemeRenamed( const QString &theme, const QString &newTheme );
961 
963  void recreateCachedImageInBackground();
964 
965  void updateAtlasFeature();
966  private:
967 
968  QgsLayoutItemMap::MapItemFlags mMapFlags = QgsLayoutItemMap::MapItemFlags();
969 
971  int mMapId = 1;
972 
973  std::unique_ptr< QgsLayoutItemMapGridStack > mGridStack;
974  std::unique_ptr< QgsLayoutItemMapOverviewStack > mOverviewStack;
975 
976  // Map region in map units really used for rendering
977  // It can be the same as mUserExtent, but it can be bigger in on dimension if mCalculate==Scale,
978  // so that full rectangle in paper is used.
979  QgsRectangle mExtent;
980 
983 
984  // Current temporary map region in map units. This is overwritten when atlas feature changes. It's also
985  // used when the user changes the map extent and an atlas preview is enabled. This allows the user
986  // to manually tweak each atlas preview page without affecting the actual original map extent.
987  QgsRectangle mAtlasFeatureExtent;
988 
989  // We have two images used for rendering/storing cached map images.
990  // the first (mCacheFinalImage) is used ONLY for storing the most recent completed map render. It's always
991  // used when drawing map item previews. The second (mCacheRenderingImage) is used temporarily while
992  // rendering a new preview image in the background. If (and only if) the background render completes, then
993  // mCacheRenderingImage is pushed into mCacheFinalImage, and used from then on when drawing the item preview.
994  // This ensures that something is always shown in the map item, even while refreshing the preview image in the
995  // background
996  std::unique_ptr< QImage > mCacheFinalImage;
997  std::unique_ptr< QImage > mCacheRenderingImage;
998  bool mUpdatesEnabled = true;
999 
1001  bool mCacheInvalidated = true;
1002 
1004  int mNumCachedLayers;
1005 
1006  // Set to true if in state of drawing. Concurrent requests to draw method are returned if set to true
1007  bool mDrawing = false;
1008 
1009  QTimer *mBackgroundUpdateTimer = nullptr;
1010  double mPreviewScaleFactor = 0;
1011 
1012  bool mDrawingPreview = false;
1013 
1015  double mXOffset = 0.0;
1017  double mYOffset = 0.0;
1018 
1019  double mLastRenderedImageOffsetX = 0.0;
1020  double mLastRenderedImageOffsetY = 0.0;
1021 
1023  double mMapRotation = 0;
1024 
1029  double mEvaluatedMapRotation = 0;
1030 
1032  bool mKeepLayerSet = false;
1033 
1035  QList< QgsMapLayerRef > mLayers;
1036 
1037  bool mKeepLayerStyles = false;
1039  QMap<QString, QString> mLayerStyleOverrides;
1040 
1042  mutable QString mCachedLayerStyleOverridesPresetName;
1044  mutable QMap<QString, QString> mCachedPresetLayerStyleOverrides;
1045 
1051  bool mFollowVisibilityPreset = false;
1052 
1057  QString mFollowVisibilityPresetName;
1058 
1060  QString mLastEvaluatedThemeName;
1061 
1069  void drawMap( QPainter *painter, const QgsRectangle &extent, QSizeF size, double dpi );
1070 
1072  void connectUpdateSlot();
1073 
1075  void syncLayerSet();
1076 
1078  const QgsLayoutItemMapGrid *constFirstMapGrid() const;
1079 
1081  const QgsLayoutItemMapOverview *constFirstMapOverview() const;
1082 
1087  QList< QgsLabelBlockingRegion > createLabelBlockingRegions( const QgsMapSettings &mapSettings ) const;
1088 
1090  QRectF mCurrentRectangle;
1092  bool mDrawAnnotations = true;
1093 
1095  bool mAtlasDriven = false;
1097  AtlasScalingMode mAtlasScalingMode = Auto;
1099  double mAtlasMargin = 0.10;
1100 
1101  std::unique_ptr< QPainter > mPainter;
1102  std::unique_ptr< QgsMapRendererCustomPainterJob > mPainterJob;
1103  bool mPainterCancelWait = false;
1104 
1105  QgsLayoutMeasurement mLabelMargin{ 0 };
1106  QgsLayoutMeasurement mEvaluatedLabelMargin{ 0 };
1107 
1108  QStringList mBlockingLabelItemUuids;
1109  QList< QPointer< QgsLayoutItem > > mBlockingLabelItems;
1110 
1112  QgsMapRendererJob::Errors mRenderingErrors;
1113 
1114  QList< QgsRenderedFeatureHandlerInterface * > mRenderedFeatureHandlers;
1115 
1116  std::unique_ptr< QgsMapRendererStagedRenderJob > mStagedRendererJob;
1117 
1118  std::unique_ptr< QgsLabelingResults > mPreviewLabelingResults;
1119  std::unique_ptr< QgsLabelingResults > mExportLabelingResults;
1120 
1121  void init();
1122 
1124  void updateToolTip();
1125 
1126  QString themeToRender( const QgsExpressionContext &context ) const;
1127 
1129  QMap<QString, QString> layerStyleOverridesToRender( const QgsExpressionContext &context ) const;
1130 
1132  QgsRectangle transformedExtent() const;
1133 
1135  void mapPolygon( const QgsRectangle &extent, QPolygonF &poly ) const;
1136 
1142  void transformShift( double &xShift, double &yShift ) const;
1143 
1144  void drawAnnotations( QPainter *painter );
1145  void drawAnnotation( const QgsAnnotation *item, QgsRenderContext &context );
1146  QPointF layoutMapPosForItem( const QgsAnnotation *item ) const;
1147 
1148  void drawMapFrame( QPainter *p );
1149  void drawMapBackground( QPainter *p );
1150 
1151  enum PartType
1152  {
1153  Start,
1154  Background,
1155  Layer,
1156  Grid,
1157  OverviewMapExtent,
1158  Frame,
1159  SelectionBoxes,
1160  End,
1161  NotLayered,
1162  };
1163 
1165  bool shouldDrawPart( PartType part ) const;
1166 
1167  PartType mCurrentExportPart = NotLayered;
1168  QStringList mExportThemes;
1169  QStringList::iterator mExportThemeIt;
1170 
1171  QgsLayoutItemMapAtlasClippingSettings *mAtlasClippingSettings = nullptr;
1172  QgsLayoutItemMapItemClipPathSettings *mItemClippingSettings = nullptr;
1173 
1178  void refreshMapExtents( const QgsExpressionContext *context = nullptr );
1179 
1180  void refreshLabelMargin( bool updateItem );
1181 
1182  QgsRectangle computeAtlasRectangle();
1183 
1184  void createStagedRenderJob( const QgsRectangle &extent, const QSizeF size, double dpi );
1185 
1186  QPolygonF calculateVisibleExtentPolygon( bool includeClipping ) const;
1187 
1188  friend class QgsLayoutItemMapGrid;
1190  friend class QgsLayoutItemLegend;
1191  friend class TestQgsLayoutMap;
1193  friend class QgsGeoPdfRenderedFeatureHandler;
1194  friend class QgsLayoutExporter;
1195 
1196 };
1197 
1198 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLayoutItemMap::MapItemFlags )
1199 
1200 #endif //QGSLAYOUTITEMMAP_H
Abstract base class for annotation items which are drawn over a map.
Definition: qgsannotation.h:53
QgsCompositionConverter class converts a QGIS 2.x composition to a QGIS 3.x layout.
This class represents a coordinate reference system (CRS).
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:124
Class that stores computed placement from labeling engine.
Handles rendering and exports of layouts to various formats.
A layout item subclass for map legends.
Contains settings relating to clipping a layout map by the current atlas feature.
void changed()
Emitted when the atlas clipping settings are changed.
A collection of grids which is drawn above the map content in a QgsLayoutItemMap.
An individual grid which is drawn above the map content in a QgsLayoutItemMap.
Contains settings relating to clipping a layout map by another layout item.
void changed()
Emitted when the item clipping settings are changed.
A collection of overviews which are drawn above the map content in a QgsLayoutItemMap.
An individual overview which is drawn above the map content in a QgsLayoutItemMap,...
Layout graphical items for displaying a map.
void extentChanged()
Emitted when the map's extent changes.
void preparedForAtlas()
Emitted when the map has been prepared for atlas rendering, just before actual rendering.
QgsMapRendererJob::Errors renderingErrors() const
Returns map rendering errors.
bool keepLayerSet() const
Returns whether a stored layer set should be used or the current layer set from the project associate...
void setKeepLayerSet(bool enabled)
Sets whether the stored layer set should be used or the current layer set of the associated project.
AtlasScalingMode
Scaling modes used for the serial rendering (atlas)
@ Predefined
A scale is chosen from the predefined scales.
@ Fixed
The current scale of the map is used for each feature of the atlas.
void layerStyleOverridesChanged()
Emitted when layer style overrides are changed...
void mapRotationChanged(double newRotation)
Emitted when the map's rotation changes.
bool isDrawing() const
True if a draw is already in progress.
QString followVisibilityPresetName() const
Preset name that decides which layers and layer styles are used for map rendering.
void previewRefreshed()
Emitted whenever the item's map preview has been refreshed.
QMap< QString, QString > layerStyleOverrides() const
Returns stored overrides of styles for layers.
void setDrawAnnotations(bool draw)
Sets whether annotations are drawn within the map.
bool followVisibilityPreset() const
Returns whether the map should follow a map theme.
void crsChanged()
Emitted when the map's coordinate reference system is changed.
QgsLayoutItemMapItemClipPathSettings * itemClippingSettings()
Returns the map's item based clip path settings.
bool atlasDriven() const
Returns whether the map extent is set to follow the current atlas feature.
bool keepLayerStyles() const
Returns whether current styles of layers should be overridden by previously stored styles.
AtlasScalingMode atlasScalingMode() const
Returns the current atlas scaling mode.
void setAtlasScalingMode(AtlasScalingMode mode)
Sets the current atlas scaling mode.
QgsLayoutItemMapAtlasClippingSettings * atlasClippingSettings()
Returns the map's atlas clipping settings.
void themeChanged(const QString &theme)
Emitted when the map's associated theme is changed.
MapItemFlag
Various flags that affect drawing of map items.
bool drawAnnotations() const
Returns whether annotations are drawn within the map.
QgsLayoutItemMapOverviewStack * overviews()
Returns the map item's overview stack, which is used to control how overviews are drawn over the map'...
QgsLayoutItemMapGridStack * grids()
Returns the map item's grid stack, which is used to control how grids are drawn over the map's conten...
void setAtlasMargin(double margin)
Sets the margin size (percentage) used when the map is in atlas mode.
void setKeepLayerStyles(bool enabled)
Sets whether current styles of layers should be overridden by previously stored styles.
Contains settings and helpers relating to a render of a QgsLayoutItem.
Definition: qgslayoutitem.h:45
Base class for graphical items within a QgsLayout.
This class provides a method of storing measurements for use in QGIS layouts using a variety of diffe...
DataDefinedProperty
Data defined properties for different item types.
@ AllProperties
All properties for item.
PropertyValueType
Specifies whether the value returned by a function should be the original, user set value,...
@ EvaluatedValue
Return the current evaluated value for the property.
Base class for layouts, which can contain items such as maps, labels, scalebars, etc.
Definition: qgslayout.h:51
A map clipping region (in map coordinates and CRS).
FeatureClippingType
Feature clipping behavior, which controls how features from vector layers will be clipped.
@ ClipPainterOnly
Applying clipping on the painter only (i.e. feature boundaries will be unchanged, but may be invisibl...
QList< QgsMapRendererJob::Error > Errors
The QgsMapSettings class contains configuration for rendering of the map.
The class is used as a container of context for various read/write operations on other objects.
A rectangle specified with double values.
Definition: qgsrectangle.h:42
Contains information about the context of a rendering operation.
An interface for classes which provider custom handlers for features rendered as part of a map render...
An interface for classes which can visit style entity (e.g.
Base class for objects with an associated (optional) temporal range.
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
#define SIP_TRANSFERTHIS
Definition: qgis_sip.h:53
#define SIP_FACTORY
Definition: qgis_sip.h:76
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsField::ConfigurationFlags) CORE_EXPORT QDataStream &operator<<(QDataStream &out
Writes the field to stream out. QGIS version compatibility is not guaranteed.
const QgsCoordinateReferenceSystem & crs