Add api for layout items to create a clipping path

qgis · Jul 28, 2020 · 2b28395 · 2b28395
1 parent 19504ad
commit 2b28395
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 0 deletions.
diff --git a/python/core/auto_generated/layout/qgslayoutitem.sip.in b/python/core/auto_generated/layout/qgslayoutitem.sip.in
@@ -246,6 +246,7 @@ Base class for graphical items within a :py:class:`QgsLayout`.
     enum Flag
     {
       FlagOverridesPaint,
+      FlagProvidesClipPath,
     };
     typedef QFlags<QgsLayoutItem::Flag> Flags;
 
@@ -1026,6 +1027,18 @@ Returns ``True`` if the visitor should continue visiting other objects, or ``Fal
 should be canceled.
 
 .. versionadded:: 3.10
+%End
+
+    virtual QgsGeometry clipPath() const;
+%Docstring
+Returns the clipping path generated by this item, in layout coordinates.
+
+.. note::
+
+   Not all items can function as clipping paths. The FlagProvidesClipPath flag
+   indicates if a particular item can function as a clipping path provider.
+
+.. versionadded:: 3.16
 %End
 
   public slots:
@@ -1107,6 +1120,15 @@ Emitted when the item's size or position changes.
 Emitted whenever the number of background tasks an item is executing changes.
 
 .. versionadded:: 3.10
+%End
+
+    void clipPathChanged();
+%Docstring
+Emitted when the item's clipping path has changed.
+
+.. seealso:: :py:func:`clipPath`
+
+.. versionadded:: 3.16
 %End
 
   protected:

diff --git a/src/core/layout/qgslayoutitem.cpp b/src/core/layout/qgslayoutitem.cpp
@@ -1165,6 +1165,11 @@ bool QgsLayoutItem::accept( QgsStyleEntityVisitorInterface *visitor ) const
   return true;
 }
 
+QgsGeometry QgsLayoutItem::clipPath() const
+{
+  return QgsGeometry();
+}
+
 void QgsLayoutItem::refresh()
 {
   QgsLayoutObject::refresh();

diff --git a/src/core/layout/qgslayoutitem.h b/src/core/layout/qgslayoutitem.h
@@ -301,6 +301,7 @@ class CORE_EXPORT QgsLayoutItem : public QgsLayoutObject, public QGraphicsRectIt
     enum Flag
     {
       FlagOverridesPaint = 1 << 1,  //!< Item overrides the default layout item painting method
+      FlagProvidesClipPath = 1 << 2, //!< Item can act as a clipping path provider (see clipPath())
     };
     Q_DECLARE_FLAGS( Flags, Flag )
 
@@ -969,6 +970,16 @@ class CORE_EXPORT QgsLayoutItem : public QgsLayoutObject, public QGraphicsRectIt
      */
     virtual bool accept( QgsStyleEntityVisitorInterface *visitor ) const;
 
+    /**
+     * Returns the clipping path generated by this item, in layout coordinates.
+     *
+     * \note Not all items can function as clipping paths. The FlagProvidesClipPath flag
+     * indicates if a particular item can function as a clipping path provider.
+     *
+     * \since QGIS 3.16
+     */
+    virtual QgsGeometry clipPath() const;
+
   public slots:
 
     /**
@@ -1044,6 +1055,15 @@ class CORE_EXPORT QgsLayoutItem : public QgsLayoutObject, public QGraphicsRectIt
      */
     void backgroundTaskCountChanged( int count );
 
+    /**
+     * Emitted when the item's clipping path has changed.
+     *
+     * \see clipPath()
+     *
+     * \since QGIS 3.16
+     */
+    void clipPathChanged();
+
   protected:
 
     /**