QGIS API Documentation  3.0.2-Girona (307d082)
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 
92  QgsLayoutItemMapGrid *grid( const QString &gridId ) const;
93 
98  QgsLayoutItemMapGrid *grid( int index ) const;
99 
105  QgsLayoutItemMapGrid &operator[]( int index );
106 
110  QList< QgsLayoutItemMapGrid * > asList() const;
111 
112  bool readXml( const QDomElement &elem, const QDomDocument &doc, const QgsReadWriteContext &context ) override;
113 
119  double maxGridExtension() const;
120 
127  void calculateMaxGridExtension( double &top, double &right, double &bottom, double &left ) const;
128 };
129 
130 //
131 // QgsLayoutItemMapGrid
132 //
133 
142 class CORE_EXPORT QgsLayoutItemMapGrid : public QgsLayoutItemMapItem
143 {
144 
145  Q_OBJECT
146 
147  public:
148 
152  enum GridUnit
153  {
155  MM,
156  CM
157  };
158 
163  {
164  Solid = 0,
167  FrameAnnotationsOnly
168  };
169 
174  {
175  ShowAll = 0,
178  HideAll
179  };
180 
185  {
186  InsideMapFrame = 0,
188  };
189 
194  {
195  Horizontal = 0,
198  BoundaryDirection
199  };
200 
205  {
206  Decimal = 0,
214  CustomFormat
215  };
216 
221  {
225  Top
226  };
227 
232  {
233  NoFrame = 0,
238  LineBorder
239  };
240 
245  {
246  FrameLeft = 0x01,
247  FrameRight = 0x02,
248  FrameTop = 0x04,
249  FrameBottom = 0x08
250  };
251  Q_DECLARE_FLAGS( FrameSideFlags, FrameSideFlag )
252 
253 
257  {
258  Longitude = 0,
259  Latitude
260  };
261 
267  QgsLayoutItemMapGrid( const QString &name, QgsLayoutItemMap *map );
268 
269  void draw( QPainter *painter ) override;
270  bool writeXml( QDomElement &elem, QDomDocument &doc, const QgsReadWriteContext &context ) const override;
271  bool readXml( const QDomElement &itemElem, const QDomDocument &doc, const QgsReadWriteContext &context ) override;
272 
277  void setCrs( const QgsCoordinateReferenceSystem &crs );
278 
283  QgsCoordinateReferenceSystem crs() const { return mCRS; }
284 
289  void setBlendMode( const QPainter::CompositionMode mode ) { mBlendMode = mode; }
290 
295  QPainter::CompositionMode blendMode() const { return mBlendMode; }
296 
297  bool usesAdvancedEffects() const override;
298 
303  double maxExtension() const;
304 
311  void calculateMaxExtension( double &top, double &right, double &bottom, double &left ) const;
312 
313  //
314  // GRID UNITS
315  //
316 
322  void setUnits( GridUnit unit );
323 
329  GridUnit units() const { return mGridUnit; }
330 
337  void setIntervalX( double interval );
338 
345  double intervalX() const { return mGridIntervalX; }
346 
353  void setIntervalY( double interval );
354 
361  double intervalY() const { return mGridIntervalY; }
362 
369  void setOffsetX( const double offset );
370 
377  double offsetX() const { return mGridOffsetX; }
378 
385  void setOffsetY( const double offset );
386 
393  double offsetY() const { return mGridOffsetY; }
394 
395  //
396  // GRID APPEARANCE
397  //
398 
404  void setStyle( const GridStyle style );
405 
411  GridStyle style() const { return mGridStyle; }
412 
418  void setCrossLength( const double length ) { mCrossLength = length; }
419 
425  double crossLength() const { return mCrossLength; }
426 
434  void setGridLineWidth( const double width );
435 
443  void setGridLineColor( const QColor &color );
444 
453  void setLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
454 
463  const QgsLineSymbol *lineSymbol() const; SIP_SKIP
464 
472  QgsLineSymbol *lineSymbol();
473 
482  void setMarkerSymbol( QgsMarkerSymbol *symbol SIP_TRANSFER );
483 
492  const QgsMarkerSymbol *markerSymbol() const; SIP_SKIP
493 
501  QgsMarkerSymbol *markerSymbol();
502 
503  //
504  // ANNOTATIONS
505  //
506 
511  void setAnnotationEnabled( const bool enabled ) { mShowGridAnnotation = enabled; }
512 
517  bool annotationEnabled() const { return mShowGridAnnotation; }
518 
523  void setAnnotationFont( const QFont &font ) { mGridAnnotationFont = font; }
524 
529  QFont annotationFont() const { return mGridAnnotationFont; }
530 
535  void setAnnotationFontColor( const QColor &color ) { mGridAnnotationFontColor = color; }
536 
541  QColor annotationFontColor() const { return mGridAnnotationFontColor; }
542 
548  void setAnnotationPrecision( const int precision ) { mGridAnnotationPrecision = precision; }
549 
555  int annotationPrecision() const { return mGridAnnotationPrecision; }
556 
564  void setAnnotationDisplay( const DisplayMode display, const BorderSide border );
565 
574  DisplayMode annotationDisplay( const BorderSide border ) const;
575 
581  void setAnnotationPosition( const AnnotationPosition position, const BorderSide side );
582 
588  AnnotationPosition annotationPosition( const BorderSide side ) const;
589 
594  void setAnnotationFrameDistance( const double distance ) { mAnnotationFrameDistance = distance; }
595 
600  double annotationFrameDistance() const { return mAnnotationFrameDistance; }
601 
606  void setAnnotationDirection( const AnnotationDirection direction, const BorderSide side );
607 
612  void setAnnotationDirection( const AnnotationDirection direction );
613 
619  AnnotationDirection annotationDirection( const BorderSide border ) const;
620 
625  void setAnnotationFormat( const AnnotationFormat format ) { mGridAnnotationFormat = format; }
626 
631  AnnotationFormat annotationFormat() const { return mGridAnnotationFormat; }
632 
638  void setAnnotationExpression( const QString &expression ) { mGridAnnotationExpressionString = expression; mGridAnnotationExpression.reset(); }
639 
645  QString annotationExpression() const { return mGridAnnotationExpressionString; }
646 
647  //
648  // GRID FRAME
649  //
650 
655  void setFrameStyle( const FrameStyle style ) { mGridFrameStyle = style; }
656 
661  FrameStyle frameStyle() const { return mGridFrameStyle; }
662 
667  void setFrameDivisions( const DisplayMode divisions, const BorderSide side );
668 
673  DisplayMode frameDivisions( const BorderSide side ) const;
674 
682  void setFrameSideFlags( QgsLayoutItemMapGrid::FrameSideFlags flags );
683 
692  void setFrameSideFlag( const QgsLayoutItemMapGrid::FrameSideFlag flag, bool on = true );
693 
701  QgsLayoutItemMapGrid::FrameSideFlags frameSideFlags() const;
702 
712  bool testFrameSideFlag( const FrameSideFlag flag ) const;
713 
720  void setFrameWidth( const double width ) { mGridFrameWidth = width; }
721 
728  double frameWidth() const { return mGridFrameWidth; }
729 
735  void setFramePenSize( const double width ) { mGridFramePenThickness = width; }
736 
742  double framePenSize() const { return mGridFramePenThickness; }
743 
751  void setFramePenColor( const QColor &color ) { mGridFramePenColor = color; }
752 
760  QColor framePenColor() const {return mGridFramePenColor;}
761 
768  void setFrameFillColor1( const QColor &color ) { mGridFrameFillColor1 = color; }
769 
776  QColor frameFillColor1() const { return mGridFrameFillColor1; }
777 
784  void setFrameFillColor2( const QColor &color ) { mGridFrameFillColor2 = color; }
785 
792  QColor frameFillColor2() const { return mGridFrameFillColor2; }
793 
795 
796  private:
797 
798  QgsLayoutItemMapGrid() = delete;
799 
800  struct GridExtension
801  {
802  GridExtension() = default;
803  double top = 0.0;
804  double right = 0.0;
805  double bottom = 0.0;
806  double left = 0.0;
807  };
808 
810  mutable bool mTransformDirty = true;
811 
815  double mGridIntervalX = 0.0;
817  double mGridIntervalY = 0.0;
819  double mGridOffsetX = 0.0;
821  double mGridOffsetY = 0.0;
823  QFont mGridAnnotationFont;
825  QColor mGridAnnotationFontColor = Qt::black;
827  int mGridAnnotationPrecision = 3;
829  bool mShowGridAnnotation = false;
830 
832  DisplayMode mLeftGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
834  DisplayMode mRightGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
836  DisplayMode mTopGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
838  DisplayMode mBottomGridAnnotationDisplay = QgsLayoutItemMapGrid::ShowAll;
839 
841  AnnotationPosition mLeftGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
843  AnnotationPosition mRightGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
845  AnnotationPosition mTopGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
847  AnnotationPosition mBottomGridAnnotationPosition = QgsLayoutItemMapGrid::OutsideMapFrame;
848 
850  double mAnnotationFrameDistance = 1.0;
851 
853  AnnotationDirection mLeftGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
855  AnnotationDirection mRightGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
857  AnnotationDirection mTopGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
859  AnnotationDirection mBottomGridAnnotationDirection = QgsLayoutItemMapGrid::Horizontal;
860  AnnotationFormat mGridAnnotationFormat = QgsLayoutItemMapGrid::Decimal;
861 
862  QString mGridAnnotationExpressionString;
863  mutable std::unique_ptr< QgsExpression > mGridAnnotationExpression;
864 
865  FrameStyle mGridFrameStyle = QgsLayoutItemMapGrid::NoFrame;
866  FrameSideFlags mGridFrameSides;
867  double mGridFrameWidth = 2.0;
868  double mGridFramePenThickness = 0.3;
869  QColor mGridFramePenColor = QColor( 0, 0, 0 );
870  QColor mGridFrameFillColor1 = Qt::white;
871  QColor mGridFrameFillColor2 = Qt::black;
872  double mCrossLength = 3.0;
873 
875  DisplayMode mLeftFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
877  DisplayMode mRightFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
879  DisplayMode mTopFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
881  DisplayMode mBottomFrameDivisions = QgsLayoutItemMapGrid::ShowAll;
882 
883  std::unique_ptr< QgsLineSymbol > mGridLineSymbol;
884  std::unique_ptr< QgsMarkerSymbol > mGridMarkerSymbol;
885 
887 
888  GridUnit mGridUnit = MapUnit;
889 
890  QPainter::CompositionMode mBlendMode = QPainter::CompositionMode_SourceOver;
891 
892  mutable QList< QPair< double, QPolygonF > > mTransformedXLines;
893  mutable QList< QPair< double, QPolygonF > > mTransformedYLines;
894  mutable QList< QgsPointXY > mTransformedIntersections;
895  QRectF mPrevPaintRect;
896  mutable QPolygonF mPrevMapPolygon;
897 
898  class QgsMapAnnotation
899  {
900  public:
901  double coordinate;
902  QPointF itemPosition;
904  };
905 
910  void drawGridFrame( QPainter *p, const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, GridExtension *extension = nullptr ) const;
911 
921  void drawCoordinateAnnotations( QPainter *p, const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, QgsExpressionContext &expressionContext, GridExtension *extension = nullptr ) const;
922 
927  void drawCoordinateAnnotation( QPainter *p, QPointF pos, const QString &annotationString, const AnnotationCoordinate coordinateType, GridExtension *extension = nullptr ) const;
928 
936  void drawAnnotation( QPainter *p, QPointF pos, int rotation, const QString &annotationText ) const;
937 
938  QString gridAnnotationString( double value, AnnotationCoordinate coord, QgsExpressionContext &expressionContext ) const;
939 
943  int xGridLines( QList< QPair< double, QLineF > > &lines ) const;
944 
948  int yGridLines( QList< QPair< double, QLineF > > &lines ) const;
949 
950  int xGridLinesCrsTransform( const QgsRectangle &bbox, const QgsCoordinateTransform &t, QList< QPair< double, QPolygonF > > &lines ) const;
951 
952  int yGridLinesCrsTransform( const QgsRectangle &bbox, const QgsCoordinateTransform &t, QList< QPair< double, QPolygonF > > &lines ) const;
953 
954  void drawGridLine( const QLineF &line, QgsRenderContext &context ) const;
955 
956  void drawGridLine( const QPolygonF &line, QgsRenderContext &context ) const;
957 
958  void sortGridLinesOnBorders( const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, QMap< double, double > &leftFrameEntries,
959  QMap< double, double > &rightFrameEntries, QMap< double, double > &topFrameEntries, QMap< double, double > &bottomFrameEntries ) const;
960 
965  void drawGridFrameBorder( QPainter *p, const QMap< double, double > &borderPos, BorderSide border, double *extension = nullptr ) const;
966 
972  BorderSide borderForLineCoord( QPointF p, const AnnotationCoordinate coordinateType ) const;
973 
975  int crsGridParams( QgsRectangle &crsRect, QgsCoordinateTransform &inverseTransform ) const;
976 
977  static QList<QPolygonF> trimLinesToMap( const QPolygonF &line, const QgsRectangle &rect );
978 
979  QPolygonF scalePolygon( const QPolygonF &polygon, const double scale ) const;
980 
982  void drawGridCrsTransform( QgsRenderContext &context, double dotsPerMM, QList< QPair< double, QLineF > > &horizontalLines,
983  QList< QPair< double, QLineF > > &verticalLines, bool calculateLinesOnly = false ) const;
984 
985  void drawGridNoTransform( QgsRenderContext &context, double dotsPerMM, QList<QPair<double, QLineF> > &horizontalLines, QList<QPair<double, QLineF> > &verticalLines, bool calculateLinesOnly = false ) const;
986 
987  void createDefaultGridLineSymbol();
988 
989  void createDefaultGridMarkerSymbol();
990 
991  void drawGridMarker( QPointF point, QgsRenderContext &context ) const;
992 
993  void drawGridFrameZebraBorder( QPainter *p, const QMap<double, double> &borderPos, BorderSide border, double *extension = nullptr ) const;
994 
995  void drawGridFrameTicks( QPainter *p, const QMap<double, double> &borderPos, BorderSide border, double *extension = nullptr ) const;
996 
997  void drawGridFrameLineBorder( QPainter *p, BorderSide border, double *extension = nullptr ) const;
998 
999  void calculateCrsTransformLines() const;
1000 
1001  bool shouldShowDivisionForSide( AnnotationCoordinate coordinate, BorderSide side ) const;
1002  bool shouldShowDivisionForDisplayMode( AnnotationCoordinate coordinate, DisplayMode mode ) const;
1003 
1004  friend class TestQgsLayoutMapGrid;
1005 
1006 };
1007 
1008 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLayoutItemMapGrid::FrameSideFlags )
1009 
1010 #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...
A rectangle specified with double values.
Definition: qgsrectangle.h:39
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.
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.
Degree/minutes, use NSEW suffix.
int annotationPrecision() const
Returns the coordinate precision for grid annotations, which is the number of decimal places shown wh...
QPainter::CompositionMode blendMode() const
Retrieves the blending mode used for drawing the grid.
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.
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.
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.