Class: QgsCategorizedSymbolRenderer¶

A feature renderer which represents features using a list of renderer categories.

Class Hierarchy¶

Base classes¶

QgsFeatureRenderer

Abstract base class for all 2D vector feature renderers.

Methods

`addCategory`	Adds a new category to the renderer.
`categories`	Returns a list of all categories recognized by the renderer.
`categoryIndexForLabel`	Returns the index of the category with the specified label (or -1 if the label was not found, or is not unique).
`categoryIndexForValue`	Returns the index for the category with the specified value (or -1 if not found).
`classAttribute`	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.
`dataDefinedSizeLegend`	Returns configuration of appearance of legend when using data-defined size for marker symbols.
`deleteAllCategories`	Deletes all existing categories from the renderer.
`deleteCategory`	Deletes the category with the specified index from the renderer.
`matchToSymbols`	Replaces category symbols with the symbols from a style that have a matching name and symbol type.
`moveCategory`	Moves an existing category at index position from to index position to.
`rebuildHash`	hashtable for faster access to symbols
`setClassAttribute`	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.
`setDataDefinedSizeLegend`	Configures appearance of legend when renderer is configured to use data-defined size for marker symbols.
`setSourceColorRamp`	Sets the source color ramp.
`setSourceSymbol`	Sets the source symbol for the renderer, which is the base symbol used for the each categories' symbol before applying the categories' color.
`skipRender`
`sortByLabel`	Sorts the existing categories by their label.
`sortByValue`	Sorts the existing categories by their value.
`sourceColorRamp`	Returns the source color ramp, from which each categories' color is derived.
`sourceSymbol`	Returns the renderer's source symbol, which is the base symbol used for the each categories' symbol before applying the categories' color.
`symbolForValue`	Returns the matching symbol corresponding to an attribute value.
`symbolForValue2`	Returns the matching symbol corresponding to an attribute value.
`updateCategoryLabel`	Changes the label for the category with the specified index.
`updateCategoryRenderState`	Changes the render state for the category with the specified index.
`updateCategorySymbol`	Changes the symbol for the category with the specified index.
`updateCategoryValue`	Changes the value for the category with the specified index.
`updateColorRamp`	Update the color ramp used and all symbols colors.
`updateSymbols`	Update all the symbols but leave categories and colors.

Static Methods

`convertFromRenderer`	Creates a new `QgsCategorizedSymbolRenderer` from an existing renderer.
`create`	Creates a categorized renderer from an XML element.
`createCategories`	Create categories for a list of values.
`displayString`	Returns a localized representation of value with the given precision, if precision is -1 then precision is guessed from the default QVariant.toString output.

class qgis.core.QgsCategorizedSymbolRenderer[source]¶

Bases: QgsFeatureRenderer

__init__(attrName: str | None = '', categories: Iterable[QgsRendererCategory] = [])

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().

Parameters:

attrName (Optional[str] = '')
categories (Iterable[QgsRendererCategory] = [])

addCategory(self, category: QgsRendererCategory)[source]¶

Adds a new category to the renderer.

See also

categories()

Parameters:: category (QgsRendererCategory)

categories(self) → List[QgsRendererCategory]¶

Returns a list of all categories recognized by the renderer.

Return type:: List[QgsRendererCategory]

categoryIndexForLabel(self, val: str | None) → int[source]¶

Returns the index of the category with the specified label (or -1 if the label was not found, or is not unique).

Parameters:: val (Optional[str])
Return type:: int

categoryIndexForValue(self, val: Any) → int[source]¶

Returns the index for the category with the specified value (or -1 if not found).

Parameters:: val (Any)
Return type:: int

classAttribute(self) → str[source]¶

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 also

setClassAttribute()

Return type:: str

static convertFromRenderer(renderer: QgsFeatureRenderer | None, layer: QgsVectorLayer | None = None) → QgsCategorizedSymbolRenderer | None[source]¶

Creates a new QgsCategorizedSymbolRenderer from an existing renderer.

Since QGIS 3.20, the optional layer parameter is required for conversions of some renderer types.

Return type:

Optional[QgsCategorizedSymbolRenderer]

Returns:

a new renderer if the conversion was possible, otherwise None.

Parameters:

renderer (Optional[QgsFeatureRenderer])
layer (Optional[QgsVectorLayer] = None)

static create(element: QDomElement, context: QgsReadWriteContext) → QgsFeatureRenderer | None[source]¶

Creates a categorized renderer from an XML element.

Parameters:

element (QDomElement)
context (QgsReadWriteContext)

Return type:

Optional[QgsFeatureRenderer]

static createCategories(values: Iterable[Any], symbol: QgsSymbol | None, layer: QgsVectorLayer | None = None, fieldName: str | None = '') → List[QgsRendererCategory][source]¶

Create categories for a list of values. The returned symbols in the category list will be a modification of symbol.

If layer and fieldName are specified it will try to find nicer values to represent the description for the categories based on the respective field configuration.

Added in version 3.6.

Parameters:

values (Iterable[Any])
symbol (Optional[QgsSymbol])
layer (Optional[QgsVectorLayer] = None)
fieldName (Optional[str] = '')

Return type:

List[QgsRendererCategory]

dataDefinedSizeLegend(self) → QgsDataDefinedSizeLegend | None[source]¶

Returns configuration of appearance of legend when using data-defined size for marker symbols. Will return None if the functionality is disabled.

Return type:: Optional[QgsDataDefinedSizeLegend]

deleteAllCategories(self)[source]¶: Deletes all existing categories from the renderer.

See also

deleteCategory()

deleteCategory(self, catIndex: int) → bool[source]¶

Deletes the category with the specified index from the renderer.

See also

deleteAllCategories()

Parameters:: catIndex (int)
Return type:: bool

static displayString(value: Any, precision: int = -1) → str[source]¶

Returns a localized representation of value with the given precision, if precision is -1 then precision is guessed from the default QVariant.toString output.

Note

Precision is ignored for integers.

Added in version 3.22.1.

Parameters:

value (Any)
precision (int = -1)

Return type:

str

matchToSymbols(self, style: QgsStyle | None, type: Qgis.SymbolType, caseSensitive: bool = True, useTolerantMatch: bool = False)[source]¶

Replaces category symbols with the symbols from a style that have a matching name and symbol type.

The unmatchedCategories list will be filled with all existing categories which could not be matched to a symbol in style.

The unmatchedSymbols list will be filled with all symbol names from style which were not matched to an existing category.

If caseSensitive is False, then a case-insensitive match will be performed. If useTolerantMatch is True, then non-alphanumeric characters in style and category names will be ignored during the match.

Returns the count of symbols matched.

Added in version 3.4.

Parameters:

style (Optional[QgsStyle])
type (Qgis.SymbolType)
caseSensitive (bool = True)
useTolerantMatch (bool = False) -> (int)

moveCategory(self, from_: int, to: int)[source]¶

Moves an existing category at index position from to index position to.

Parameters:

from (int)
to (int)

rebuildHash(self)[source]¶: hashtable for faster access to symbols

setClassAttribute(self, attr: str | None)[source]¶

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 also

classAttribute()

Parameters:: attr (Optional[str])

setDataDefinedSizeLegend(self, settings: QgsDataDefinedSizeLegend | None)[source]¶

Configures appearance of legend when renderer is configured to use data-defined size for marker symbols. This allows configuring for which values (symbol sizes) should be shown in the legend, whether to display different symbol sizes collapsed in one legend node or separated across multiple legend nodes etc.

When renderer does not use data-defined size or does not use marker symbols, these settings will be ignored. Takes ownership of the passed settings objects. None is a valid input that disables data-defined size legend.

Parameters:: settings (Optional[QgsDataDefinedSizeLegend])

setSourceColorRamp(self, ramp: QgsColorRamp | None)[source]¶

Sets the source color ramp.

Parameters:: ramp (Optional[QgsColorRamp]) – color ramp. Ownership is transferred to the renderer

See also

sourceColorRamp()

See also

setSourceSymbol()

setSourceSymbol(self, sym: QgsSymbol | None)[source]¶

Sets the source symbol for the renderer, which is the base symbol used for the each categories’ symbol before applying the categories’ color.

Parameters:: sym (Optional[QgsSymbol]) – source symbol, ownership is transferred to the renderer

See also

sourceSymbol()

See also

setSourceColorRamp()

skipRender(self) → QgsSymbol | None[source]¶

Deprecated since version 3.40.

No longer used, will be removed in QGIS 4.0.

Return type:: Optional[QgsSymbol]

sortByLabel(self, order: Qt.SortOrder = Qt.AscendingOrder)[source]¶

Sorts the existing categories by their label.

See also

sortByValue()

Parameters:: order (Qt.SortOrder = Qt.AscendingOrder)

sortByValue(self, order: Qt.SortOrder = Qt.AscendingOrder)[source]¶

Sorts the existing categories by their value.

See also

sortByLabel()

Parameters:: order (Qt.SortOrder = Qt.AscendingOrder)

sourceColorRamp(self) → QgsColorRamp | None[source]¶

Returns the source color ramp, from which each categories’ color is derived.

See also

setSourceColorRamp()

See also

sourceSymbol()

Return type:: Optional[QgsColorRamp]

sourceSymbol(self) → QgsSymbol | None[source]¶

Returns the renderer’s source symbol, which is the base symbol used for the each categories’ symbol before applying the categories’ color.

See also

setSourceSymbol()

See also

sourceColorRamp()

Return type:: Optional[QgsSymbol]

symbolForValue(self, value: Any) → QgsSymbol | None[source]¶

Returns the matching symbol corresponding to an attribute value.

Deprecated since version 3.40: Use variant which takes a second bool argument instead.

Parameters:: value (Any)
Return type:: Optional[QgsSymbol]

symbolForValue2(self, value: Any)¶

Returns the matching symbol corresponding to an attribute value.

Will return None if no matching symbol was found for value, or if the category corresponding to value is currently disabled (see QgsRendererCategory.renderState()).

If foundMatchingSymbol is specified then it will be set to True if a matching category was found. This can be used to differentiate between None returned as a result of no matching category vs None as a result of disabled categories.

Parameters:: value (Any) -> (Optional[QgsSymbol])

updateCategoryLabel(self, catIndex: int, label: str | None) → bool[source]¶

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.

See also

updateCategoryValue()

See also

updateCategoryLabel()

See also

updateCategoryRenderState()

Parameters:

catIndex (int)
label (Optional[str])

Return type:

bool

updateCategoryRenderState(self, catIndex: int, render: bool) → bool[source]¶

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 also

updateCategoryValue()

See also

updateCategorySymbol()

See also

updateCategoryLabel()

Parameters: