QGIS API Documentation  3.4.15-Madeira (e83d02e274)
qgslayoutitemmapgrid.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgslayoutitemmapgrid.h
3  ----------------------
4  begin : October 2017
5  copyright : (C) 2017 by Marco Hugentobler, Nyall Dawson
6  email : marco dot hugentobler at sourcepole dot ch
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 QGSLAYOUTITEMMAPGRID_H
19 #define QGSLAYOUTITEMMAPGRID_H
20 
21 #include "qgis_core.h"
22 #include "qgis_sip.h"
23 #include "qgis.h"
24 #include "qgslayoutitemmapitem.h"
25 #include "qgssymbol.h"
26 #include <QPainter>
27 
30 class QgsLayoutItemMap;
31 class QDomDocument;
32 class QDomElement;
33 class QPainter;
34 class QgsRenderContext;
35 
46 {
47  public:
48 
53 
62  void addGrid( QgsLayoutItemMapGrid *grid SIP_TRANSFER );
63 
70  void removeGrid( const QString &gridId );
71 
78  void moveGridUp( const QString &gridId );
79 
86  void moveGridDown( const QString &gridId );
87 
91  QgsLayoutItemMapGrid *grid( const QString &gridId ) const;
92 
96  QgsLayoutItemMapGrid *grid( int index ) const;
97 
102  QgsLayoutItemMapGrid &operator[]( int index );
103 
107  QList< QgsLayoutItemMapGrid * > asList() const;
108 
109  bool readXml( const QDomElement &elem, const QDomDocument &doc, const QgsReadWriteContext &context ) override;
110 
116  double maxGridExtension() const;
117 
124  void calculateMaxGridExtension( double &top, double &right, double &bottom, double &left ) const;
125 };
126 
127 //
128 // QgsLayoutItemMapGrid
129 //
130 
139 class CORE_EXPORT QgsLayoutItemMapGrid : public QgsLayoutItemMapItem
140 {
141 
142  Q_OBJECT
143 
144  public:
145 
149  enum GridUnit
150  {
152  MM,
153  CM
154  };
155 
160  {
161  Solid = 0,
164  FrameAnnotationsOnly
165  };
166 
171  {
172  ShowAll = 0,
175  HideAll
176  };
177 
182  {
183  InsideMapFrame = 0,
185  };
186 
191  {
192  Horizontal = 0,
195  BoundaryDirection
196  };
197 
202  {
203  Decimal = 0,
211  CustomFormat
212  };
213 
218  {
222  Top
223  };
224 
229  {
230  NoFrame = 0,
235  LineBorder
236  };
237 
242  {
243  FrameLeft = 0x01,
244  FrameRight = 0x02,
245  FrameTop = 0x04,
246  FrameBottom = 0x08
247  };
248  Q_DECLARE_FLAGS( FrameSideFlags, FrameSideFlag )
249 
250 
254  {
255  Longitude = 0,
256  Latitude
257  };
258 
264  QgsLayoutItemMapGrid( const QString &name, QgsLayoutItemMap *map );
265 
266  void draw( QPainter *painter ) override;
267  bool writeXml( QDomElement &elem, QDomDocument &doc, const QgsReadWriteContext &context ) const override;
268  bool readXml( const QDomElement &itemElem, const QDomDocument &doc, const QgsReadWriteContext &context ) override;
269 
274  void setCrs( const QgsCoordinateReferenceSystem &crs );
275 
280  QgsCoordinateReferenceSystem crs() const { return mCRS; }
281 
286  void setBlendMode( const QPainter::CompositionMode mode ) { mBlendMode = mode; }
287 
292  QPainter::CompositionMode blendMode() const { return mBlendMode; }
293 
294  bool usesAdvancedEffects() const override;
295 
300  double maxExtension() const;
301 
308  void calculateMaxExtension( double &top, double &right, double &bottom, double &left ) const;
309 
310  //
311  // GRID UNITS
312  //
313 
319  void setUnits( GridUnit unit );
320 
326  GridUnit units() const { return mGridUnit; }
327 
334  void setIntervalX( double interval );
335 
342  double intervalX() const { return mGridIntervalX; }
343 
350  void setIntervalY( double interval );
351 
358  double intervalY() const { return mGridIntervalY; }
359 
366  void setOffsetX( double offset );
367 
374  double offsetX() const { return mGridOffsetX; }
375 
382  void setOffsetY( double offset );
383 
390  double offsetY() const { return mGridOffsetY; }
391 
392  //
393  // GRID APPEARANCE
394  //
395 
401  void setStyle( GridStyle style );
402 
408  GridStyle style() const { return mGridStyle; }
409 
415  void setCrossLength( const double length ) { mCrossLength = length; }
416 
422  double crossLength() const { return mCrossLength; }
423 
431  void setGridLineWidth( double width );
432 
440  void setGridLineColor( const QColor &color );
441 
450  void setLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
451 
460  const QgsLineSymbol *lineSymbol() const; SIP_SKIP
461 
469  QgsLineSymbol *lineSymbol();
470 
479  void setMarkerSymbol( QgsMarkerSymbol *symbol SIP_TRANSFER );
480 
489  const QgsMarkerSymbol *markerSymbol() const; SIP_SKIP
490 
498  QgsMarkerSymbol *markerSymbol();
499 
500  //
501  // ANNOTATIONS
502  //
503 
508  void setAnnotationEnabled( const bool enabled ) { mShowGridAnnotation = enabled; }
509 
514  bool annotationEnabled() const { return mShowGridAnnotation; }
515 
520  void setAnnotationFont( const QFont &font ) { mGridAnnotationFont = font; }
521 
526  QFont annotationFont() const { return mGridAnnotationFont; }
527 
532  void setAnnotationFontColor( const QColor &color ) { mGridAnnotationFontColor = color; }
533 
538  QColor annotationFontColor() const { return mGridAnnotationFontColor; }
539 
545  void setAnnotationPrecision( const int precision ) { mGridAnnotationPrecision = precision; }
546 
552  int annotationPrecision() const { return mGridAnnotationPrecision; }
553 
561  void setAnnotationDisplay( DisplayMode display, BorderSide border );
562 
571  DisplayMode annotationDisplay( BorderSide border ) const;
572 
578  void setAnnotationPosition( AnnotationPosition position, BorderSide side );
579 
585  AnnotationPosition annotationPosition( BorderSide side ) const;
586 
591  void setAnnotationFrameDistance( const double distance ) { mAnnotationFrameDistance = distance; }
592 
597  double annotationFrameDistance() const { return mAnnotationFrameDistance; }
598 
603  void setAnnotationDirection( AnnotationDirection direction, BorderSide side );
604 
609  void setAnnotationDirection( AnnotationDirection direction );
610 
616  AnnotationDirection annotationDirection( BorderSide border ) const;
617 
622  void setAnnotationFormat( const AnnotationFormat format ) { mGridAnnotationFormat = format; }
623 
628  AnnotationFormat annotationFormat() const { return mGridAnnotationFormat; }
629 
635  void setAnnotationExpression( const QString &expression ) { mGridAnnotationExpressionString = expression; mGridAnnotationExpression.reset(); }
636 
642  QString annotationExpression() const { return mGridAnnotationExpressionString; }
643 
644  //
645  // GRID FRAME
646  //
647 
652  void setFrameStyle( const FrameStyle style ) { mGridFrameStyle = style; }
653 
658  FrameStyle frameStyle() const { return mGridFrameStyle; }
659 
664  void setFrameDivisions( DisplayMode divisions, BorderSide side );
665 
670  DisplayMode frameDivisions( BorderSide side ) const;
671 
679  void setFrameSideFlags( QgsLayoutItemMapGrid::FrameSideFlags flags );
680 
689  void setFrameSideFlag( QgsLayoutItemMapGrid::FrameSideFlag flag, bool on = true );
690 
698  QgsLayoutItemMapGrid::FrameSideFlags frameSideFlags() const;
699 
709  bool testFrameSideFlag( FrameSideFlag flag ) const;
710 
717  void setFrameWidth( const double width ) { mGridFrameWidth = width; }
718 
725  double frameWidth() const { return mGridFrameWidth; }
726 
732  void setFramePenSize( const double width ) { mGridFramePenThickness = width; }
733 
739  double framePenSize() const { return mGridFramePenThickness; }
740 
748  void setFramePenColor( const QColor &color ) { mGridFramePenColor = color; }
749 
757  QColor framePenColor() const {return mGridFramePenColor;}
758 
765  void setFrameFillColor1( const QColor &color ) { mGridFrameFillColor1 = color; }
766 
773  QColor frameFillColor1() const { return mGridFrameFillColor1; }
774 
781  void setFrameFillColor2( const QColor &color ) { mGridFrameFillColor2 = color; }
782 
789  QColor frameFillColor2() const { return mGridFrameFillColor2; }
790 
792 
793  private:
794 
795  QgsLayoutItemMapGrid() = delete;
796 
797  struct GridExtension
798  {
799  GridExtension() = default;
800  double top = 0.0;
801  double right = 0.0;
802  double bottom = 0.0;
803  double left = 0.0;
804  };
805 
807  mutable bool mTransformDirty = true;
808 
812  double mGridIntervalX = 0.0;
814  double mGridIntervalY = 0.0;
816  double mGridOffsetX = 0.0;
818  double mGridOffsetY = 0.0;
820  QFont mGridAnnotationFont;
822  QColor mGridAnnotationFontColor = Qt::black;
824  int mGridAnnotationPrecision = 3;
826  bool mShowGridAnnotation = false;
827 
829  DisplayMode mLeftGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
831  DisplayMode mRightGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
833  DisplayMode mTopGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
835  DisplayMode mBottomGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
836 
838  AnnotationPosition mLeftGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
840  AnnotationPosition mRightGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
842  AnnotationPosition mTopGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
844  AnnotationPosition mBottomGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
845 
847  double mAnnotationFrameDistance = 1.0;
848 
850  AnnotationDirection mLeftGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
852  AnnotationDirection mRightGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
854  AnnotationDirection mTopGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
856  AnnotationDirection mBottomGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
857  AnnotationFormat mGridAnnotationFormat = QgsLayoutItemMapGrid::Decimal;
858 
859  QString mGridAnnotationExpressionString;
860  mutable std::unique_ptr< QgsExpression > mGridAnnotationExpression;
861 
862  FrameStyle mGridFrameStyle = QgsLayoutItemMapGrid::NoFrame;
863  FrameSideFlags mGridFrameSides;
864  double mGridFrameWidth = 2.0;
865  double mGridFramePenThickness = 0.3;
866  QColor mGridFramePenColor = QColor( 0, 0, 0 );
867  QColor mGridFrameFillColor1 = Qt::white;
868  QColor mGridFrameFillColor2 = Qt::black;
869  double mCrossLength = 3.0;
870 
872  DisplayMode mLeftFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
874  DisplayMode mRightFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
876  DisplayMode mTopFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
878  DisplayMode mBottomFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
879 
880  std::unique_ptr< QgsLineSymbol > mGridLineSymbol;
881  std::unique_ptr< QgsMarkerSymbol > mGridMarkerSymbol;
882 
884 
885  GridUnit mGridUnit = MapUnit;
886 
887  QPainter::CompositionMode mBlendMode = QPainter::CompositionMode_SourceOver;
888 
889  mutable QList< QPair< double, QPolygonF > > mTransformedXLines;
890  mutable QList< QPair< double, QPolygonF > > mTransformedYLines;
891  mutable QList< QgsPointXY > mTransformedIntersections;
892  QRectF mPrevPaintRect;
893  mutable QPolygonF mPrevMapPolygon;
894 
895  class QgsMapAnnotation
896  {
897  public:
898  double coordinate;
899  QPointF itemPosition;
901  };
902 
907  void drawGridFrame( QPainter *p, const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, GridExtension *extension = nullptr ) const;
908 
918  void drawCoordinateAnnotations( QPainter *p, const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, QgsExpressionContext &expressionContext, GridExtension *extension = nullptr ) const;
919 
924  void drawCoordinateAnnotation( QPainter *p, QPointF pos, const QString &annotationString, AnnotationCoordinate coordinateType, GridExtension *extension = nullptr ) const;
925 
933  void drawAnnotation( QPainter *p, QPointF pos, int rotation, const QString &annotationText ) const;
934 
935  QString gridAnnotationString( double value, AnnotationCoordinate coord, QgsExpressionContext &expressionContext ) const;
936 
940  int xGridLines( QList< QPair< double, QLineF > > &lines ) const;
941 
945  int yGridLines( QList< QPair< double, QLineF > > &lines ) const;
946 
947  int xGridLinesCrsTransform( const QgsRectangle &bbox, const QgsCoordinateTransform &t, QList< QPair< double, QPolygonF > > &lines ) const;
948 
949  int yGridLinesCrsTransform( const QgsRectangle &bbox, const QgsCoordinateTransform &t, QList< QPair< double, QPolygonF > > &lines ) const;
950 
951  void drawGridLine( const QLineF &line, QgsRenderContext &context ) const;
952 
953  void drawGridLine( const QPolygonF &line, QgsRenderContext &context ) const;
954 
955  void sortGridLinesOnBorders( const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, QMap< double, double > &leftFrameEntries,
956  QMap< double, double > &rightFrameEntries, QMap< double, double > &topFrameEntries, QMap< double, double > &bottomFrameEntries ) const;
957 
962  void drawGridFrameBorder( QPainter *p, const QMap< double, double > &borderPos, BorderSide border, double *extension = nullptr ) const;
963 
969  BorderSide borderForLineCoord( QPointF p, AnnotationCoordinate coordinateType ) const;
970 
972  int crsGridParams( QgsRectangle &crsRect, QgsCoordinateTransform &inverseTransform ) const;
973 
974  static QList<QPolygonF> trimLinesToMap( const QPolygonF &line, const QgsRectangle &rect );
975 
976  QPolygonF scalePolygon( const QPolygonF &polygon, double scale ) const;
977 
979  void drawGridCrsTransform( QgsRenderContext &context, double dotsPerMM, QList< QPair< double, QLineF > > &horizontalLines,
980  QList< QPair< double, QLineF > > &verticalLines, bool calculateLinesOnly = false ) const;
981 
982  void drawGridNoTransform( QgsRenderContext &context, double dotsPerMM, QList<QPair<double, QLineF> > &horizontalLines, QList<QPair<double, QLineF> > &verticalLines, bool calculateLinesOnly = false ) const;
983 
984  void createDefaultGridLineSymbol();
985 
986  void createDefaultGridMarkerSymbol();
987 
988  void drawGridMarker( QPointF point, QgsRenderContext &context ) const;
989 
990  void drawGridFrameZebraBorder( QPainter *p, const QMap<double, double> &borderPos, BorderSide border, double *extension = nullptr ) const;
991 
992  void drawGridFrameTicks( QPainter *p, const QMap<double, double> &borderPos, BorderSide border, double *extension = nullptr ) const;
993 
994  void drawGridFrameLineBorder( QPainter *p, BorderSide border, double *extension = nullptr ) const;
995 
996  void calculateCrsTransformLines() const;
997 
998  bool shouldShowDivisionForSide( AnnotationCoordinate coordinate, BorderSide side ) const;
999  bool shouldShowDivisionForDisplayMode( AnnotationCoordinate coordinate, DisplayMode mode ) const;
1000 
1001  friend class TestQgsLayoutMapGrid;
1002 
1003 };
1004 
1005 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLayoutItemMapGrid::FrameSideFlags )
1006 
1007 #endif // QGSLAYOUTITEMMAPGRID_H
double offsetX() const
Returns the offset for grid lines in the x-direction.
void setAnnotationExpression(const QString &expression)
Sets the expression used for drawing grid annotations.
void setFramePenSize(const double width)
Sets the width of the stroke drawn in the grid frame.
The class is used as a container of context for various read/write operations on other objects...
int precision
A rectangle specified with double values.
Definition: qgsrectangle.h:40
QgsExpressionContext createExpressionContext() const override
Creates an expression context relating to the objects&#39; current state.
Degree/minutes/seconds, use NSEW suffix.
QString annotationExpression() const
Returns the expression used for drawing grid annotations.
void setAnnotationFontColor(const QColor &color)
Sets the font color used for drawing grid annotations.
QgsCoordinateReferenceSystem crs() const
Retrieves the CRS for the grid.
void setFrameFillColor1(const QColor &color)
Sets the first fill color used for the grid frame.
int annotationPrecision() const
Returns the coordinate precision for grid annotations, which is the number of decimal places shown wh...
FrameSideFlag
Flags for controlling which side of the map a frame is drawn on.
double frameWidth() const
Gets the grid frame width in layout units.
An item which is drawn inside a QgsLayoutItemMap, e.g., a grid or map overview.
Draw annotations vertically, ascending.
QColor frameFillColor2() const
Retrieves the second fill color for the grid frame.
A collection of map items which are drawn above the map content in a QgsLayoutItemMap.
FrameStyle
Style for grid frame.
DisplayMode
Display settings for grid annotations and frames.
QColor frameFillColor1() const
Retrieves the first fill color for the grid frame.
void setBlendMode(const QPainter::CompositionMode mode)
Sets the blending mode used for drawing the grid.
double framePenSize() const
Retrieves the width of the stroke drawn in the grid frame.
Grid units in millimeters.
Degree/minutes, use - for S/W coordinates.
const QgsCoordinateReferenceSystem & crs
Degree/minutes, use NSEW suffix.
QList< QgsLayoutItemMapItem * > asList() const
Returns a list of QgsLayoutItemMapItems contained by the stack.
virtual bool usesAdvancedEffects() const
Returns true if the item is drawn using advanced effects, such as blend modes.
A marker symbol type, for rendering Point and MultiPoint geometries.
Definition: qgssymbol.h:732
A line symbol type, for rendering LineString and MultiLineString geometries.
Definition: qgssymbol.h:920
QFont annotationFont() const
Returns the font used for drawing grid annotations.
void setFrameWidth(const double width)
Sets the grid frame width (in layout units).
void setAnnotationFont(const QFont &font)
Sets the font used for drawing grid annotations.
QPainter::CompositionMode blendMode() const
Retrieves the blending mode used for drawing the grid.
Draw line crosses at intersections of grid lines.
QColor annotationFontColor() const
Returns the font color used for drawing grid annotations.
virtual bool writeXml(QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context) const
Stores map item state in a DOM element, where element is the DOM element corresponding to a &#39;LayoutMa...
Tick markers drawn inside map frame.
Layout graphical items for displaying a map.
A collection of grids which is drawn above the map content in a QgsLayoutItemMap. ...
Draw annotations horizontally.
#define SIP_SKIP
Definition: qgis_sip.h:119
void setFrameFillColor2(const QColor &color)
Sets the second fill color used for the grid frame.
virtual bool readXml(const QDomElement &element, const QDomDocument &doc, const QgsReadWriteContext &context)=0
Sets the item stack&#39;s state from a DOM document, where element is a DOM node corresponding to a &#39;Layo...
Decimal degrees, use - for S/W coordinates.
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
void setFramePenColor(const QColor &color)
Sets the color of the stroke drawn in the grid frame.
Decimal degrees, use NSEW suffix.
#define SIP_TRANSFER
Definition: qgis_sip.h:36
Show latitude/y annotations/divisions only.
void setAnnotationEnabled(const bool enabled)
Sets whether annotations should be shown for the grid.
GridUnit units() const
Returns the units used for grid measurements such as the interval and offset for grid lines...
void setFrameStyle(const FrameStyle style)
Sets the grid frame style.
virtual void draw(QPainter *painter)=0
Draws the item on to a destination painter.
AnnotationFormat
Format for displaying grid annotations.
double crossLength() const
Retrieves the length (in layout units) of the cross segments drawn for the grid.
QgsLayoutItemMapItem & operator[](int index)
Returns a reference to an item at the specified index within the stack.
double intervalX() const
Returns the interval between grid lines in the x-direction.
An individual grid which is drawn above the map content in a QgsLayoutItemMap.
AnnotationDirection
Direction of grid annotations.
GridUnit
Unit for grid values.
Show both latitude and longitude annotations/divisions.
AnnotationPosition
Position for grid annotations.
virtual bool readXml(const QDomElement &element, const QDomDocument &doc, const QgsReadWriteContext &context)
Sets the map item state from a DOM document, where element is the DOM node corresponding to a &#39;Layout...
AnnotationCoordinate
Annotation coordinate type.
void setAnnotationPrecision(const int precision)
Sets the coordinate precision for grid annotations.
BorderSide
Border sides for annotations.
FrameStyle frameStyle() const
Returns the grid frame style.
Contains information about the context of a rendering operation.
Degree/minutes/seconds, with minutes using leading zeros where required.
Draw annotations vertically, descending.
Show longitude/x annotations/divisions only.
AnnotationFormat annotationFormat() const
Returns the format for drawing grid annotations.
void setCrossLength(const double length)
Sets the length (in layout units) of the cross segments drawn for the grid.
void setAnnotationFormat(const AnnotationFormat format)
Sets the format for drawing grid annotations.
Draw markers at intersections of grid lines.
Degree/minutes, with minutes using leading zeros where required.
This class represents a coordinate reference system (CRS).
Class for doing transforms between two map coordinate systems.
double intervalY() const
Returns the interval between grid lines in the y-direction.
void setAnnotationFrameDistance(const double distance)
Sets the distance between the map frame and annotations.
GridStyle
Grid drawing style.
Tick markers drawn both inside and outside the map frame.
GridStyle style() const
Returns the grid&#39;s style, which controls how the grid is drawn over the map&#39;s contents.
double annotationFrameDistance() const
Returns the distance between the map frame and annotations.
QColor framePenColor() const
Retrieves the color of the stroke drawn in the grid frame.
Draw annotations outside the map frame.
Grid units follow map units.
bool enabled() const
Returns whether the item will be drawn.
double offsetY() const
Returns the offset for grid lines in the y-direction.
Degree/minutes/seconds, use - for S/W coordinates.
bool annotationEnabled() const
Returns whether annotations are shown for the grid.
Tick markers drawn outside map frame.