QGIS API Documentation  3.17.0-Master (8af46bc54f)
Public Types | Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
QgsLayerTreeLayer Class Reference

Layer tree node points to a map layer. More...

#include <qgslayertreelayer.h>

Inheritance diagram for QgsLayerTreeLayer:
Inheritance graph
[legend]

Public Types

enum  LegendNodesSplitBehavior { UseDefaultLegendSetting, AllowSplittingLegendNodesOverMultipleColumns, PreventSplittingLegendNodesOverMultipleColumns }
 Legend node column split behavior. More...
 
- Public Types inherited from QgsLayerTreeNode
enum  NodeType { NodeGroup, NodeLayer }
 Enumeration of possible tree node types. More...
 

Signals

void layerLoaded ()
 Emitted when a previously unavailable layer got loaded. More...
 
void layerWillBeUnloaded ()
 Emitted when a previously available layer got unloaded (from layer registry). More...
 
- Signals inherited from QgsLayerTreeNode
void addedChildren (QgsLayerTreeNode *node, int indexFrom, int indexTo)
 Emitted when one or more nodes have been added to a node within the tree. More...
 
void customPropertyChanged (QgsLayerTreeNode *node, const QString &key)
 Emitted when a custom property of a node within the tree has been changed or removed. More...
 
void expandedChanged (QgsLayerTreeNode *node, bool expanded)
 Emitted when the collapsed/expanded state of a node within the tree has been changed. More...
 
void nameChanged (QgsLayerTreeNode *node, QString name)
 Emitted when the name of the node is changed. More...
 
void removedChildren (QgsLayerTreeNode *node, int indexFrom, int indexTo)
 Emitted when one or more nodes has been removed from a node within the tree. More...
 
void visibilityChanged (QgsLayerTreeNode *node)
 Emitted when check state of a node within the tree has been changed. More...
 
void willAddChildren (QgsLayerTreeNode *node, int indexFrom, int indexTo)
 Emitted when one or more nodes will be added to a node within the tree. More...
 
void willRemoveChildren (QgsLayerTreeNode *node, int indexFrom, int indexTo)
 Emitted when one or more nodes will be removed from a node within the tree. More...
 

Public Member Functions

 QgsLayerTreeLayer (QgsMapLayer *layer)
 
 QgsLayerTreeLayer (const QgsLayerTreeLayer &other)
 
 QgsLayerTreeLayer (const QString &layerId, const QString &name=QString(), const QString &source=QString(), const QString &provider=QString())
 Constructor for QgsLayerTreeLayer using weak references to layer ID, name, public source, and provider key. More...
 
QgsLayerTreeLayerclone () const override
 Create a copy of the node. Returns new instance. More...
 
QString dump () const override
 Returns string with layer tree structure. For debug purposes only. More...
 
QString labelExpression () const
 Returns the expression member of the LayerTreeNode. More...
 
QgsMapLayerlayer () const
 Returns the map layer associated with this node. More...
 
QString layerId () const
 Returns the ID for the map layer associated with this node. More...
 
LegendNodesSplitBehavior legendSplitBehavior () const
 Returns the column split behavior for the node. More...
 
QString name () const override
 Returns the layer's name. More...
 
QgsLegendPatchShape patchShape () const
 Returns the symbol patch shape to use when rendering the legend node symbol. More...
 
QSizeF patchSize () const
 Returns the user (overridden) size for the legend node. More...
 
void resolveReferences (const QgsProject *project, bool looseMatching=false) override
 Resolves reference to layer from stored layer ID (if it has not been resolved already) More...
 
void setLabelExpression (const QString &expression)
 set the expression to evaluate More...
 
void setLegendSplitBehavior (LegendNodesSplitBehavior behavior)
 Sets the column split behavior for the node. More...
 
void setName (const QString &n) override
 Sets the layer's name. More...
 
void setPatchShape (const QgsLegendPatchShape &shape)
 Sets the symbol patch shape to use when rendering the legend node symbol. More...
 
void setPatchSize (QSizeF size)
 Sets the user (overridden) size for the legend node. More...
 
void setUseLayerName (bool use=true)
 Uses the layer's name if use is true, or the name manually set if false. More...
 
bool useLayerName () const
 Returns whether the layer's name is used, or the name manually set. More...
 
void writeXml (QDomElement &parentElement, const QgsReadWriteContext &context) override
 Write layer tree to XML. More...
 
- Public Member Functions inherited from QgsLayerTreeNode
 ~QgsLayerTreeNode () override
 
QList< QgsLayerTreeNode * > abandonChildren ()
 Removes the childrens, disconnect all the forwarded and external signals and sets their parent to nullptr. More...
 
QList< QgsMapLayer *> checkedLayers () const
 Returns a list of any checked layers which belong to this node or its children. More...
 
QList< QgsLayerTreeNode * > children ()
 Gets list of children of the node. Children are owned by the parent. More...
 
QList< QgsLayerTreeNode * > children () const
 Gets list of children of the node. Children are owned by the parent. More...
 
QStringList customProperties () const
 Returns list of keys stored in custom properties. More...
 
QVariant customProperty (const QString &key, const QVariant &defaultValue=QVariant()) const
 Read a custom property from layer. Properties are stored in a map and saved in project file. More...
 
int depth () const
 Returns the depth of this node, i.e. More...
 
bool isExpanded () const
 Returns whether the node should be shown as expanded or collapsed in GUI. More...
 
bool isItemVisibilityCheckedRecursive () const
 Returns whether this node is checked and all its children. More...
 
bool isItemVisibilityUncheckedRecursive () const
 Returns whether this node is unchecked and all its children. More...
 
bool isVisible () const
 Returns whether a node is really visible (ie checked and all its ancestors checked as well) More...
 
bool itemVisibilityChecked () const
 Returns whether a node is checked (independently of its ancestors or children) More...
 
NodeType nodeType () const
 Find out about type of the node. It is usually shorter to use convenience functions from QgsLayerTree namespace for that. More...
 
QgsLayerTreeNodeparent ()
 Gets pointer to the parent. If parent is nullptr, the node is a root node. More...
 
void removeCustomProperty (const QString &key)
 Remove a custom property from layer. Properties are stored in a map and saved in project file. More...
 
void setCustomProperty (const QString &key, const QVariant &value)
 Sets a custom property for the node. Properties are stored in a map and saved in project file. More...
 
void setExpanded (bool expanded)
 Sets whether the node should be shown as expanded or collapsed in GUI. More...
 
void setItemVisibilityChecked (bool checked)
 Check or uncheck a node (independently of its ancestors or children) More...
 
void setItemVisibilityCheckedParentRecursive (bool checked)
 Check or uncheck a node and all its parents. More...
 
virtual void setItemVisibilityCheckedRecursive (bool checked)
 Check or uncheck a node and all its children (taking into account exclusion rules) More...
 
bool takeChild (QgsLayerTreeNode *node)
 Remove a child from a node. More...
 

Static Public Member Functions

static QgsLayerTreeLayerreadXml (QDomElement &element, const QgsReadWriteContext &context)
 Read layer node from XML. More...
 
static QgsLayerTreeLayerreadXml (QDomElement &element, const QgsProject *project, const QgsReadWriteContext &context)
 Read layer node from XML. More...
 
- Static Public Member Functions inherited from QgsLayerTreeNode
static QgsLayerTreeNodereadXml (QDomElement &element, const QgsReadWriteContext &context)
 Read layer tree from XML. More...
 
static QgsLayerTreeNodereadXml (QDomElement &element, const QgsProject *project)
 Read layer tree from XML. More...
 

Protected Member Functions

void attachToLayer ()
 
- Protected Member Functions inherited from QgsLayerTreeNode
 QgsLayerTreeNode (NodeType t, bool checked=true)
 Constructor. More...
 
 QgsLayerTreeNode (const QgsLayerTreeNode &other)
 
void insertChildrenPrivate (int index, QList< QgsLayerTreeNode *> nodes)
 Low-level insertion of children to the node. The children must not have any parent yet! More...
 
virtual void makeOrphan ()
 Sets parent to nullptr and disconnects all external and forwarded signals. More...
 
void readCommonXml (QDomElement &element)
 Read common XML elements. More...
 
void removeChildrenPrivate (int from, int count, bool destroy=true)
 Low-level removal of children from the node. More...
 
void writeCommonXml (QDomElement &element)
 Write common XML elements. More...
 

Protected Attributes

QString mLabelExpression
 Expression to evaluate in the legend. More...
 
QString mLayerName
 Layer name - only used if layer does not exist or if mUseLayerName is false. More...
 
QgsMapLayerRef mRef
 Weak reference to the layer (or just it's ID if the reference is not resolved yet) More...
 
bool mUseLayerName = true
 
- Protected Attributes inherited from QgsLayerTreeNode
bool mChecked
 
QList< QgsLayerTreeNode * > mChildren
 list of children - node is responsible for their deletion More...
 
bool mExpanded
 whether the node should be shown in GUI as expanded More...
 
NodeType mNodeType
 type of the node - determines which subclass is used More...
 
QgsLayerTreeNodemParent = nullptr
 pointer to the parent node - nullptr in case of root node More...
 
QgsObjectCustomProperties mProperties
 custom properties attached to the node More...
 

Detailed Description

Layer tree node points to a map layer.

The node can exist also without a valid instance of a layer (just ID). That means the referenced layer does not need to be loaded in order to use it in layer tree. In such case, resolveReferences() method can be called once the layer is loaded.

A map layer is supposed to be present in one layer tree just once. It is however possible that temporarily a layer exists in one tree more than just once, e.g. while reordering items with drag and drop.

Since
QGIS 2.4

Definition at line 43 of file qgslayertreelayer.h.

Member Enumeration Documentation

◆ LegendNodesSplitBehavior

Legend node column split behavior.

Since
QGIS 3.14
Enumerator
UseDefaultLegendSetting 

Inherit default legend column splitting setting.

AllowSplittingLegendNodesOverMultipleColumns 

Allow splitting node's legend nodes across multiple columns.

PreventSplittingLegendNodesOverMultipleColumns 

Prevent splitting node's legend nodes across multiple columns.

Definition at line 189 of file qgslayertreelayer.h.

Constructor & Destructor Documentation

◆ QgsLayerTreeLayer() [1/3]

QgsLayerTreeLayer::QgsLayerTreeLayer ( QgsMapLayer layer)
explicit

Definition at line 24 of file qgslayertreelayer.cpp.

◆ QgsLayerTreeLayer() [2/3]

QgsLayerTreeLayer::QgsLayerTreeLayer ( const QgsLayerTreeLayer other)

Definition at line 39 of file qgslayertreelayer.cpp.

◆ QgsLayerTreeLayer() [3/3]

QgsLayerTreeLayer::QgsLayerTreeLayer ( const QString &  layerId,
const QString &  name = QString(),
const QString &  source = QString(),
const QString &  provider = QString() 
)
explicit

Constructor for QgsLayerTreeLayer using weak references to layer ID, name, public source, and provider key.

Definition at line 32 of file qgslayertreelayer.cpp.

Member Function Documentation

◆ attachToLayer()

void QgsLayerTreeLayer::attachToLayer ( )
protected

Definition at line 71 of file qgslayertreelayer.cpp.

◆ clone()

QgsLayerTreeLayer * QgsLayerTreeLayer::clone ( ) const
overridevirtual

Create a copy of the node. Returns new instance.

Implements QgsLayerTreeNode.

Definition at line 188 of file qgslayertreelayer.cpp.

◆ dump()

QString QgsLayerTreeLayer::dump ( ) const
overridevirtual

Returns string with layer tree structure. For debug purposes only.

Implements QgsLayerTreeNode.

Definition at line 183 of file qgslayertreelayer.cpp.

◆ labelExpression()

QString QgsLayerTreeLayer::labelExpression ( ) const
inline

Returns the expression member of the LayerTreeNode.

Since
QGIS 3.10

Definition at line 144 of file qgslayertreelayer.h.

◆ layer()

QgsMapLayer* QgsLayerTreeLayer::layer ( ) const
inline

Returns the map layer associated with this node.

Warning
This can be (and often is!) nullptr, e.g. in the case of a layer node representing a layer which has not yet been fully loaded into a project, or a layer node representing a layer with an invalid data source. The returned pointer must ALWAYS be checked to avoid dereferencing nullptr.
See also
layerId()

Definition at line 74 of file qgslayertreelayer.h.

◆ layerId()

QString QgsLayerTreeLayer::layerId ( ) const
inline

Returns the ID for the map layer associated with this node.

See also
layer()

Definition at line 63 of file qgslayertreelayer.h.

◆ layerLoaded

void QgsLayerTreeLayer::layerLoaded ( )
signal

Emitted when a previously unavailable layer got loaded.

◆ layerWillBeUnloaded

void QgsLayerTreeLayer::layerWillBeUnloaded ( )
signal

Emitted when a previously available layer got unloaded (from layer registry).

Since
QGIS 2.6

◆ legendSplitBehavior()

LegendNodesSplitBehavior QgsLayerTreeLayer::legendSplitBehavior ( ) const
inline

Returns the column split behavior for the node.

This value controls how legend nodes belonging the to layer may be split over multiple columns in legends.

See also
setLegendSplitBehavior()
Since
QGIS 3.14

Definition at line 204 of file qgslayertreelayer.h.

◆ name()

QString QgsLayerTreeLayer::name ( ) const
overridevirtual

Returns the layer's name.

See also
setName()
Since
QGIS 3.0

Implements QgsLayerTreeNode.

Definition at line 81 of file qgslayertreelayer.cpp.

◆ patchShape()

QgsLegendPatchShape QgsLayerTreeLayer::patchShape ( ) const

Returns the symbol patch shape to use when rendering the legend node symbol.

See also
setPatchShape()
Since
QGIS 3.14

Definition at line 227 of file qgslayertreelayer.cpp.

◆ patchSize()

QSizeF QgsLayerTreeLayer::patchSize ( ) const
inline

Returns the user (overridden) size for the legend node.

If either the width or height are non-zero, they will be used when rendering the legend node instead of the default symbol width or height from QgsLegendSettings.

See also
setPatchSize()
Since
QGIS 3.14

Definition at line 171 of file qgslayertreelayer.h.

◆ readXml() [1/2]

QgsLayerTreeLayer * QgsLayerTreeLayer::readXml ( QDomElement &  element,
const QgsReadWriteContext context 
)
static

Read layer node from XML.

Returns new instance. Does not resolve textual references to layers. Call resolveReferences() afterwards to do it.

Definition at line 104 of file qgslayertreelayer.cpp.

◆ readXml() [2/2]

QgsLayerTreeLayer * QgsLayerTreeLayer::readXml ( QDomElement &  element,
const QgsProject project,
const QgsReadWriteContext context 
)
static

Read layer node from XML.

Returns new instance. Also resolves textual references to layers from the project (calls resolveReferences() internally).

Since
QGIS 3.0

Definition at line 143 of file qgslayertreelayer.cpp.

◆ resolveReferences()

void QgsLayerTreeLayer::resolveReferences ( const QgsProject project,
bool  looseMatching = false 
)
overridevirtual

Resolves reference to layer from stored layer ID (if it has not been resolved already)

Since
QGIS 3.0

Implements QgsLayerTreeNode.

Definition at line 50 of file qgslayertreelayer.cpp.

◆ setLabelExpression()

void QgsLayerTreeLayer::setLabelExpression ( const QString &  expression)

set the expression to evaluate

Since
QGIS 3.10

Definition at line 222 of file qgslayertreelayer.cpp.

◆ setLegendSplitBehavior()

void QgsLayerTreeLayer::setLegendSplitBehavior ( LegendNodesSplitBehavior  behavior)
inline

Sets the column split behavior for the node.

This value controls how legend nodes belonging the to layer may be split over multiple columns in legends.

See also
legendSplitBehavior()
Since
QGIS 3.14

Definition at line 214 of file qgslayertreelayer.h.

◆ setName()

void QgsLayerTreeLayer::setName ( const QString &  n)
overridevirtual

Sets the layer's name.

See also
name()
Since
QGIS 3.0

Implements QgsLayerTreeNode.

Definition at line 86 of file qgslayertreelayer.cpp.

◆ setPatchShape()

void QgsLayerTreeLayer::setPatchShape ( const QgsLegendPatchShape shape)

Sets the symbol patch shape to use when rendering the legend node symbol.

See also
patchShape()
Since
QGIS 3.14

Definition at line 232 of file qgslayertreelayer.cpp.

◆ setPatchSize()

void QgsLayerTreeLayer::setPatchSize ( QSizeF  size)
inline

Sets the user (overridden) size for the legend node.

If either the width or height are non-zero, they will be used when rendering the legend node instead of the default symbol width or height from QgsLegendSettings.

See also
patchSize()
Since
QGIS 3.14

Definition at line 182 of file qgslayertreelayer.h.

◆ setUseLayerName()

void QgsLayerTreeLayer::setUseLayerName ( bool  use = true)

Uses the layer's name if use is true, or the name manually set if false.

Since
QGIS 3.8

Definition at line 206 of file qgslayertreelayer.cpp.

◆ useLayerName()

bool QgsLayerTreeLayer::useLayerName ( ) const

Returns whether the layer's name is used, or the name manually set.

Since
QGIS 3.8

Definition at line 211 of file qgslayertreelayer.cpp.

◆ writeXml()

void QgsLayerTreeLayer::writeXml ( QDomElement &  parentElement,
const QgsReadWriteContext context 
)
overridevirtual

Write layer tree to XML.

Implements QgsLayerTreeNode.

Definition at line 151 of file qgslayertreelayer.cpp.

Member Data Documentation

◆ mLabelExpression

QString QgsLayerTreeLayer::mLabelExpression
protected

Expression to evaluate in the legend.

Definition at line 237 of file qgslayertreelayer.h.

◆ mLayerName

QString QgsLayerTreeLayer::mLayerName
protected

Layer name - only used if layer does not exist or if mUseLayerName is false.

Definition at line 235 of file qgslayertreelayer.h.

◆ mRef

QgsMapLayerRef QgsLayerTreeLayer::mRef
protected

Weak reference to the layer (or just it's ID if the reference is not resolved yet)

Definition at line 233 of file qgslayertreelayer.h.

◆ mUseLayerName

bool QgsLayerTreeLayer::mUseLayerName = true
protected

Definition at line 240 of file qgslayertreelayer.h.


The documentation for this class was generated from the following files: