Class: QgsMapLayerComboBox

A combobox which displays a dynamic list of layers from a QGIS project.

QgsMapLayerComboBox is automatically populated with all the layers from the project. Any changes to the project’s layers are immediately reflected in the combobox, such as addition of new layers, layer renaming, or layer removal. Accordingly, this widget should ALWAYS be used when presenting a choice of layers to a user, instead of manually populated comboboxes.

In addition to the automatic layer population, QgsMapLayerComboBox also presents a user-friendly choice of layers by showing standard icons representing the different layer types (eg raster, mesh, or polygon/point/line icons for vector layers). Helpful tooltips will be shown if the user hovers over any of the layers, helping guide the user to the correct layer choice.

Optionally, the list of available layers can be filtered to a subset of the project’s layers (such as only showing raster layers, or only spatial layers) by calling setFilters().

By default, the combobox will be populated using layers from the current project (see QgsProject.instance()), however a specific source project can be set via setProject().

QgsMapLayerComboBox in the collapsed state

QgsMapLayerComboBox in the expanded state

Class Hierarchy

Base classes

QComboBox
QWidget
QObject
QPaintDevice

Methods

additionalItems	Returns the list of additional (non map layer) items included at the end of the combo box.
additionalLayers	Returns the list of additional layers added to the combobox.
allowEmptyLayer	Returns True if the combo box allows the empty layer ("not set") choice.
currentLayer	Returns the current layer selected in the combo box.
exceptedLayerList	Returns a list of layers which should be excluded from the combo box.
excludedProviders	Returns the list of data providers which are excluded from the combobox.
filters	Returns any currently used filters on the listed layers.
indexChanged
layer	Returns the layer currently shown at the specified index within the combo box.
rowsChanged
setAdditionalItems	Sets a list of additional (non map layer) items to include at the end of the combobox.
setAdditionalLayers	Sets a list of additional layers to include in the combobox.
setAllowEmptyLayer	Sets whether an optional empty layer ("not set") option is shown in the combo box.
setExceptedLayerList	Sets a list of layers which should be excluded from the combo box.
setExcludedProviders	Sets a list of data providers which should be excluded from the combobox.
setFilters	Sets filters for the layers displayed in the combo box.
setLayer	Sets the current layer selected in the combo box.
setProject	Sets the project from which map layers are shown.
setShowCrs	Sets whether the CRS of layers is also included in the combo box text.
showCrs	Returns True if the combo box shows the layer's CRS.

Signals

layerChanged

Emitted whenever the currently selected layer changes.

class qgis.gui.QgsMapLayerComboBox

Bases: QComboBox

__init__(parent: QWidget | None = None)

QgsMapLayerComboBox creates a combo box to display the list of layers currently in the project.

The layers can be filtered and/or ordered.

Parameters:

parent (Optional[QWidget] = None)

additionalItems(self) → List[str]

Returns the list of additional (non map layer) items included at the end of the combo box.

See also

setAdditionalItems()

Return type:

List[str]

additionalLayers(self) → List[QgsMapLayer]

Returns the list of additional layers added to the combobox.

See also

setAdditionalLayers()

Added in version 3.22.

Return type:

List[QgsMapLayer]

allowEmptyLayer(self) → bool

Returns True if the combo box allows the empty layer (“not set”) choice.

See also

setAllowEmptyLayer()

Return type:

bool

currentLayer(self) → QgsMapLayer | None

Returns the current layer selected in the combo box.

See also

layer()

Return type:

Optional[QgsMapLayer]

exceptedLayerList(self) → List[QgsMapLayer]

Returns a list of layers which should be excluded from the combo box.

See also

setExceptedLayerList()

Return type:

List[QgsMapLayer]

excludedProviders(self) → List[str]

Returns the list of data providers which are excluded from the combobox.

See also

setExcludedProviders()

Return type:

List[str]

filters(self) → Qgis.LayerFilters

Returns any currently used filters on the listed layers.

See also

setFilters()

Return type:

Qgis.LayerFilters

indexChanged(self, i: int)

Parameters:

i (int)

layer(self, layerIndex: int) → QgsMapLayer | None

Returns the layer currently shown at the specified index within the combo box.

Parameters:

layerIndex (int) – position of layer to return

See also

currentLayer()

Return type:

Optional[QgsMapLayer]

signal layerChanged(layer: QgsMapLayer)

Emitted whenever the currently selected layer changes.

Parameters:

layer (QgsMapLayer)

rowsChanged(self)

setAdditionalItems(self, items: Iterable[str | None])

Sets a list of additional (non map layer) items to include at the end of the combobox. These may represent additional layers such as layers which are not included in the project, or paths to layers which have not yet been loaded into QGIS.

See also

additionalItems()

Parameters:

items (Iterable[Optional[str]])

setAdditionalLayers(self, layers: Iterable[QgsMapLayer])

Sets a list of additional layers to include in the combobox.

This method allows adding additional layers, which are not part of a project’s layers, into the combobox.

See also

additionalLayers()

Added in version 3.22.

Parameters:

layers (Iterable[QgsMapLayer])

setAllowEmptyLayer(self, allowEmpty: bool, text: str | None = '', icon: QIcon = QIcon())

Sets whether an optional empty layer (“not set”) option is shown in the combo box.

Since QGIS 3.20, the optional text and icon arguments allows the text and icon for the empty layer item to be set.

See also

allowEmptyLayer()

Parameters:

• allowEmpty (bool)

• text (Optional[str] = '')

• icon (QIcon = QIcon())

setExceptedLayerList(self, layerList: Iterable[QgsMapLayer])

Sets a list of layers which should be excluded from the combo box.

See also

exceptedLayerList()

Parameters:

layerList (Iterable[QgsMapLayer])

setExcludedProviders(self, providers: Iterable[str | None])

Sets a list of data providers which should be excluded from the combobox.

See also

excludedProviders()

Parameters:

providers (Iterable[Optional[str]])

setFilters(self, filters: Qgis.LayerFilters | Qgis.LayerFilter)

Sets filters for the layers displayed in the combo box.

This method allows filtering layers according to layer type and/or geometry type.

See also

filters()

Parameters:

filters (Union[Qgis.LayerFilters, Qgis.LayerFilter])

setFilters(self, filters: int)

Filters according to layer type and/or geometry type.

Note

for API compatibility

Added in version 3.34.

Deprecated since version 3.34: Use the flag signature instead.

Parameters:

filters (int)

setLayer(self, layer: QgsMapLayer | None)

Sets the current layer selected in the combo box.

Parameters:

layer (Optional[QgsMapLayer])

setProject(self, project: QgsProject | None)

Sets the project from which map layers are shown.

If project is None then QgsProject.instance() will be used.

Added in version 3.24.

Parameters:

project (Optional[QgsProject])

setShowCrs(self, showCrs: bool)

Sets whether the CRS of layers is also included in the combo box text.

See also

showCrs()

Parameters:

showCrs (bool)

showCrs(self) → bool

Returns True if the combo box shows the layer’s CRS.

See also

setShowCrs()

Return type:

bool