QGIS/python/core/auto_generated/symbology/qgsrenderer.sip.in

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






typedef QList<QgsSymbol *> QgsSymbolList;





class QgsSymbolLevelItem
{
%Docstring(signature="appended")
Represents a symbol level during vector rendering operations.
%End

%TypeHeaderCode
#include "qgsrenderer.h"
%End
  public:
    QgsSymbolLevelItem( QgsSymbol *symbol, int layer );

    QgsSymbol *symbol() const;
%Docstring
The symbol of this symbol level
%End

    int layer() const;
%Docstring
The layer of this symbol level
%End

  protected:
};

typedef QList< QgsSymbolLevelItem > QgsSymbolLevel;

typedef QList< QList< QgsSymbolLevelItem > > QgsSymbolLevelOrder;



class QgsFeatureRenderer
{
%Docstring(signature="appended")
Abstract base class for all 2D vector feature renderers.
%End

%TypeHeaderCode
#include "qgsrenderer.h"
%End
%ConvertToSubClassCode

    const QString type = sipCpp->type();

    if ( type == QLatin1String( "singleSymbol" ) )
      sipType = sipType_QgsSingleSymbolRenderer;
    else if ( type == QLatin1String( "categorizedSymbol" ) )
      sipType = sipType_QgsCategorizedSymbolRenderer;
    else if ( type == QLatin1String( "graduatedSymbol" ) )
      sipType = sipType_QgsGraduatedSymbolRenderer;
    else if ( type == QLatin1String( "RuleRenderer" ) )
      sipType = sipType_QgsRuleBasedRenderer;
    else if ( type == QLatin1String( "heatmapRenderer" ) )
      sipType = sipType_QgsHeatmapRenderer;
    else if ( type == QLatin1String( "invertedPolygonRenderer" ) )
      sipType = sipType_QgsInvertedPolygonRenderer;
    else if ( type == QLatin1String( "pointCluster" ) )
      sipType = sipType_QgsPointClusterRenderer;
    else if ( type == QLatin1String( "pointDisplacement" ) )
      sipType = sipType_QgsPointDisplacementRenderer;
    else if ( type == QLatin1String( "25dRenderer" ) )
      sipType = sipType_Qgs25DRenderer;
    else if ( type == QLatin1String( "nullSymbol" ) )
      sipType = sipType_QgsNullSymbolRenderer;
    else if ( type == QLatin1String( "embeddedSymbol" ) )
      sipType = sipType_QgsEmbeddedSymbolRenderer;
    else
      sipType = 0;
%End
  public:

    enum class Property
    {
      HeatmapRadius,
      HeatmapMaximum,
    };

    static const QgsPropertiesDefinition &propertyDefinitions();
%Docstring
Returns the symbol property definitions.

.. versionadded:: 3.18
%End


    static QgsFeatureRenderer *defaultRenderer( Qgis::GeometryType geomType ) /Factory/;
%Docstring
Returns a new renderer - used by default in vector layers
%End

    QString type() const;

    virtual QgsSymbol *symbolForFeature( const QgsFeature &feature, QgsRenderContext &context ) const = 0;
%Docstring
To be overridden

Must be called between :py:func:`~QgsFeatureRenderer.startRender` and
:py:func:`~QgsFeatureRenderer.stopRender` calls.

:param feature: feature
:param context: render context

:return: returns pointer to symbol or 0 if symbol was not found
%End

    virtual QgsSymbol *originalSymbolForFeature( const QgsFeature &feature, QgsRenderContext &context ) const;
%Docstring
Returns symbol for feature. The difference compared to
:py:func:`~QgsFeatureRenderer.symbolForFeature` is that it returns
original symbol which can be used as an identifier for renderer's rule -
the former may return a temporary replacement of a symbol for use in
rendering.
%End

    virtual QSet< QString > legendKeysForFeature( const QgsFeature &feature, QgsRenderContext &context ) const;
%Docstring
Returns legend keys matching a specified feature.
%End

    virtual void startRender( QgsRenderContext &context, const QgsFields &fields );
%Docstring
Must be called when a new render cycle is started. A call to
:py:func:`~QgsFeatureRenderer.startRender` must always be followed by a
corresponding call to :py:func:`~QgsFeatureRenderer.stopRender` after
all features have been rendered.

:param context: Additional information passed to the renderer about the
                job which will be rendered
:param fields: The fields available for rendering

.. seealso:: :py:func:`stopRender`

.. warning::

   This method is not thread safe. Before calling :py:func:`~QgsFeatureRenderer.startRender` in a non-main thread,
   the renderer should instead be cloned and :py:func:`~QgsFeatureRenderer.startRender`/:py:func:`~QgsFeatureRenderer.stopRender` called on the clone.
%End

    virtual void stopRender( QgsRenderContext &context );
%Docstring
Must be called when a render cycle has finished, to allow the renderer
to clean up.

Calls to :py:func:`~QgsFeatureRenderer.stopRender` must always be
preceded by a call to :py:func:`~QgsFeatureRenderer.startRender`.

.. warning::

   This method is not thread safe. Before calling :py:func:`~QgsFeatureRenderer.startRender` in a non-main thread,
   the renderer should instead be cloned and :py:func:`~QgsFeatureRenderer.startRender`/:py:func:`~QgsFeatureRenderer.stopRender` called on the clone.

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

    virtual bool canSkipRender();
%Docstring
Returns ``True`` if the renderer can be entirely skipped, i.e. if it is
known in advance that no features will be rendered.

.. warning::

   Must be called between :py:func:`~QgsFeatureRenderer.startRender` and :py:func:`~QgsFeatureRenderer.stopRender` calls.

.. versionadded:: 3.30
%End

    virtual QString filter( const QgsFields &fields = QgsFields() );
%Docstring
If a renderer does not require all the features this method may be
overridden and return an expression used as where clause. This will be
called once after :py:func:`~QgsFeatureRenderer.startRender` and before
the first call to :py:func:`~QgsFeatureRenderer.renderFeature`. By
default this returns a null string and all features will be requested.
You do not need to specify the extent in here, this is taken care of
separately and will be combined with a filter returned from this method.

:return: An expression used as where clause
%End

    virtual QSet<QString> usedAttributes( const QgsRenderContext &context ) const = 0;
%Docstring
Returns a list of attributes required by this renderer. Attributes not
listed in here may not have been requested from the provider at
rendering time.

:return: A set of attributes
%End

    virtual bool usesEmbeddedSymbols() const;
%Docstring
Returns ``True`` if the renderer uses embedded symbols for features. The
default implementation returns ``False``.

.. versionadded:: 3.20
%End

    virtual bool filterNeedsGeometry() const;
%Docstring
Returns ``True`` if this renderer requires the geometry to apply the
filter.
%End

    virtual ~QgsFeatureRenderer();

    virtual QgsFeatureRenderer *clone() const = 0 /Factory/;
%Docstring
Create a deep copy of this renderer. Should be implemented by all
subclasses and generate a proper subclass.

:return: A copy of this renderer
%End

    virtual bool renderFeature( const QgsFeature &feature, QgsRenderContext &context, int layer = -1, bool selected = false, bool drawVertexMarker = false ) throw( QgsCsException );
%Docstring
Render a feature using this renderer in the given context. Must be
called between :py:func:`~QgsFeatureRenderer.startRender` and
:py:func:`~QgsFeatureRenderer.stopRender` calls. Default implementation
renders a symbol as determined by
:py:func:`~QgsFeatureRenderer.symbolForFeature` call. Returns ``True``
if the feature has been returned (this is used for example to determine
whether the feature may be labelled).

If layer is not -1, the renderer should draw only a particular layer
from symbols (in order to support symbol level rendering).

.. seealso:: :py:func:`startRender`

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

    virtual QString dump() const;
%Docstring
Returns debug information about this renderer
%End

    enum Capability
    {
      SymbolLevels,
      MoreSymbolsPerFeature,
      Filter,
      ScaleDependent
    };

    typedef QFlags<QgsFeatureRenderer::Capability> Capabilities;


    virtual QgsFeatureRenderer::Capabilities capabilities();
%Docstring
Returns details about internals of this renderer.

E.g. if you only want to deal with visible features:

.. code-block:: python

     if not renderer.capabilities().testFlag(QgsFeatureRenderer.Filter) or renderer.willRenderFeature(feature, context):
         deal_with_my_feature()
     else:
         skip_the_curren_feature()
%End

    virtual Qgis::FeatureRendererFlags flags() const;
%Docstring
Returns flags associated with the renderer.

.. versionadded:: 3.40
%End

    virtual QgsSymbolList symbols( QgsRenderContext &context ) const;
%Docstring
Returns list of symbols used by the renderer.

:param context: render context
%End

    bool usingSymbolLevels() const;
    void setUsingSymbolLevels( bool usingSymbolLevels );

    static QgsFeatureRenderer *load( QDomElement &symbologyElem, const QgsReadWriteContext &context ) /Factory/;
%Docstring
create a renderer from XML element
%End

    virtual QDomElement save( QDomDocument &doc, const QgsReadWriteContext &context );
%Docstring
Stores renderer properties to an XML element.

Subclasses which override this method should call
:py:func:`~QgsFeatureRenderer.saveRendererData` as part of their
implementation in order to store all common base class properties in the
returned DOM element.
%End

    virtual QDomElement writeSld( QDomDocument &doc, const QString &styleName, const QVariantMap &props = QVariantMap() ) const;
%Docstring
create the SLD UserStyle element following the SLD v1.1 specs with the
given name
%End

    static QgsFeatureRenderer *loadSld( const QDomNode &node, Qgis::GeometryType geomType, QString &errorMessage ) /Factory/;
%Docstring
Create a new renderer according to the information contained in the
UserStyle element of a SLD style document

:param node: the node in the SLD document whose the UserStyle element is
             a child
:param geomType: the geometry type of the features, used to convert
                 Symbolizer elements
:param errorMessage: it will contain the error message if something went
                     wrong

:return: the renderer
%End

    virtual void toSld( QDomDocument &doc, QDomElement &element, const QVariantMap &props = QVariantMap() ) const;
%Docstring
used from subclasses to create SLD Rule elements following SLD v1.1
specs
%End

    QSet< QString > legendKeys() const;
%Docstring
Returns the set of all legend keys used by the renderer.

.. seealso:: :py:func:`legendSymbolItems`

.. versionadded:: 3.32
%End

    virtual bool legendSymbolItemsCheckable() const;
%Docstring
Returns ``True`` if symbology items in legend are checkable.
%End

    virtual bool legendSymbolItemChecked( const QString &key );
%Docstring
Returns ``True`` if the legend symbology item with the specified ``key``
is checked.

.. seealso:: :py:func:`checkLegendSymbolItem`

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

    virtual void checkLegendSymbolItem( const QString &key, bool state = true );
%Docstring
Sets whether the legend symbology item with the specified ``ley`` should
be checked.

.. seealso:: :py:func:`legendSymbolItemChecked`

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

    virtual void setLegendSymbolItem( const QString &key, QgsSymbol *symbol /Transfer/ );
%Docstring
Sets the symbol to be used for a legend symbol item.

:param key: rule key for legend symbol
:param symbol: new symbol for legend item. Ownership is transferred to
               renderer.

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

    virtual QString legendKeyToExpression( const QString &key, QgsVectorLayer *layer, bool &ok /Out/ ) const;
%Docstring
Attempts to convert the specified legend rule ``key`` to a QGIS
expression matching the features displayed using that key.

:param key: legend key
:param layer: associated vector layer

:return: - QGIS expression string for matching features with the
           specified key
         - ok: ``True`` if legend key was successfully converted to a
           filter expression

.. seealso:: :py:func:`legendKeys`

.. versionadded:: 3.26
%End

    virtual QgsLegendSymbolList legendSymbolItems() const;
%Docstring
Returns a list of symbology items for the legend

.. seealso:: :py:func:`createLegendNodes`

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

    virtual QList<QgsLayerTreeModelLegendNode *> createLegendNodes( QgsLayerTreeLayer *nodeLayer ) const /Factory/;
%Docstring
Returns a list of legend nodes to be used for the legend for the
renderer.

Ownership is transferred to the caller.

The default implementation creates a legend node for each symbol item
returned by :py:func:`~QgsFeatureRenderer.legendSymbolItems`

.. seealso:: :py:func:`legendSymbolItems`

.. versionadded:: 3.38
%End

    virtual QString legendClassificationAttribute() const;
%Docstring
If supported by the renderer, return classification attribute for the
use in legend
%End

    void setVertexMarkerAppearance( Qgis::VertexMarkerType type, double size );
%Docstring
Sets type and size of editing vertex markers for subsequent rendering
%End

    virtual bool willRenderFeature( const QgsFeature &feature, QgsRenderContext &context ) const;
%Docstring
Returns whether the renderer will render a feature or not. Must be
called between :py:func:`~QgsFeatureRenderer.startRender` and
:py:func:`~QgsFeatureRenderer.stopRender` calls. Default implementation
uses :py:func:`~QgsFeatureRenderer.symbolForFeature`.
%End

    virtual QgsSymbolList symbolsForFeature( const QgsFeature &feature, QgsRenderContext &context ) const;
%Docstring
Returns list of symbols used for rendering the feature. For renderers
that do not support MoreSymbolsPerFeature it is more efficient to use
:py:func:`~QgsFeatureRenderer.symbolForFeature`
%End

    virtual QgsSymbolList originalSymbolsForFeature( const QgsFeature &feature, QgsRenderContext &context ) const;
%Docstring
Equivalent of :py:func:`~QgsFeatureRenderer.originalSymbolsForFeature`
call extended to support renderers that may use more symbols per feature
- similar to :py:func:`~QgsFeatureRenderer.symbolsForFeature`
%End

    virtual void modifyRequestExtent( QgsRectangle &extent, QgsRenderContext &context );
%Docstring
Allows for a renderer to modify the extent of a feature request prior to
rendering

:param extent: reference to request's filter extent. Modify extent to
               change the extent of feature request
:param context: render context
%End

    QgsPaintEffect *paintEffect() const;
%Docstring
Returns the current paint effect for the renderer.

:return: paint effect

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

    void setPaintEffect( QgsPaintEffect *effect /Transfer/ );
%Docstring
Sets the current paint effect for the renderer.

:param effect: paint effect. Ownership is transferred to the renderer.

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

    bool forceRasterRender() const;
%Docstring
Returns whether the renderer must render as a raster.

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

    void setForceRasterRender( bool forceRaster );
%Docstring
Sets whether the renderer should be rendered to a raster destination.

:param forceRaster: set to ``True`` if renderer must be drawn on a
                    raster surface. This may be desirable for highly
                    detailed layers where rendering as a vector would
                    result in a large, complex vector output.

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

    void setDataDefinedProperty( Property key, const QgsProperty &property );
%Docstring
Sets a data defined property for the renderer. Any existing property
with the same key will be overwritten.

.. seealso:: :py:func:`dataDefinedProperties`

.. seealso:: Property

.. versionadded:: 3.38
%End

    QgsPropertyCollection &dataDefinedProperties();
%Docstring
Returns a reference to the renderer's property collection, used for data
defined overrides.

.. seealso:: :py:func:`setDataDefinedProperties`

.. seealso:: Property

.. versionadded:: 3.38
%End


    void setDataDefinedProperties( const QgsPropertyCollection &collection );
%Docstring
Sets the renderer's property collection, used for data defined
overrides.

:param collection: property collection. Existing properties will be
                   replaced.

.. seealso:: :py:func:`dataDefinedProperties`

.. versionadded:: 3.38
%End

    double referenceScale() const;
%Docstring
Returns the symbology reference scale.

This represents the desired scale denominator for the rendered map, eg
1000.0 for a 1:1000 map render. A value of -1 indicates that symbology
scaling by reference scale is disabled.

The symbology reference scale is an optional property which specifies
the reference scale at which symbology in paper units (such a
millimeters or points) is fixed to. For instance, if the scale is 1000
then a 2mm thick line will be rendered at exactly 2mm thick when a map
is rendered at 1:1000, or 1mm thick when rendered at 1:2000, or 4mm
thick at 1:500.

.. seealso:: :py:func:`setReferenceScale`

.. versionadded:: 3.22
%End

    void setReferenceScale( double scale );
%Docstring
Sets the symbology reference ``scale``.

This should match the desired scale denominator for the rendered map, eg
1000.0 for a 1:1000 map render. Set to -1 to disable symbology scaling
by reference scale.

The symbology reference scale is an optional property which specifies
the reference scale at which symbology in paper units (such a
millimeters or points) is fixed to. For instance, if ``scale`` is set to
1000 then a 2mm thick line will be rendered at exactly 2mm thick when a
map is rendered at 1:1000, or 1mm thick when rendered at 1:2000, or 4mm
thick at 1:500.

.. seealso:: :py:func:`referenceScale`

.. versionadded:: 3.22
%End

    QgsFeatureRequest::OrderBy orderBy() const;
%Docstring
Gets the order in which features shall be processed by this renderer.

.. note::

   this property has no effect if :py:func:`~QgsFeatureRenderer.orderByEnabled` is ``False``

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

    void setOrderBy( const QgsFeatureRequest::OrderBy &orderBy );
%Docstring
Define the order in which features shall be processed by this renderer.

.. note::

   this property has no effect if :py:func:`~QgsFeatureRenderer.orderByEnabled` is ``False``

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

    bool orderByEnabled() const;
%Docstring
Returns whether custom ordering will be applied before features are
processed by this renderer.

.. seealso:: :py:func:`orderBy`

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

    void setOrderByEnabled( bool enabled );
%Docstring
Sets whether custom ordering should be applied before features are
processed by this renderer.

:param enabled: set to ``True`` to enable custom feature ordering

.. seealso:: :py:func:`setOrderBy`

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

    virtual void setEmbeddedRenderer( QgsFeatureRenderer *subRenderer /Transfer/ );
%Docstring
Sets an embedded renderer (subrenderer) for this feature renderer. The
base class implementation does nothing with subrenderers, but individual
derived classes can use these to modify their behavior.

:param subRenderer: the embedded renderer. Ownership will be
                    transferred.

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

    virtual const QgsFeatureRenderer *embeddedRenderer() const;
%Docstring
Returns the current embedded renderer (subrenderer) for this feature
renderer. The base class implementation does not use subrenderers and
will always return ``None``.

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

    virtual bool accept( QgsStyleEntityVisitorInterface *visitor ) const;
%Docstring
Accepts the specified symbology ``visitor``, causing it to visit all
symbols associated with the renderer.

Returns ``True`` if the visitor should continue visiting other objects,
or ``False`` if visiting should be canceled.

.. versionadded:: 3.10
%End

    void copyRendererData( QgsFeatureRenderer *destRenderer ) const;
%Docstring
Clones generic renderer data to another renderer.

Currently clones

- Order by
- Paint effect
- Reference scale
- Symbol levels enabled/disabled
- Force raster render enabled/disabled
- Data defined properties

:param destRenderer: destination renderer for copied effect

.. versionadded:: 3.22
%End

    double maximumExtentBuffer( QgsRenderContext &context ) const;
%Docstring
Returns the maximum extent buffer found in this renderer's symbols.

.. note::

   Returns 0 if the renderer doesn't have any symbols.

.. versionadded:: 3.42
%End

  protected:
    QgsFeatureRenderer( const QString &type );

    void renderFeatureWithSymbol( const QgsFeature &feature, QgsSymbol *symbol, QgsRenderContext &context, int layer, bool selected, bool drawVertexMarker ) throw( QgsCsException );
%Docstring
Render the ``feature`` with the ``symbol`` using ``context``. Use
``layer`` to specify the symbol layer, ``selected`` to specify if it
should be rendered as selected and ``drawVertexMarker`` to specify if
vertex markers should be rendered.
%End

    void renderVertexMarker( QPointF pt, QgsRenderContext &context );
%Docstring
render editing vertex marker at specified point
%End
    void renderVertexMarkerPolyline( QPolygonF &pts, QgsRenderContext &context );
%Docstring
render editing vertex marker for a polyline
%End
    void renderVertexMarkerPolygon( QPolygonF &pts, QList<QPolygonF> *rings, QgsRenderContext &context );
%Docstring
render editing vertex marker for a polygon
%End

    static QPointF _getPoint( QgsRenderContext &context, const QgsPoint &point );
%Docstring
Creates a point in screen coordinates from a wkb string in map
coordinates
%End

    void saveRendererData( QDomDocument &doc, QDomElement &element, const QgsReadWriteContext &context );
%Docstring
Saves generic renderer data into the specified ``element``.

This method should be called in a subclass'
:py:func:`~QgsFeatureRenderer.save` implementation in order to store all
common base class properties in the DOM ``element``.

.. versionadded:: 3.22
%End








    static void convertSymbolSizeScale( QgsSymbol *symbol, Qgis::ScaleMethod method, const QString &field );
%Docstring
Converts old sizeScale expressions to symbol level data defined sizes.
%End

    static void convertSymbolRotation( QgsSymbol *symbol, const QString &field );
%Docstring
Converts old rotation expressions to symbol level data defined angles.
%End



  private:
    QgsFeatureRenderer( const QgsFeatureRenderer & );
    QgsFeatureRenderer &operator=( const QgsFeatureRenderer & );
};

QFlags<QgsFeatureRenderer::Capability> operator|(QgsFeatureRenderer::Capability f1, QFlags<QgsFeatureRenderer::Capability> f2);



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