QGIS API Documentation  2.99.0-Master (ba079d8)
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 
49 {
50  public:
51 
56 
65  void addGrid( QgsComposerMapGrid *grid SIP_TRANSFER );
66 
73  void removeGrid( const QString &gridId );
74 
81  void moveGridUp( const QString &gridId );
82 
89  void moveGridDown( const QString &gridId );
90 
96  const QgsComposerMapGrid *constGrid( const QString &gridId ) const;
97 
103  QgsComposerMapGrid *grid( const QString &gridId ) const;
104 
110  QgsComposerMapGrid *grid( const int index ) const;
111 
118  QgsComposerMapGrid &operator[]( int idx );
119 
123  QList< QgsComposerMapGrid * > asList() const;
124 
131  bool readXml( const QDomElement &elem, const QDomDocument &doc ) override;
132 
138  double maxGridExtension() const;
139 
150  void calculateMaxGridExtension( double &top, double &right, double &bottom, double &left ) const;
151 };
152 
153 //
154 // QgsComposerMapGrid
155 //
156 
164 class CORE_EXPORT QgsComposerMapGrid : public QgsComposerMapItem
165 {
166 
167  Q_OBJECT
168 
169  public:
170 
173  enum GridUnit
174  {
176  MM,
177  CM
178  };
179 
183  {
184  Solid = 0,
187  FrameAnnotationsOnly
188  };
189 
193  {
194  ShowAll = 0,
197  HideAll
198  };
199 
203  {
204  InsideMapFrame = 0,
206  };
207 
211  {
212  Horizontal = 0,
215  BoundaryDirection
216  };
217 
221  {
222  Decimal = 0,
230  CustomFormat
231  };
232 
236  {
240  Top
241  };
242 
246  {
247  NoFrame = 0,
252  LineBorder
253  };
254 
258  {
259  FrameLeft = 0x01,
260  FrameRight = 0x02,
261  FrameTop = 0x04,
262  FrameBottom = 0x08
263  };
264  Q_DECLARE_FLAGS( FrameSideFlags, FrameSideFlag )
265 
266 
269  {
270  Longitude = 0,
271  Latitude
272  };
273 
278  QgsComposerMapGrid( const QString &name, QgsComposerMap *map );
279 
280  virtual ~QgsComposerMapGrid();
281 
285  void draw( QPainter *painter ) override;
286 
292  bool writeXml( QDomElement &elem, QDomDocument &doc ) const override;
293 
299  bool readXml( const QDomElement &itemElem, const QDomDocument &doc ) override;
300 
305  void setCrs( const QgsCoordinateReferenceSystem &crs );
306 
311  QgsCoordinateReferenceSystem crs() const { return mCRS; }
312 
317  void setBlendMode( const QPainter::CompositionMode mode ) { mBlendMode = mode; }
318 
323  QPainter::CompositionMode blendMode() const { return mBlendMode; }
324 
325  bool usesAdvancedEffects() const override;
326 
331  double maxExtension();
332 
343  void calculateMaxExtension( double &top, double &right, double &bottom, double &left );
344 
345  //
346  // GRID UNITS
347  //
348 
354  void setUnits( const GridUnit unit );
355 
361  GridUnit units() const { return mGridUnit; }
362 
369  void setIntervalX( const double interval );
370 
377  double intervalX() const { return mGridIntervalX; }
378 
385  void setIntervalY( const double interval );
386 
393  double intervalY() const { return mGridIntervalY; }
394 
401  void setOffsetX( const double offset );
402 
409  double offsetX() const { return mGridOffsetX; }
410 
417  void setOffsetY( const double offset );
418 
425  double offsetY() const { return mGridOffsetY; }
426 
427  //
428  // GRID APPEARANCE
429  //
430 
436  void setStyle( const GridStyle style );
437 
443  GridStyle style() const { return mGridStyle; }
444 
450  void setCrossLength( const double length ) { mCrossLength = length; }
451 
457  double crossLength() const { return mCrossLength; }
458 
466  void setGridLineWidth( const double width );
467 
475  void setGridLineColor( const QColor &color );
476 
484  void setLineSymbol( QgsLineSymbol *symbol SIP_TRANSFER );
485 
494  const QgsLineSymbol *lineSymbol() const { return mGridLineSymbol; } SIP_SKIP
495 
503  QgsLineSymbol *lineSymbol() { return mGridLineSymbol; }
504 
512  void setMarkerSymbol( QgsMarkerSymbol *symbol );
513 
522  const QgsMarkerSymbol *markerSymbol() const { return mGridMarkerSymbol; } SIP_SKIP
523 
531  QgsMarkerSymbol *markerSymbol() { return mGridMarkerSymbol; }
532 
533  //
534  // ANNOTATIONS
535  //
536 
541  void setAnnotationEnabled( const bool enabled ) { mShowGridAnnotation = enabled; }
542 
547  bool annotationEnabled() const { return mShowGridAnnotation; }
548 
553  void setAnnotationFont( const QFont &font ) { mGridAnnotationFont = font; }
554 
559  QFont annotationFont() const { return mGridAnnotationFont; }
560 
565  void setAnnotationFontColor( const QColor &color ) { mGridAnnotationFontColor = color; }
566 
571  QColor annotationFontColor() const { return mGridAnnotationFontColor; }
572 
577  void setAnnotationPrecision( const int precision ) { mGridAnnotationPrecision = precision; }
578 
583  int annotationPrecision() const { return mGridAnnotationPrecision; }
584 
592  void setAnnotationDisplay( const DisplayMode display, const BorderSide border );
593 
602  DisplayMode annotationDisplay( const BorderSide border ) const;
603 
610  void setAnnotationPosition( const AnnotationPosition position, const BorderSide border );
611 
618  AnnotationPosition annotationPosition( const BorderSide border ) const;
619 
624  void setAnnotationFrameDistance( const double distance ) { mAnnotationFrameDistance = distance; }
625 
630  double annotationFrameDistance() const { return mAnnotationFrameDistance; }
631 
637  void setAnnotationDirection( const AnnotationDirection direction, const BorderSide border );
638 
643  void setAnnotationDirection( const AnnotationDirection direction );
644 
650  AnnotationDirection annotationDirection( const BorderSide border ) const;
651 
656  void setAnnotationFormat( const AnnotationFormat format ) { mGridAnnotationFormat = format; }
657 
662  AnnotationFormat annotationFormat() const { return mGridAnnotationFormat; }
663 
670  void setAnnotationExpression( const QString &expression ) { mGridAnnotationExpressionString = expression; mGridAnnotationExpression.reset(); }
671 
678  QString annotationExpression() const { return mGridAnnotationExpressionString; }
679 
680  //
681  // GRID FRAME
682  //
683 
688  void setFrameStyle( const FrameStyle style ) { mGridFrameStyle = style; }
689 
694  FrameStyle frameStyle() const { return mGridFrameStyle; }
695 
702  void setFrameDivisions( const DisplayMode divisions, const BorderSide border );
703 
710  DisplayMode frameDivisions( const BorderSide border ) const;
711 
719  void setFrameSideFlags( QgsComposerMapGrid::FrameSideFlags flags );
720 
728  void setFrameSideFlag( const FrameSideFlag flag, bool on = true );
729 
737  FrameSideFlags frameSideFlags() const;
738 
747  bool testFrameSideFlag( const FrameSideFlag flag ) const;
748 
755  void setFrameWidth( const double width ) { mGridFrameWidth = width; }
756 
763  double frameWidth() const { return mGridFrameWidth; }
764 
770  void setFramePenSize( const double width ) { mGridFramePenThickness = width; }
771 
777  double framePenSize() const { return mGridFramePenThickness; }
778 
786  void setFramePenColor( const QColor &color ) { mGridFramePenColor = color; }
787 
795  QColor framePenColor() const {return mGridFramePenColor;}
796 
803  void setFrameFillColor1( const QColor &color ) { mGridFrameFillColor1 = color; }
804 
811  QColor frameFillColor1() const { return mGridFrameFillColor1; }
812 
819  void setFrameFillColor2( const QColor &color ) { mGridFrameFillColor2 = color; }
820 
827  QColor frameFillColor2() const { return mGridFrameFillColor2; }
828 
829  virtual QgsExpressionContext createExpressionContext() const override;
830 
831  private:
832 
833  QgsComposerMapGrid(); //forbidden
834 
835  struct GridExtension
836  {
837  GridExtension()
838  : top( 0.0 )
839  , right( 0.0 )
840  , bottom( 0.0 )
841  , left( 0.0 )
842  {}
843  double top;
844  double right;
845  double bottom;
846  double left;
847  };
848 
849  /*True if a re-transformation of grid lines is required*/
850  bool mTransformDirty;
851 
853  GridStyle mGridStyle;
855  double mGridIntervalX;
857  double mGridIntervalY;
859  double mGridOffsetX;
861  double mGridOffsetY;
863  QFont mGridAnnotationFont;
865  QColor mGridAnnotationFontColor;
867  int mGridAnnotationPrecision;
869  bool mShowGridAnnotation;
870 
872  DisplayMode mLeftGridAnnotationDisplay;
874  DisplayMode mRightGridAnnotationDisplay;
876  DisplayMode mTopGridAnnotationDisplay;
878  DisplayMode mBottomGridAnnotationDisplay;
879 
881  AnnotationPosition mLeftGridAnnotationPosition;
883  AnnotationPosition mRightGridAnnotationPosition;
885  AnnotationPosition mTopGridAnnotationPosition;
887  AnnotationPosition mBottomGridAnnotationPosition;
888 
890  double mAnnotationFrameDistance;
891 
893  AnnotationDirection mLeftGridAnnotationDirection;
895  AnnotationDirection mRightGridAnnotationDirection;
897  AnnotationDirection mTopGridAnnotationDirection;
899  AnnotationDirection mBottomGridAnnotationDirection;
900  AnnotationFormat mGridAnnotationFormat;
901 
902  QString mGridAnnotationExpressionString;
903  mutable std::unique_ptr< QgsExpression > mGridAnnotationExpression;
904 
905  FrameStyle mGridFrameStyle;
906  FrameSideFlags mGridFrameSides;
907  double mGridFrameWidth;
908  double mGridFramePenThickness;
909  QColor mGridFramePenColor;
910  QColor mGridFrameFillColor1;
911  QColor mGridFrameFillColor2;
912  double mCrossLength;
913 
915  DisplayMode mLeftFrameDivisions;
917  DisplayMode mRightFrameDivisions;
919  DisplayMode mTopFrameDivisions;
921  DisplayMode mBottomFrameDivisions;
922 
923  QgsLineSymbol *mGridLineSymbol = nullptr;
924  QgsMarkerSymbol *mGridMarkerSymbol = nullptr;
925 
927 
928  GridUnit mGridUnit;
929 
930  QPainter::CompositionMode mBlendMode;
931 
932  QList< QPair< double, QPolygonF > > mTransformedXLines;
933  QList< QPair< double, QPolygonF > > mTransformedYLines;
934  QList< QgsPoint > mTransformedIntersections;
935  QRectF mPrevPaintRect;
936  QPolygonF mPrevMapPolygon;
937 
938  class QgsMapAnnotation
939  {
940  public:
941  double coordinate;
942  QPointF itemPosition;
944  };
945 
946  void init();
947 
951  void drawGridFrame( QPainter *p, const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, GridExtension *extension = nullptr ) const;
952 
961  void drawCoordinateAnnotations( QPainter *p, const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, QgsExpressionContext &expressionContext, GridExtension *extension = nullptr ) const;
962 
966  void drawCoordinateAnnotation( QPainter *p, QPointF pos, const QString &annotationString, const AnnotationCoordinate coordinateType, GridExtension *extension = nullptr ) const;
967 
974  void drawAnnotation( QPainter *p, QPointF pos, int rotation, const QString &annotationText ) const;
975 
976  QString gridAnnotationString( double value, AnnotationCoordinate coord, QgsExpressionContext &expressionContext ) const;
977 
980  int xGridLines( QList< QPair< double, QLineF > > &lines ) const;
981 
984  int yGridLines( QList< QPair< double, QLineF > > &lines ) const;
985 
986  int xGridLinesCrsTransform( const QgsRectangle &bbox, const QgsCoordinateTransform &t, QList< QPair< double, QPolygonF > > &lines ) const;
987 
988  int yGridLinesCrsTransform( const QgsRectangle &bbox, const QgsCoordinateTransform &t, QList< QPair< double, QPolygonF > > &lines ) const;
989 
990  void drawGridLine( const QLineF &line, QgsRenderContext &context ) const;
991 
992  void drawGridLine( const QPolygonF &line, QgsRenderContext &context ) const;
993 
994  void sortGridLinesOnBorders( const QList< QPair< double, QLineF > > &hLines, const QList< QPair< double, QLineF > > &vLines, QMap< double, double > &leftFrameEntries,
995  QMap< double, double > &rightFrameEntries, QMap< double, double > &topFrameEntries, QMap< double, double > &bottomFrameEntries ) const;
996 
1000  void drawGridFrameBorder( QPainter *p, const QMap< double, double > &borderPos, BorderSide border, double *extension = nullptr ) const;
1001 
1006  BorderSide borderForLineCoord( QPointF p, const AnnotationCoordinate coordinateType ) const;
1007 
1009  int crsGridParams( QgsRectangle &crsRect, QgsCoordinateTransform &inverseTransform ) const;
1010 
1011  static QList<QPolygonF> trimLinesToMap( const QPolygonF &line, const QgsRectangle &rect );
1012 
1013  QPolygonF scalePolygon( const QPolygonF &polygon, const double scale ) const;
1014 
1016  void drawGridCrsTransform( QgsRenderContext &context, double dotsPerMM, QList< QPair< double, QLineF > > &horizontalLines,
1017  QList< QPair< double, QLineF > > &verticalLines, bool calculateLinesOnly = false );
1018 
1019  void drawGridNoTransform( QgsRenderContext &context, double dotsPerMM, QList<QPair<double, QLineF> > &horizontalLines, QList<QPair<double, QLineF> > &verticalLines, bool calculateLinesOnly = false ) const;
1020 
1021  void createDefaultGridLineSymbol();
1022 
1023  void createDefaultGridMarkerSymbol();
1024 
1025  void drawGridMarker( QPointF point, QgsRenderContext &context ) const;
1026 
1027  void drawGridFrameZebraBorder( QPainter *p, const QMap<double, double> &borderPos, BorderSide border, double *extension = nullptr ) const;
1028 
1029  void drawGridFrameTicks( QPainter *p, const QMap<double, double> &borderPos, BorderSide border, double *extension = nullptr ) const;
1030 
1031  void drawGridFrameLineBorder( QPainter *p, BorderSide border, double *extension = nullptr ) const;
1032 
1033  void calculateCrsTransformLines();
1034 
1035  bool shouldShowDivisionForSide( AnnotationCoordinate coordinate, BorderSide side ) const;
1036  bool shouldShowDivisionForDisplayMode( AnnotationCoordinate coordinate, DisplayMode mode ) const;
1037 
1038  friend class TestQgsComposerMapGrid;
1039 };
1040 
1041 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsComposerMapGrid::FrameSideFlags )
1042 
1043 #endif // QGSCOMPOSERMAPGRID_H
QColor annotationFontColor() const
Gets the font color used for drawing grid annotations.
A rectangle specified with double values.
Definition: qgsrectangle.h:38
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:102
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:24
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.