QGIS/python/core/auto_generated/qgsmapsettings.sip.in

/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgsmapsettings.h                                            *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/






class QgsLabelBlockingRegion
{
%Docstring

Label blocking region (in map coordinates and CRS).

.. versionadded:: 3.6
%End

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

    explicit QgsLabelBlockingRegion( const QgsGeometry &geometry );
%Docstring
Constructor for a label blocking region
%End

    QgsGeometry geometry;

};


class QgsMapSettings : QgsTemporalRangeObject
{
%Docstring
The QgsMapSettings class contains configuration for rendering of the map.
The rendering itself is done by QgsMapRendererJob subclasses.

In order to set up QgsMapSettings instance, it is necessary to set at least
few members: extent, output size and layers.

Some systems use high DPI scaling that is an alternative to the traditional
DPI scaling. The operating system provides Qt with a scaling ratio and it
scales window, event, and desktop geometry. The Cocoa platform plugin sets
the scaling ratio as QWindow.devicePixelRatio().
To properly render the map on such systems, the map settings device pixel
ratio shall be set accordingly.

.. versionadded:: 2.4
%End

%TypeHeaderCode
#include "qgsmapsettings.h"
%End
  public:
    QgsMapSettings();

    QgsRectangle extent() const;
%Docstring
Returns geographical coordinates of the rectangle that should be rendered.
The actual visible extent used for rendering could be slightly different
since the given extent may be expanded in order to fit the aspect ratio
of output size. Use visibleExtent() to get the resulting extent.
%End

    void setExtent( const QgsRectangle &rect, bool magnified = true );
%Docstring
Set coordinates of the rectangle which should be rendered.
The actual visible extent used for rendering could be slightly different
since the given extent may be expanded in order to fit the aspect ratio
of output size. Use visibleExtent() to get the resulting extent.
%End

    double extentBuffer() const;
%Docstring
Returns the buffer in map units to use around the visible extent for rendering
symbols whose corresponding geometries are outside the visible extent.

.. seealso:: :py:func:`setExtentBuffer`

.. versionadded:: 3.10
%End

    void setExtentBuffer( double buffer );
%Docstring
Sets the buffer in map units to use around the visible extent for rendering
symbols whose corresponding geometries are outside the visible extent. This
is useful when using tiles to avoid cut symbols at tile boundaries.

.. versionadded:: 3.10
%End

    QSize outputSize() const;
%Docstring
Returns the size of the resulting map image
%End
    void setOutputSize( QSize size );
%Docstring
Sets the size of the resulting map image
%End

    float devicePixelRatio() const;
%Docstring
Returns device pixel ratio
Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.

.. versionadded:: 3.4
%End

    void setDevicePixelRatio( float dpr );
%Docstring
Sets the device pixel ratio
Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.

.. versionadded:: 3.4
%End

    QSize deviceOutputSize() const;
%Docstring
Returns the device output size of the map canvas
This is equivalent to the output size multiplicated
by the device pixel ratio.

.. versionadded:: 3.4
%End

    double rotation() const;
%Docstring
Returns the rotation of the resulting map image, in degrees clockwise.

.. seealso:: :py:func:`setRotation`

.. versionadded:: 2.8
%End

    void setRotation( double rotation );
%Docstring
Sets the ``rotation`` of the resulting map image, in degrees clockwise.

.. seealso:: :py:func:`rotation`

.. versionadded:: 2.8
%End

    double outputDpi() const;
%Docstring
Returns DPI used for conversion between real world units (e.g. mm) and pixels
Default value is 96
%End
    void setOutputDpi( double dpi );
%Docstring
Sets DPI used for conversion between real world units (e.g. mm) and pixels
%End

    void setMagnificationFactor( double factor );
%Docstring
Set the magnification factor.

:param factor: the factor of magnification

.. seealso:: :py:func:`magnificationFactor`

.. versionadded:: 2.16
%End

