From 224df0a273e9fb13be5462c3fd3bba990a760793 Mon Sep 17 00:00:00 2001 From: Nyall Dawson Date: Mon, 7 Jan 2019 14:58:03 +1000 Subject: [PATCH] Add missing documentation for QgsCategorizedRenderer --- .../qgscategorizedsymbolrenderer.sip.in | 78 ++++++++++++++++- .../symbology/qgscategorizedsymbolrenderer.h | 84 +++++++++++++++++-- 2 files changed, 153 insertions(+), 9 deletions(-) diff --git a/python/core/auto_generated/symbology/qgscategorizedsymbolrenderer.sip.in b/python/core/auto_generated/symbology/qgscategorizedsymbolrenderer.sip.in index aa6e4a48df4..bc775bbed47 100644 --- a/python/core/auto_generated/symbology/qgscategorizedsymbolrenderer.sip.in +++ b/python/core/auto_generated/symbology/qgscategorizedsymbolrenderer.sip.in @@ -135,6 +135,14 @@ class QgsCategorizedSymbolRenderer : QgsFeatureRenderer public: QgsCategorizedSymbolRenderer( const QString &attrName = QString(), const QgsCategoryList &categories = QgsCategoryList() ); +%Docstring +Constructor for QgsCategorizedSymbolRenderer. + +The ``attrName`` argument specifies the layer's field name, or expression, which the categories will be matched against. + +A list of renderer ``categories`` can optionally be specified. If no categories are specified in the constructor, they +can be added later by calling addCategory(). +%End virtual QgsSymbol *symbolForFeature( const QgsFeature &feature, QgsRenderContext &context ) const; @@ -171,15 +179,18 @@ symbol for the renderer. %End const QgsCategoryList &categories() const; +%Docstring +Returns a list of all categories recognized by the renderer. +%End int categoryIndexForValue( const QVariant &val ); %Docstring -Returns index of category with specified value (-1 if not found) +Returns the index for the category with the specified value (or -1 if not found). %End int categoryIndexForLabel( const QString &val ); %Docstring -Returns index of category with specified label (-1 if not found or not unique) +Returns the index of the category with the specified label (or -1 if the label was not found, or is not unique). .. versionadded:: 2.5 %End @@ -193,6 +204,8 @@ If ``value`` is a list, then the category will match any of the values from this .. seealso:: :py:func:`updateCategorySymbol` .. seealso:: :py:func:`updateCategoryLabel` + +.. seealso:: :py:func:`updateCategoryRenderState` %End bool updateCategorySymbol( int catIndex, QgsSymbol *symbol /Transfer/ ); @@ -204,6 +217,8 @@ Ownership of ``symbol`` is transferred to the renderer. .. seealso:: :py:func:`updateCategoryValue` .. seealso:: :py:func:`updateCategoryLabel` + +.. seealso:: :py:func:`updateCategoryRenderState` %End bool updateCategoryLabel( int catIndex, const QString &label ); @@ -216,32 +231,87 @@ legends and the layer tree. .. seealso:: :py:func:`updateCategoryValue` .. seealso:: :py:func:`updateCategoryLabel` + +.. seealso:: :py:func:`updateCategoryRenderState` %End bool updateCategoryRenderState( int catIndex, bool render ); %Docstring +Changes the render state for the category with the specified index. + +The render state indicates whether or not the category will be rendered, +and is reflected in whether the category is checked with the project's layer tree. + +.. seealso:: :py:func:`updateCategoryValue` + +.. seealso:: :py:func:`updateCategorySymbol` + +.. seealso:: :py:func:`updateCategoryLabel` .. versionadded:: 2.5 %End void addCategory( const QgsRendererCategory &category ); +%Docstring +Adds a new ``category`` to the renderer. + +.. seealso:: :py:func:`categories` +%End + bool deleteCategory( int catIndex ); +%Docstring +Deletes the category with the specified index from the renderer. + +.. seealso:: :py:func:`deleteAllCategories` +%End + void deleteAllCategories(); +%Docstring +Deletes all existing categories from the renderer. + +.. seealso:: :py:func:`deleteCategory` +%End void moveCategory( int from, int to ); %Docstring -Moves the category at index position from to index position to. +Moves an existing category at index position from to index position to. %End void sortByValue( Qt::SortOrder order = Qt::AscendingOrder ); +%Docstring +Sorts the existing categories by their value. + +.. seealso:: :py:func:`sortByLabel` +%End + void sortByLabel( Qt::SortOrder order = Qt::AscendingOrder ); +%Docstring +Sorts the existing categories by their label. + +.. seealso:: :py:func:`sortByValue` +%End QString classAttribute() const; +%Docstring +Returns the class attribute for the renderer, which is the field name +or expression string from the layer which will be matched against the +renderer categories. + +.. seealso:: :py:func:`setClassAttribute` +%End + void setClassAttribute( const QString &attr ); +%Docstring +Sets the class attribute for the renderer, which is the field name +or expression string from the layer which will be matched against the +renderer categories. + +.. seealso:: :py:func:`classAttribute` +%End static QgsFeatureRenderer *create( QDomElement &element, const QgsReadWriteContext &context ) /Factory/; %Docstring -create renderer from XML element +Creates a categorized renderer from an XML ``element``. %End virtual QDomElement save( QDomDocument &doc, const QgsReadWriteContext &context ); diff --git a/src/core/symbology/qgscategorizedsymbolrenderer.h b/src/core/symbology/qgscategorizedsymbolrenderer.h index 28b4175cc5a..8236ba6a2d5 100644 --- a/src/core/symbology/qgscategorizedsymbolrenderer.h +++ b/src/core/symbology/qgscategorizedsymbolrenderer.h @@ -149,6 +149,14 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer { public: + /** + * Constructor for QgsCategorizedSymbolRenderer. + * + * The \a attrName argument specifies the layer's field name, or expression, which the categories will be matched against. + * + * A list of renderer \a categories can optionally be specified. If no categories are specified in the constructor, they + * can be added later by calling addCategory(). + */ QgsCategorizedSymbolRenderer( const QString &attrName = QString(), const QgsCategoryList &categories = QgsCategoryList() ); QgsSymbol *symbolForFeature( const QgsFeature &feature, QgsRenderContext &context ) const override; @@ -172,13 +180,18 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer */ void updateSymbols( QgsSymbol *sym ); + /** + * Returns a list of all categories recognized by the renderer. + */ const QgsCategoryList &categories() const { return mCategories; } - //! Returns index of category with specified value (-1 if not found) + /** + * Returns the index for the category with the specified value (or -1 if not found). + */ int categoryIndexForValue( const QVariant &val ); /** - * Returns index of category with specified label (-1 if not found or not unique) + * Returns the index of the category with the specified label (or -1 if the label was not found, or is not unique). * \since QGIS 2.5 */ int categoryIndexForLabel( const QString &val ); @@ -190,6 +203,7 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer * * \see updateCategorySymbol() * \see updateCategoryLabel() + * \see updateCategoryRenderState() */ bool updateCategoryValue( int catIndex, const QVariant &value ); @@ -200,6 +214,7 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer * * \see updateCategoryValue() * \see updateCategoryLabel() + * \see updateCategoryRenderState() */ bool updateCategorySymbol( int catIndex, QgsSymbol *symbol SIP_TRANSFER ); @@ -211,26 +226,85 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer * * \see updateCategoryValue() * \see updateCategoryLabel() + * \see updateCategoryRenderState() */ bool updateCategoryLabel( int catIndex, const QString &label ); - //! \since QGIS 2.5 + /** + * Changes the render state for the category with the specified index. + * + * The render state indicates whether or not the category will be rendered, + * and is reflected in whether the category is checked with the project's layer tree. + * + * \see updateCategoryValue() + * \see updateCategorySymbol() + * \see updateCategoryLabel() + * + * \since QGIS 2.5 + */ bool updateCategoryRenderState( int catIndex, bool render ); + /** + * Adds a new \a category to the renderer. + * + * \see categories() + */ void addCategory( const QgsRendererCategory &category ); + + /** + * Deletes the category with the specified index from the renderer. + * + * \see deleteAllCategories() + */ bool deleteCategory( int catIndex ); + + /** + * Deletes all existing categories from the renderer. + * + * \see deleteCategory() + */ void deleteAllCategories(); - //! Moves the category at index position from to index position to. + /** + * Moves an existing category at index position from to index position to. + */ void moveCategory( int from, int to ); + /** + * Sorts the existing categories by their value. + * + * \see sortByLabel() + */ void sortByValue( Qt::SortOrder order = Qt::AscendingOrder ); + + /** + * Sorts the existing categories by their label. + * + * \see sortByValue() + */ void sortByLabel( Qt::SortOrder order = Qt::AscendingOrder ); + /** + * Returns the class attribute for the renderer, which is the field name + * or expression string from the layer which will be matched against the + * renderer categories. + * + * \see setClassAttribute() + */ QString classAttribute() const { return mAttrName; } + + /** + * Sets the class attribute for the renderer, which is the field name + * or expression string from the layer which will be matched against the + * renderer categories. + * + * \see classAttribute() + */ void setClassAttribute( const QString &attr ) { mAttrName = attr; } - //! create renderer from XML element + /** + * Creates a categorized renderer from an XML \a element. + */ static QgsFeatureRenderer *create( QDomElement &element, const QgsReadWriteContext &context ) SIP_FACTORY; QDomElement save( QDomDocument &doc, const QgsReadWriteContext &context ) override;