Class: QgsCategorizedSymbolRenderer

class qgis.core.QgsCategorizedSymbolRenderer(attrName: str = '', categories: Iterable[QgsRendererCategory] = [])

Bases: QgsFeatureRenderer

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

Methods

accept

param visitor

addCategory

Adds a new category to the renderer.

capabilities

rtype

QgsFeatureRenderer.Capabilities

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

checkLegendSymbolItem

param key

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.

clone

rtype

QgsCategorizedSymbolRenderer

convertFromRenderer

Creates a new QgsCategorizedSymbolRenderer from an existing renderer.

convertSymbolRotation

convertSymbolSizeScale

create

Creates a categorized renderer from an XML element.

createCategories

Create categories for a list of values.

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.

dump

rtype

str

filter

param fields

filterNeedsGeometry

rtype

bool

legendClassificationAttribute

rtype

str

legendKeysForFeature

param feature

legendSymbolItemChecked

param key

legendSymbolItems

rtype

List[QgsLegendSymbolItem]

legendSymbolItemsCheckable

rtype

bool

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.

originalSymbolForFeature

param feature

rebuildHash

hashtable for faster access to symbols

renderFeatureWithSymbol

Render the feature with the symbol using context.

renderVertexMarker

render editing vertex marker at specified point

renderVertexMarkerPolygon

render editing vertex marker for a polygon

renderVertexMarkerPolyline

render editing vertex marker for a polyline

save

param doc

saveRendererData

Saves generic renderer data into the specified element.

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.

setLegendSymbolItem

param key

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.

startRender

param context

stopRender

param context

symbolForFeature

param feature

symbolForValue

Returns the matching symbol corresponding to an attribute value.

symbolForValue2

Returns the matching symbol corresponding to an attribute value.

symbols

param context

toSld

param doc

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.

usedAttributes

param context

accept(self, visitor: QgsStyleEntityVisitorInterface) bool
Parameters

visitor (QgsStyleEntityVisitorInterface) –

Return type

bool

addCategory(self, category: QgsRendererCategory)

Adds a new category to the renderer.

See also

categories()

Parameters

category (QgsRendererCategory) –

capabilities(self) QgsFeatureRenderer.Capabilities
Return type

QgsFeatureRenderer.Capabilities

categories(self) List[QgsRendererCategory]

Returns a list of all categories recognized by the renderer.

Return type

List[QgsRendererCategory]

categoryIndexForLabel(self, val: str) int

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

New in version 2.5.

Parameters

val (str) –

Return type

int

categoryIndexForValue(self, val: Any) int

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

Parameters

val (Any) –

Return type

int

checkLegendSymbolItem(self, key: str, state: bool = True)
Parameters
  • key (str) –

  • state (bool = True) –

classAttribute(self) str

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.

Return type

str

clone(self) QgsCategorizedSymbolRenderer
Return type

QgsCategorizedSymbolRenderer

convertFromRenderer(renderer: QgsFeatureRenderer, layer: QgsVectorLayer = None) QgsCategorizedSymbolRenderer

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

QgsCategorizedSymbolRenderer

Returns

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

New in version 2.5.

Parameters
convertSymbolRotation(symbol: QgsSymbol, field: str)

Note

this function is used to convert old rotations expressions to symbol level DataDefined angle

convertSymbolSizeScale(symbol: QgsSymbol, method: Qgis.ScaleMethod, field: str)

Note

this function is used to convert old sizeScale expressions to symbol level DataDefined size

create(element: QDomElement, context: QgsReadWriteContext) QgsFeatureRenderer

Creates a categorized renderer from an XML element.

Parameters
Return type

QgsFeatureRenderer

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

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.

New in version 3.6.

Parameters
Return type

List[QgsRendererCategory]

dataDefinedSizeLegend(self) QgsDataDefinedSizeLegend

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

New in version 3.0.

Return type

QgsDataDefinedSizeLegend

deleteAllCategories(self)

Deletes all existing categories from the renderer.

See also

deleteCategory()

deleteCategory(self, catIndex: int) bool

Deletes the category with the specified index from the renderer.

Parameters

catIndex (int) –

Return type

bool

dump(self) str
Return type

str

filter(self, fields: QgsFields = QgsFields()) str
Parameters

fields (QgsFields = QgsFields()) –

Return type

str

filterNeedsGeometry(self) bool
Return type

bool

legendClassificationAttribute(self) str
Return type

str

legendKeysForFeature(self, feature: QgsFeature, context: QgsRenderContext) Set[str]
Parameters
Return type

Set[str]

legendSymbolItemChecked(self, key: str) bool
Parameters

key (str) –

Return type

bool

legendSymbolItems(self) List[QgsLegendSymbolItem]
Return type

List[QgsLegendSymbolItem]

legendSymbolItemsCheckable(self) bool
Return type

bool

matchToSymbols(self, style: QgsStyle, type: Qgis.SymbolType, caseSensitive: bool = True, useTolerantMatch: bool = False) Tuple[int, List[Any], List[str]]

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.

New in version 3.4.

Parameters
  • style (QgsStyle) –

  • type (Qgis.SymbolType) –

  • caseSensitive (bool = True) –

  • useTolerantMatch (bool = False) –

Return type

Tuple[int, List[Any], List[str]]

moveCategory(self, from_: int, to: int)

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

