Skip to content
Permalink
Browse files

[layouts][api] Add API to allow map items to be clipped (take their s…

…hape from)

other layout items which provide clipping paths

Opens the door for non-rectangular layout maps
  • Loading branch information
nyalldawson committed Jul 28, 2020
1 parent 77badc0 commit 915615aec4dcd6fb0bc7d6b267a637dfdb210bc0
@@ -113,6 +113,137 @@ Emitted when the atlas clipping settings are changed.
};


class QgsLayoutItemMapItemClipPathSettings : QObject
{
%Docstring
Contains settings relating to clipping a layout map by another layout item.

.. versionadded:: 3.16
%End

%TypeHeaderCode
#include "qgslayoutitemmap.h"
%End
public:

QgsLayoutItemMapItemClipPathSettings( QgsLayoutItemMap *map /TransferThis/ = 0 );
%Docstring
Constructor for QgsLayoutItemMapItemClipPathSettings, with the specified ``map`` parent.
%End

bool isActive() const;
%Docstring
Returns ``True`` if the item clipping is enabled and set to a valid source item.

.. seealso:: :py:func:`enabled`

.. seealso:: :py:func:`sourceItem`
%End

bool enabled() const;
%Docstring
Returns ``True`` if the map content should be clipped to the associated item.

.. seealso:: :py:func:`setEnabled`
%End

void setEnabled( bool enabled );
%Docstring
Sets whether the map content should be clipped to the associated item.

.. seealso:: :py:func:`enabled`
%End

QgsGeometry clippedMapExtent() const;
%Docstring
Returns the geometry to use for clipping the parent map, in the map item's CRS.
%End

QgsMapClippingRegion toMapClippingRegion() const;
%Docstring
Returns the clip path as a map clipping region.
%End

void setSourceItem( QgsLayoutItem *item );
%Docstring
Sets the source ``item`` which will provide the clipping path for the map.

The specified ``item`` must return the QgsLayoutItem.FlagProvidesClipPath flag.

.. seealso:: :py:func:`sourceItem`
%End

QgsLayoutItem *sourceItem();
%Docstring
Returns the source item which will provide the clipping path for the map, or ``None``
if no item is set.

.. seealso:: :py:func:`setSourceItem`
%End

QgsMapClippingRegion::FeatureClippingType featureClippingType() const;
%Docstring
Returns the feature clipping type to apply when clipping to the associated item.

.. seealso:: :py:func:`setFeatureClippingType`
%End

void setFeatureClippingType( QgsMapClippingRegion::FeatureClippingType type );
%Docstring
Sets the feature clipping ``type`` to apply when clipping to the associated item.

.. seealso:: :py:func:`featureClippingType`
%End

bool forceLabelsInsideFeature() const;
%Docstring
Returns ``True`` if labels should only be placed inside the clip path geometry.

.. seealso:: :py:func:`setForceLabelsInsideFeature`
%End

void setForceLabelsInsideFeature( bool forceInside );
%Docstring
Sets whether labels should only be placed inside the clip path geometry.

.. seealso:: :py:func:`forceLabelsInsideFeature`
%End

bool writeXml( QDomElement &element, QDomDocument &document, const QgsReadWriteContext &context ) const;
%Docstring
Stores settings in a DOM element, where ``element`` is the DOM element
corresponding to a 'LayoutMap' tag.

.. seealso:: :py:func:`readXml`
%End

bool readXml( const QDomElement &element, const QDomDocument &doc, const QgsReadWriteContext &context );
%Docstring
Sets the setting's state from a DOM document, where ``element`` is the DOM
node corresponding to a 'LayoutMap' tag.

.. seealso:: :py:func:`writeXml`

.. seealso:: :py:func:`finalizeRestoreFromXml`
%End

void finalizeRestoreFromXml();
%Docstring
To be called after all pending items have been restored from XML.

.. seealso:: :py:func:`readXml`
%End

signals:

void changed();
%Docstring
Emitted when the item clipping settings are changed.
%End

};


class QgsLayoutItemMap : QgsLayoutItem, QgsTemporalRangeObject
{
%Docstring
@@ -731,6 +862,13 @@ Creates a transform from layout coordinates to map coordinates.
%Docstring
Returns the map's atlas clipping settings.

.. versionadded:: 3.16
%End

QgsLayoutItemMapItemClipPathSettings *itemClippingSettings();
%Docstring
Returns the map's item based clip path settings.

.. versionadded:: 3.16
%End

0 comments on commit 915615a

Please sign in to comment.
You can’t perform that action at this time.