Additional documentation regarding custom properties for QgsLayerTree…

…Node and QgsMapLayer
qgis · Mar 9, 2025 · 97c41ab · 97c41ab
1 parent a5ebb3a
commit 97c41ab
Show file tree

Hide file tree

Showing 2 changed files with 128 additions and 0 deletions.
diff --git a/src/core/layertree/qgslayertreenode.h b/src/core/layertree/qgslayertreenode.h
@@ -59,6 +59,9 @@ class QgsMapLayer;
  * used by third party plugins. Custom properties are stored also in the project
  * file. The storage is not efficient for large amount of data.
  *
+ * Note that additional (and separate) custom properties may be applied to an
+ * associated QgsMapLayer (QgsVectorLayer, etc.) object.
+ *
  * Custom properties that have already been used within QGIS:
  *
  * - "loading" - whether the project is being currently loaded (root node only)
@@ -69,6 +72,56 @@ class QgsMapLayer;
  * - "legend/..." - properties for legend appearance customization
  * - "expandedLegendNodes" - list of layer's legend nodes' rules in expanded state
  *
+ * All custom properties used with QgsLayerTreeNode (with where they are set
+ * indicated); plugins may set additional ones:
+ *
+ * - "embedded-invisible-layers"
+ *       QgsLayerTreeUtils::replaceChildrenOfEmbeddedGroups
+ * - "embedded_project"
+ *       QgsLayerTreeRegistryBridge::layersAdded
+ *       QgsProject::loadEmbeddedNodes
+ *       QgsProject::createEmbeddedGroup
+ * - "embedded"
+ *       QgsLayerTreeRegistryBridge::layersAdded
+ *       QgsLayerTreeUtils::replaceChildrenOfEmbeddedGroups
+ *       QgsProject::createEmbeddedGroup
+ *       QgsProject::initializeEmbeddedSubtree
+ * - "expandedLegendNodes"
+ *       QgsMapThemeCollection::applyThemeToLayer
+ *       QgsLayerTreeView::updateExpandedStateToNode
+ *       QgsLayerTreeView : _expandAllLegendNodes (static function)
+ * - "legend/column-break-"*
+ *       QgsMapLayerLegendUtils::setLegendNodeColumnBreak
+ * - "legend/custom-ramp-settings-*"
+ *       QgsMapLayerLegendUtils::setLegendNodeColorRampSettings
+ * - "legend/custom-symbol-"*
+ *       QgsMapLayerLegendUtils::setLegendNodeCustomSymbol
+ * - "legend/label-"*
+ *       QgsMapLayerLegendUtils::setLegendNodeUserLabel
+ * - "legend/node-order"
+ *       QgsMapLayerLegendUtils::setLegendNodeOrder
+ * - "legend/patch-shape-"*
+ *       QgsMapLayerLegendUtils::setLegendNodePatchShape
+ * - "legend/symbol-size-"*
+ *       QgsMapLayerLegendUtils::setLegendNodeSymbolSize
+ * - "legend/title-style"
+ *       QgsLegendRenderer::setNodeLegendStyle
+ * - "overview"
+ *       QgisApp::addAllToOverview
+ *       QgisApp::removeAllFromOverview
+ *       QgsLayerTreeViewDefaultActions::showInOverview
+ * - "showFeatureCount"
+ *       QgsLayerTreeModel::connectToLayer
+ *       QgsLayerTreeViewDefaultActions::showFeatureCount
+ *       QgsWms::layerTree (top-level function, QgsWms is the namespace)
+ * - "wmsAbstract"
+ *       QgisApp::legendGroupSetWmsData
+ * - "wmsShortName"
+ *       QgisApp::legendGroupSetWmsData
+ * - "wmsTitle"
+ *       QgisApp::legendGroupSetWmsData
+ *
+ *
  * \see QgsLayerTree
  * \see QgsLayerTreeLayer
  * \see QgsLayerTreeGroup

diff --git a/src/core/qgsmaplayer.h b/src/core/qgsmaplayer.h
@@ -71,6 +71,81 @@ class QgsBox3D;
  * \ingroup core
  * \brief Base class for all map layer types.
  * This is the base class for all map layer types (vector, raster).
+ *
+ * Custom properties: Every map layer may have custom properties assigned to it.
+ * This mechanism allows third parties store additional data with the nodes.
+ * The properties are used within QGIS code, but may be also used by third party
+ * plugins. Custom properties are stored also in the project file. The storage
+ * is not efficient for large amount of data.
+ *
+ * Note that additional (and separate) custom properties may be applied to an
+ * associated QgsLayerTreeLayer (QgsLayerTreeNode) object.
+ *
+ * All custom properties used by QGIS with QgsMapLayer (with where they are set
+ * indicated); plugins may set additional ones:
+ *
+ * - "dualview/previewExpressions"
+ *       QgsDualView::saveRecentDisplayExpressions
+ * - "embeddedWidgets/count"
+ *       QgsLayerTreeEmbeddedConfigWidget::applyToLayer
+ * - "embeddedWidgets/"*"/id"
+ *       QgsLayerTreeEmbeddedConfigWidget::applyToLayer
+ * - "geopdf/"*
+ *       QgsGeospatialPdfLayerTreeModel::setData
+ * - "identify/format"
+ *       QgsIdentifyResultsDialog::formatChanged
+ *       QgsRasterLayer::init
+ * - "_include_in_elevation_profiles"
+ *       QgsElevationProfileLayerTreeModel::setData
+ * - "isOfflineEditable"
+ *       QgsOfflineEditing::convertToOfflineLayer
+ * - "lastDxfOutputAttribute"
+ *       QgsVectorLayerAndAttributeModel::saveLayersOutputAttribute
+ * - "lastMaximumNumberOfBlocks"
+ *       QgsVectorLayerAndAttributeModel::saveLayersOutputAttribute
+ * - "layerNameSuffix"
+ *       QgsOfflineEditing::convertToOfflineLayer
+ * - "_layer_was_editable"
+ *       QgsProject::addLayer
+ * - "_legend_added"
+ *       QgsAppLayerHandling::addSublayers
+ * - "legend/expressionFilterEnabled"
+ *       QgsLayerTreeUtils::setLegendFilterByExpression
+ * - "legend/expressionFilter"
+ *       QgsLayerTreeUtils::setLegendFilterByExpression
+ * - "loading"
+ *       QgsProject::readProjectFile
+ * - "metadata/"*
+ *       QgsLayerMetadata::saveToLayer
+ * - "OnConvertFormatRegeneratePrimaryKey"
+ *       QgsProcessingUtils::createFeatureSink
+ * - "_prevGroupBlendMode"
+ *       QgsGroupLayer::setChildLayers
+ * - "remoteLayerId"
+ *       QgsOfflineEditing::convertToOfflineLayer
+ * - "remoteProvider"
+ *       QgsOfflineEditing::convertToOfflineLayer
+ * - "remoteSource"
+ *       QgsOfflineEditing::convertToOfflineLayer
+ * - "skipMemoryLayersCheck"
+ *       Not currently set by QGIS; if set on a memory layer will suppress on-
+ *       close unsaved data loss warning for that layer.
+ * - "sldStyleName"
+ *       QgsWms::QgsRenderer::setLayerSld (QgsWms is the namespace)
+ * - "storedSubsetString"
+ *       QgsPointCloudLayer::setSubsetString
+ *       QgsRasterLayer::setSubsetString
+ *       QgsVectorLayer::setSubsetString
+ * - "userNotes"
+ *       QgsLayerNotesUtils::setLayerNotes
+ * - "variableNames"
+ *       QgsExpressionContextUtils::setLayerVariable
+ * - "WMSBackgroundLayer"
+ *       QgsRasterLayerProperties::apply
+ * - "WMSPrintLayer"
+ *       QgsRasterLayerProperties::apply
+ * - "WMSPublishDataSourceUrl"
+ *       QgsRasterLayerProperties::apply
  */
 class CORE_EXPORT QgsMapLayer : public QObject
 {