From 8f113d14e1397ac9fd8064138d2a2153cbb8a5a9 Mon Sep 17 00:00:00 2001 From: Nyall Dawson Date: Fri, 25 Apr 2025 08:30:03 +1000 Subject: [PATCH] Improve QgsMapLayerComboBox docs --- .../auto_generated/qgsmaplayercombobox.sip.in | 32 ++++++++++++++++--- .../auto_generated/qgsmaplayercombobox.sip.in | 32 ++++++++++++++++--- src/gui/qgsmaplayercombobox.h | 29 ++++++++++++++--- 3 files changed, 81 insertions(+), 12 deletions(-) diff --git a/python/PyQt6/gui/auto_generated/qgsmaplayercombobox.sip.in b/python/PyQt6/gui/auto_generated/qgsmaplayercombobox.sip.in index c73ddcbc9b3..965166c0fe1 100644 --- a/python/PyQt6/gui/auto_generated/qgsmaplayercombobox.sip.in +++ b/python/PyQt6/gui/auto_generated/qgsmaplayercombobox.sip.in @@ -14,7 +14,29 @@ class QgsMapLayerComboBox : QComboBox { %Docstring(signature="appended") -A combobox which displays a list of layers. +A combobox which displays a dynamic list of layers from a QGIS project. + +:py:class:`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, +:py:class:`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 :py:func:`~setFilters`. + +By default, the combobox will be populated using layers from the current +project (see :py:func:`QgsProject.instance()`), however a specific +source project can be set via :py:func:`~setProject`. %End %TypeHeaderCode @@ -24,7 +46,9 @@ A combobox which displays a list of layers. explicit QgsMapLayerComboBox( QWidget *parent /TransferThis/ = 0 ); %Docstring QgsMapLayerComboBox creates a combo box to display the list of layers -(currently in the registry). The layers can be filtered and/or ordered. +currently in the project. + +The layers can be filtered and/or ordered. %End void setFilters( Qgis::LayerFilters filters ); @@ -136,8 +160,8 @@ Returns ``True`` if the combo box shows the layer's CRS. %Docstring 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 map layer registry, or paths to layers which -have not yet been loaded into QGIS. +are not included in the project, or paths to layers which have not yet +been loaded into QGIS. .. seealso:: :py:func:`additionalItems` %End diff --git a/python/gui/auto_generated/qgsmaplayercombobox.sip.in b/python/gui/auto_generated/qgsmaplayercombobox.sip.in index c73ddcbc9b3..965166c0fe1 100644 --- a/python/gui/auto_generated/qgsmaplayercombobox.sip.in +++ b/python/gui/auto_generated/qgsmaplayercombobox.sip.in @@ -14,7 +14,29 @@ class QgsMapLayerComboBox : QComboBox { %Docstring(signature="appended") -A combobox which displays a list of layers. +A combobox which displays a dynamic list of layers from a QGIS project. + +:py:class:`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, +:py:class:`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 :py:func:`~setFilters`. + +By default, the combobox will be populated using layers from the current +project (see :py:func:`QgsProject.instance()`), however a specific +source project can be set via :py:func:`~setProject`. %End %TypeHeaderCode @@ -24,7 +46,9 @@ A combobox which displays a list of layers. explicit QgsMapLayerComboBox( QWidget *parent /TransferThis/ = 0 ); %Docstring QgsMapLayerComboBox creates a combo box to display the list of layers -(currently in the registry). The layers can be filtered and/or ordered. +currently in the project. + +The layers can be filtered and/or ordered. %End void setFilters( Qgis::LayerFilters filters ); @@ -136,8 +160,8 @@ Returns ``True`` if the combo box shows the layer's CRS. %Docstring 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 map layer registry, or paths to layers which -have not yet been loaded into QGIS. +are not included in the project, or paths to layers which have not yet +been loaded into QGIS. .. seealso:: :py:func:`additionalItems` %End diff --git a/src/gui/qgsmaplayercombobox.h b/src/gui/qgsmaplayercombobox.h index 50ab045c4b4..9afb056a3c4 100644 --- a/src/gui/qgsmaplayercombobox.h +++ b/src/gui/qgsmaplayercombobox.h @@ -28,7 +28,27 @@ class QgsVectorLayer; /** * \ingroup gui - * \brief A combobox which displays a list of layers. + * \brief 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(). */ class GUI_EXPORT QgsMapLayerComboBox : public QComboBox { @@ -40,7 +60,8 @@ class GUI_EXPORT QgsMapLayerComboBox : public QComboBox public: /** - * \brief QgsMapLayerComboBox creates a combo box to display the list of layers (currently in the registry). + * \brief QgsMapLayerComboBox creates a combo box to display the list of layers currently in the project. + * * The layers can be filtered and/or ordered. */ explicit QgsMapLayerComboBox( QWidget *parent SIP_TRANSFERTHIS = nullptr ); @@ -134,8 +155,8 @@ class GUI_EXPORT QgsMapLayerComboBox : public QComboBox /** * 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 map - * layer registry, or paths to layers which have not yet been loaded into QGIS. + * 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 additionalItems() */ void setAdditionalItems( const QStringList &items );