[sip, doxygen] Geometry modifier bindings

and lots of doxymentation

python/core/core.sip

@@ -290,9 +290,7 @@
 %Include symbology-ng/qgslinesymbollayerv2.sip
 %Include symbology-ng/qgsmarkersymbollayerv2.sip
 %Include symbology-ng/qgssymbollayerv2registry.sip
-%Include symbology-ng/qgspolygongeneratorsymbollayerv2.sip
+%Include symbology-ng/qgsgeometrygeneratorsymbollayerv2.sip
-%Include symbology-ng/qgslinegeneratorsymbollayerv2.sip
-%Include symbology-ng/qgspointgeneratorsymbollayerv2.sip
 
 %Include symbology-ng/qgssymbologyv2conversion.sip
 

python/core/symbology-ng/qgsgeometrygeneratorsymbollayerv2.sip

@@ -1,5 +1,5 @@
 /***************************************************************************
- qgslinegeneratorsymbollayerv2.sip
+ qgsgeometrygeneratorsymbollayerv2.sip
  ---------------------
  begin                : November 2015
  copyright            : (C) 2015 by Matthias Kuhn
@@ -12,18 +12,26 @@
  *   (at your option) any later version.                                   *
  *                                                                         *
  ***************************************************************************/
-class QgsLineGeneratorSymbolLayerV2 : QgsLineSymbolLayerV2
+class QgsGeometryGeneratorSymbolLayerV2 : QgsSymbolLayerV2
 {
 %TypeHeaderCode
-#include "qgslinegeneratorsymbollayerv2.h"
+#include "qgsgeometrygeneratorsymbollayerv2.h"
 %End
   public:
     static QgsSymbolLayerV2* create( const QgsStringMap& properties = QgsStringMap() );
 
-    QgsLineGeneratorSymbolLayerV2( QgsLineSymbolV2* symbol, const QgsStringMap& properties = QgsStringMap() );
-
     QString layerType() const;
 
+    /**
+     * Set the type of symbol which should be created.
+     * Should match with the return type of the expression.
+     *
+     * @param symbolType The symbol type which shall be used below this symbol.
+     */
+    void setSymbolType( QgsSymbolV2::SymbolType symbolType );
+
+    QgsSymbolV2::SymbolType symbolType() const;
+
     void startRender( QgsSymbolV2RenderContext& context );
 
     void stopRender( QgsSymbolV2RenderContext& context );
@@ -36,6 +44,9 @@ class QgsLineGeneratorSymbolLayerV2 : QgsLineSymbolLayerV2
 
     void setGeometryExpression( const QString& exp );
 
+    /**
+     * Get the expression to generate this geometry.
+     */
     QString geometryExpression() const;
 
     virtual QgsSymbolV2* subSymbol();
@@ -49,8 +60,8 @@ class QgsLineGeneratorSymbolLayerV2 : QgsLineSymbolLayerV2
     //! care about the geometry of its parents.
     bool isCompatibleWithSymbol( QgsSymbolV2* symbol );
 
-    virtual void renderPolyline( const QPolygonF& point, QgsSymbolV2RenderContext& context );
+    virtual void render( QgsSymbolV2RenderContext& context );
 
   private:
-    QgsLineGeneratorSymbolLayerV2( const QgsLineGeneratorSymbolLayerV2& copy );
+    QgsGeometryGeneratorSymbolLayerV2( const QgsGeometryGeneratorSymbolLayerV2& copy );
 };

python/core/symbology-ng/qgspointgeneratorsymbollayerv2.sip

@@ -1,56 +0,0 @@
-/***************************************************************************
- qgspointgeneratorsymbollayerv2.sip
- ---------------------
- begin                : November 2015
- copyright            : (C) 2015 by Matthias Kuhn
- email                : matthias at opengis dot ch
- ***************************************************************************
- *                                                                         *
- *   This program is free software; you can redistribute it and/or modify  *
- *   it under the terms of the GNU General Public License as published by  *
- *   the Free Software Foundation; either version 2 of the License, or     *
- *   (at your option) any later version.                                   *
- *                                                                         *
- ***************************************************************************/
-class QgsPointGeneratorSymbolLayerV2 : QgsMarkerSymbolLayerV2
-{
-%TypeHeaderCode
-#include "qgspointgeneratorsymbollayerv2.h"
-%End
-  public:
-    static QgsSymbolLayerV2* create( const QgsStringMap& properties = QgsStringMap() );
-
-    QgsPointGeneratorSymbolLayerV2( QgsMarkerSymbolV2* symbol, const QgsStringMap& properties = QgsStringMap() );
-
-    QString layerType() const;
-
-    void startRender( QgsSymbolV2RenderContext& context );
-
-    void stopRender( QgsSymbolV2RenderContext& context );
-
-    QgsSymbolLayerV2* clone() const;
-
-    QgsStringMap properties() const;
-
-    void drawPreviewIcon( QgsSymbolV2RenderContext& context, QSize size );
-
-    void setGeometryExpression( const QString& exp );
-
-    QString geometryExpression() const;
-
-    virtual QgsSymbolV2* subSymbol();
-
-    virtual bool setSubSymbol( QgsSymbolV2* symbol );
-
-    virtual QSet<QString> usedAttributes() const;
-
-    //! Will always return true.
-    //! This is a hybrid layer, it constructs its own geometry so it does not
-    //! care about the geometry of its parents.
-    bool isCompatibleWithSymbol( QgsSymbolV2* symbol );
-
-    void renderPoint( const QPointF& point, QgsSymbolV2RenderContext& context );
-
-  private:
-    QgsPointGeneratorSymbolLayerV2( const QgsPointGeneratorSymbolLayerV2& copy );
-};

python/core/symbology-ng/qgspolygongeneratorsymbollayerv2.sip

@@ -1,56 +0,0 @@
-/***************************************************************************
- qgspolygongeneratorsymbollayerv2.sip
- ---------------------
- begin                : November 2015
- copyright            : (C) 2015 by Matthias Kuhn
- email                : matthias at opengis dot ch
- ***************************************************************************
- *                                                                         *
- *   This program is free software; you can redistribute it and/or modify  *
- *   it under the terms of the GNU General Public License as published by  *
- *   the Free Software Foundation; either version 2 of the License, or     *
- *   (at your option) any later version.                                   *
- *                                                                         *
- ***************************************************************************/
-class QgsPolygonGeneratorSymbolLayerV2 : QgsFillSymbolLayerV2
-{
-%TypeHeaderCode
-#include "qgspolygongeneratorsymbollayerv2.h"
-%End
-  public:
-    static QgsSymbolLayerV2* create( const QgsStringMap& properties = QgsStringMap() );
-
-    QgsPolygonGeneratorSymbolLayerV2( QgsFillSymbolV2* symbol, const QgsStringMap& properties = QgsStringMap() );
-
-    QString layerType() const;
-
-    void startRender( QgsSymbolV2RenderContext& context );
-
-    void stopRender( QgsSymbolV2RenderContext& context );
-
-    QgsSymbolLayerV2* clone() const;
-
-    QgsStringMap properties() const;
-
-    void drawPreviewIcon( QgsSymbolV2RenderContext& context, QSize size );
-
-    void setGeometryExpression( const QString& exp );
-
-    QString geometryExpression() const;
-
-    virtual QgsSymbolV2* subSymbol();
-
-    virtual bool setSubSymbol( QgsSymbolV2* symbol );
-
-    virtual QSet<QString> usedAttributes() const;
-
-    //! Will always return true.
-    //! This is a hybrid layer, it constructs its own geometry so it does not
-    //! care about the geometry of its parents.
-    bool isCompatibleWithSymbol( QgsSymbolV2* symbol );
-
-    void renderPolygon( const QPolygonF& points, QList<QPolygonF>* rings, QgsSymbolV2RenderContext& context );
-
-  private:
-    QgsPolygonGeneratorSymbolLayerV2( const QgsPolygonGeneratorSymbolLayerV2& copy );
-};

