QGIS API Documentation  2.99.0-Master (cd0ba91)
qgscomposermapgrid.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgscomposermapgrid.h
3  --------------------
4  begin : December 2013
5  copyright : (C) 2013 by Marco Hugentobler
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 QGSCOMPOSERMAPGRID_H
19 #define QGSCOMPOSERMAPGRID_H
20 
21 #include "qgis_core.h"
22 #include "qgis_sip.h"
23 #include "qgis.h"
24 #include "qgscomposermapitem.h"
26 #include "qgsrectangle.h"
27 #include <QString>
28 #include <QPainter>
29 
31 class QgsLineSymbol;
32 class QgsMarkerSymbol;
33 class QgsComposerMapGrid;
34 class QgsComposerMap;
35 class QDomDocument;
36 class QDomElement;
37 class QPainter;
38 class QgsRenderContext;
39 
50 {
51  public:
52 
58 
68  void addGrid( QgsComposerMapGrid *grid SIP_TRANSFER );
69 
77  void removeGrid( const QString &gridId );
78 
86  void moveGridUp( const QString &gridId );
87 
95  void moveGridDown( const QString &gridId );
96 
103  const QgsComposerMapGrid *constGrid( const QString &gridId ) const;
104 
111  QgsComposerMapGrid *grid( const QString &gridId ) const;
112 
119  QgsComposerMapGrid *grid( const int index ) const;
120 
128  QgsComposerMapGrid &operator[]( int idx );
129 
134  QList< QgsComposerMapGrid * > asList() const;
135 
143  bool readXml( const QDomElement &elem, const QDomDocument &doc ) override;
144 
151  double maxGridExtension() const;
152 
164  void calculateMaxGridExtension( double &top, double &right, double &bottom, double &left ) const;
165 };
166 
167 //
168 // QgsComposerMapGrid
169 //
170 
179 class CORE_EXPORT QgsComposerMapGrid : public QgsComposerMapItem
180 {
181 
182  Q_OBJECT
183 
184  public:
185 
189  enum GridUnit
190  {
192  MM,
193  CM
194  };
195 
200  {
201  Solid = 0,
204  FrameAnnotationsOnly
205  };
206 
211  {
212  ShowAll = 0,
215  HideAll
216  };
217 
222  {
223  InsideMapFrame = 0,
225  };
226 
231  {
232  Horizontal = 0,
235  BoundaryDirection
236  };
237 
242  {
243  Decimal = 0,
251  CustomFormat
252  };
253 
258  {
262  Top
263  };
264 
269  {
270  NoFrame = 0,
275  LineBorder
276  };
277 
282  {
283  FrameLeft = 0x01,
284  FrameRight = 0x02,
285  FrameTop = 0x04,
286  FrameBottom = 0x08
287  };
288  Q_DECLARE_FLAGS( FrameSideFlags, FrameSideFlag )
289 
290 
294  {
295  Longitude = 0,
296  Latitude
297  };
298 
304  QgsComposerMapGrid( const QString &name, QgsComposerMap *map );
305 
306  virtual ~QgsComposerMapGrid();
307 
312  void draw( QPainter *painter ) override;
313 
320  bool writeXml( QDomElement &elem, QDomDocument &doc ) const override;
321 
328  bool readXml( const QDomElement &itemElem, const QDomDocument &doc ) override;
329 
335  void setCrs( const QgsCoordinateReferenceSystem &crs );
336 
342  QgsCoordinateReferenceSystem crs() const { return mCRS; }
343 
349  void setBlendMode( const QPainter::CompositionMode mode ) { mBlendMode = mode; }
350 
356  QPainter::CompositionMode blendMode() const { return mBlendMode; }
357 
358  bool usesAdvancedEffects() const override;
359 
365  double maxExtension();
366 
378  void calculateMaxExtension( double &top, double &right, double &bottom, double &left );
379 
380  //
381  // GRID UNITS
382  //
383 
390  void setUnits( const GridUnit unit );
391 
398  GridUnit units() const { return mGridUnit; }
399 
407  void setIntervalX( const double interval );
408 
416  double intervalX() const { return mGridIntervalX; }
417 
425  void setIntervalY( const double interval );
426 
434  double intervalY() const { return mGridIntervalY; }
435 
443  void setOffsetX( const double offset );
444 
452  double offsetX() const { return mGridOffsetX; }
453 
461  void setOffsetY( const double offset );
462 
470  double offsetY() const { return mGridOffsetY; }
471 
472  //
473  // GRID APPEARANCE
474  //
475 
482  void setStyle( const GridStyle style );
483 
490  GridStyle style() const { return mGridStyle; }
491 
498  void setCrossLength( const double length ) { mCrossLength = length; }
499 
506  double crossLength() const { return mCrossLength; }
507 
516  void setGridLineWidth( const double width );
517 
526  void setGridLineColor( const QColor &color );
527 
536  void setLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
537 
547  const QgsLineSymbol *lineSymbol() const { return mGridLineSymbol; } SIP_SKIP
548 
557  QgsLineSymbol *lineSymbol() { return mGridLineSymbol; }
558 
567  void setMarkerSymbol( QgsMarkerSymbol *symbol SIP_TRANSFER );
568 
578  const QgsMarkerSymbol *markerSymbol() const { return mGridMarkerSymbol; } SIP_SKIP
579 
588  QgsMarkerSymbol *markerSymbol() { return mGridMarkerSymbol; }
589 
590  //
591  // ANNOTATIONS
592  //
593 
599  void setAnnotationEnabled( const bool enabled ) { mShowGridAnnotation = enabled; }
600 
606  bool annotationEnabled() const { return mShowGridAnnotation; }
607 
613  void setAnnotationFont( const QFont &font ) { mGridAnnotationFont = font; }
614 
620  QFont annotationFont() const { return mGridAnnotationFont; }
621 
627  void setAnnotationFontColor( const QColor &color ) { mGridAnnotationFontColor = color; }
628 
634  QColor annotationFontColor() const { return mGridAnnotationFontColor; }
635 
641  void setAnnotationPrecision( const int precision ) { mGridAnnotationPrecision = precision; }
642 
648  int annotationPrecision() const { return mGridAnnotationPrecision; }
649 
658  void setAnnotationDisplay( const DisplayMode display, const BorderSide border );
659 
669  DisplayMode annotationDisplay( const BorderSide border ) const;
670 
678  void setAnnotationPosition( const AnnotationPosition position, const BorderSide border );
679 
687  AnnotationPosition annotationPosition( const BorderSide border ) const;
688 
694  void setAnnotationFrameDistance( const double distance ) { mAnnotationFrameDistance = distance; }
695 
701  double annotationFrameDistance() const { return mAnnotationFrameDistance; }
702 
709  void setAnnotationDirection( const AnnotationDirection direction, const BorderSide border );
710 
716  void setAnnotationDirection( const AnnotationDirection direction );
717 
724  AnnotationDirection annotationDirection( const BorderSide border ) const;
725 
731  void setAnnotationFormat( const AnnotationFormat format ) { mGridAnnotationFormat = format; }
732 
738  AnnotationFormat annotationFormat() const { return mGridAnnotationFormat; }
739 
747  void setAnnotationExpression( const QString &expression ) { mGridAnnotationExpressionString = expression; mGridAnnotationExpression.reset(); }
748 
756  QString annotationExpression() const { return mGridAnnotationExpressionString; }
757 
758  //
759  // GRID FRAME
760  //
761 
767  void setFrameStyle( const FrameStyle style ) { mGridFrameStyle = style; }
768 
774  FrameStyle frameStyle() const { return mGridFrameStyle; }
775 
783  void setFrameDivisions( const DisplayMode divisions, const BorderSide border );
784 
792  DisplayMode frameDivisions( const BorderSide border ) const;
793 
802  void setFrameSideFlags( QgsComposerMapGrid::FrameSideFlags flags );
803 
812  void setFrameSideFlag( const FrameSideFlag flag, bool on = true );
813 
822  FrameSideFlags frameSideFlags() const;
823 
833  bool testFrameSideFlag( const FrameSideFlag flag ) const;
834 
842  void setFrameWidth( const double width ) { mGridFrameWidth = width; }
843 
851  double frameWidth() const { return mGridFrameWidth; }
852 
859  void setFramePenSize( const double width ) { mGridFramePenThickness = width; }
860 
867  double framePenSize() const { return mGridFramePenThickness; }
868 
877  void setFramePenColor( const QColor &color ) { mGridFramePenColor = color; }
878 
887  QColor framePenColor() const {return mGridFramePenColor;}
888 
896  void setFrameFillColor1( const QColor &color ) { mGridFrameFillColor1 = color; }
897 
905  QColor frameFillColor1() const { return mGridFrameFillColor1; }
906 
914  void setFrameFillColor2( const QColor &color ) { mGridFrameFillColor2 = color; }
915 
923  QColor frameFillColor2() const { return mGridFrameFillColor2; }
924 
925  virtual QgsExpressionContext createExpressionContext() const override;
926 
927  private:
928 
929  QgsComposerMapGrid(); //forbidden
930 
931  struct GridExtension
932  {
933  GridExtension() = default;
934  double top = 0.0;
935  double right = 0.0;
936  double bottom = 0.0;
937  double left = 0.0;
938  };
939 
940  /*True if a re-transformation of grid lines is required*/
941  bool mTransformDirty;
942 
944  GridStyle mGridStyle;
946  double mGridIntervalX;
948  double mGridIntervalY;
950  double mGridOffsetX;
952  double mGridOffsetY;
954  QFont mGridAnnotationFont;
956  QColor mGridAnnotationFontColor;
958  int mGridAnnotationPrecision;
960  bool mShowGridAnnotation;
961 
963  DisplayMode mLeftGridAnnotationDisplay;
965  DisplayMode mRightGridAnnotationDisplay;
967  DisplayMode mTopGridAnnotationDisplay;
969  DisplayMode mBottomGridAnnotationDisplay;
970 
972  AnnotationPosition mLeftGridAnnotationPosition;
974  AnnotationPosition mRightGridAnnotationPosition;
976  AnnotationPosition mTopGridAnnotationPosition;
978  AnnotationPosition mBottomGridAnnotationPosition;
979 
981  double mAnnotationFrameDistance;
982 
984  AnnotationDirection mLeftGridAnnotationDirection;
986  AnnotationDirection mRightGridAnnotationDirection;
988  AnnotationDirection mTopGridAnnotationDirection;
990  AnnotationDirection mBottomGridAnnotationDirection;
991  AnnotationFormat mGridAnnotationFormat;
992 
993  QString mGridAnnotationExpressionString;
994  mutable std::unique_ptr< QgsExpression > mGridAnnotationExpression;
995 
996  FrameStyle mGridFrameStyle;
997  FrameSideFlags mGridFrameSides;
998  double mGridFrameWidth;
999  double mGridFramePenThickness;
1000  QColor mGridFramePenColor;
1001  QColor mGridFrameFillColor1;
1002  QColor mGridFrameFillColor2;
1003  double mCrossLength;
1004 
1006  DisplayMode mLeftFrameDivisions;
1008  DisplayMode mRightFrameDivisions;
1010  DisplayMode mTopFrameDivisions;
1012  DisplayMode mBottomFrameDivisions;
1013 
1014  QgsLineSymbol *mGridLineSymbol = nullptr;
1015  QgsMarkerSymbol *mGridMarkerSymbol = nullptr;
1016 
1018 
1019  GridUnit mGridUnit;
1020 
1021  QPainter::CompositionMode mBlendMode;
1022 
1023  QList< QPair< double, QPolygonF > > mTransformedXLines;
1024  QList< QPair< double, QPolygonF > > mTransformedYLines;
1025  QList< QgsPointXY > mTransformedIntersections;
1026  QRectF mPrevPaintRect;
1027  QPolygonF mPrevMapPolygon;
1028 
1029  class QgsMapAnnotation
1030  {
1031  public:
1032  double coordinate;
1033  QPointF itemPosition;
1035  };
1036 
1037  void init();
1038 
1043  void drawGridFrame( QPainter *p, const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, GridExtension *extension = nullptr ) const;
1044 
1054  void drawCoordinateAnnotations( QPainter *p, const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, QgsExpressionContext &expressionContext, GridExtension *extension = nullptr ) const;
1055 
1060  void drawCoordinateAnnotation( QPainter *p, QPointF pos, const QString &annotationString, const AnnotationCoordinate coordinateType, GridExtension *extension = nullptr ) const;
1061 
1069  void drawAnnotation( QPainter *p, QPointF pos, int rotation, const QString &annotationText ) const;
1070 
1071  QString gridAnnotationString( double value, AnnotationCoordinate coord, QgsExpressionContext &expressionContext ) const;
1072 
1076  int xGridLines( QList< QPair< double, QLineF > > &lines ) const;
1077 
1081  int yGridLines( QList< QPair< double, QLineF > > &lines ) const;
1082 
1083  int xGridLinesCrsTransform( const QgsRectangle &bbox, const QgsCoordinateTransform &t, QList< QPair< double, QPolygonF > > &lines ) const;
1084 
1085  int yGridLinesCrsTransform( const QgsRectangle &bbox, const QgsCoordinateTransform &t, QList< QPair< double, QPolygonF > > &lines ) const;
1086 
1087  void drawGridLine( const QLineF &line, QgsRenderContext &context ) const;
1088 
1089  void drawGridLine( const QPolygonF &line, QgsRenderContext &context ) const;
1090 
1091  void sortGridLinesOnBorders( const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, QMap< double, double > &leftFrameEntries,
1092  QMap< double, double > &rightFrameEntries, QMap< double, double > &topFrameEntries, QMap< double, double > &bottomFrameEntries ) const;
1093 
1098  void drawGridFrameBorder( QPainter *p, const QMap< double, double > &borderPos, BorderSide border, double *extension = nullptr ) const;
1099 
1105  BorderSide borderForLineCoord( QPointF p, const AnnotationCoordinate coordinateType ) const;
1106 
1108  int crsGridParams( QgsRectangle &crsRect, QgsCoordinateTransform &inverseTransform ) const;
1109 
1110  static QList<QPolygonF> trimLinesToMap( const QPolygonF &line, const QgsRectangle &rect );
1111 
1112  QPolygonF scalePolygon( const QPolygonF &polygon, const double scale ) const;
1113 
1115  void drawGridCrsTransform( QgsRenderContext &context, double dotsPerMM, QList< QPair< double, QLineF > > &horizontalLines,
1116  QList< QPair< double, QLineF > > &verticalLines, bool calculateLinesOnly = false );
1117 
1118  void drawGridNoTransform( QgsRenderContext &context, double dotsPerMM, QList<QPair<double, QLineF> > &horizontalLines, QList<QPair<double, QLineF> > &verticalLines, bool calculateLinesOnly = false ) const;
1119 
1120  void createDefaultGridLineSymbol();
1121 
1122  void createDefaultGridMarkerSymbol();
1123 
1124  void drawGridMarker( QPointF point, QgsRenderContext &context ) const;
1125 
1126  void drawGridFrameZebraBorder( QPainter *p, const QMap<double, double> &borderPos, BorderSide border, double *extension = nullptr ) const;
1127 
1128  void drawGridFrameTicks( QPainter *p, const QMap<double, double> &borderPos, BorderSide border, double *extension = nullptr ) const;
1129 
1130  void drawGridFrameLineBorder( QPainter *p, BorderSide border, double *extension = nullptr ) const;
1131 
1132  void calculateCrsTransformLines();
1133 
1134  bool shouldShowDivisionForSide( AnnotationCoordinate coordinate, BorderSide side ) const;
1135  bool shouldShowDivisionForDisplayMode( AnnotationCoordinate coordinate, DisplayMode mode ) const;
1136 
1137  friend class TestQgsComposerMapGrid;
1138 };
1139 
1140 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsComposerMapGrid::FrameSideFlags )
1141 
1142 #endif // QGSCOMPOSERMAPGRID_H
QColor annotationFontColor() const
Gets the font color used for drawing grid annotations.
A rectangle specified with double values.
Definition: qgsrectangle.h:39
QFont annotationFont() const
Gets the font used for drawing grid annotations.
QColor frameFillColor2() const
Retrieves the second fill color for the grid frame.
void setBlendMode(const QPainter::CompositionMode mode)
Sets the blending mode used for drawing the grid.
virtual bool readXml(const QDomElement &itemElem, const QDomDocument &doc) override
Sets map item state from a DOM document.
virtual QgsExpressionContext createExpressionContext() const
Creates an expression context relating to the objects&#39; current state.
double intervalY() const
Gets the interval between grid lines in the y-direction.
GridStyle
Grid drawing style.
QPainter::CompositionMode blendMode() const
Retrieves the blending mode used for drawing the grid.
virtual void draw(QPainter *painter)=0
Draws the item on to a painter.
Draw line crosses at intersections of grid lines.
void setFramePenSize(const double width)
Sets the width of the stroke drawn in the grid frame.
Degree/minutes, with minutes using leading zeros where required.
QString annotationExpression() const
Returns the expression used for drawing grid annotations.
A collection of grids which is drawn above the map content in a QgsComposerMap.
FrameStyle
Style for grid frame.
virtual bool writeXml(QDomElement &elem, QDomDocument &doc) const override
Stores map item state in DOM element.
Draw annotations outside the map frame.
QColor frameFillColor1() const
Retrieves the first fill color for the grid frame.
virtual bool readXml(const QDomElement &elem, const QDomDocument &doc)=0
Sets the item stack&#39;s state from a DOM document.
void setAnnotationExpression(const QString &expression)
Sets the expression used for drawing grid annotations.
double intervalX() const
Gets the interval between grid lines in the x-direction.
Tick markers drawn outside map frame.
void setAnnotationFont(const QFont &font)
Sets the font used for drawing grid annotations.
Degree/minutes, use NSEW suffix.
const QgsLineSymbol * lineSymbol() const
Gets the line symbol used for drawing grid lines.
AnnotationDirection
Direction of grid annotations.
QColor framePenColor() const
Retrieves the color of the stroke drawn in the grid frame.
double crossLength() const
Retrieves the length of the cross segments drawn for the grid.
AnnotationFormat
Format for displaying grid annotations.
An item which is drawn inside a QgsComposerMap, e.g., a grid or map overview.
void setCrossLength(const double length)
Sets the length of the cross segments drawn for the grid.
Show latitude/y annotations/divisions only.
Black/white pattern.
QgsMarkerSymbol * markerSymbol()
Gets the marker symbol used for drawing grid points.
#define SIP_SKIP
Definition: qgis_sip.h:119
double offsetY() const
Gets the offset for grid lines in the y-direction.
FrameStyle frameStyle() const
Gets the grid frame style.
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
DisplayMode
Display settings for grid annotations and frames.
void setAnnotationFormat(const AnnotationFormat format)
Sets the format for drawing grid annotations.
AnnotationPosition
Position for grid annotations.
double frameWidth() const
Gets the grid frame width.
Grid units in millimeters.
#define SIP_TRANSFER
Definition: qgis_sip.h:36
void setAnnotationEnabled(const bool enabled)
Sets whether annotations should be shown for the grid.
GridStyle style() const
Gets the grid&#39;s style, which controls how the grid is drawn over the map&#39;s contents.
QgsComposerMapItem & operator[](int idx)
Returns a reference to an item within the stack.
FrameSideFlag
Flags for controlling which side of the map a frame is drawn on.
Decimal degrees, use NSEW suffix.
An individual grid which is drawn above the map content in a QgsComposerMap.
void setFrameWidth(const double width)
Sets the grid frame width.
bool annotationEnabled() const
Gets whether annotations are shown for the grid.
void setAnnotationFontColor(const QColor &color)
Sets the font color used for drawing grid annotations.
int annotationPrecision() const
Returns the coordinate precision for grid annotations.
Object representing map window.
QList< QgsComposerMapItem *> asList() const
Returns a list of QgsComposerMapItems contained by the stack.
BorderSide
Border sides for annotations.
void setFrameFillColor1(const QColor &color)
Sets the first fill color used for the grid frame.
void setFramePenColor(const QColor &color)
Sets the color of the stroke drawn in the grid frame.
Degree/minutes/seconds, use NSEW suffix.
double annotationFrameDistance() const
Gets the distance between the map frame and annotations.
double offsetX() const
Gets the offset for grid lines in the x-direction.
Degree/minutes/seconds, with minutes using leading zeros where required.
virtual bool enabled() const
Returns whether the item will be drawn.
Contains information about the context of a rendering operation.
AnnotationFormat annotationFormat() const
Gets the format for drawing grid annotations.
QgsLineSymbol * lineSymbol()
Gets the line symbol used for drawing grid lines.
A collection of map items which are drawn above the map content in a QgsComposerMap.
const QgsMarkerSymbol * markerSymbol() const
Gets the marker symbol used for drawing grid points.
Draw annotations vertically, descending.
This class represents a coordinate reference system (CRS).
void setAnnotationPrecision(const int precision)
Sets the coordinate precision for grid annotations.
virtual bool usesAdvancedEffects() const
Returns true if the item is drawn using advanced effects, such as blend modes.
Class for doing transforms between two map coordinate systems.
Tick markers drawn both inside and outside the map frame.
Degree/minutes, use - for S/W coordinates.
GridUnit units() const
Gets the units used for grid measurements such as the interval and offset for grid lines...
Draw markers at intersections of grid lines.
void setFrameFillColor2(const QColor &color)
Sets the second fill color used for the grid frame.
void setFrameStyle(const FrameStyle style)
Sets the grid frame style.
Draw annotations vertically, ascending.
Degree/minutes/seconds, use - for S/W coordinates.
GridUnit
Unit for grid values.
QgsCoordinateReferenceSystem crs() const
Retrieves the CRS for the grid.
Show longitude/x annotations/divisions only.
Grid units follow map units.
AnnotationCoordinate
Annotation coordinate type.
double framePenSize() const
Retrieves the width of the stroke drawn in the grid frame.
void setAnnotationFrameDistance(const double distance)
Sets the distance between the map frame and annotations.
Tick markers drawn inside map frame.