    double magnificationFactor() const;
%Docstring
Returns the magnification factor.

.. seealso:: :py:func:`setMagnificationFactor`

.. versionadded:: 2.16
%End

    QStringList layerIds() const;
%Docstring
Gets list of layer IDs for map rendering
The layers are stored in the reverse order of how they are rendered (layer with index 0 will be on top)
%End

    QList<QgsMapLayer *> layers() const;
%Docstring
Gets list of layers for map rendering
The layers are stored in the reverse order of how they are rendered (layer with index 0 will be on top)
%End

    void setLayers( const QList<QgsMapLayer *> &layers );
%Docstring
Set list of layers for map rendering. The layers must be registered in :py:class:`QgsProject`.
The layers are stored in the reverse order of how they are rendered (layer with index 0 will be on top)

.. note::

   Any non-spatial layers will be automatically stripped from the list (since they cannot be rendered!).
%End

    QMap<QString, QString> layerStyleOverrides() const;
%Docstring
Gets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one

.. versionadded:: 2.8
%End

    void setLayerStyleOverrides( const QMap<QString, QString> &overrides );
%Docstring
Set map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one

.. versionadded:: 2.8
%End

 QString customRenderFlags() const;
%Docstring
Gets custom rendering flags. Layers might honour these to alter their rendering.

:return: custom flags strings, separated by ';'

.. seealso:: :py:func:`setCustomRenderFlags`

.. versionadded:: 2.16

.. deprecated::
   use \see customRenderingFlags().
%End

 void setCustomRenderFlags( const QString &customRenderFlags );
%Docstring
Sets the custom rendering flags. Layers might honour these to alter their rendering.

:param customRenderFlags: custom flags strings, separated by ';'

.. seealso:: :py:func:`customRenderFlags`

.. versionadded:: 2.16

.. deprecated::
   use \see setCustomRenderingFlag() instead.
%End

    QVariantMap customRenderingFlags() const;
%Docstring
Gets custom rendering flags. Layers might honour these to alter their rendering.

:return: a map of custom flags

.. seealso:: :py:func:`setCustomRenderingFlag`

.. versionadded:: 3.12
%End

    void setCustomRenderingFlag( const QString &flag, const QVariant &value );
%Docstring
Sets a custom rendering flag. Layers might honour these to alter their rendering.

:param flag: the flag name
:param value: the flag value

.. seealso:: :py:func:`customRenderingFlags`

.. versionadded:: 3.12
%End

    void clearCustomRenderingFlag( const QString &flag );
%Docstring
Clears the specified custom rendering flag.

:param flag: the flag name

.. seealso:: :py:func:`setCustomRenderingFlag`

.. versionadded:: 3.12
%End

    void setDestinationCrs( const QgsCoordinateReferenceSystem &crs );
%Docstring
sets destination coordinate reference system
%End
    QgsCoordinateReferenceSystem destinationCrs() const;
%Docstring
returns CRS of destination coordinate reference system
%End

    QgsUnitTypes::DistanceUnit mapUnits() const;
%Docstring
Gets units of map's geographical coordinates - used for scale calculation
%End

    bool setEllipsoid( const QString &ellipsoid );
%Docstring
Sets the ``ellipsoid`` by its acronym. Known ellipsoid acronyms can be
retrieved using :py:func:`QgsEllipsoidUtils.acronyms()`
Calculations will only use the ellipsoid if a valid ellipsoid has been set.

:return: ``True`` if ellipsoid was successfully set

.. seealso:: :py:func:`ellipsoid`

.. versionadded:: 3.0
%End

    QString ellipsoid() const;
%Docstring
Returns ellipsoid's acronym. Calculations will only use the
ellipsoid if a valid ellipsoid has been set.

.. seealso:: :py:func:`setEllipsoid`

.. versionadded:: 3.0
%End

    void setBackgroundColor( const QColor &color );
%Docstring
Sets the background color of the map
%End
    QColor backgroundColor() const;
%Docstring
Gets the background color of the map
%End