Parameters
  • from (int) –

  • to (int) –

originalSymbolForFeature(self, feature: QgsFeature, context: QgsRenderContext) QgsSymbol
Parameters
Return type

QgsSymbol

rebuildHash(self)

hashtable for faster access to symbols

renderFeatureWithSymbol(self, feature: QgsFeature, symbol: QgsSymbol, context: QgsRenderContext, layer: int, selected: bool, drawVertexMarker: bool)

Render the feature with the symbol using context. Use layer to specify the symbol layer, selected to specify if it should be rendered as selected and drawVertexMarker to specify if vertex markers should be rendered.

renderVertexMarker(self, pt: Union[QPointF, QPoint], context: QgsRenderContext)

render editing vertex marker at specified point

renderVertexMarkerPolygon(self, pts: QPolygonF, rings: Iterable[QPolygonF], context: QgsRenderContext)

render editing vertex marker for a polygon

renderVertexMarkerPolyline(self, pts: QPolygonF, context: QgsRenderContext)

render editing vertex marker for a polyline

save(self, doc: QDomDocument, context: QgsReadWriteContext) QDomElement
Parameters
Return type

QDomElement

saveRendererData(self, doc: QDomDocument, element: QDomElement, context: QgsReadWriteContext)

Saves generic renderer data into the specified element.

This method should be called in a subclass’ save() implementation in order to store all common base class properties in the DOM element.

New in version 3.22.

setClassAttribute(self, attr: str)

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 (str) –

setDataDefinedSizeLegend(self, settings: QgsDataDefinedSizeLegend)

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.

New in version 3.0.

Parameters

settings (QgsDataDefinedSizeLegend) –

setLegendSymbolItem(self, key: str, symbol: QgsSymbol)
Parameters
setSourceColorRamp(self, ramp: QgsColorRamp)

Sets the source color ramp.

Parameters

ramp (QgsColorRamp) – color ramp. Ownership is transferred to the renderer

setSourceSymbol(self, sym: QgsSymbol)

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 (QgsSymbol) – source symbol, ownership is transferred to the renderer

See also

sourceSymbol()

skipRender(self) QgsSymbol

Deprecated since version No: longer used, will be removed in QGIS 4.0

Return type

QgsSymbol

sortByLabel(self, order: Qt.SortOrder = Qt.AscendingOrder)

Sorts the existing categories by their label.

See also

sortByValue()

Parameters

order (Qt.SortOrder = Qt.AscendingOrder) –

sortByValue(self, order: Qt.SortOrder = Qt.AscendingOrder)

Sorts the existing categories by their value.

See also

sortByLabel()

Parameters

order (Qt.SortOrder = Qt.AscendingOrder) –

sourceColorRamp(self) QgsColorRamp

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

See also

sourceSymbol()

Return type

QgsColorRamp

sourceSymbol(self) QgsSymbol

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

Return type

QgsSymbol

startRender(self, context: QgsRenderContext, fields: QgsFields)
Parameters
stopRender(self, context: QgsRenderContext)
Parameters

context (QgsRenderContext) –

symbolForFeature(self, feature: QgsFeature, context: QgsRenderContext) QgsSymbol
Parameters
Return type

QgsSymbol

symbolForValue(self, value: Any) QgsSymbol

Returns the matching symbol corresponding to an attribute value.

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

Parameters

value (Any) –

Return type

QgsSymbol

symbolForValue2(self, value: Any) Tuple[QgsSymbol, bool]

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.

Note

available in Python bindings as symbolForValue2

Parameters

value (Any) –

Return type

Tuple[QgsSymbol, bool]

symbols(self, context: QgsRenderContext) List[QgsSymbol]
Parameters

context (QgsRenderContext) –

Return type

List[QgsSymbol]

toSld(self, doc: QDomDocument, element: QDomElement, props: Dict[str, Any] = {})
Parameters
  • doc (QDomDocument) –

  • element (QDomElement) –

  • props (Dict[str) –

updateCategoryLabel(self, catIndex: int, label: str) bool

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.

Parameters
  • catIndex (int) –

  • label (str) –

Return type

bool

updateCategoryRenderState(self, catIndex: int, render: bool) bool

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.

New in version 2.5.

Parameters
  • catIndex (int) –

  • render (bool) –

Return type

bool

updateCategorySymbol(self, catIndex: int, symbol: QgsSymbol) bool

Changes the symbol for the category with the specified index.

Ownership of symbol is transferred to the renderer.

Parameters
Return type

bool

updateCategoryValue(self, catIndex: int, value: Any) bool

Changes the value for the category with the specified index.

If value is a list, then the category will match any of the values from this list.

Parameters
  • catIndex (int) –

  • value (Any) –

Return type

bool

updateColorRamp(self, ramp: QgsColorRamp)

Update the color ramp used and all symbols colors.

Parameters

ramp (QgsColorRamp) – color ramp. Ownership is transferred to the renderer

New in version 2.5.

updateSymbols(self, sym: QgsSymbol)

Update all the symbols but leave categories and colors. This method also sets the source symbol for the renderer.

Parameters

sym (QgsSymbol) – source symbol to use for categories. Ownership is not transferred.

usedAttributes(self, context: QgsRenderContext) Set[str]
Parameters

context (QgsRenderContext) –

Return type

Set[str]