Skip to content

Commit

Permalink
Backport Dox improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
nyalldawson committed Jan 11, 2019
1 parent 0697f0f commit 2aeb38c
Show file tree
Hide file tree
Showing 2 changed files with 212 additions and 9 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@ The ``render`` argument indicates whether the category should initially be rende
%End

QgsRendererCategory( const QgsRendererCategory &cat );
%Docstring
Copy constructor.
%End

QVariant value() const;
%Docstring
Expand Down Expand Up @@ -129,6 +132,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;

Expand Down Expand Up @@ -165,47 +176,137 @@ 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

bool updateCategoryValue( int catIndex, const QVariant &value );
%Docstring
Changes the value for the category with the specified index.

.. seealso:: :py:func:`updateCategorySymbol`

.. seealso:: :py:func:`updateCategoryLabel`

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

bool updateCategorySymbol( int catIndex, QgsSymbol *symbol /Transfer/ );
%Docstring
Changes the ``symbol`` for the category with the specified index.

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 );
%Docstring
Changes the ``label`` for the category with the specified index.

A category's label is used to represent the category within
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 );
Expand Down
112 changes: 107 additions & 5 deletions src/core/symbology/qgscategorizedsymbolrenderer.h
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,9 @@ class CORE_EXPORT QgsRendererCategory
*/
QgsRendererCategory( const QVariant &value, QgsSymbol *symbol SIP_TRANSFER, const QString &label, bool render = true );

/**
* Copy constructor.
*/
QgsRendererCategory( const QgsRendererCategory &cat );
QgsRendererCategory &operator=( QgsRendererCategory cat );

Expand Down Expand Up @@ -141,6 +144,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;
Expand All @@ -164,38 +175,129 @@ 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 );

/**
* Changes the value for the category with the specified index.
*
* \see updateCategorySymbol()
* \see updateCategoryLabel()
* \see updateCategoryRenderState()
*/
bool updateCategoryValue( int catIndex, const QVariant &value );

/**
* Changes the \a symbol for the category with the specified index.
*
* Ownership of \a symbol is transferred to the renderer.
*
* \see updateCategoryValue()
* \see updateCategoryLabel()
* \see updateCategoryRenderState()
*/
bool updateCategorySymbol( int catIndex, QgsSymbol *symbol SIP_TRANSFER );

/**
* Changes the \a label for the category with the specified index.
*
* A category's label is used to represent the category within
* legends and the layer tree.
*
* \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;
Expand Down

0 comments on commit 2aeb38c

Please sign in to comment.