QGIS API Documentation  3.0.2-Girona (307d082)
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 
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 
129 #ifdef SIP_RUN
131  // the conversions have to be static, because they're using multiple inheritance
132  // (seen in PyQt4 .sip files for some QGraphicsItem classes)
133  switch ( sipCpp->type() )
134  {
135  // really, these *should* use the constants from QgsLayoutItemRegistry, but sip doesn't like that!
136  case QGraphicsItem::UserType + 101:
137  sipType = sipType_QgsLayoutItemGroup;
138  *sipCppRet = static_cast<QgsLayoutItemGroup *>( sipCpp );
139  break;
140  case QGraphicsItem::UserType + 102:
141  sipType = sipType_QgsLayoutItemPage;
142  *sipCppRet = static_cast<QgsLayoutItemPage *>( sipCpp );
143  break;
144  case QGraphicsItem::UserType + 103:
145  sipType = sipType_QgsLayoutItemMap;
146  *sipCppRet = static_cast<QgsLayoutItemMap *>( sipCpp );
147  break;
148  case QGraphicsItem::UserType + 104:
149  sipType = sipType_QgsLayoutItemPicture;
150  *sipCppRet = static_cast<QgsLayoutItemPicture *>( sipCpp );
151  break;
152  case QGraphicsItem::UserType + 105:
153  sipType = sipType_QgsLayoutItemLabel;
154  *sipCppRet = static_cast<QgsLayoutItemLabel *>( sipCpp );
155  break;
156  case QGraphicsItem::UserType + 106:
157  sipType = sipType_QgsLayoutItemLegend;
158  *sipCppRet = static_cast<QgsLayoutItemLegend *>( sipCpp );
159  break;
160  case QGraphicsItem::UserType + 107:
161  sipType = sipType_QgsLayoutItemShape;
162  *sipCppRet = static_cast<QgsLayoutItemShape *>( sipCpp );
163  break;
164  case QGraphicsItem::UserType + 108:
165  sipType = sipType_QgsLayoutItemPolygon;
166  *sipCppRet = static_cast<QgsLayoutItemPolygon *>( sipCpp );
167  break;
168  case QGraphicsItem::UserType + 109:
169  sipType = sipType_QgsLayoutItemPolyline;
170  *sipCppRet = static_cast<QgsLayoutItemPolyline *>( sipCpp );
171  break;
172  case QGraphicsItem::UserType + 110:
173  sipType = sipType_QgsLayoutItemScaleBar;
174  *sipCppRet = static_cast<QgsLayoutItemScaleBar *>( sipCpp );
175  break;
176  case QGraphicsItem::UserType + 111:
177  sipType = sipType_QgsLayoutFrame;
178  *sipCppRet = static_cast<QgsLayoutFrame *>( sipCpp );
179  break;
180  default:
181  sipType = 0;
182  }
183  SIP_END
184 #endif
185 
186  Q_OBJECT
187  Q_PROPERTY( bool locked READ isLocked WRITE setLocked NOTIFY lockChanged )
188 
189  public:
190 
193  {
203  };
204 
207  {
208  UndoNone = -1,
209  UndoIncrementalMove = 1,
278 
280  };
281 
288  explicit QgsLayoutItem( QgsLayout *layout, bool manageZValue = true );
289 
290  ~QgsLayoutItem() override;
291 
296  virtual void cleanup();
297 
303  int type() const override;
304 
308  virtual QIcon icon() const { return QgsApplication::getThemeIcon( QStringLiteral( "/mLayoutItem.svg" ) ); }
309 
317  virtual QString uuid() const { return mUuid; }
318 
325  QString id() const { return mId; }
326 
333  virtual void setId( const QString &id );
334 
341  virtual QString displayName() const;
342 
346  virtual void setSelected( bool selected );
347 
354  virtual void setVisibility( const bool visible );
355 
361  void setLocked( const bool locked );
362 
368  bool isLocked() const { return mIsLocked; }
369 
375  bool isGroupMember() const;
376 
382  QgsLayoutItemGroup *parentGroup() const;
383 
389  void setParentGroup( QgsLayoutItemGroup *group );
390 
399  virtual int numberExportLayers() const { return 0; }
400 
406  void paint( QPainter *painter, const QStyleOptionGraphicsItem *itemStyle, QWidget *pWidget ) override;
407 
414  void setReferencePoint( const ReferencePoint &point );
415 
422  ReferencePoint referencePoint() const { return mReferencePoint; }
423 
430  virtual QgsLayoutSize fixedSize() const { return mFixedSize; }
431 
438  virtual QgsLayoutSize minimumSize() const { return mMinimumSize; }
439 
454  virtual void attemptResize( const QgsLayoutSize &size, bool includesFrame = false );
455 
481  virtual void attemptMove( const QgsLayoutPoint &point, bool useReferencePoint = true, bool includesFrame = false, int page = -1 );
482 
498  void attemptSetSceneRect( const QRectF &rect, bool includesFrame = false );
499 
512  void attemptMoveBy( double deltaX, double deltaY );
513 
522  QgsLayoutPoint positionWithUnits() const { return mItemPosition; }
523 
528  int page() const;
529 
535  QPointF pagePos() const;
536 
542  QgsLayoutPoint pagePositionWithUnits() const;
543 
549  QgsLayoutSize sizeWithUnits() const { return mItemSize; }
550 
561  double itemRotation() const;
562 
570  bool writeXml( QDomElement &parentElement, QDomDocument &document, const QgsReadWriteContext &context ) const;
571 
587  bool readXml( const QDomElement &itemElement, const QDomDocument &document, const QgsReadWriteContext &context );
588 
597  virtual void finalizeRestoreFromXml();
598 
599  QgsAbstractLayoutUndoCommand *createCommand( const QString &text, int id, QUndoCommand *parent = nullptr ) override SIP_FACTORY;
600 
608  bool frameEnabled() const { return mFrame; }
609 
617  virtual void setFrameEnabled( bool drawFrame );
618 
626  void setFrameStrokeColor( const QColor &color );
627 
635  QColor frameStrokeColor() const { return mFrameColor; }
636 
644  virtual void setFrameStrokeWidth( const QgsLayoutMeasurement &width );
645 
653  QgsLayoutMeasurement frameStrokeWidth() const { return mFrameWidth; }
654 
662  Qt::PenJoinStyle frameJoinStyle() const { return mFrameJoinStyle; }
663 
671  void setFrameJoinStyle( const Qt::PenJoinStyle style );
672 
678  bool hasBackground() const { return mBackground; }
679 
685  void setBackgroundEnabled( bool drawBackground );
686 
693  QColor backgroundColor() const { return mBackgroundColor; }
694 
700  void setBackgroundColor( const QColor &color );
701 
706  QPainter::CompositionMode blendMode() const { return mBlendMode; }
707 
712  void setBlendMode( const QPainter::CompositionMode mode );
713 
721  double itemOpacity() const { return mOpacity; }
722 
730  void setItemOpacity( double opacity );
731 
736  bool excludeFromExports() const;
737 
742  void setExcludeFromExports( bool exclude );
743 
753  virtual bool containsAdvancedEffects() const;
754 
760  virtual bool requiresRasterization() const;
761 
772  virtual double estimatedFrameBleed() const;
773 
783  virtual QRectF rectWithFrame() const;
784 
791  virtual void moveContent( double dx, double dy );
792 
799  virtual void setMoveContentPreviewOffset( double dx, double dy );
800 
807  virtual void zoomContent( double factor, QPointF point );
808 
817  void beginCommand( const QString &commandText, UndoCommand command = UndoNone );
818 
824  void endCommand();
825 
831  void cancelCommand();
832 
836  bool shouldDrawItem() const;
837 
839 
840  public slots:
841 
846  void refresh() override;
847 
851  virtual void invalidateCache();
852 
856  virtual void redraw();
857 
864  virtual void refreshDataDefinedProperty( const QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties );
865 
875  virtual void setItemRotation( double rotation, bool adjustPosition = true );
876 
882  virtual void rotateItem( const double angle, const QPointF &transformOrigin );
883 
884  signals:
885 
889  void frameChanged();
890 
896  void lockChanged();
897 
901  void rotationChanged( double newRotation );
902 
906  void sizePositionChanged();
907 
908  protected:
909 
915  virtual void drawDebugRect( QPainter *painter );
916 
923  virtual void draw( QgsLayoutItemRenderContext &context ) = 0;
924 
928  virtual void drawFrame( QgsRenderContext &context );
929 
933  virtual void drawBackground( QgsRenderContext &context );
934 
941  virtual void setFixedSize( const QgsLayoutSize &size );
942 
949  virtual void setMinimumSize( const QgsLayoutSize &size );
950 
959  virtual QSizeF applyItemSizeConstraint( const QSizeF &targetSize );
960 
968  void refreshItemSize();
969 
975  void refreshItemPosition();
976 
987  void refreshItemRotation( QPointF *origin = nullptr );
988 
994  void refreshOpacity( bool updateItem = true );
995 
1001  void refreshFrame( bool updateItem = true );
1002 
1008  void refreshBackgroundColor( bool updateItem = true );
1009 
1013  void refreshBlendMode();
1014 
1019  QPointF adjustPointForReferencePosition( const QPointF &point, const QSizeF &size, const ReferencePoint &reference ) const;
1020 
1024  QPointF positionAtReferencePoint( const ReferencePoint &reference ) const;
1025 
1030  QgsLayoutPoint topLeftToReferencePoint( const QgsLayoutPoint &point ) const;
1031 
1040  virtual bool writePropertiesToElement( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
1041 
1057  virtual bool readPropertiesFromElement( const QDomElement &element, const QDomDocument &document, const QgsReadWriteContext &context );
1058 
1062  QgsLayoutSize applyDataDefinedSize( const QgsLayoutSize &size );
1063 
1064  private:
1065 
1066  // true if layout manages the z value for this item
1067  bool mLayoutManagesZValue = false;
1068 
1070  QString mId;
1071 
1073  QString mUuid;
1074 
1076  QString mTemplateUuid;
1077 
1079  QString mParentGroupUuid;
1080 
1081  ReferencePoint mReferencePoint = UpperLeft;
1082  QgsLayoutSize mFixedSize;
1083  QgsLayoutSize mMinimumSize;
1084 
1085  QgsLayoutSize mItemSize;
1086  QgsLayoutPoint mItemPosition;
1087  double mItemRotation = 0.0;
1088 
1090  bool mExcludeFromExports = false;
1091 
1096  bool mEvaluatedExcludeFromExports = false;
1097 
1099  QPainter::CompositionMode mBlendMode = QPainter::CompositionMode_SourceOver;
1100  std::unique_ptr< QgsLayoutEffect > mEffect;
1101 
1103  double mOpacity = 1.0;
1104 
1105  QImage mItemCachedImage;
1106  double mItemCacheDpi = -1;
1107 
1108  bool mIsLocked = false;
1109 
1111  bool mFrame = false;
1113  QColor mFrameColor = QColor( 0, 0, 0 );
1117  Qt::PenJoinStyle mFrameJoinStyle = Qt::MiterJoin;
1118 
1120  bool mBackground = true;
1122  QColor mBackgroundColor = QColor( 255, 255, 255 );
1123 
1124  bool mBlockUndoCommands = false;
1125 
1126  void initConnectionsToLayout();
1127 
1129  void preparePainter( QPainter *painter );
1130  bool shouldDrawAntialiased() const;
1131  bool shouldDrawDebugRect() const;
1132 
1133  QSizeF applyMinimumSize( const QSizeF &targetSize );
1134  QSizeF applyFixedSize( const QSizeF &targetSize );
1135  QgsLayoutPoint applyDataDefinedPosition( const QgsLayoutPoint &position );
1136 
1137  double applyDataDefinedRotation( const double rotation );
1138  void updateStoredItemPosition();
1139  QPointF itemPositionAtReferencePoint( const ReferencePoint reference, const QSizeF &size ) const;
1140  void setScenePos( const QPointF &destinationPos );
1141  bool shouldBlockUndoCommands() const;
1142 
1143  void applyDataDefinedOrientation( double &width, double &height, const QgsExpressionContext &context );
1144 
1145  friend class TestQgsLayoutItem;
1146  friend class TestQgsLayoutView;
1147  friend class QgsLayout;
1148  friend class QgsLayoutItemGroup;
1150 };
1151 
1152 #endif //QGSLAYOUTITEM_H
1153 
1154 
1155 
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:175
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
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.