QGIS API Documentation  3.4.3-Madeira (2f64a3c)
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 <QGraphicsRectItem>
28 #include <QIcon>
29 #include <QPainter>
30 
31 class QgsLayout;
32 class QPainter;
33 class QgsLayoutItemGroup;
34 class QgsLayoutEffect;
35 
36 
43 class CORE_EXPORT QgsLayoutItemRenderContext
44 {
45  public:
46 
57  QgsLayoutItemRenderContext( QgsRenderContext &context, double viewScaleFactor = 1.0 );
58 
61 
63  QgsLayoutItemRenderContext &operator=( const QgsLayoutItemRenderContext &other ) = delete;
64 
71  QgsRenderContext &renderContext() { return mRenderContext; }
72 
81  const QgsRenderContext &renderContext() const { return mRenderContext; } SIP_SKIP
82 
93  double viewScaleFactor() const { return mViewScaleFactor; }
94 
95  private:
96 
97 #ifdef SIP_RUN
99 #endif
100 
101  QgsRenderContext &mRenderContext;
102  double mViewScaleFactor = 1.0;
103 };
104 
111 class CORE_EXPORT QgsLayoutItem : public QgsLayoutObject, public QGraphicsRectItem, public QgsLayoutUndoObjectInterface
112 {
113 #ifdef SIP_RUN
114 #include "qgslayoutitemgroup.h"
115 #include "qgslayoutitemmap.h"
116 #include "qgslayoutitempicture.h"
117 #include "qgslayoutitemlabel.h"
118 #include "qgslayoutitemlegend.h"
119 #include "qgslayoutitempolygon.h"
120 #include "qgslayoutitempolyline.h"
121 #include "qgslayoutitemscalebar.h"
122 #include "qgslayoutframe.h"
123 #include "qgslayoutitemshape.h"
124 #include "qgslayoutitempage.h"
125 #endif
126 
127 #ifdef SIP_RUN
129 
130  // FREAKKKKIIN IMPORTANT!!!!!!!!!!!
131  // IF YOU PUT SOMETHING HERE, PUT IT IN QgsLayoutObject CASTING *****ALSO******
132  // (it's not enough for it to be in only one of the places, as sip inconsistently
133  // decides which casting code to perform here)
134 
135  // the conversions have to be static, because they're using multiple inheritance
136  // (seen in PyQt4 .sip files for some QGraphicsItem classes)
137  switch ( sipCpp->type() )
138  {
139  // really, these *should* use the constants from QgsLayoutItemRegistry, but sip doesn't like that!
140  case QGraphicsItem::UserType + 101:
141  sipType = sipType_QgsLayoutItemGroup;
142  *sipCppRet = static_cast<QgsLayoutItemGroup *>( sipCpp );
143  break;
144  case QGraphicsItem::UserType + 102:
145  sipType = sipType_QgsLayoutItemPage;
146  *sipCppRet = static_cast<QgsLayoutItemPage *>( sipCpp );
147  break;
148  case QGraphicsItem::UserType + 103:
149  sipType = sipType_QgsLayoutItemMap;
150  *sipCppRet = static_cast<QgsLayoutItemMap *>( sipCpp );
151  break;
152  case QGraphicsItem::UserType + 104:
153  sipType = sipType_QgsLayoutItemPicture;
154  *sipCppRet = static_cast<QgsLayoutItemPicture *>( sipCpp );
155  break;
156  case QGraphicsItem::UserType + 105:
157  sipType = sipType_QgsLayoutItemLabel;
158  *sipCppRet = static_cast<QgsLayoutItemLabel *>( sipCpp );
159  break;
160  case QGraphicsItem::UserType + 106:
161  sipType = sipType_QgsLayoutItemLegend;
162  *sipCppRet = static_cast<QgsLayoutItemLegend *>( sipCpp );
163  break;
164  case QGraphicsItem::UserType + 107:
165  sipType = sipType_QgsLayoutItemShape;
166  *sipCppRet = static_cast<QgsLayoutItemShape *>( sipCpp );
167  break;
168  case QGraphicsItem::UserType + 108:
169  sipType = sipType_QgsLayoutItemPolygon;
170  *sipCppRet = static_cast<QgsLayoutItemPolygon *>( sipCpp );
171  break;
172  case QGraphicsItem::UserType + 109:
173  sipType = sipType_QgsLayoutItemPolyline;
174  *sipCppRet = static_cast<QgsLayoutItemPolyline *>( sipCpp );
175  break;
176  case QGraphicsItem::UserType + 110:
177  sipType = sipType_QgsLayoutItemScaleBar;
178  *sipCppRet = static_cast<QgsLayoutItemScaleBar *>( sipCpp );
179  break;
180  case QGraphicsItem::UserType + 111:
181  sipType = sipType_QgsLayoutFrame;
182  *sipCppRet = static_cast<QgsLayoutFrame *>( sipCpp );
183  break;
184 
185  // did you read that comment above? NO? Go read it now. You're about to break stuff.
186 
187  default:
188  sipType = NULL;
189  }
190  SIP_END
191 #endif
192 
193 
194  Q_OBJECT
195  Q_PROPERTY( bool locked READ isLocked WRITE setLocked NOTIFY lockChanged )
196 
197  public:
198 
201  {
211  };
212 
215  {
216  UndoNone = -1,
217  UndoIncrementalMove = 1,
286 
288  };
289 
294  enum Flag
295  {
296  FlagOverridesPaint = 1 << 1,
297  };
298  Q_DECLARE_FLAGS( Flags, Flag )
299 
300 
306  explicit QgsLayoutItem( QgsLayout *layout, bool manageZValue = true );
307 
308  ~QgsLayoutItem() override;
309 
314  virtual void cleanup();
315 
321  int type() const override;
322 
326  virtual QIcon icon() const { return QgsApplication::getThemeIcon( QStringLiteral( "/mLayoutItem.svg" ) ); }
327 
335  virtual QString uuid() const { return mUuid; }
336 
341  virtual Flags itemFlags() const;
342 
349  QString id() const { return mId; }
350 
357  virtual void setId( const QString &id );
358 
365  virtual QString displayName() const;
366 
370  virtual void setSelected( bool selected );
371 
378  virtual void setVisibility( bool visible );
379 
385  void setLocked( bool locked );
386 
392  bool isLocked() const { return mIsLocked; }
393 
399  bool isGroupMember() const;
400 
406  QgsLayoutItemGroup *parentGroup() const;
407 
413  void setParentGroup( QgsLayoutItemGroup *group );
414 
423  virtual int numberExportLayers() const { return 0; }
424 
430  void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget ) override;
431 
438  void setReferencePoint( ReferencePoint point );
439 
446  ReferencePoint referencePoint() const { return mReferencePoint; }
447 
454  virtual QgsLayoutSize fixedSize() const { return mFixedSize; }
455 
462  virtual QgsLayoutSize minimumSize() const { return mMinimumSize; }
463 
478  virtual void attemptResize( const QgsLayoutSize &size, bool includesFrame = false );
479 
505  virtual void attemptMove( const QgsLayoutPoint &point, bool useReferencePoint = true, bool includesFrame = false, int page = -1 );
506 
522  void attemptSetSceneRect( const QRectF &rect, bool includesFrame = false );
523 
536  void attemptMoveBy( double deltaX, double deltaY );
537 
546  QgsLayoutPoint positionWithUnits() const { return mItemPosition; }
547 
552  int page() const;
553 
559  QPointF pagePos() const;
560 
566  QgsLayoutPoint pagePositionWithUnits() const;
567 
573  QgsLayoutSize sizeWithUnits() const { return mItemSize; }
574 
585  double itemRotation() const;
586 
594  bool writeXml( QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context ) const;
595 
611  bool readXml( const QDomElement &itemElement, const QDomDocument &document, const QgsReadWriteContext &context );
612 
621  virtual void finalizeRestoreFromXml();
622 
623  QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id, QUndoCommand *parent = nullptr ) override SIP_FACTORY;
624 
632  bool frameEnabled() const { return mFrame; }
633 
641  virtual void setFrameEnabled( bool drawFrame );
642 
650  void setFrameStrokeColor( const QColor &color );
651 
659  QColor frameStrokeColor() const { return mFrameColor; }
660 
668  virtual void setFrameStrokeWidth( QgsLayoutMeasurement width );
669 
677  QgsLayoutMeasurement frameStrokeWidth() const { return mFrameWidth; }
678 
686  Qt::PenJoinStyle frameJoinStyle() const { return mFrameJoinStyle; }
687 
695  void setFrameJoinStyle( Qt::PenJoinStyle style );
696 
702  bool hasBackground() const { return mBackground; }
703 
709  void setBackgroundEnabled( bool drawBackground );
710 
717  QColor backgroundColor() const { return mBackgroundColor; }
718 
724  void setBackgroundColor( const QColor &color );
725 
730  QPainter::CompositionMode blendMode() const { return mBlendMode; }
731 
736  void setBlendMode( QPainter::CompositionMode mode );
737 
745  double itemOpacity() const { return mOpacity; }
746 
754  void setItemOpacity( double opacity );
755 
760  bool excludeFromExports() const;
761 
766  void setExcludeFromExports( bool exclude );
767 
777  virtual bool containsAdvancedEffects() const;
778 
784  virtual bool requiresRasterization() const;
785 
796  virtual double estimatedFrameBleed() const;
797 
807  virtual QRectF rectWithFrame() const;
808 
815  virtual void moveContent( double dx, double dy );
816 
823  virtual void setMoveContentPreviewOffset( double dx, double dy );
824 
831  virtual void zoomContent( double factor, QPointF point );
832 
841  void beginCommand( const QString &commandText, UndoCommand command = UndoNone );
842 
848  void endCommand();
849 
855  void cancelCommand();
856 
860  bool shouldDrawItem() const;
861 
863 
864  public slots:
865 
870  void refresh() override;
871 
875  virtual void invalidateCache();
876 
880  virtual void redraw();
881 
888  virtual void refreshDataDefinedProperty( QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties );
889 
899  virtual void setItemRotation( double rotation, bool adjustPosition = true );
900 
906  virtual void rotateItem( double angle, QPointF transformOrigin );
907 
908  signals:
909 
913  void frameChanged();
914 
920  void lockChanged();
921 
925  void rotationChanged( double newRotation );
926 
930  void sizePositionChanged();
931 
932  protected:
933 
939  virtual void drawDebugRect( QPainter *painter );
940 
947  virtual void draw( QgsLayoutItemRenderContext &context ) = 0;
948 
952  virtual void drawFrame( QgsRenderContext &context );
953 
957  virtual void drawBackground( QgsRenderContext &context );
958 
965  virtual void setFixedSize( const QgsLayoutSize &size );
966 
973  virtual void setMinimumSize( const QgsLayoutSize &size );
974 
983  virtual QSizeF applyItemSizeConstraint( QSizeF targetSize );
984 
992  void refreshItemSize();
993 
999  void refreshItemPosition();
1000 
1011  void refreshItemRotation( QPointF *origin = nullptr );
1012 
1018  void refreshOpacity( bool updateItem = true );
1019 
1025  void refreshFrame( bool updateItem = true );
1026 
1032  void refreshBackgroundColor( bool updateItem = true );
1033 
1037  void refreshBlendMode();
1038 
1043  QPointF adjustPointForReferencePosition( QPointF point, QSizeF size, ReferencePoint reference ) const;
1044 
1048  QPointF positionAtReferencePoint( ReferencePoint reference ) const;
1049 
1054  QgsLayoutPoint topLeftToReferencePoint( const QgsLayoutPoint &point ) const;
1055 
1064  virtual bool writePropertiesToElement( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
1065 
1081  virtual bool readPropertiesFromElement( const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context );
1082 
1086  QgsLayoutSize applyDataDefinedSize( const QgsLayoutSize &size );
1087 
1088  private:
1089 
1090  // true if layout manages the z value for this item
1091  bool mLayoutManagesZValue = false;
1092 
1094  QString mId;
1095 
1097  QString mUuid;
1098 
1100  QString mTemplateUuid;
1101 
1103  QString mParentGroupUuid;
1104 
1105  ReferencePoint mReferencePoint = UpperLeft;
1106  QgsLayoutSize mFixedSize;
1107  QgsLayoutSize mMinimumSize;
1108 
1109  QgsLayoutSize mItemSize;
1110  QgsLayoutPoint mItemPosition;
1111  double mItemRotation = 0.0;
1112 
1114  bool mExcludeFromExports = false;
1115 
1120  bool mEvaluatedExcludeFromExports = false;
1121 
1123  QPainter::CompositionMode mBlendMode = QPainter::CompositionMode_SourceOver;
1124  std::unique_ptr< QgsLayoutEffect > mEffect;
1125 
1127  double mOpacity = 1.0;
1128  double mEvaluatedOpacity = 1.0;
1129 
1130  QImage mItemCachedImage;
1131  double mItemCacheDpi = -1;
1132 
1133  bool mIsLocked = false;
1134 
1136  bool mFrame = false;
1138  QColor mFrameColor = QColor( 0, 0, 0 );
1142  Qt::PenJoinStyle mFrameJoinStyle = Qt::MiterJoin;
1143 
1145  bool mBackground = true;
1147  QColor mBackgroundColor = QColor( 255, 255, 255 );
1148 
1149  bool mBlockUndoCommands = false;
1150 
1151  void initConnectionsToLayout();
1152 
1154  void preparePainter( QPainter *painter );
1155  bool shouldDrawAntialiased() const;
1156  bool shouldDrawDebugRect() const;
1157  QSizeF applyMinimumSize( QSizeF targetSize );
1158  QSizeF applyFixedSize( QSizeF targetSize );
1159  QgsLayoutPoint applyDataDefinedPosition( const QgsLayoutPoint &position );
1160 
1161  double applyDataDefinedRotation( double rotation );
1162  void updateStoredItemPosition();
1163  QPointF itemPositionAtReferencePoint( ReferencePoint reference, QSizeF size ) const;
1164  void setScenePos( QPointF destinationPos );
1165  bool shouldBlockUndoCommands() const;
1166 
1167  void applyDataDefinedOrientation( double &width, double &height, const QgsExpressionContext &context );
1168 
1169  friend class TestQgsLayoutItem;
1170  friend class TestQgsLayoutView;
1171  friend class QgsLayout;
1172  friend class QgsLayoutItemGroup;
1174 };
1175 
1176 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLayoutItem::Flags )
1177 
1178 #endif //QGSLAYOUTITEM_H
1179 
1180 
1181 
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:93
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
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:71
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:43
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:81
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.