Improve documentation for renderer registry metadata (refs #13973)

wonder-sk · wonder-sk · commit 492c1a9ff024 · 2016-01-25T18:16:32.000+01:00
diff --git a/python/core/symbology-ng/qgsrendererv2registry.sip b/python/core/symbology-ng/qgsrendererv2registry.sip
@@ -19,8 +19,14 @@ class QgsRendererV2AbstractMetadata
     /** Return new instance of the renderer given the DOM element. Returns NULL on error.
      * Pure virtual function: must be implemented in derived classes.  */
     virtual QgsFeatureRendererV2* createRenderer( QDomElement& elem ) = 0 /Factory/;
-    /** Return new instance of settings widget for the renderer. Returns NULL on error. */
-    virtual QgsRendererV2Widget* createRendererWidget( QgsVectorLayer* layer, QgsStyleV2* style, QgsFeatureRendererV2* renderer ) /Factory/;
+    /** Return new instance of settings widget for the renderer. Returns NULL on error.
+     *
+     * The \a oldRenderer argument may refer to previously used renderer (or it is null).
+     * If not null, it may be used to initialize GUI of the widget from the previous settings.
+     * The old renderer does not have to be of the same type as returned by createRenderer().
+     * When using \a oldRenderer make sure to make a copy of it - it will be deleted afterwards.
+     */
+    virtual QgsRendererV2Widget* createRendererWidget( QgsVectorLayer* layer, QgsStyleV2* style, QgsFeatureRendererV2* oldRenderer ) /Factory/;
 
     virtual QgsFeatureRendererV2* createRendererFromSld( QDomElement& elem, QGis::GeometryType geomType ) /Factory/;
 };
diff --git a/src/core/symbology-ng/qgsrendererv2registry.h b/src/core/symbology-ng/qgsrendererv2registry.h
@@ -49,9 +49,15 @@ class CORE_EXPORT QgsRendererV2AbstractMetadata
     /** Return new instance of the renderer given the DOM element. Returns NULL on error.
      * Pure virtual function: must be implemented in derived classes.  */
     virtual QgsFeatureRendererV2* createRenderer( QDomElement& elem ) = 0;
-    /** Return new instance of settings widget for the renderer. Returns NULL on error. */
-    virtual QgsRendererV2Widget* createRendererWidget( QgsVectorLayer* layer, QgsStyleV2* style, QgsFeatureRendererV2* renderer )
-    { Q_UNUSED( layer ); Q_UNUSED( style ); Q_UNUSED( renderer ); return nullptr; }
+    /** Return new instance of settings widget for the renderer. Returns NULL on error.
+     *
+     * The \a oldRenderer argument may refer to previously used renderer (or it is null).
+     * If not null, it may be used to initialize GUI of the widget from the previous settings.
+     * The old renderer does not have to be of the same type as returned by createRenderer().
+     * When using \a oldRenderer make sure to make a copy of it - it will be deleted afterwards.
+     */
+    virtual QgsRendererV2Widget* createRendererWidget( QgsVectorLayer* layer, QgsStyleV2* style, QgsFeatureRendererV2* oldRenderer )
+    { Q_UNUSED( layer ); Q_UNUSED( style ); Q_UNUSED( oldRenderer ); return nullptr; }
 
     virtual QgsFeatureRendererV2* createRendererFromSld( QDomElement& elem, QGis::GeometryType geomType )
     { Q_UNUSED( elem ); Q_UNUSED( geomType ); return nullptr; }
