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
{

%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

.. note::

   this function is used to convert old sizeScale expressions to symbol
   level DataDefined size
%End

    static void convertSymbolRotation( QgsSymbol *symbol, const QString &field );
%Docstring

.. note::

   this function is used to convert old rotations expressions to symbol
   level DataDefined angle
%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   *
 ************************************************************************/