    void setSelectionColor( const QColor &color );
%Docstring
Sets color that is used for drawing of selected vector features
%End
    QColor selectionColor() const;
%Docstring
Gets color that is used for drawing of selected vector features
%End

    enum Flag
    {
      Antialiasing,
      DrawEditingInfo,
      ForceVectorOutput,
      UseAdvancedEffects,
      DrawLabeling,
      UseRenderingOptimization,
      DrawSelection,
      DrawSymbolBounds,
      RenderMapTile,
      RenderPartialOutput,
      RenderPreviewJob,
      RenderBlocking,
      // TODO: ignore scale-based visibility (overview)
    };
    typedef QFlags<QgsMapSettings::Flag> Flags;


    void setFlags( QgsMapSettings::Flags flags );
%Docstring
Sets combination of flags that will be used for rendering
%End
    void setFlag( Flag flag, bool on = true );
%Docstring
Enable or disable a particular flag (other flags are not affected)
%End
    Flags flags() const;
%Docstring
Returns combination of flags used for rendering
%End
    bool testFlag( Flag flag ) const;
%Docstring
Check whether a particular flag is enabled
%End

    QgsRenderContext::TextRenderFormat textRenderFormat() const;
%Docstring
Returns the text render format, which dictates how text is rendered (e.g. as paths or real text objects).

.. seealso:: :py:func:`setTextRenderFormat`

.. versionadded:: 3.4.3
%End

    void setTextRenderFormat( QgsRenderContext::TextRenderFormat format );
%Docstring
Sets the text render ``format``, which dictates how text is rendered (e.g. as paths or real text objects).

.. warning::

   Calling the setLabelingEngineSettings() method will reset the text render format to match the default
   text render format from the label engine settings.

.. seealso:: :py:func:`textRenderFormat`

.. versionadded:: 3.4.3
%End

    void setOutputImageFormat( QImage::Format format );
%Docstring
sets format of internal QImage
%End
    QImage::Format outputImageFormat() const;
%Docstring
format of internal QImage, default QImage.Format_ARGB32_Premultiplied
%End

    bool hasValidSettings() const;
%Docstring
Check whether the map settings are valid and can be used for rendering
%End
    QgsRectangle visibleExtent() const;
%Docstring
Returns the actual extent derived from requested extent that takes takes output image size into account
%End

    QPolygonF visiblePolygon() const;
%Docstring
Returns the visible area as a polygon (may be rotated)

.. versionadded:: 2.8
%End
    double mapUnitsPerPixel() const;
%Docstring
Returns the distance in geographical coordinates that equals to one pixel in the map
%End

    double scale() const;
%Docstring
Returns the calculated map scale.
The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.
%End

    void setExpressionContext( const QgsExpressionContext &context );
%Docstring
Sets the expression context. This context is used for all expression evaluation
associated with this map settings.

.. seealso:: :py:func:`expressionContext`

.. versionadded:: 2.12
%End

    const QgsExpressionContext &expressionContext() const;
%Docstring
Gets the expression context. This context should be used for all expression evaluation
associated with this map settings.

.. seealso:: :py:func:`setExpressionContext`

.. versionadded:: 2.12
%End

    QgsCoordinateTransformContext transformContext() const;
%Docstring
Returns the coordinate transform context, which stores various
information regarding which datum transforms should be used when transforming points
from a source to destination coordinate reference system.

.. seealso:: :py:func:`setTransformContext`

.. versionadded:: 3.0
%End

    void setTransformContext( const QgsCoordinateTransformContext &context );
%Docstring
Sets the coordinate transform ``context``, which stores various
information regarding which datum transforms should be used when transforming points
from a source to destination coordinate reference system.

.. seealso:: :py:func:`transformContext`

.. versionadded:: 3.0
%End

    const QgsPathResolver &pathResolver() const;
%Docstring
Returns the path resolver for conversion between relative and absolute paths
during rendering operations, e.g. for resolving relative symbol paths.

.. seealso:: :py:func:`setPathResolver`

.. versionadded:: 3.0
%End

    void setPathResolver( const QgsPathResolver &resolver );
%Docstring
Sets the path ``resolver`` for conversion between relative and absolute paths
during rendering operations, e.g. for resolving relative symbol paths.

.. seealso:: :py:func:`pathResolver`

.. versionadded:: 3.0
%End

    const QgsMapToPixel &mapToPixel() const;

    double layerToMapUnits( const QgsMapLayer *layer, const QgsRectangle &referenceExtent = QgsRectangle() ) const;
%Docstring
Computes an *estimated* conversion factor between layer and map units: layerUnits * layerToMapUnits = mapUnits

:param layer: The layer
:param referenceExtent: A reference extent based on which to perform the computation. If not specified, the layer extent is used

.. versionadded:: 2.12
%End

    QgsRectangle layerExtentToOutputExtent( const QgsMapLayer *layer, QgsRectangle extent ) const;
%Docstring
transform bounding box from layer's CRS to output CRS

.. seealso:: :py:func:`layerToMapCoordinates`

:return: a bounding box (aligned rectangle) containing the transformed extent
%End

    QgsRectangle outputExtentToLayerExtent( const QgsMapLayer *layer, QgsRectangle extent ) const;
%Docstring
transform bounding box from output CRS to layer's CRS

.. seealso:: :py:func:`mapToLayerCoordinates`

:return: a bounding box (aligned rectangle) containing the transformed extent
%End

    QgsPointXY layerToMapCoordinates( const QgsMapLayer *layer, QgsPointXY point ) const;
%Docstring
transform point coordinates from layer's CRS to output CRS

:return: the transformed point
%End

    QgsRectangle layerToMapCoordinates( const QgsMapLayer *layer, QgsRectangle rect ) const;
%Docstring
transform rectangle from layer's CRS to output CRS

.. seealso:: :py:func:`layerExtentToOutputExtent`

:return: the transformed rectangle
%End

    QgsPointXY mapToLayerCoordinates( const QgsMapLayer *layer, QgsPointXY point ) const;
%Docstring
transform point coordinates from output CRS to layer's CRS

:return: the transformed point
%End

    QgsRectangle mapToLayerCoordinates( const QgsMapLayer *layer, QgsRectangle rect ) const;
%Docstring
transform rectangle from output CRS to layer's CRS

.. seealso:: :py:func:`outputExtentToLayerExtent`

:return: the transformed rectangle
%End

    QgsCoordinateTransform layerTransform( const QgsMapLayer *layer ) const;
%Docstring
Returns the coordinate transform from layer's CRS to destination CRS

:return: transform - may be invalid if the transform is not needed
%End

    QgsRectangle fullExtent() const;
%Docstring
returns current extent of layer set
%End


    void readXml( QDomNode &node );
%Docstring
serialization */
%End

    void writeXml( QDomNode &node, QDomDocument &doc );

    void setSegmentationTolerance( double tolerance );
%Docstring
Sets the segmentation tolerance applied when rendering curved geometries

:param tolerance: the segmentation tolerance*
%End
    double segmentationTolerance() const;
%Docstring
Gets the segmentation tolerance applied when rendering curved geometries
%End

    void setSegmentationToleranceType( QgsAbstractGeometry::SegmentationToleranceType type );
%Docstring
Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)

:param type: the segmentation tolerance typename*
%End
    QgsAbstractGeometry::SegmentationToleranceType segmentationToleranceType() const;
%Docstring
Gets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)
%End

    void setLabelingEngineSettings( const QgsLabelingEngineSettings &settings );
%Docstring
Sets the global configuration of the labeling engine.

.. note::

   Calling this method will reset the textRenderFormat() to match the default
   text render format from the label engine ``settings``.

.. seealso:: :py:func:`labelingEngineSettings`


.. versionadded:: 3.0
%End

    const QgsLabelingEngineSettings &labelingEngineSettings() const;
%Docstring
Returns the global configuration of the labeling engine.

.. seealso:: :py:func:`setLabelingEngineSettings`

.. versionadded:: 3.0
%End

    QgsGeometry labelBoundaryGeometry() const;
%Docstring
Returns the label boundary geometry, which restricts where in the rendered map labels are permitted to be
placed. By default this is a null geometry, which indicates that labels can be placed anywhere within
the map's visiblePolygon().

The geometry is specified using the map's destinationCrs().

.. seealso:: :py:func:`setLabelBoundaryGeometry`

.. seealso:: :py:func:`labelBlockingRegions`

.. versionadded:: 3.6
%End

    void setLabelBoundaryGeometry( const QgsGeometry &boundary );
%Docstring
Sets the label ``boundary`` geometry, which restricts where in the rendered map labels are permitted to be
placed.

A null ``boundary`` geometry (the default) indicates that labels can be placed anywhere within
the map's visiblePolygon().

The geometry is specified using the map's destinationCrs().

.. seealso:: :py:func:`labelBoundaryGeometry`

.. seealso:: :py:func:`setLabelBlockingRegions`

.. versionadded:: 3.6
%End

    void setLabelBlockingRegions( const QList< QgsLabelBlockingRegion > &regions );
%Docstring
Sets a list of ``regions`` to avoid placing labels within.

.. seealso:: :py:func:`labelBlockingRegions`

.. seealso:: :py:func:`setLabelBoundaryGeometry`

.. versionadded:: 3.6
%End

    QList< QgsLabelBlockingRegion > labelBlockingRegions() const;
%Docstring
Returns the list of regions to avoid placing labels within.

.. seealso:: :py:func:`setLabelBlockingRegions`

.. seealso:: :py:func:`labelBoundaryGeometry`

.. versionadded:: 3.6
%End

    void setSimplifyMethod( const QgsVectorSimplifyMethod &method );
%Docstring
Sets the simplification setting to use when rendering vector layers.

If the simplify ``method`` is enabled, it will override all other layer-specific simplification
settings and will apply to all vector layers rendered for the map.

This can be used to specify global simplification methods to apply during map exports,
e.g. to allow vector layers to be simplified to an appropriate maximum level of detail
during PDF exports.

The default is to use no global simplification, and fallback to individual layer's settings instead.

.. seealso:: :py:func:`simplifyMethod`

.. versionadded:: 3.10
%End

    const QgsVectorSimplifyMethod &simplifyMethod() const;
%Docstring
Returns the simplification settings to use when rendering vector layers.

If enabled, it will override all other layer-specific simplification
settings and will apply to all vector layers rendered for the map.

The default is to use no global simplification, and fallback to individual layer's settings instead.

.. seealso:: :py:func:`setSimplifyMethod`

.. versionadded:: 3.10
%End

    void addRenderedFeatureHandler( QgsRenderedFeatureHandlerInterface *handler );
%Docstring
Adds a rendered feature ``handler`` to use while rendering the map settings.

Ownership of ``handler`` is NOT transferred, and it is the caller's responsibility to ensure
that the handler exists for the lifetime of the map render job.

.. seealso:: :py:func:`renderedFeatureHandlers`

.. versionadded:: 3.10
%End

    QList< QgsRenderedFeatureHandlerInterface * > renderedFeatureHandlers() const;
%Docstring
Returns the list of rendered feature handlers to use while rendering the map settings.

.. seealso:: :py:func:`addRenderedFeatureHandler`

.. versionadded:: 3.10
%End

  protected:




















    void updateDerived();

};

QFlags<QgsMapSettings::Flag> operator|(QgsMapSettings::Flag f1, QFlags<QgsMapSettings::Flag> f2);



/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgsmapsettings.h                                            *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
 ************************************************************************/