QGIS API Documentation  3.17.0-Master (8af46bc54f)
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,
293 
295  };
296 
301  enum Flag
302  {
303  FlagOverridesPaint = 1 << 1,
304  FlagProvidesClipPath = 1 << 2,
305  };
306  Q_DECLARE_FLAGS( Flags, Flag )
307 
308 
314  explicit QgsLayoutItem( QgsLayout *layout, bool manageZValue = true );
315 
316  ~QgsLayoutItem() override;
317 
322  virtual void cleanup();
323 
329  int type() const override;
330 
334  virtual QIcon icon() const { return QgsApplication::getThemeIcon( QStringLiteral( "/mLayoutItem.svg" ) ); }
335 
343  virtual QString uuid() const { return mUuid; }
344 
349  virtual Flags itemFlags() const;
350 
357  QString id() const { return mId; }
358 
365  virtual void setId( const QString &id );
366 
373  virtual QString displayName() const;
374 
378  virtual void setSelected( bool selected );
379 
386  virtual void setVisibility( bool visible );
387 
393  void setLocked( bool locked );
394 
400  bool isLocked() const { return mIsLocked; }
401 
407  bool isGroupMember() const;
408 
414  QgsLayoutItemGroup *parentGroup() const;
415 
421  void setParentGroup( QgsLayoutItemGroup *group );
422 
428  {
433  };
434 
441  virtual ExportLayerBehavior exportLayerBehavior() const;
442 
456  Q_DECL_DEPRECATED virtual int numberExportLayers() const SIP_DEPRECATED;
457 
465  virtual void startLayeredExport();
466 
474  virtual void stopLayeredExport();
475 
483  virtual bool nextExportPart();
484 
490  struct CORE_EXPORT ExportLayerDetail
491  {
493  QString name;
494 
496  QString mapLayerId;
497 
502  QPainter::CompositionMode compositionMode = QPainter::CompositionMode_SourceOver;
503 
508  double opacity = 1.0;
509 
511  QString mapTheme;
512  };
513 
521  virtual QgsLayoutItem::ExportLayerDetail exportLayerDetails() const;
522 
528  void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget ) override;
529 
536  void setReferencePoint( ReferencePoint point );
537 
544  ReferencePoint referencePoint() const { return mReferencePoint; }
545 
552  virtual QgsLayoutSize fixedSize() const { return mFixedSize; }
553 
560  virtual QgsLayoutSize minimumSize() const { return mMinimumSize; }
561 
576  virtual void attemptResize( const QgsLayoutSize &size, bool includesFrame = false );
577 
603  virtual void attemptMove( const QgsLayoutPoint &point, bool useReferencePoint = true, bool includesFrame = false, int page = -1 );
604 
620  void attemptSetSceneRect( const QRectF &rect, bool includesFrame = false );
621 
634  void attemptMoveBy( double deltaX, double deltaY );
635 
644  QgsLayoutPoint positionWithUnits() const { return mItemPosition; }
645 
650  int page() const;
651 
657  QPointF pagePos() const;
658 
664  QgsLayoutPoint pagePositionWithUnits() const;
665 
671  QgsLayoutSize sizeWithUnits() const { return mItemSize; }
672 
683  double itemRotation() const;
684 
692  bool writeXml( QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context ) const;
693 
709  bool readXml( const QDomElement &itemElement, const QDomDocument &document, const QgsReadWriteContext &context );
710 
719  virtual void finalizeRestoreFromXml();
720 
721  QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id, QUndoCommand *parent = nullptr ) override SIP_FACTORY;
722 
730  bool frameEnabled() const { return mFrame; }
731 
739  virtual void setFrameEnabled( bool drawFrame );
740 
748  void setFrameStrokeColor( const QColor &color );
749 
757  QColor frameStrokeColor() const { return mFrameColor; }
758 
766  virtual void setFrameStrokeWidth( QgsLayoutMeasurement width );
767 
775  QgsLayoutMeasurement frameStrokeWidth() const { return mFrameWidth; }
776 
784  Qt::PenJoinStyle frameJoinStyle() const { return mFrameJoinStyle; }
785 
793  void setFrameJoinStyle( Qt::PenJoinStyle style );
794 
800  bool hasBackground() const { return mBackground; }
801 
807  void setBackgroundEnabled( bool drawBackground );
808 
815  QColor backgroundColor() const { return mBackgroundColor; }
816 
822  void setBackgroundColor( const QColor &color );
823 
828  QPainter::CompositionMode blendMode() const { return mBlendMode; }
829 
834  void setBlendMode( QPainter::CompositionMode mode );
835 
843  double itemOpacity() const { return mOpacity; }
844 
852  void setItemOpacity( double opacity );
853 
858  bool excludeFromExports() const;
859 
864  void setExcludeFromExports( bool exclude );
865 
875  virtual bool containsAdvancedEffects() const;
876 
882  virtual bool requiresRasterization() const;
883 
894  virtual double estimatedFrameBleed() const;
895 
905  virtual QRectF rectWithFrame() const;
906 
913  virtual void moveContent( double dx, double dy );
914 
921  virtual void setMoveContentPreviewOffset( double dx, double dy );
922 
929  virtual void zoomContent( double factor, QPointF point );
930 
939  void beginCommand( const QString &commandText, UndoCommand command = UndoNone );
940 
946  void endCommand();
947 
953  void cancelCommand();
954 
958  bool shouldDrawItem() const;
959 
961 
971  virtual bool accept( QgsStyleEntityVisitorInterface *visitor ) const;
972 
981  virtual QgsGeometry clipPath() const;
982 
983  public slots:
984 
989  void refresh() override;
990 
994  virtual void invalidateCache();
995 
999  virtual void redraw();
1000 
1007  virtual void refreshDataDefinedProperty( QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties );
1008 
1018  virtual void setItemRotation( double rotation, bool adjustPosition = true );
1019 
1025  virtual void rotateItem( double angle, QPointF transformOrigin );
1026 
1027  signals:
1028 
1032  void frameChanged();
1033 
1039  void lockChanged();
1040 
1044  void rotationChanged( double newRotation );
1045 
1049  void sizePositionChanged();
1050 
1056  void backgroundTaskCountChanged( int count );
1057 
1065  void clipPathChanged();
1066 
1067  protected:
1068 
1074  virtual void drawDebugRect( QPainter *painter );
1075 
1082  virtual void draw( QgsLayoutItemRenderContext &context ) = 0;
1083 
1091  virtual QPainterPath framePath() const;
1092 
1098  virtual void drawFrame( QgsRenderContext &context );
1099 
1105  virtual void drawBackground( QgsRenderContext &context );
1106 
1113  virtual void setFixedSize( const QgsLayoutSize &size );
1114 
1121  virtual void setMinimumSize( const QgsLayoutSize &size );
1122 
1131  virtual QSizeF applyItemSizeConstraint( QSizeF targetSize );
1132 
1140  void refreshItemSize();
1141 
1147  void refreshItemPosition();
1148 
1159  void refreshItemRotation( QPointF *origin = nullptr );
1160 
1166  void refreshOpacity( bool updateItem = true );
1167 
1173  void refreshFrame( bool updateItem = true );
1174 
1180  void refreshBackgroundColor( bool updateItem = true );
1181 
1185  void refreshBlendMode();
1186 
1191  QPointF adjustPointForReferencePosition( QPointF point, QSizeF size, ReferencePoint reference ) const;
1192 
1196  QPointF positionAtReferencePoint( ReferencePoint reference ) const;
1197 
1202  QgsLayoutPoint topLeftToReferencePoint( const QgsLayoutPoint &point ) const;
1203 
1212  virtual bool writePropertiesToElement( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
1213 
1229  virtual bool readPropertiesFromElement( const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context );
1230 
1234  QgsLayoutSize applyDataDefinedSize( const QgsLayoutSize &size );
1235 
1236  private:
1237 
1238  // true if layout manages the z value for this item
1239  bool mLayoutManagesZValue = false;
1240 
1242  QString mId;
1243 
1245  QString mUuid;
1246 
1248  QString mTemplateUuid;
1249 
1251  QString mParentGroupUuid;
1252 
1253  ReferencePoint mReferencePoint = UpperLeft;
1254  QgsLayoutSize mFixedSize;
1255  QgsLayoutSize mMinimumSize;
1256 
1257  QgsLayoutSize mItemSize;
1258  QgsLayoutPoint mItemPosition;
1259  double mItemRotation = 0.0;
1260 
1262  bool mExcludeFromExports = false;
1263 
1268  bool mEvaluatedExcludeFromExports = false;
1269 
1271  QPainter::CompositionMode mBlendMode = QPainter::CompositionMode_SourceOver;
1272  std::unique_ptr< QgsLayoutEffect > mEffect;
1273 
1275  double mOpacity = 1.0;
1276  double mEvaluatedOpacity = 1.0;
1277 
1278  QImage mItemCachedImage;
1279  double mItemCacheDpi = -1;
1280 
1281  bool mIsLocked = false;
1282 
1284  bool mFrame = false;
1286  QColor mFrameColor = QColor( 0, 0, 0 );
1290  Qt::PenJoinStyle mFrameJoinStyle = Qt::MiterJoin;
1291 
1293  bool mBackground = true;
1295  QColor mBackgroundColor = QColor( 255, 255, 255 );
1296 
1297  bool mBlockUndoCommands = false;
1298 
1299  void initConnectionsToLayout();
1300 
1302  void preparePainter( QPainter *painter );
1303  bool shouldDrawAntialiased() const;
1304  bool shouldDrawDebugRect() const;
1305  QSizeF applyMinimumSize( QSizeF targetSize );
1306  QSizeF applyFixedSize( QSizeF targetSize );
1307  QgsLayoutPoint applyDataDefinedPosition( const QgsLayoutPoint &position );
1308 
1309  double applyDataDefinedRotation( double rotation );
1310  void updateStoredItemPosition();
1311  QPointF itemPositionAtReferencePoint( ReferencePoint reference, QSizeF size ) const;
1312  void setScenePos( QPointF destinationPos );
1313  bool shouldBlockUndoCommands() const;
1314 
1315  void applyDataDefinedOrientation( double &width, double &height, const QgsExpressionContext &context );
1316 
1317  friend class TestQgsLayoutItem;
1318  friend class TestQgsLayoutView;
1319  friend class QgsLayout;
1320  friend class QgsLayoutItemGroup;
1322 };
1323 
1324 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLayoutItem::Flags )
1325 
1326 #endif //QGSLAYOUTITEM_H
1327 
1328 
1329 
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.
Legend maximum symbol size.
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.
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsField::ConfigurationFlags) CORE_EXPORT QDataStream &operator<<(QDataStream &out
Writes the field to stream out. QGIS version compatibility is not guaranteed.
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:123
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:194
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:177
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 subdivisions.
Scalebar number of segments.
Rotation adjustment.
Contains details of a particular export layer relating to a layout item.
Legend minimum symbol size.
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.