Skip to content

Commit 2aeb38c

Browse files
nyalldawsonnyalldawson
committedJan 11, 2019
Backport Dox improvements
1 parent 0697f0f commit 2aeb38c

File tree

2 files changed

+212
-9
lines changed

2 files changed

+212
-9
lines changed
 

‎python/core/auto_generated/symbology/qgscategorizedsymbolrenderer.sip.in

Lines changed: 105 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,9 @@ The ``render`` argument indicates whether the category should initially be rende
3737
%End
3838

3939
QgsRendererCategory( const QgsRendererCategory &cat );
40+
%Docstring
41+
Copy constructor.
42+
%End
4043

4144
QVariant value() const;
4245
%Docstring
@@ -129,6 +132,14 @@ class QgsCategorizedSymbolRenderer : QgsFeatureRenderer
129132
public:
130133

131134
QgsCategorizedSymbolRenderer( const QString &attrName = QString(), const QgsCategoryList &categories = QgsCategoryList() );
135+
%Docstring
136+
Constructor for QgsCategorizedSymbolRenderer.
137+
138+
The ``attrName`` argument specifies the layer's field name, or expression, which the categories will be matched against.
139+
140+
A list of renderer ``categories`` can optionally be specified. If no categories are specified in the constructor, they
141+
can be added later by calling addCategory().
142+
%End
132143

133144
virtual QgsSymbol *symbolForFeature( const QgsFeature &feature, QgsRenderContext &context ) const;
134145

@@ -165,47 +176,137 @@ symbol for the renderer.
165176
%End
166177

167178
const QgsCategoryList &categories() const;
179+
%Docstring
180+
Returns a list of all categories recognized by the renderer.
181+
%End
168182

169183
int categoryIndexForValue( const QVariant &val );
170184
%Docstring
171-
Returns index of category with specified value (-1 if not found)
185+
Returns the index for the category with the specified value (or -1 if not found).
172186
%End
173187

174188
int categoryIndexForLabel( const QString &val );
175189
%Docstring
176-
Returns index of category with specified label (-1 if not found or not unique)
190+
Returns the index of the category with the specified label (or -1 if the label was not found, or is not unique).
177191

178192
.. versionadded:: 2.5
179193
%End
180194

181195
bool updateCategoryValue( int catIndex, const QVariant &value );
196+
%Docstring
197+
Changes the value for the category with the specified index.
198+
199+
.. seealso:: :py:func:`updateCategorySymbol`
200+
201+
.. seealso:: :py:func:`updateCategoryLabel`
202+
203+
.. seealso:: :py:func:`updateCategoryRenderState`
204+
%End
205+
182206
bool updateCategorySymbol( int catIndex, QgsSymbol *symbol /Transfer/ );
207+
%Docstring
208+
Changes the ``symbol`` for the category with the specified index.
209+
210+
Ownership of ``symbol`` is transferred to the renderer.
211+
212+
.. seealso:: :py:func:`updateCategoryValue`
213+
214+
.. seealso:: :py:func:`updateCategoryLabel`
215+
216+
.. seealso:: :py:func:`updateCategoryRenderState`
217+
%End
218+
183219
bool updateCategoryLabel( int catIndex, const QString &label );
220+
%Docstring
221+
Changes the ``label`` for the category with the specified index.
222+
223+
A category's label is used to represent the category within
224+
legends and the layer tree.
225+
226+
.. seealso:: :py:func:`updateCategoryValue`
227+
228+
.. seealso:: :py:func:`updateCategoryLabel`
229+
230+
.. seealso:: :py:func:`updateCategoryRenderState`
231+
%End
184232

185233
bool updateCategoryRenderState( int catIndex, bool render );
186234
%Docstring
235+
Changes the render state for the category with the specified index.
236+
237+
The render state indicates whether or not the category will be rendered,
238+
and is reflected in whether the category is checked with the project's layer tree.
239+
240+
.. seealso:: :py:func:`updateCategoryValue`
241+
242+
.. seealso:: :py:func:`updateCategorySymbol`
243+
244+
.. seealso:: :py:func:`updateCategoryLabel`
187245

