QGIS API Documentation  3.8.0-Zanzibar (11aff65)
qgslayoutitem.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgslayoutitem.h
3  -------------------
4  begin : June 2017
5  copyright : (C) 2017 by Nyall Dawson
6  email : nyall dot dawson at gmail dot com
7  ***************************************************************************/
8 /***************************************************************************
9  * *
10  * This program is free software; you can redistribute it and/or modify *
11  * it under the terms of the GNU General Public License as published by *
12  * the Free Software Foundation; either version 2 of the License, or *
13  * (at your option) any later version. *
14  * *
15  ***************************************************************************/
16 
17 #ifndef QGSLAYOUTITEM_H
18 #define QGSLAYOUTITEM_H
19 
20 #include "qgis_core.h"
21 #include "qgslayoutobject.h"
22 #include "qgslayoutsize.h"
23 #include "qgslayoutpoint.h"
24 #include "qgsrendercontext.h"
25 #include "qgslayoutundocommand.h"
26 #include "qgslayoutmeasurement.h"
27 #include "qgsapplication.h"
28 #include <QGraphicsRectItem>
29 #include <QIcon>
30 #include <QPainter>
31 
32 class QgsLayout;
33 class QPainter;
34 class QgsLayoutItemGroup;
35 class QgsLayoutEffect;
36 
37 
44 class CORE_EXPORT QgsLayoutItemRenderContext
45 {
46  public:
47 
58  QgsLayoutItemRenderContext( QgsRenderContext &context, double viewScaleFactor = 1.0 );
59 
62 
64  QgsLayoutItemRenderContext &operator=( const QgsLayoutItemRenderContext &other ) = delete;
65 
72  QgsRenderContext &renderContext() { return mRenderContext; }
73 
82  const QgsRenderContext &renderContext() const { return mRenderContext; } SIP_SKIP
83 
94  double viewScaleFactor() const { return mViewScaleFactor; }
95 
96  private:
97 
98 #ifdef SIP_RUN
100 #endif
101 
102  QgsRenderContext &mRenderContext;
103  double mViewScaleFactor = 1.0;
104 };
105 
112 class CORE_EXPORT QgsLayoutItem : public QgsLayoutObject, public QGraphicsRectItem, public QgsLayoutUndoObjectInterface
113 {
114 #ifdef SIP_RUN
115 #include "qgslayoutitemgroup.h"
116 #include "qgslayoutitemmap.h"
117 #include "qgslayoutitempicture.h"
118 #include "qgslayoutitemlabel.h"
119 #include "qgslayoutitemlegend.h"
120 #include "qgslayoutitempolygon.h"
121 #include "qgslayoutitempolyline.h"
122 #include "qgslayoutitemscalebar.h"
123 #include "qgslayoutframe.h"
124 #include "qgslayoutitemshape.h"
125 #include "qgslayoutitempage.h"
126 #endif
127 
128 #ifdef SIP_RUN
130 
131  // FREAKKKKIIN IMPORTANT!!!!!!!!!!!
132  // IF YOU PUT SOMETHING HERE, PUT IT IN QgsLayoutObject CASTING *****ALSO******
133  // (it's not enough for it to be in only one of the places, as sip inconsistently
134  // decides which casting code to perform here)
135 
136  // the conversions have to be static, because they're using multiple inheritance
137  // (seen in PyQt4 .sip files for some QGraphicsItem classes)
138  switch ( sipCpp->type() )
139  {
140  // really, these *should* use the constants from QgsLayoutItemRegistry, but sip doesn't like that!
141  case QGraphicsItem::UserType + 101:
142  sipType = sipType_QgsLayoutItemGroup;
143  *sipCppRet = static_cast<QgsLayoutItemGroup *>( sipCpp );
144  break;
145  case QGraphicsItem::UserType + 102:
146  sipType = sipType_QgsLayoutItemPage;
147  *sipCppRet = static_cast<QgsLayoutItemPage *>( sipCpp );
148  break;
149  case QGraphicsItem::UserType + 103:
150  sipType = sipType_QgsLayoutItemMap;
151  *sipCppRet = static_cast<QgsLayoutItemMap *>( sipCpp );
152  break;
153  case QGraphicsItem::UserType + 104:
154  sipType = sipType_QgsLayoutItemPicture;
155  *sipCppRet = static_cast<QgsLayoutItemPicture *>( sipCpp );
156  break;
157  case QGraphicsItem::UserType + 105:
158  sipType = sipType_QgsLayoutItemLabel;
159  *sipCppRet = static_cast<QgsLayoutItemLabel *>( sipCpp );
160  break;
161  case QGraphicsItem::UserType + 106:
162  sipType = sipType_QgsLayoutItemLegend;
163  *sipCppRet = static_cast<QgsLayoutItemLegend *>( sipCpp );
164  break;
165  case QGraphicsItem::UserType + 107:
166  sipType = sipType_QgsLayoutItemShape;
167  *sipCppRet = static_cast<QgsLayoutItemShape *>( sipCpp );
168  break;
169  case QGraphicsItem::UserType + 108:
170  sipType = sipType_QgsLayoutItemPolygon;
171  *sipCppRet = static_cast<QgsLayoutItemPolygon *>( sipCpp );
172  break;
173  case QGraphicsItem::UserType + 109:
174  sipType = sipType_QgsLayoutItemPolyline;
175  *sipCppRet = static_cast<QgsLayoutItemPolyline *>( sipCpp );
176  break;
177  case QGraphicsItem::UserType + 110:
178  sipType = sipType_QgsLayoutItemScaleBar;
179  *sipCppRet = static_cast<QgsLayoutItemScaleBar *>( sipCpp );
180  break;
181  case QGraphicsItem::UserType + 111:
182  sipType = sipType_QgsLayoutFrame;
183  *sipCppRet = static_cast<QgsLayoutFrame *>( sipCpp );
184  break;
185 
186  // did you read that comment above? NO? Go read it now. You're about to break stuff.
187 
188  default:
189  sipType = NULL;
190  }
191  SIP_END
192 #endif
193 
194 
195  Q_OBJECT
196  Q_PROPERTY( bool locked READ isLocked WRITE setLocked NOTIFY lockChanged )
197 
198  public:
199 
202  {
212  };
213 
216  {
217  UndoNone = -1,
218  UndoIncrementalMove = 1,
288 
290  };
291 
296  enum Flag
297  {
298  FlagOverridesPaint = 1 << 1,
299  };
300  Q_DECLARE_FLAGS( Flags, Flag )
301 
302 
308  explicit QgsLayoutItem( QgsLayout *layout, bool manageZValue = true );
309 
310  ~QgsLayoutItem() override;
311 
316  virtual void cleanup();
317 
323  int type() const override;
324 
328  virtual QIcon icon() const { return QgsApplication::getThemeIcon( QStringLiteral( "/mLayoutItem.svg" ) ); }
329 
337  virtual QString uuid() const { return mUuid; }
338 
343  virtual Flags itemFlags() const;
344 
351  QString id() const { return mId; }
352 
359  virtual void setId( const QString &id );
360 
367  virtual QString displayName() const;
368 
372  virtual void setSelected( bool selected );
373 
380  virtual void setVisibility( bool visible );
381 
387  void setLocked( bool locked );
388 
394  bool isLocked() const { return mIsLocked; }
395 
401  bool isGroupMember() const;
402 
408  QgsLayoutItemGroup *parentGroup() const;
409 
415  void setParentGroup( QgsLayoutItemGroup *group );
416 
425  virtual int numberExportLayers() const { return 0; }
426 
432  void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget ) override;
433 
440  void setReferencePoint( ReferencePoint point );
441 
448  ReferencePoint referencePoint() const { return mReferencePoint; }
449 
456  virtual QgsLayoutSize fixedSize() const { return mFixedSize; }
457 
464  virtual QgsLayoutSize minimumSize() const { return mMinimumSize; }
465 
480  virtual void attemptResize( const QgsLayoutSize &size, bool includesFrame = false );
481 
507  virtual void attemptMove( const QgsLayoutPoint &point, bool useReferencePoint = true, bool includesFrame = false, int page = -1 );
508 
524  void attemptSetSceneRect( const QRectF &rect, bool includesFrame = false );
525 
538  void attemptMoveBy( double deltaX, double deltaY );
539 
548  QgsLayoutPoint positionWithUnits() const { return mItemPosition; }
549 
554  int page() const;
555 
561  QPointF pagePos() const;
562 
568  QgsLayoutPoint pagePositionWithUnits() const;
569 
575  QgsLayoutSize sizeWithUnits() const { return mItemSize; }
576 
587  double itemRotation() const;
588 
596  bool writeXml( QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context ) const;
597 
613  bool readXml( const QDomElement &itemElement, const QDomDocument &document, const QgsReadWriteContext &context );
614 
623  virtual void finalizeRestoreFromXml();
624 
625  QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id, QUndoCommand *parent = nullptr ) override SIP_FACTORY;
626 
634  bool frameEnabled() const { return mFrame; }
635 
643  virtual void setFrameEnabled( bool drawFrame );
644 
652  void setFrameStrokeColor( const QColor &color );
653 
661  QColor frameStrokeColor() const { return mFrameColor; }
662 
670  virtual void setFrameStrokeWidth( QgsLayoutMeasurement width );
671 
679  QgsLayoutMeasurement frameStrokeWidth() const { return mFrameWidth; }
680 
688  Qt::PenJoinStyle frameJoinStyle() const { return mFrameJoinStyle; }
689 
697  void setFrameJoinStyle( Qt::PenJoinStyle style );
698 
704  bool hasBackground() const { return mBackground; }
705 
711  void setBackgroundEnabled( bool drawBackground );
712 
719  QColor backgroundColor() const { return mBackgroundColor; }
720 
726  void setBackgroundColor( const QColor &color );
727 
732  QPainter::CompositionMode blendMode() const { return mBlendMode; }
733 
738  void setBlendMode( QPainter::CompositionMode mode );
739 
747  double itemOpacity() const { return mOpacity; }
748 
756  void setItemOpacity( double opacity );
757 
762  bool excludeFromExports() const;
763 
768  void setExcludeFromExports( bool exclude );
769 
779  virtual bool containsAdvancedEffects() const;
780 
786  virtual bool requiresRasterization() const;
787 
798  virtual double estimatedFrameBleed() const;
799 
809  virtual QRectF rectWithFrame() const;
810 
817  virtual void moveContent( double dx, double dy );
818 
825  virtual void setMoveContentPreviewOffset( double dx, double dy );
826 
833  virtual void zoomContent( double factor, QPointF point );
834 
843  void beginCommand( const QString &commandText, UndoCommand command = UndoNone );
844 
850  void endCommand();
851 
857  void cancelCommand();
858 
862  bool shouldDrawItem() const;
863 
865 
866  public slots:
867 
872  void refresh() override;
873 
877  virtual void invalidateCache();
878 
882  virtual void redraw();
883 
890  virtual void refreshDataDefinedProperty( QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties );
891 
901  virtual void setItemRotation( double rotation, bool adjustPosition = true );
902 
908  virtual void rotateItem( double angle, QPointF transformOrigin );
909 
910  signals:
911 
915  void frameChanged();
916 
922  void lockChanged();
923 
927  void rotationChanged( double newRotation );
928 
932  void sizePositionChanged();
933 
934  protected:
935 
941  virtual void drawDebugRect( QPainter *painter );
942 
949  virtual void draw( QgsLayoutItemRenderContext &context ) = 0;
950 
954  virtual void drawFrame( QgsRenderContext &context );
955 
959  virtual void drawBackground( QgsRenderContext &context );
960 
967  virtual void setFixedSize( const QgsLayoutSize &size );
968 
975  virtual void setMinimumSize( const QgsLayoutSize &size );
976 
985  virtual QSizeF applyItemSizeConstraint( QSizeF targetSize );
986 
994  void refreshItemSize();
995 
1001  void refreshItemPosition();
1002 
1013  void refreshItemRotation( QPointF *origin = nullptr );
1014 
1020  void refreshOpacity( bool updateItem = true );
1021 
1027  void refreshFrame( bool updateItem = true );
1028 
1034  void refreshBackgroundColor( bool updateItem = true );
1035 
1039  void refreshBlendMode();
1040 
1045  QPointF adjustPointForReferencePosition( QPointF point, QSizeF size, ReferencePoint reference ) const;
1046 
1050  QPointF positionAtReferencePoint( ReferencePoint reference ) const;
1051 
1056  QgsLayoutPoint topLeftToReferencePoint( const QgsLayoutPoint &point ) const;
1057 
1066  virtual bool writePropertiesToElement( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
1067 
1083  virtual bool readPropertiesFromElement( const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context );
1084 
1088  QgsLayoutSize applyDataDefinedSize( const QgsLayoutSize &size );
1089 
1090  private:
1091 
1092  // true if layout manages the z value for this item
1093  bool mLayoutManagesZValue = false;
1094 
1096  QString mId;
1097 
1099  QString mUuid;
1100 
1102  QString mTemplateUuid;
1103 
1105  QString mParentGroupUuid;
1106 
1107  ReferencePoint mReferencePoint = UpperLeft;
1108  QgsLayoutSize mFixedSize;
1109  QgsLayoutSize mMinimumSize;
1110 
1111  QgsLayoutSize mItemSize;
1112  QgsLayoutPoint mItemPosition;
1113  double mItemRotation = 0.0;
1114 
1116  bool mExcludeFromExports = false;
1117 
1122  bool mEvaluatedExcludeFromExports = false;
1123 
1125  QPainter::CompositionMode mBlendMode = QPainter::CompositionMode_SourceOver;
1126  std::unique_ptr< QgsLayoutEffect > mEffect;
1127 
1129  double mOpacity = 1.0;
1130  double mEvaluatedOpacity = 1.0;
1131 
1132  QImage mItemCachedImage;
1133  double mItemCacheDpi = -1;
1134 
1135  bool mIsLocked = false;
1136 
1138  bool mFrame = false;
1140  QColor mFrameColor = QColor( 0, 0, 0 );
1144  Qt::PenJoinStyle mFrameJoinStyle = Qt::MiterJoin;
1145 
1147  bool mBackground = true;
1149  QColor mBackgroundColor = QColor( 255, 255, 255 );
1150 
1151  bool mBlockUndoCommands = false;
1152 
1153  void initConnectionsToLayout();
1154 
1156  void preparePainter( QPainter *painter );
1157  bool shouldDrawAntialiased() const;
1158  bool shouldDrawDebugRect() const;
1159  QSizeF applyMinimumSize( QSizeF targetSize );
1160  QSizeF applyFixedSize( QSizeF targetSize );
1161  QgsLayoutPoint applyDataDefinedPosition( const QgsLayoutPoint &position );
1162 
1163  double applyDataDefinedRotation( double rotation );
1164  void updateStoredItemPosition();
1165  QPointF itemPositionAtReferencePoint( ReferencePoint reference, QSizeF size ) const;
1166  void setScenePos( QPointF destinationPos );
1167  bool shouldBlockUndoCommands() const;
1168 
1169  void applyDataDefinedOrientation( double &width, double &height, const QgsExpressionContext &context );
1170 
1171  friend class TestQgsLayoutItem;
1172  friend class TestQgsLayoutView;
1173  friend class QgsLayout;
1174  friend class QgsLayoutItemGroup;
1176 };
1177 
1178 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLayoutItem::Flags )
1179 
1180 #endif //QGSLAYOUTITEM_H
1181 
1182 
1183 
Map rotation changed.
The class is used as a container of context for various read/write operations on other objects...
QgsLayoutPoint positionWithUnits() const
Returns the item&#39;s current position, including units.
double viewScaleFactor() const
Returns the current view zoom (scale factor).
Definition: qgslayoutitem.h:94
virtual QIcon icon() const
Returns the item&#39;s icon.
Map grid frame pen color.
QgsExpressionContext createExpressionContext() const override
Creates an expression context relating to the objects&#39; current state.
Base class for graphical items within a QgsLayout.
Lower left corner of item.
Base class for commands to undo/redo layout and layout object changes.
A layout item subclass for text labels.
UndoCommand
Layout item undo commands, used for collapsing undo commands.
QgsLayoutSize sizeWithUnits() const
Returns the item&#39;s current size, including units.
Upper center of item.
bool frameEnabled() const
Returns true if the item includes a frame.
A container for grouping several QgsLayoutItems.
A layout item subclass that displays SVG files or raster format images (jpg, png, ...
Scalebar secondary fill color.
static QIcon getThemeIcon(const QString &name)
Helper to get a theme icon.
virtual QgsLayoutSize fixedSize() const
Returns the fixed size of the item, if applicable, or an empty size if item can be freely resized...
Layout item for node based polygon shapes.
Opacity adjustment.
Lower right corner of item.
double ANALYSIS_EXPORT angle(QgsPoint *p1, QgsPoint *p2, QgsPoint *p3, QgsPoint *p4)
Calculates the angle between two segments (in 2 dimension, z-values are ignored)
Definition: MathUtils.cpp:786
Margin for labels from edge of map.
QgsLayoutMeasurement frameStrokeWidth() const
Returns the frame&#39;s stroke width.
This class provides a method of storing points, consisting of an x and y coordinate, for use in QGIS layouts.
ReferencePoint
Fixed position reference point.
A QGraphicsEffect subclass used for rendering layout items onto a scene with custom composition modes...
Layout graphical items for displaying a map.
Layout item for node based polyline shapes.
Map grid frame fill color 1.
virtual QgsLayoutSize minimumSize() const
Returns the minimum allowed size of the item, if applicable, or an empty size if item can be freely r...
This class provides a method of storing measurements for use in QGIS layouts using a variety of diffe...
Upper right corner of item.
#define SIP_SKIP
Definition: qgis_sip.h:119
bool hasBackground() const
Returns true if the item has a background.
Lower center of item.
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
QgsRenderContext & renderContext()
Returns a reference to the context&#39;s render context.
Definition: qgslayoutitem.h:72
Middle right of item.
QColor backgroundColor() const
Returns the background color for this item.
Layout item for basic filled shapes (e.g.
Map grid frame fill color 2.
virtual int numberExportLayers() const
Returns the number of layers that this item requires for exporting during layered exports (e...
#define SIP_FORCE
Definition: qgis_sip.h:124
#define SIP_END
Definition: qgis_sip.h:182
Scalebar map units per segment.
double itemOpacity() const
Returns the item&#39;s opacity.
QString id() const
Returns the item&#39;s ID name.
#define SIP_FACTORY
Definition: qgis_sip.h:69
Base id for plugin based item undo commands.
Upper left corner of item.
QPainter::CompositionMode blendMode() const
Returns the item&#39;s composition blending mode.
Base class for layouts, which can contain items such as maps, labels, scalebars, etc.
Definition: qgslayout.h:49
Flag
Flags for controlling how an item behaves.
QColor frameStrokeColor() const
Returns the frame&#39;s stroke color.
Item content zoomed.
ReferencePoint referencePoint() const
Returns the reference point for positioning of the layout item.
Middle left of item.
Contains settings and helpers relating to a render of a QgsLayoutItem.
Definition: qgslayoutitem.h:44
virtual QgsAbstractLayoutUndoCommand * createCommand(const QString &text, int id=0, QUndoCommand *parent=nullptr)=0
Creates a new layout undo command with the specified text and parent.
QgsCompositionConverter class converts a QGIS 2.x composition to a QGIS 3.x layout.
Shape symbol style.
Contains information about the context of a rendering operation.
Map frame annotation distance.
Qt::PenJoinStyle frameJoinStyle() const
Returns the join style used for drawing the item&#39;s frame.
Center of item.
const QgsRenderContext & renderContext() const
Returns a reference to the context&#39;s render context.
Definition: qgslayoutitem.h:82
virtual QString uuid() const
Returns the item identification string.
#define SIP_CONVERT_TO_SUBCLASS_CODE(code)
Definition: qgis_sip.h:165
Interface for layout objects which support undo/redo commands.
Background color adjustment.
A layout item subclass for scale bars.
A base class for objects which belong to a layout.
bool isLocked() const
Returns true if the item is locked, and cannot be interacted with using the mouse.
Stroke color adjustment.
A layout item subclass for map legends.
virtual void refresh()
Refreshes the object, causing a recalculation of any property overrides.
This class provides a method of storing sizes, consisting of a width and height, for use in QGIS layo...
Definition: qgslayoutsize.h:40
Scalebar number of segments.
Rotation adjustment.
DataDefinedProperty
Data defined properties for different item types.
Base class for frame items, which form a layout multiframe item.
Stroke width adjustment.
Item representing the paper in a layout.
Map atlas margin changed.
All properties for item.