QGIS API Documentation  3.6.0-Noosa (5873452)
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 "qgslayoutitemmapitem.h"
24 #include "qgssymbol.h"
25 #include <QPainter>
26 
29 class QgsLayoutItemMap;
30 class QDomDocument;
31 class QDomElement;
32 class QPainter;
33 class QgsRenderContext;
34 
45 {
46  public:
47 
52 
61  void addGrid( QgsLayoutItemMapGrid *grid SIP_TRANSFER );
62 
69  void removeGrid( const QString &gridId );
70 
77  void moveGridUp( const QString &gridId );
78 
85  void moveGridDown( const QString &gridId );
86 
90  QgsLayoutItemMapGrid *grid( const QString &gridId ) const;
91 
95  QgsLayoutItemMapGrid *grid( int index ) const;
96 
101  QgsLayoutItemMapGrid &operator[]( int index );
102 
106  QList< QgsLayoutItemMapGrid * > asList() const;
107 
108  bool readXml( const QDomElement &elem, const QDomDocument &doc, const QgsReadWriteContext &context ) override;
109 
115  double maxGridExtension() const;
116 
123  void calculateMaxGridExtension( double &top, double &right, double &bottom, double &left ) const;
124 };
125 
126 //
127 // QgsLayoutItemMapGrid
128 //
129 
138 class CORE_EXPORT QgsLayoutItemMapGrid : public QgsLayoutItemMapItem
139 {
140 
141  Q_OBJECT
142 
143  public:
144 
148  enum GridUnit
149  {
151  MM,
152  CM
153  };
154 
159  {
160  Solid = 0,
163  FrameAnnotationsOnly
164  };
165 
170  {
171  ShowAll = 0,
174  HideAll
175  };
176 
181  {
182  InsideMapFrame = 0,
184  };
185 
190  {
191  Horizontal = 0,
194  BoundaryDirection
195  };
196 
201  {
202  Decimal = 0,
210  CustomFormat
211  };
212 
217  {
221  Top
222  };
223 
228  {
229  NoFrame = 0,
237  };
238 
243  {
244  FrameLeft = 0x01,
245  FrameRight = 0x02,
246  FrameTop = 0x04,
247  FrameBottom = 0x08
248  };
249  Q_DECLARE_FLAGS( FrameSideFlags, FrameSideFlag )
250 
251 
255  {
256  Longitude = 0,
257  Latitude
258  };
259 
265  QgsLayoutItemMapGrid( const QString &name, QgsLayoutItemMap *map );
266 
267  void draw( QPainter *painter ) override;
268  bool writeXml( QDomElement &elem, QDomDocument &doc, const QgsReadWriteContext &context ) const override;
269  bool readXml( const QDomElement &itemElem, const QDomDocument &doc, const QgsReadWriteContext &context ) override;
270 
275  void setCrs( const QgsCoordinateReferenceSystem &crs );
276 
281  QgsCoordinateReferenceSystem crs() const { return mCRS; }
282 
287  void setBlendMode( const QPainter::CompositionMode mode ) { mBlendMode = mode; }
288 
293  QPainter::CompositionMode blendMode() const { return mBlendMode; }
294 
295  bool usesAdvancedEffects() const override;
296 
301  double maxExtension() const;
302 
309  void calculateMaxExtension( double &top, double &right, double &bottom, double &left ) const;
310 
311  //
312  // GRID UNITS
313  //
314 
320  void setUnits( GridUnit unit );
321 
327  GridUnit units() const { return mGridUnit; }
328 
335  void setIntervalX( double interval );
336 
343  double intervalX() const { return mGridIntervalX; }
344 
351  void setIntervalY( double interval );
352 
359  double intervalY() const { return mGridIntervalY; }
360 
367  void setOffsetX( double offset );
368 
375  double offsetX() const { return mGridOffsetX; }
376 
383  void setOffsetY( double offset );
384 
391  double offsetY() const { return mGridOffsetY; }
392 
393  //
394  // GRID APPEARANCE
395  //
396 
402  void setStyle( GridStyle style );
403 
409  GridStyle style() const { return mGridStyle; }
410 
416  void setCrossLength( const double length ) { mCrossLength = length; }
417 
423  double crossLength() const { return mCrossLength; }
424 
432  void setGridLineWidth( double width );
433 
441  void setGridLineColor( const QColor &color );
442 
451  void setLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
452 
461  const QgsLineSymbol *lineSymbol() const; SIP_SKIP
462 
470  QgsLineSymbol *lineSymbol();
471 
480  void setMarkerSymbol( QgsMarkerSymbol *symbol SIP_TRANSFER );
481 
490  const QgsMarkerSymbol *markerSymbol() const; SIP_SKIP
491 
499  QgsMarkerSymbol *markerSymbol();
500 
501  //
502  // ANNOTATIONS
503  //
504 
509  void setAnnotationEnabled( const bool enabled ) { mShowGridAnnotation = enabled; }
510 
515  bool annotationEnabled() const { return mShowGridAnnotation; }
516 
521  void setAnnotationFont( const QFont &font ) { mGridAnnotationFont = font; }
522 
527  QFont annotationFont() const { return mGridAnnotationFont; }
528 
533  void setAnnotationFontColor( const QColor &color ) { mGridAnnotationFontColor = color; }
534 
539  QColor annotationFontColor() const { return mGridAnnotationFontColor; }
540 
546  void setAnnotationPrecision( const int precision ) { mGridAnnotationPrecision = precision; }
547 
553  int annotationPrecision() const { return mGridAnnotationPrecision; }
554 
562  void setAnnotationDisplay( DisplayMode display, BorderSide border );
563 
572  DisplayMode annotationDisplay( BorderSide border ) const;
573 
579  void setAnnotationPosition( AnnotationPosition position, BorderSide side );
580 
586  AnnotationPosition annotationPosition( BorderSide side ) const;
587 
592  void setAnnotationFrameDistance( const double distance ) { mAnnotationFrameDistance = distance; }
593 
598  double annotationFrameDistance() const { return mAnnotationFrameDistance; }
599 
604  void setAnnotationDirection( AnnotationDirection direction, BorderSide side );
605 
610  void setAnnotationDirection( AnnotationDirection direction );
611 
617  AnnotationDirection annotationDirection( BorderSide border ) const;
618 
623  void setAnnotationFormat( const AnnotationFormat format ) { mGridAnnotationFormat = format; }
624 
629  AnnotationFormat annotationFormat() const { return mGridAnnotationFormat; }
630 
636  void setAnnotationExpression( const QString &expression ) { mGridAnnotationExpressionString = expression; mGridAnnotationExpression.reset(); }
637 
643  QString annotationExpression() const { return mGridAnnotationExpressionString; }
644 
645  //
646  // GRID FRAME
647  //
648 
653  void setFrameStyle( const FrameStyle style ) { mGridFrameStyle = style; }
654 
659  FrameStyle frameStyle() const { return mGridFrameStyle; }
660 
665  void setFrameDivisions( DisplayMode divisions, BorderSide side );
666 
671  DisplayMode frameDivisions( BorderSide side ) const;
672 
680  void setFrameSideFlags( QgsLayoutItemMapGrid::FrameSideFlags flags );
681 
690  void setFrameSideFlag( QgsLayoutItemMapGrid::FrameSideFlag flag, bool on = true );
691 
699  QgsLayoutItemMapGrid::FrameSideFlags frameSideFlags() const;
700 
710  bool testFrameSideFlag( FrameSideFlag flag ) const;
711 
718  void setFrameWidth( const double width ) { mGridFrameWidth = width; }
719 
726  double frameWidth() const { return mGridFrameWidth; }
727 
734  void setFrameMargin( const double margin ) { mGridFrameMargin = margin; }
735 
742  double frameMargin() const { return mGridFrameMargin; }
743 
749  void setFramePenSize( const double width ) { mGridFramePenThickness = width; }
750 
756  double framePenSize() const { return mGridFramePenThickness; }
757 
765  void setFramePenColor( const QColor &color ) { mGridFramePenColor = color; }
766 
774  QColor framePenColor() const {return mGridFramePenColor;}
775 
782  void setFrameFillColor1( const QColor &color ) { mGridFrameFillColor1 = color; }
783 
790  QColor frameFillColor1() const { return mGridFrameFillColor1; }
791 
798  void setFrameFillColor2( const QColor &color ) { mGridFrameFillColor2 = color; }
799 
806  QColor frameFillColor2() const { return mGridFrameFillColor2; }
807 
809 
810  private:
811 
812  QgsLayoutItemMapGrid() = delete;
813 
814  struct GridExtension
815  {
816  GridExtension() = default;
817  double top = 0.0;
818  double right = 0.0;
819  double bottom = 0.0;
820  double left = 0.0;
821  };
822 
824  mutable bool mTransformDirty = true;
825 
829  double mGridIntervalX = 0.0;
831  double mGridIntervalY = 0.0;
833  double mGridOffsetX = 0.0;
835  double mGridOffsetY = 0.0;
837  QFont mGridAnnotationFont;
839  QColor mGridAnnotationFontColor = Qt::black;
841  int mGridAnnotationPrecision = 3;
843  bool mShowGridAnnotation = false;
844 
846  DisplayMode mLeftGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
848  DisplayMode mRightGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
850  DisplayMode mTopGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
852  DisplayMode mBottomGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
853 
855  AnnotationPosition mLeftGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
857  AnnotationPosition mRightGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
859  AnnotationPosition mTopGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
861  AnnotationPosition mBottomGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
862 
864  double mAnnotationFrameDistance = 1.0;
865 
867  AnnotationDirection mLeftGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
869  AnnotationDirection mRightGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
871  AnnotationDirection mTopGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
873  AnnotationDirection mBottomGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
874  AnnotationFormat mGridAnnotationFormat = QgsLayoutItemMapGrid::Decimal;
875 
876  QString mGridAnnotationExpressionString;
877  mutable std::unique_ptr< QgsExpression > mGridAnnotationExpression;
878 
879  FrameStyle mGridFrameStyle = QgsLayoutItemMapGrid::NoFrame;
880  FrameSideFlags mGridFrameSides;
881  double mGridFrameWidth = 2.0;
882  double mGridFramePenThickness = 0.3;
883  QColor mGridFramePenColor = QColor( 0, 0, 0 );
884  QColor mGridFrameFillColor1 = Qt::white;
885  QColor mGridFrameFillColor2 = Qt::black;
886  double mCrossLength = 3.0;
887  double mGridFrameMargin = 0.0;
888 
890  DisplayMode mLeftFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
892  DisplayMode mRightFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
894  DisplayMode mTopFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
896  DisplayMode mBottomFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
897 
898  std::unique_ptr< QgsLineSymbol > mGridLineSymbol;
899  std::unique_ptr< QgsMarkerSymbol > mGridMarkerSymbol;
900 
902 
903  GridUnit mGridUnit = MapUnit;
904 
905  QPainter::CompositionMode mBlendMode = QPainter::CompositionMode_SourceOver;
906 
907  mutable QList< QPair< double, QPolygonF > > mTransformedXLines;
908  mutable QList< QPair< double, QPolygonF > > mTransformedYLines;
909  mutable QList< QgsPointXY > mTransformedIntersections;
910  QRectF mPrevPaintRect;
911  mutable QPolygonF mPrevMapPolygon;
912 
913  class QgsMapAnnotation
914  {
915  public:
916  double coordinate;
917  QPointF itemPosition;
919  };
920 
925  void drawGridFrame( QPainter *p, const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, GridExtension *extension = nullptr ) const;
926 
936  void drawCoordinateAnnotations( QPainter *p, const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, QgsExpressionContext &expressionContext, GridExtension *extension = nullptr ) const;
937 
942  void drawCoordinateAnnotation( QPainter *p, QPointF pos, const QString &annotationString, AnnotationCoordinate coordinateType, GridExtension *extension = nullptr ) const;
943 
951  void drawAnnotation( QPainter *p, QPointF pos, int rotation, const QString &annotationText ) const;
952 
953  QString gridAnnotationString( double value, AnnotationCoordinate coord, QgsExpressionContext &expressionContext ) const;
954 
958  int xGridLines( QList< QPair< double, QLineF > > &lines ) const;
959 
963  int yGridLines( QList< QPair< double, QLineF > > &lines ) const;
964 
965  int xGridLinesCrsTransform( const QgsRectangle &bbox, const QgsCoordinateTransform &t, QList< QPair< double, QPolygonF > > &lines ) const;
966 
967  int yGridLinesCrsTransform( const QgsRectangle &bbox, const QgsCoordinateTransform &t, QList< QPair< double, QPolygonF > > &lines ) const;
968 
969  void drawGridLine( const QLineF &line, QgsRenderContext &context ) const;
970 
971  void drawGridLine( const QPolygonF &line, QgsRenderContext &context ) const;
972 
973  void sortGridLinesOnBorders( const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, QMap< double, double > &leftFrameEntries,
974  QMap< double, double > &rightFrameEntries, QMap< double, double > &topFrameEntries, QMap< double, double > &bottomFrameEntries ) const;
975 
980  void drawGridFrameBorder( QPainter *p, const QMap< double, double > &borderPos, BorderSide border, double *extension = nullptr ) const;
981 
987  BorderSide borderForLineCoord( QPointF p, AnnotationCoordinate coordinateType ) const;
988 
990  int crsGridParams( QgsRectangle &crsRect, QgsCoordinateTransform &inverseTransform ) const;
991 
992  static QList<QPolygonF> trimLinesToMap( const QPolygonF &line, const QgsRectangle &rect );
993 
994  QPolygonF scalePolygon( const QPolygonF &polygon, double scale ) const;
995 
997  void drawGridCrsTransform( QgsRenderContext &context, double dotsPerMM, QList< QPair< double, QLineF > > &horizontalLines,
998  QList< QPair< double, QLineF > > &verticalLines, bool calculateLinesOnly = false ) const;
999 
1000  void drawGridNoTransform( QgsRenderContext &context, double dotsPerMM, QList<QPair<double, QLineF> > &horizontalLines, QList<QPair<double, QLineF> > &verticalLines, bool calculateLinesOnly = false ) const;
1001 
1002  void createDefaultGridLineSymbol();
1003 
1004  void createDefaultGridMarkerSymbol();
1005 
1006  void drawGridMarker( QPointF point, QgsRenderContext &context ) const;
1007 
1008  void drawGridFrameZebraBorder( QPainter *p, const QMap<double, double> &borderPos, BorderSide border, double *extension = nullptr ) const;
1009 
1010  void drawGridFrameTicks( QPainter *p, const QMap<double, double> &borderPos, BorderSide border, double *extension = nullptr ) const;
1011 
1012  void drawGridFrameLineBorder( QPainter *p, BorderSide border, double *extension = nullptr ) const;
1013 
1014  void calculateCrsTransformLines() const;
1015 
1016  bool shouldShowDivisionForSide( AnnotationCoordinate coordinate, BorderSide side ) const;
1017  bool shouldShowDivisionForDisplayMode( AnnotationCoordinate coordinate, DisplayMode mode ) const;
1018 
1019  friend class TestQgsLayoutMapGrid;
1020 
1021 };
1022 
1023 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLayoutItemMapGrid::FrameSideFlags )
1024 
1025 #endif // QGSLAYOUTITEMMAPGRID_H
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.
double offsetY() const
Returns the offset for grid lines in the y-direction.
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:41
double intervalX() const
Returns the interval between grid lines in the x-direction.
QgsExpressionContext createExpressionContext() const override
Creates an expression context relating to the objects&#39; current state.
Degree/minutes/seconds, use NSEW suffix.
bool annotationEnabled() const
Returns whether annotations are shown for the grid.
void setAnnotationFontColor(const QColor &color)
Sets the font color used for drawing grid annotations.
void setFrameFillColor1(const QColor &color)
Sets the first fill color used for the grid frame.
QColor framePenColor() const
Retrieves the color of the stroke drawn in the grid frame.
QColor annotationFontColor() const
Returns the font color used for drawing grid annotations.
double framePenSize() const
Retrieves the width of the stroke drawn in the grid frame.
FrameSideFlag
Flags for controlling which side of the map a frame is drawn on.
An item which is drawn inside a QgsLayoutItemMap, e.g., a grid or map overview.
Draw annotations vertically, ascending.
void setFrameMargin(const double margin)
Sets the grid frame margin (in layout units).
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.
double intervalY() const
Returns the interval between grid lines in the y-direction.
void setBlendMode(const QPainter::CompositionMode mode)
Sets the blending mode used for drawing the grid.
double crossLength() const
Retrieves the length (in layout units) of the cross segments drawn for the grid.
Grid units in millimeters.
Degree/minutes, use - for S/W coordinates.
double offsetX() const
Returns the offset for grid lines in the x-direction.
QFont annotationFont() const
Returns the font used for drawing grid annotations.
double frameMargin() const
Sets the grid frame Margin (in layout units).
const QgsCoordinateReferenceSystem & crs
Degree/minutes, use NSEW suffix.
int annotationPrecision() const
Returns the coordinate precision for grid annotations, which is the number of decimal places shown wh...
A marker symbol type, for rendering Point and MultiPoint geometries.
Definition: qgssymbol.h:732
QPainter::CompositionMode blendMode() const
Retrieves the blending mode used for drawing the grid.
A line symbol type, for rendering LineString and MultiLineString geometries.
Definition: qgssymbol.h:920
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.
virtual bool usesAdvancedEffects() const
Returns true if the item is drawn using advanced effects, such as blend modes.
Draw line crosses at intersections of grid lines.
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.
AnnotationFormat annotationFormat() const
Returns the format for drawing grid annotations.
#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...
QColor frameFillColor1() const
Retrieves the first fill color for the grid frame.
QString annotationExpression() const
Returns the expression used for drawing grid annotations.
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
bool enabled() const
Returns whether the item will be drawn.
Show latitude/y annotations/divisions only.
void setAnnotationEnabled(const bool enabled)
Sets whether annotations should be shown for the grid.
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 annotationFrameDistance() const
Returns the distance between the map frame and annotations.
QgsLayoutItemMapItem & operator[](int index)
Returns a reference to an item at the specified index within the stack.
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.
QList< QgsLayoutItemMapItem *> asList() const
Returns a list of QgsLayoutItemMapItems contained by the stack.
void setAnnotationPrecision(const int precision)
Sets the coordinate precision for grid annotations.
BorderSide
Border sides for annotations.
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.
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.
FrameStyle frameStyle() const
Returns the grid frame style.
Black/white pattern, with nautical style diagonals on corners.
Degree/minutes, with minutes using leading zeros where required.
This class represents a coordinate reference system (CRS).
double frameWidth() const
Gets the grid frame width in layout units.
Class for doing transforms between two map coordinate systems.
GridUnit units() const
Returns the units used for grid measurements such as the interval and offset for grid lines...
void setAnnotationFrameDistance(const double distance)
Sets the distance between the map frame and annotations.
GridStyle
Grid drawing style.
Simple solid line frame, with nautical style diagonals on corners.
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.
Draw annotations outside the map frame.
QColor frameFillColor2() const
Retrieves the second fill color for the grid frame.
Grid units follow map units.
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...
QgsCoordinateReferenceSystem crs() const
Retrieves the CRS for the grid.
Degree/minutes/seconds, use - for S/W coordinates.
Tick markers drawn outside map frame.