188246
.. versionadded:: 2.5
189247
%End
190248

191249
void addCategory( const QgsRendererCategory &category );
250+
%Docstring
251+
Adds a new ``category`` to the renderer.
252+
253+
.. seealso:: :py:func:`categories`
254+
%End
255+
192256
bool deleteCategory( int catIndex );
257+
%Docstring
258+
Deletes the category with the specified index from the renderer.
259+
260+
.. seealso:: :py:func:`deleteAllCategories`
261+
%End
262+
193263
void deleteAllCategories();
264+
%Docstring
265+
Deletes all existing categories from the renderer.
266+
267+
.. seealso:: :py:func:`deleteCategory`
268+
%End
194269

195270
void moveCategory( int from, int to );
196271
%Docstring
197-
Moves the category at index position from to index position to.
272+
Moves an existing category at index position from to index position to.
198273
%End
199274

200275
void sortByValue( Qt::SortOrder order = Qt::AscendingOrder );
276+
%Docstring
277+
Sorts the existing categories by their value.
278+
279+
.. seealso:: :py:func:`sortByLabel`
280+
%End
281+
201282
void sortByLabel( Qt::SortOrder order = Qt::AscendingOrder );
283+
%Docstring
284+
Sorts the existing categories by their label.
285+
286+
.. seealso:: :py:func:`sortByValue`
287+
%End
202288

203289
QString classAttribute() const;
290+
%Docstring
291+
Returns the class attribute for the renderer, which is the field name
292+
or expression string from the layer which will be matched against the
293+
renderer categories.
294+
295+
.. seealso:: :py:func:`setClassAttribute`
296+
%End
297+
204298
void setClassAttribute( const QString &attr );
299+
%Docstring
300+
Sets the class attribute for the renderer, which is the field name
301+
or expression string from the layer which will be matched against the
302+
renderer categories.
303+
304+
.. seealso:: :py:func:`classAttribute`
305+
%End
205306

206307
static QgsFeatureRenderer *create( QDomElement &element, const QgsReadWriteContext &context ) /Factory/;
207308
%Docstring
208-
create renderer from XML element
309+
Creates a categorized renderer from an XML ``element``.
209310
%End
210311

211312
virtual QDomElement save( QDomDocument &doc, const QgsReadWriteContext &context );

‎src/core/symbology/qgscategorizedsymbolrenderer.h

Lines changed: 107 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,9 @@ class CORE_EXPORT QgsRendererCategory
5252
*/
5353
QgsRendererCategory( const QVariant &value, QgsSymbol *symbol SIP_TRANSFER, const QString &label, bool render = true );
5454

55+
/**
56+
* Copy constructor.
57+
*/
5558
QgsRendererCategory( const QgsRendererCategory &cat );
5659
QgsRendererCategory &operator=( QgsRendererCategory cat );
5760

