QGIS API Documentation  3.9.0-Master (224899f119)
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;
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,
289 
291  };
292 
297  enum Flag
298  {
299  FlagOverridesPaint = 1 << 1,
300  };
301  Q_DECLARE_FLAGS( Flags, Flag )
302 
303 
309  explicit QgsLayoutItem( QgsLayout *layout, bool manageZValue = true );
310 
311  ~QgsLayoutItem() override;
312 
317  virtual void cleanup();
318 
324  int type() const override;
325 
329  virtual QIcon icon() const { return QgsApplication::getThemeIcon( QStringLiteral( "/mLayoutItem.svg" ) ); }
330 
338  virtual QString uuid() const { return mUuid; }
339 
344  virtual Flags itemFlags() const;
345 
352  QString id() const { return mId; }
353 
360  virtual void setId( const QString &id );
361 
368  virtual QString displayName() const;
369 
373  virtual void setSelected( bool selected );
374 
381  virtual void setVisibility( bool visible );
382 
388  void setLocked( bool locked );
389 
395  bool isLocked() const { return mIsLocked; }
396 
402  bool isGroupMember() const;
403 
409  QgsLayoutItemGroup *parentGroup() const;
410 
416  void setParentGroup( QgsLayoutItemGroup *group );
417 
423  {
428  };
429 
436  virtual ExportLayerBehavior exportLayerBehavior() const;
437 
451  Q_DECL_DEPRECATED virtual int numberExportLayers() const SIP_DEPRECATED;
452 
460  virtual void startLayeredExport();
461 
469  virtual void stopLayeredExport();
470 
478  virtual bool nextExportPart();
479 
485  struct CORE_EXPORT ExportLayerDetail
486  {
488  QString name;
489 
491  QString mapLayerId;
492 
494  QString mapTheme;
495  };
496 
504  virtual QgsLayoutItem::ExportLayerDetail exportLayerDetails() const;
505 
511  void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget ) override;
512 
519  void setReferencePoint( ReferencePoint point );
520 
527  ReferencePoint referencePoint() const { return mReferencePoint; }
528 
535  virtual QgsLayoutSize fixedSize() const { return mFixedSize; }
536 
543  virtual QgsLayoutSize minimumSize() const { return mMinimumSize; }
544 
559  virtual void attemptResize( const QgsLayoutSize &size, bool includesFrame = false );
560 
586  virtual void attemptMove( const QgsLayoutPoint &point, bool useReferencePoint = true, bool includesFrame = false, int page = -1 );
587 
603  void attemptSetSceneRect( const QRectF &rect, bool includesFrame = false );
604 
617  void attemptMoveBy( double deltaX, double deltaY );
618 
627  QgsLayoutPoint positionWithUnits() const { return mItemPosition; }
628 
633  int page() const;
634 
640  QPointF pagePos() const;
641 
647  QgsLayoutPoint pagePositionWithUnits() const;
648 
654  QgsLayoutSize sizeWithUnits() const { return mItemSize; }
655 
666  double itemRotation() const;
667 
675  bool writeXml( QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context ) const;
676 
692  bool readXml( const QDomElement &itemElement, const QDomDocument &document, const QgsReadWriteContext &context );
693 
702  virtual void finalizeRestoreFromXml();
703 
704  QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id, QUndoCommand *parent = nullptr ) override SIP_FACTORY;
705 
713  bool frameEnabled() const { return mFrame; }
714 
722  virtual void setFrameEnabled( bool drawFrame );
723 
731  void setFrameStrokeColor( const QColor &color );
732 
740  QColor frameStrokeColor() const { return mFrameColor; }
741 
749  virtual void setFrameStrokeWidth( QgsLayoutMeasurement width );
750 
758  QgsLayoutMeasurement frameStrokeWidth() const { return mFrameWidth; }
759 
767  Qt::PenJoinStyle frameJoinStyle() const { return mFrameJoinStyle; }
768 
776  void setFrameJoinStyle( Qt::PenJoinStyle style );
777 
783  bool hasBackground() const { return mBackground; }
784 
790  void setBackgroundEnabled( bool drawBackground );
791 
798  QColor backgroundColor() const { return mBackgroundColor; }
799 
805  void setBackgroundColor( const QColor &color );
806 
811  QPainter::CompositionMode blendMode() const { return mBlendMode; }
812 
817  void setBlendMode( QPainter::CompositionMode mode );
818 
826  double itemOpacity() const { return mOpacity; }
827 
835  void setItemOpacity( double opacity );
836 
841  bool excludeFromExports() const;
842 
847  void setExcludeFromExports( bool exclude );
848 
858  virtual bool containsAdvancedEffects() const;
859 
865  virtual bool requiresRasterization() const;
866 
877  virtual double estimatedFrameBleed() const;
878 
888  virtual QRectF rectWithFrame() const;
889 
896  virtual void moveContent( double dx, double dy );
897 
904  virtual void setMoveContentPreviewOffset( double dx, double dy );
905 
912  virtual void zoomContent( double factor, QPointF point );
913 
922  void beginCommand( const QString &commandText, UndoCommand command = UndoNone );
923 
929  void endCommand();
930 
936  void cancelCommand();
937 
941  bool shouldDrawItem() const;
942 
944 
954  virtual bool accept( QgsStyleEntityVisitorInterface *visitor ) const;
955 
956  public slots:
957 
962  void refresh() override;
963 
967  virtual void invalidateCache();
968 
972  virtual void redraw();
973 
980  virtual void refreshDataDefinedProperty( QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties );
981 
991  virtual void setItemRotation( double rotation, bool adjustPosition = true );
992 
998  virtual void rotateItem( double angle, QPointF transformOrigin );
999 
1000  signals:
1001 
1005  void frameChanged();
1006 
1012  void lockChanged();
1013 
1017  void rotationChanged( double newRotation );
1018 
1022  void sizePositionChanged();
1023 
1029  void backgroundTaskCountChanged( int count );
1030 
1031  protected:
1032 
1038  virtual void drawDebugRect( QPainter *painter );
1039 
1046  virtual void draw( QgsLayoutItemRenderContext &context ) = 0;
1047 
1051  virtual void drawFrame( QgsRenderContext &context );
1052 
1056  virtual void drawBackground( QgsRenderContext &context );
1057 
1064  virtual void setFixedSize( const QgsLayoutSize &size );
1065 
1072  virtual void setMinimumSize( const QgsLayoutSize &size );
1073 
1082  virtual QSizeF applyItemSizeConstraint( QSizeF targetSize );
1083 
1091  void refreshItemSize();
1092 
1098  void refreshItemPosition();
1099 
1110  void refreshItemRotation( QPointF *origin = nullptr );
1111 
1117  void refreshOpacity( bool updateItem = true );
1118 
1124  void refreshFrame( bool updateItem = true );
1125 
1131  void refreshBackgroundColor( bool updateItem = true );
1132 
1136  void refreshBlendMode();
1137 
1142  QPointF adjustPointForReferencePosition( QPointF point, QSizeF size, ReferencePoint reference ) const;
1143 
1147  QPointF positionAtReferencePoint( ReferencePoint reference ) const;
1148 
1153  QgsLayoutPoint topLeftToReferencePoint( const QgsLayoutPoint &point ) const;
1154 
1163  virtual bool writePropertiesToElement( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
1164 
1180  virtual bool readPropertiesFromElement( const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context );
1181 
1185  QgsLayoutSize applyDataDefinedSize( const QgsLayoutSize &size );
1186 
1187  private:
1188 
1189  // true if layout manages the z value for this item
1190  bool mLayoutManagesZValue = false;
1191 
1193  QString mId;
1194 
1196  QString mUuid;
1197 
1199  QString mTemplateUuid;
1200 
1202  QString mParentGroupUuid;
1203 
1204  ReferencePoint mReferencePoint = UpperLeft;
1205  QgsLayoutSize mFixedSize;
1206  QgsLayoutSize mMinimumSize;
1207 
1208  QgsLayoutSize mItemSize;
1209  QgsLayoutPoint mItemPosition;
1210  double mItemRotation = 0.0;
1211 
1213  bool mExcludeFromExports = false;
1214 
1219  bool mEvaluatedExcludeFromExports = false;
1220 
1222  QPainter::CompositionMode mBlendMode = QPainter::CompositionMode_SourceOver;
1223  std::unique_ptr< QgsLayoutEffect > mEffect;
1224 
1226  double mOpacity = 1.0;
1227  double mEvaluatedOpacity = 1.0;
1228 
1229  QImage mItemCachedImage;
1230  double mItemCacheDpi = -1;
1231 
1232  bool mIsLocked = false;
1233 
1235  bool mFrame = false;
1237  QColor mFrameColor = QColor( 0, 0, 0 );
1241  Qt::PenJoinStyle mFrameJoinStyle = Qt::MiterJoin;
1242 
1244  bool mBackground = true;
1246  QColor mBackgroundColor = QColor( 255, 255, 255 );
1247 
1248  bool mBlockUndoCommands = false;
1249 
1250  void initConnectionsToLayout();
1251 
1253  void preparePainter( QPainter *painter );
1254  bool shouldDrawAntialiased() const;
1255  bool shouldDrawDebugRect() const;
1256  QSizeF applyMinimumSize( QSizeF targetSize );
1257  QSizeF applyFixedSize( QSizeF targetSize );
1258  QgsLayoutPoint applyDataDefinedPosition( const QgsLayoutPoint &position );
1259 
1260  double applyDataDefinedRotation( double rotation );
1261  void updateStoredItemPosition();
1262  QPointF itemPositionAtReferencePoint( ReferencePoint reference, QSizeF size ) const;
1263  void setScenePos( QPointF destinationPos );
1264  bool shouldBlockUndoCommands() const;
1265 
1266  void applyDataDefinedOrientation( double &width, double &height, const QgsExpressionContext &context );
1267 
1268  friend class TestQgsLayoutItem;
1269  friend class TestQgsLayoutView;
1270  friend class QgsLayout;
1271  friend class QgsLayoutItemGroup;
1273 };
1274 
1275 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLayoutItem::Flags )
1276 
1277 #endif //QGSLAYOUTITEM_H
1278 
1279 
1280 
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.
Item must be placed in its own individual layer.
Base class for commands to undo/redo layout and layout object changes.
A layout item subclass for text labels.
Item contains multiple sublayers which must be individually exported.
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.
QString mapTheme
Associated map theme, or an empty string if this export layer does not need to be associated with a m...
Item can only be placed on layers with other items of the same type, but multiple items of this type ...
Opacity adjustment.
Lower right corner of item.
An interface for classes which can visit style entity (e.g.
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.
QString name
User-friendly name for the export layer.
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:126
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.
#define SIP_FORCE
Definition: qgis_sip.h:131
#define SIP_END
Definition: qgis_sip.h:189
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:76
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.
#define SIP_DEPRECATED
Definition: qgis_sip.h:106
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.
ExportLayerBehavior
Behavior of item when exporting to layered outputs.
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:172
Interface for layout objects which support undo/redo commands.
Background color adjustment.
Item can be placed on a layer with any other item (default behavior)
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.
QString mapLayerId
Associated map layer ID, or an empty string if this export layer is not associated with a map layer...
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.
Contains details of a particular export layer relating to a layout item.
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.