Skip to content

Commit 0b072e6

Browse files
committed
Added some doxygen documentation and minor code cleanups
1 parent e92ff00 commit 0b072e6

12 files changed

+145
-33
lines changed

src/core/layertree/qgslayertree.h

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,21 +20,35 @@
2020
#include "qgslayertreegroup.h"
2121
#include "qgslayertreelayer.h"
2222

23+
/**
24+
* Namespace with helper functions for layer tree operations.
25+
*
26+
* Only generally useful routines should be here. Miscellaneous utility functions for work
27+
* with the layer tree are in QgsLayerTreeUtils class.
28+
*
29+
* @note added in 2.4
30+
*/
2331
namespace QgsLayerTree
2432
{
33+
//! Check whether the node is a valid group node
2534
inline bool isGroup( QgsLayerTreeNode* node )
2635
{
2736
return node && node->nodeType() == QgsLayerTreeNode::NodeGroup;
2837
}
38+
39+
//! Check whether the node is a valid layer node
2940
inline bool isLayer( QgsLayerTreeNode* node )
3041
{
3142
return node && node->nodeType() == QgsLayerTreeNode::NodeLayer;
3243
}
3344

45+
//! Cast node to a group. No type checking is done - use isGroup() to find out whether this operation is legal.
3446
inline QgsLayerTreeGroup* toGroup( QgsLayerTreeNode* node )
3547
{
3648
return static_cast<QgsLayerTreeGroup*>( node );
3749
}
50+
51+
//! Cast node to a layer. No type checking is done - use isLayer() to find out whether this operation is legal.
3852
inline QgsLayerTreeLayer* toLayer( QgsLayerTreeNode* node )
3953
{
4054
return static_cast<QgsLayerTreeLayer*>( node );

src/core/layertree/qgslayertreegroup.cpp

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@
1818
#include "qgslayertree.h"
1919
#include "qgslayertreeutils.h"
2020

21+
#include <QDomElement>
22+
#include <QStringList>
23+
24+
2125
QgsLayerTreeGroup::QgsLayerTreeGroup( const QString& name, Qt::CheckState checked )
2226
: QgsLayerTreeNode( NodeGroup )
2327
, mName( name )
@@ -271,8 +275,8 @@ QStringList QgsLayerTreeGroup::childLayerIds() const
271275

272276
void QgsLayerTreeGroup::layerDestroyed()
273277
{
274-
QgsMapLayer* layer = static_cast<QgsMapLayer*>( sender() );
275-
removeLayer( layer );
278+
//QgsMapLayer* layer = static_cast<QgsMapLayer*>( sender() );
279+
//removeLayer( layer );
276280
}
277281

278282
void QgsLayerTreeGroup::nodeVisibilityChanged( QgsLayerTreeNode* node )

src/core/layertree/qgslayertreegroup.h

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,14 @@
1818

1919
#include "qgslayertreenode.h"
2020

21+
class QgsMapLayer;
2122
class QgsLayerTreeLayer;
2223

24+
/**
25+
* Layer tree group node serves as a container for layers and further groups.
26+
*
27+
* @note added in 2.4
28+
*/
2329
class QgsLayerTreeGroup : public QgsLayerTreeNode
2430
{
2531
Q_OBJECT

src/core/layertree/qgslayertreelayer.cpp

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,15 @@
1616
#include "qgslayertreelayer.h"
1717

1818
#include "qgslayertreeutils.h"
19+
#include "qgsmaplayer.h"
1920
#include "qgsmaplayerregistry.h"
2021

2122

2223
QgsLayerTreeLayer::QgsLayerTreeLayer( QgsMapLayer *layer )
23-
: QgsLayerTreeNode( NodeLayer ), mLayerId( layer->id() ), mLayer( layer ), mVisible( Qt::Checked )
24+
: QgsLayerTreeNode( NodeLayer )
25+
, mLayerId( layer->id() )
26+
, mLayer( layer )
27+
, mVisible( Qt::Checked )
2428
{
2529
Q_ASSERT( QgsMapLayerRegistry::instance()->mapLayer( mLayerId ) == layer );
2630
}
@@ -63,6 +67,20 @@ void QgsLayerTreeLayer::attachToLayer()
6367
}
6468
}
6569

70+
71+
QString QgsLayerTreeLayer::layerName() const
72+
{
73+
return mLayer ? mLayer->name() : mLayerName;
74+
}
75+
76+
void QgsLayerTreeLayer::setLayerName( const QString& n )
77+
{
78+
if ( mLayer )
79+
mLayer->setLayerName( n );
80+
else
81+
mLayerName = n;
82+
}
83+
6684
void QgsLayerTreeLayer::setVisible( Qt::CheckState state )
6785
{
6886
if ( mVisible == state )

src/core/layertree/qgslayertreelayer.h

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,25 @@
1818

1919
#include "qgslayertreenode.h"
2020

21+
class QgsMapLayer;
22+
2123
/**
22-
* Layer Node
24+
* Layer tree node points to a map layer.
25+
*
26+
* When using with existing QgsMapLayer instance, it is expected that the layer
27+
* has been registered in QgsMapLayerRegistry earlier.
2328
*
24-
* It is expected that the layer is registered in QgsMapLayerRegistry.
29+
* The node can exist also without a valid instance of a layer (just ID). That
30+
* means the referenced layer does not need to be loaded in order to use it
31+
* in layer tree. In such case, the node will start listening to map layer
32+
* registry updates in expectation that the layer (identified by its ID) will
33+
* be loaded later.
2534
*
26-
* One layer is supposed to be present in one layer tree just once. It is possible that temporarily a layer
27-
* temporarily exists in one tree more than once, e.g. while reordering items.
35+
* A map layer is supposed to be present in one layer tree just once. It is
36+
* however possible that temporarily a layer exists in one tree more than just
37+
* once, e.g. while reordering items with drag and drop.
2838
*
29-
* Can exist also without a valid instance of a layer (just ID),
30-
* so that referenced layer does not need to be loaded in order to use it in layer tree.
39+
* @note added in 2.4
3140
*/
3241
class QgsLayerTreeLayer : public QgsLayerTreeNode
3342
{
@@ -42,8 +51,8 @@ class QgsLayerTreeLayer : public QgsLayerTreeNode
4251

4352
QgsMapLayer* layer() const { return mLayer; }
4453

45-
QString layerName() const { return mLayer ? mLayer->name() : mLayerName; }
46-
void setLayerName( const QString& n ) { if ( mLayer ) mLayer->setLayerName( n ); else mLayerName = n; }
54+
QString layerName() const;
55+
void setLayerName( const QString& n );
4756

4857
Qt::CheckState isVisible() const { return mVisible; }
4958
void setVisible( Qt::CheckState visible );

src/core/layertree/qgslayertreenode.cpp

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@
1818
#include "qgslayertree.h"
1919
#include "qgslayertreeutils.h"
2020

21+
#include <QDomElement>
22+
#include <QStringList>
23+
2124

2225
QgsLayerTreeNode::QgsLayerTreeNode( QgsLayerTreeNode::NodeType t )
2326
: mNodeType( t )
@@ -39,6 +42,11 @@ QgsLayerTreeNode::QgsLayerTreeNode( const QgsLayerTreeNode& other )
3942
insertChildren( -1, clonedChildren );
4043
}
4144

45+
QgsLayerTreeNode::~QgsLayerTreeNode()
46+
{
47+
qDeleteAll( mChildren );
48+
}
49+
4250
QgsLayerTreeNode* QgsLayerTreeNode::readXML( QDomElement& element )
4351
{
4452
QgsLayerTreeNode* node = 0;
@@ -83,11 +91,6 @@ void QgsLayerTreeNode::writeCommonXML( QDomElement& element )
8391
mProperties.writeXml( element, doc );
8492
}
8593

86-
void QgsLayerTreeNode::addChild( QgsLayerTreeNode *node )
87-
{
88-
insertChild( -1, node );
89-
}
90-
9194
void QgsLayerTreeNode::insertChild( int index, QgsLayerTreeNode *node )
9295
{
9396
QList<QgsLayerTreeNode*> nodes;

src/core/layertree/qgslayertreenode.h

Lines changed: 56 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -18,37 +18,76 @@
1818

1919
#include <QObject>
2020

21-
#include "qgsmaplayer.h"
21+
#include "qgsobjectcustomproperties.h"
22+
23+
class QDomElement;
2224

2325
/**
24-
* One node of the layer tree - group or layer.
26+
* This class is a base class for nodes in a layer tree.
27+
* Layer tree is a hierarchical structure consisting of group and layer nodes:
28+
* - group nodes are containers and may contain children (layer and group nodes)
29+
* - layer nodes point to map layers, they do not contain further children
30+
*
31+
* Layer trees may be used for organization of layers, typically a layer tree
32+
* is exposed to the user using QgsLayerTreeView widget which shows the tree
33+
* and allows manipulation with the tree.
34+
*
35+
* Ownership of nodes: every node is owned by its parent. Therefore once node
36+
* is added to a layer tree, it is the responsibility of the parent to delete it
37+
* when the node is not needed anymore. Deletion of root node of a tree will
38+
* delete all nodes of the tree.
39+
*
40+
* Signals: signals are propagated from children to parent. That means it is
41+
* sufficient to connect to root node in order to get signals about updates
42+
* in the whole layer tree. When adding or removing a node that contains further
43+
* children (i.e. a whole subtree), the addition/removal signals are emitted
44+
* only for the root node of the subtree that is being added or removed.
45+
*
46+
* Custom properties: Every node may have some custom properties assigned to it.
47+
* This mechanism allows third parties store additional data with the nodes.
48+
* The properties are used within QGIS code (whether to show layer in overview,
49+
* whether the node is embedded from another project etc), but may be also
50+
* used by third party plugins. Custom properties are stored also in the project
51+
* file. The storage is not efficient for large amount of data.
2552
*
26-
* Once added to the tree, nodes are owned by their parent.
53+
* @see also QgsLayerTree, QgsLayerTreeLayer, QgsLayerTreeGroup
54+
* @note added in 2.4
2755
*/
2856
class CORE_EXPORT QgsLayerTreeNode : public QObject
2957
{
3058
Q_OBJECT
3159
public:
60+
61+
//! Enumeration of possible tree node types
3262
enum NodeType
3363
{
34-
NodeGroup,
35-
NodeLayer
64+
NodeGroup, //!< container of other groups and layers
65+
NodeLayer //!< leaf node pointing to a layer
3666
};
3767

38-
~QgsLayerTreeNode() { qDeleteAll( mChildren ); }
68+
~QgsLayerTreeNode();
3969

70+
//! Find out about type of the node. It is usually shorter to use convenience functions from QgsLayerTree namespace for that
4071
NodeType nodeType() { return mNodeType; }
72+
//! Get pointer to the parent. If parent is a null pointer, the node is a root node
4173
QgsLayerTreeNode* parent() { return mParent; }
74+
//! Get list of children of the node. Children are owned by the parent
4275
QList<QgsLayerTreeNode*> children() { return mChildren; }
4376

77+
//! Read layer tree from XML. Returns new instance
4478
static QgsLayerTreeNode* readXML( QDomElement& element );
79+
//! Write layer tree to XML
4580
virtual void writeXML( QDomElement& parentElement ) = 0;
4681

82+
//! Return string with layer tree structure. For debug purposes only
4783
virtual QString dump() const = 0;
4884

85+
//! Create a copy of the node. Returns new instance
4986
virtual QgsLayerTreeNode* clone() const = 0;
5087

88+
//! Return whether the node should be shown as expanded or collapsed in GUI
5189
bool isExpanded() const { return mExpanded; }
90+
//! Set whether the node should be shown as expanded or collapsed in GUI
5291
void setExpanded( bool expanded ) { mExpanded = expanded; }
5392

5493
/** Set a custom property for the node. Properties are stored in a map and saved in project file. */
@@ -62,16 +101,17 @@ class CORE_EXPORT QgsLayerTreeNode : public QObject
62101

63102
signals:
64103

65-
// low-level signals (mainly for the model)
66-
104+
//! Emitted when one or more nodes will be added to a node within the tree
67105
void willAddChildren( QgsLayerTreeNode* node, int indexFrom, int indexTo );
106+
//! Emitted when one or more nodes have been added to a node within the tree
68107
void addedChildren( QgsLayerTreeNode* node, int indexFrom, int indexTo );
69-
108+
//! Emitted when one or more nodes will be removed from a node within the tree
70109
void willRemoveChildren( QgsLayerTreeNode* node, int indexFrom, int indexTo );
110+
//! Emitted when one or more nodes has been removed from a node within the tree
71111
void removedChildren( QgsLayerTreeNode* node, int indexFrom, int indexTo );
72-
112+
//! Emitted when check state of a node within the tree has been changed
73113
void visibilityChanged( QgsLayerTreeNode* node, Qt::CheckState state );
74-
114+
//! Emitted when a custom property of a node within the tree has been changed or removed
75115
void customPropertyChanged( QgsLayerTreeNode* node, QString key );
76116

77117
protected:
@@ -85,18 +125,22 @@ class CORE_EXPORT QgsLayerTreeNode : public QObject
85125
void writeCommonXML( QDomElement& element );
86126

87127
// the child must not be in any tree yet!
88-
void addChild( QgsLayerTreeNode* node );
89128
void insertChildren( int index, QList<QgsLayerTreeNode*> nodes );
90129
void insertChild( int index, QgsLayerTreeNode* node );
91130
void removeChildAt( int i );
92131
void removeChildrenRange( int from, int count );
93132

94133

95134
protected:
135+
//! type of the node - determines which subclass is used
96136
NodeType mNodeType;
137+
//! pointer to the parent node - null in case of root node
97138
QgsLayerTreeNode* mParent;
139+
//! list of children - node is responsible for their deletion
98140
QList<QgsLayerTreeNode*> mChildren;
141+
//! whether the node should be shown in GUI as expanded
99142
bool mExpanded;
143+
//! custom properties attached to the node
100144
QgsObjectCustomProperties mProperties;
101145
};
102146

src/core/layertree/qgslayertreeregistrybridge.h

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,16 @@ class QgsLayerTreeNode;
2525
class QgsMapLayer;
2626

2727
/**
28-
* Listens to the updates in map layer registry and does changes in layer tree
28+
* Listens to the updates in map layer registry and does changes in layer tree.
29+
*
30+
* When connected to a layer tree, any layers added to the map layer registry
31+
* will be also added to the layer tree. Similarly, map layers that are removed
32+
* from registry will be removed from the layer tree.
33+
*
34+
* If a layer is completely removed from the layer tree, it will be also removed
35+
* from the map layer registry.
36+
*
37+
* @note added in 2.4
2938
*/
3039
class CORE_EXPORT QgsLayerTreeRegistryBridge : public QObject
3140
{

src/core/layertree/qgslayertreeutils.h

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,18 @@ class QStringList;
2525
class QgsLayerTreeGroup;
2626
class QgsLayerTreeLayer;
2727

28+
/**
29+
* Assorted functions for dealing with layer trees.
30+
*
31+
* @note added in 2.4
32+
*/
2833
class CORE_EXPORT QgsLayerTreeUtils
2934
{
3035
public:
3136

32-
// return a new instance - or null on error
37+
//! Try to load layer tree from <legend> tag from project files from QGIS 2.2 and below
3338
static bool readOldLegend( QgsLayerTreeGroup* root, const QDomElement& legendElem );
34-
39+
//! Try to load custom layer order from <legend> tag from project files from QGIS 2.2 and below
3540
static bool readOldLegendLayerOrder( const QDomElement& legendElem, bool& hasCustomOrder, QStringList& order );
3641

3742
static QString checkStateToXml( Qt::CheckState state );

src/gui/layertree/qgslayertreemapcanvasbridge.cpp

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717

1818
#include "qgslayertree.h"
1919
#include "qgslayertreeutils.h"
20+
#include "qgsmaplayer.h"
2021

2122
#include "qgsmapcanvas.h"
2223

src/gui/layertree/qgslayertreemodel.cpp

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -622,7 +622,6 @@ QMimeData* QgsLayerTreeModel::mimeData( const QModelIndexList& indexes ) const
622622
QString txt = doc.toString();
623623

624624
mimeData->setData( "application/qgis.layertreemodeldata", txt.toUtf8() );
625-
qDebug( "%s", txt.toUtf8().data() );
626625
return mimeData;
627626
}
628627

src/gui/layertree/qgslayertreeview.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
#include "qgslayertree.h"
1919
#include "qgslayertreemodel.h"
2020
#include "qgslayertreeviewdefaultactions.h"
21+
#include "qgsmaplayer.h"
2122

2223
#include <QMenu>
2324
#include <QContextMenuEvent>
@@ -141,7 +142,6 @@ void QgsLayerTreeView::onCurrentChanged( QModelIndex current, QModelIndex previo
141142
if ( layerPrevious == layerCurrent )
142143
return;
143144

144-
qDebug( "current layer changed!" );
145145
emit currentLayerChanged( layerCurrent );
146146
}
147147

0 commit comments

Comments
 (0)