@@ -141,6 +144,14 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer
141144
{
142145
public:
143146

147+
/**
148+
* Constructor for QgsCategorizedSymbolRenderer.
149+
*
150+
* The \a attrName argument specifies the layer's field name, or expression, which the categories will be matched against.
151+
*
152+
* A list of renderer \a categories can optionally be specified. If no categories are specified in the constructor, they
153+
* can be added later by calling addCategory().
154+
*/
144155
QgsCategorizedSymbolRenderer( const QString &attrName = QString(), const QgsCategoryList &categories = QgsCategoryList() );
145156

146157
QgsSymbol *symbolForFeature( const QgsFeature &feature, QgsRenderContext &context ) const override;
@@ -164,38 +175,129 @@ class CORE_EXPORT QgsCategorizedSymbolRenderer : public QgsFeatureRenderer
164175
*/
165176
void updateSymbols( QgsSymbol *sym );
166177

178+
/**
179+
* Returns a list of all categories recognized by the renderer.
180+
*/
167181
const QgsCategoryList &categories() const { return mCategories; }
168182

169-
//! Returns index of category with specified value (-1 if not found)
183+
/**
184+
* Returns the index for the category with the specified value (or -1 if not found).
185+
*/
170186
int categoryIndexForValue( const QVariant &val );
171187

172188
/**
173-
* Returns index of category with specified label (-1 if not found or not unique)
189+
* Returns the index of the category with the specified label (or -1 if the label was not found, or is not unique).
174190
* \since QGIS 2.5
175191
*/
176192
int categoryIndexForLabel( const QString &val );
177193

194+
/**
195+
* Changes the value for the category with the specified index.
196+
*
197+
* \see updateCategorySymbol()
198+
* \see updateCategoryLabel()
199+
* \see updateCategoryRenderState()
200+
*/
178201
bool updateCategoryValue( int catIndex, const QVariant &value );
202+
203+
/**
204+
* Changes the \a symbol for the category with the specified index.
205+
*
206+
* Ownership of \a symbol is transferred to the renderer.
207+
*
208+
* \see updateCategoryValue()
209+
* \see updateCategoryLabel()
210+
* \see updateCategoryRenderState()
211+
*/
179212
bool updateCategorySymbol( int catIndex, QgsSymbol *symbol SIP_TRANSFER );
213+
214+
/**
215+
* Changes the \a label for the category with the specified index.
216+
*
217+
* A category's label is used to represent the category within
218+
* legends and the layer tree.
219+
*
220+
* \see updateCategoryValue()
221+
* \see updateCategoryLabel()
222+
* \see updateCategoryRenderState()
223+
*/
180224
bool updateCategoryLabel( int catIndex, const QString &label );
181225

182-
//! \since QGIS 2.5
226+
/**
227+
* Changes the render state for the category with the specified index.
228+
*
229+
* The render state indicates whether or not the category will be rendered,
230+
* and is reflected in whether the category is checked with the project's layer tree.
231+
*
232+
* \see updateCategoryValue()
233+
* \see updateCategorySymbol()
234+
* \see updateCategoryLabel()
235+
*
236+
* \since QGIS 2.5
237+
*/
183238
bool updateCategoryRenderState( int catIndex, bool render );
184239

240+
/**
241+
* Adds a new \a category to the renderer.
242+
*
243+
* \see categories()
244+
*/
185245
void addCategory( const QgsRendererCategory &category );
246+
247+
/**
248+
* Deletes the category with the specified index from the renderer.
249+
*
250+
* \see deleteAllCategories()
251+
*/
186252
bool deleteCategory( int catIndex );
253+
254+
/**
255+
* Deletes all existing categories from the renderer.
256+
*
257+
* \see deleteCategory()
258+
*/
187259
void deleteAllCategories();
188260

189-
//! Moves the category at index position from to index position to.
261+
/**
262+
* Moves an existing category at index position from to index position to.
263+
*/
190264
void moveCategory( int from, int to );
191265

266+
/**
267+
* Sorts the existing categories by their value.
268+
*
269+
* \see sortByLabel()
270+
*/
192271
void sortByValue( Qt::SortOrder order = Qt::AscendingOrder );
272+
273+
/**
274+
* Sorts the existing categories by their label.
275+
*
276+
* \see sortByValue()
277+
*/
193278
void sortByLabel( Qt::SortOrder order = Qt::AscendingOrder );
194279

280+
/**
281+
* Returns the class attribute for the renderer, which is the field name
282+
* or expression string from the layer which will be matched against the
283+
* renderer categories.
284+
*
285+
* \see setClassAttribute()
286+
*/
195287
QString classAttribute() const { return mAttrName; }
288+
289+
/**
290+
* Sets the class attribute for the renderer, which is the field name
291+
* or expression string from the layer which will be matched against the
292+
* renderer categories.
293+
*
294+
* \see classAttribute()
295+
*/
196296
void setClassAttribute( const QString &attr ) { mAttrName = attr; }
197297

198-
//! create renderer from XML element
298+
/**
299+
* Creates a categorized renderer from an XML \a element.
300+
*/
199301
static QgsFeatureRenderer *create( QDomElement &element, const QgsReadWriteContext &context ) SIP_FACTORY;
200302

201303
QDomElement save( QDomDocument &doc, const QgsReadWriteContext &context ) override;

0 commit comments

Comments
 (0)