python/core/symbology-ng/qgssymbollayerv2.sip

@@ -58,8 +58,8 @@ class QgsSymbolLayerV2
 	sipType = sipType_QgsFillSymbolLayerV2;
       break;
 
-    default:
+    case QgsSymbolV2::Hybrid:
-      sipType = 0;
+      sipType = sipType_QgsGeometryGeneratorSymbolLayerV2;
       break;
   }
 %End

python/core/symbology-ng/qgssymbolv2.sip

@@ -160,6 +160,11 @@ class QgsSymbolV2
      */
     bool clipFeaturesToExtent() const;
 
+    /**
+     * Return a list of attributes required to render this feature.
+     * This should include any attributes required by the symbology including
+     * the ones required by expressions.
+     */
     QSet<QString> usedAttributes() const;
 
     /** Returns whether the symbol utilises any data defined properties.
@@ -170,10 +175,41 @@ class QgsSymbolV2
     void setLayer( const QgsVectorLayer* layer );
     const QgsVectorLayer* layer() const;
 
+    /**
+     * Render a feature.
+     */
+    void renderFeature( const QgsFeature& feature, QgsRenderContext& context, int layer = -1, bool selected = false, bool drawVertexMarker = false, int currentVertexMarkerType = 0, int currentVertexMarkerSize = 0 );
+
   protected:
     QgsSymbolV2( SymbolType type, const QgsSymbolLayerV2List& layers /Transfer/ ); // can't be instantiated
 
+    /**
+     * Creates a point in screen coordinates from a wkb string in map
+     * coordinates
+     */
+    static const unsigned char* _getPoint( QPointF& pt, QgsRenderContext& context, const unsigned char* wkb );
+    /**
+     * Creates a line string in screen coordinates from a wkb string in map
+     * coordinates
+     */
+    static const unsigned char* _getLineString( QPolygonF& pts, QgsRenderContext& context, const unsigned char* wkb, bool clipToExtent = true );
+    /**
+     * Creates a polygon in screen coordinates from a wkb string in map
+     * coordinates
+     */
+    static const unsigned char* _getPolygon( QPolygonF& pts, QList<QPolygonF>& holes, QgsRenderContext& context, const unsigned char* wkb, bool clipToExtent = true );
+
     QgsSymbolLayerV2List cloneLayers() const /Factory/;
+    /**
+     * Renders a context using a particular symbol layer without passing in a
+     * geometry. This is used as fallback, if the symbol being rendered is not
+     * compatible with the specified layer. In such a case, this method can be
+     * called and will call the layer's rendering method anyway but the
+     * geometry passed to the layer will be empty.
+     * This is required for layers that generate their own geometry from other
+     * information in the rendering context.
+     */
+    void renderUsingLayer( QgsSymbolLayerV2* layer, QgsSymbolV2RenderContext& context );
 
     //! check whether a symbol layer type can be used within the symbol
     //! (marker-marker, line-line, fill-fill/line)

python/gui/symbology-ng/qgssymbollayerv2widget.sip

@@ -63,7 +63,18 @@ class QgsSymbolLayerV2Widget : QWidget
     virtual QString dataDefinedPropertyLabel( const QString &entryName ) /Deprecated/;
 
   signals:
+    /**
+     * Should be emitted whenever configuration changes happened on this symbol layer configuration.
+     * If the subsymbol is changed, {@link symbolChanged()} should be emitted instead.
+     */
     void changed();
+    /**
+     * Should be emitted whenever the sub symbol changed on this symbol layer configuration.
+     * Normally {@link changed()} should be preferred.
+     *
+     * @see {@link changed()}
+     */
+    void symbolChanged();
 
   protected slots:
     void updateDataDefinedProperty();
@@ -424,3 +435,19 @@ class QgsCentroidFillSymbolLayerV2Widget : QgsSymbolLayerV2Widget
     virtual void setSymbolLayer( QgsSymbolLayerV2* layer );
     virtual QgsSymbolLayerV2* symbolLayer();
 };
+
+
+class QgsGeometryGeneratorSymbolLayerWidget : QgsSymbolLayerV2Widget
+{
+%TypeHeaderCode
+#include <qgssymbollayerv2widget.h>
+%End
+  public:
+    QgsGeometryGeneratorSymbolLayerWidget( const QgsVectorLayer* vl, QWidget* parent /TransferThis/ = nullptr );
+
+    static QgsSymbolLayerV2Widget* create( const QgsVectorLayer* vl ) /Factory/;
+
+    // from base class
+    virtual void setSymbolLayer( QgsSymbolLayerV2* layer );
+    virtual QgsSymbolLayerV2* symbolLayer();
+};

src/core/qgsclipper.h

@@ -65,15 +65,17 @@ class CORE_EXPORT QgsClipper
     static const double MIN_Y;
 
 
-    // A handy way to refer to the four boundaries
+    //! A handy way to refer to the four boundaries
     enum Boundary {XMax, XMin, YMax, YMin};
 
-    // Trims the given feature to a rectangular box. Returns the trimmed
+    /**
-    // feature in x and y. The shapeOpen parameter determines whether
+     * Trims the given feature to a rectangular box. Returns the trimmed
-    // the function treats the points as a closed shape (polygon), or as
+     * feature in x and y. The shapeOpen parameter determines whether
-    // an open shape (linestring).
+     * the function treats the points as a closed shape (polygon), or as
-    //
+     * an open shape (linestring).
-    // @note not available in python bindings on android
+     *
+     * @note not available in python bindings on android
+     */
     static void trimFeature( QVector<double>& x,
                              QVector<double>& y,
                              bool shapeOpen );

src/core/qgsrelation.h

@@ -251,6 +251,10 @@ class CORE_EXPORT QgsRelation
     bool isValid() const;
 
   protected:
+    /**
+     * Updates the validity status of this relation.
+     * Will be called internally whenever a member is changed.
+     */
     void updateRelationStatus();
 
   private:

src/core/symbology-ng/qgsgeometrygeneratorsymbollayerv2.h

@@ -53,8 +53,14 @@ class CORE_EXPORT QgsGeometryGeneratorSymbolLayerV2 : public QgsSymbolLayerV2
 
     void drawPreviewIcon( QgsSymbolV2RenderContext& context, QSize size ) override;
 
+    /**
+     * Set the expression to generate this geometry.
+     */
     void setGeometryExpression( const QString& exp );
 
+    /**
+     * Get the expression to generate this geometry.
+     */
     QString geometryExpression() const { return mExpression->expression(); }
 
     virtual QgsSymbolV2* subSymbol() override { return mSymbol; }
@@ -68,6 +74,16 @@ class CORE_EXPORT QgsGeometryGeneratorSymbolLayerV2 : public QgsSymbolLayerV2
     //! care about the geometry of its parents.
     bool isCompatibleWithSymbol( QgsSymbolV2* symbol ) override;
 
+    /**
+     * Will render this symbol layer using the context.
+     * In comparison to other symbols there is no geometry passed in, since
+     * the geometry will be created based on information from the context
+     * which contains a QgsRenderContext which in turn contains an expression
+     * context which is available to the evaluated expression.
+     *
+     * @param context The rendering context which will be used to render and to
+     *                construct a geometry.
+     */
     virtual void render( QgsSymbolV2RenderContext& context );
 
   private:

src/core/symbology-ng/qgssymbolv2.h

@@ -217,6 +217,11 @@ class CORE_EXPORT QgsSymbolV2
      */
     bool clipFeaturesToExtent() const { return mClipFeaturesToExtent; }
 
+    /**
+     * Return a list of attributes required to render this feature.
+     * This should include any attributes required by the symbology including
+     * the ones required by expressions.
+     */
     QSet<QString> usedAttributes() const;
 
     /** Returns whether the symbol utilises any data defined properties.
@@ -228,17 +233,45 @@ class CORE_EXPORT QgsSymbolV2
     void setLayer( const QgsVectorLayer* layer ) { mLayer = layer; }
     const QgsVectorLayer* layer() const { return mLayer; }
 
+    /**
+     * Render a feature.
+     */
     void renderFeature( const QgsFeature& feature, QgsRenderContext& context, int layer = -1, bool selected = false, bool drawVertexMarker = false, int currentVertexMarkerType = 0, int currentVertexMarkerSize = 0 );
 
   protected:
     QgsSymbolV2( SymbolType type, const QgsSymbolLayerV2List& layers ); // can't be instantiated
 
+    /**
+     * Creates a point in screen coordinates from a wkb string in map
+     * coordinates
+     */
     static const unsigned char* _getPoint( QPointF& pt, QgsRenderContext& context, const unsigned char* wkb );
+    /**
+     * Creates a line string in screen coordinates from a wkb string in map
+     * coordinates
+     */
     static const unsigned char* _getLineString( QPolygonF& pts, QgsRenderContext& context, const unsigned char* wkb, bool clipToExtent = true );
+    /**
+     * Creates a polygon in screen coordinates from a wkb string in map
+     * coordinates
+     */
     static const unsigned char* _getPolygon( QPolygonF& pts, QList<QPolygonF>& holes, QgsRenderContext& context, const unsigned char* wkb, bool clipToExtent = true );
 
+    /**
+     * Retrieve a cloned list of all layers that make up this symbol.
+     * Ownership is transferred to the caller.
+     */
     QgsSymbolLayerV2List cloneLayers() const;
 
+    /**
+     * Renders a context using a particular symbol layer without passing in a
+     * geometry. This is used as fallback, if the symbol being rendered is not
+     * compatible with the specified layer. In such a case, this method can be
+     * called and will call the layer's rendering method anyway but the
+     * geometry passed to the layer will be empty.
+     * This is required for layers that generate their own geometry from other
+     * information in the rendering context.
+     */
     void renderUsingLayer( QgsSymbolLayerV2* layer, QgsSymbolV2RenderContext& context );
 
     //! check whether a symbol layer type can be used within the symbol

src/gui/symbology-ng/qgssymbollayerv2widget.cpp

@@ -3129,4 +3129,3 @@ void QgsGeometryGeneratorSymbolLayerWidget::updateSymbolType()
 
   emit symbolChanged();
 }
-

src/gui/symbology-ng/qgssymbollayerv2widget.h

@@ -667,15 +667,18 @@ class GUI_EXPORT QgsGeometryGeneratorSymbolLayerWidget : public QgsSymbolLayerV2
     Q_OBJECT
 
   public:
-    QgsGeometryGeneratorSymbolLayerWidget( const QgsVectorLayer* vl, QWidget* parent = NULL );
+    QgsGeometryGeneratorSymbolLayerWidget( const QgsVectorLayer* vl, QWidget* parent = 0 );
 
+    /**
+     * Will be registered as factory
+     */
     static QgsSymbolLayerV2Widget* create( const QgsVectorLayer* vl ) { return new QgsGeometryGeneratorSymbolLayerWidget( vl ); }
 
     // from base class
     virtual void setSymbolLayer( QgsSymbolLayerV2* layer ) override;
     virtual QgsSymbolLayerV2* symbolLayer() override;
 
-  protected:
+  private:
     QgsGeometryGeneratorSymbolLayerV2* mLayer;
 
   private slots: