Added some doxygen documentation and minor code cleanups

Author: wonder-sk

src/core/layertree/qgslayertree.h

@@ -20,21 +20,35 @@
 #include "qgslayertreegroup.h"
 #include "qgslayertreelayer.h"
 
+/**
+ * Namespace with helper functions for layer tree operations.
+ *
+ * Only generally useful routines should be here. Miscellaneous utility functions for work
+ * with the layer tree are in QgsLayerTreeUtils class.
+ *
+ * @note added in 2.4
+ */
 namespace QgsLayerTree
 {
+  //! Check whether the node is a valid group node
   inline bool isGroup( QgsLayerTreeNode* node )
   {
     return node && node->nodeType() == QgsLayerTreeNode::NodeGroup;
   }
+
+  //! Check whether the node is a valid layer node
   inline bool isLayer( QgsLayerTreeNode* node )
   {
     return node && node->nodeType() == QgsLayerTreeNode::NodeLayer;
   }
 
+  //! Cast node to a group. No type checking is done - use isGroup() to find out whether this operation is legal.
   inline QgsLayerTreeGroup* toGroup( QgsLayerTreeNode* node )
   {
     return static_cast<QgsLayerTreeGroup*>( node );
   }
+
+  //! Cast node to a layer. No type checking is done - use isLayer() to find out whether this operation is legal.
   inline QgsLayerTreeLayer* toLayer( QgsLayerTreeNode* node )
   {
     return static_cast<QgsLayerTreeLayer*>( node );

src/core/layertree/qgslayertreegroup.cpp

@@ -18,6 +18,10 @@
 #include "qgslayertree.h"
 #include "qgslayertreeutils.h"
 
+#include <QDomElement>
+#include <QStringList>
+
+
 QgsLayerTreeGroup::QgsLayerTreeGroup( const QString& name, Qt::CheckState checked )
     : QgsLayerTreeNode( NodeGroup )
     , mName( name )
@@ -271,8 +275,8 @@ QStringList QgsLayerTreeGroup::childLayerIds() const
 
 void QgsLayerTreeGroup::layerDestroyed()
 {
-  QgsMapLayer* layer = static_cast<QgsMapLayer*>( sender() );
-  removeLayer( layer );
+  //QgsMapLayer* layer = static_cast<QgsMapLayer*>( sender() );
+  //removeLayer( layer );
 }
 
 void QgsLayerTreeGroup::nodeVisibilityChanged( QgsLayerTreeNode* node )

src/core/layertree/qgslayertreegroup.h

@@ -18,8 +18,14 @@
 
 #include "qgslayertreenode.h"
 
+class QgsMapLayer;
 class QgsLayerTreeLayer;
 
+/**
+ * Layer tree group node serves as a container for layers and further groups.
+ *
+ * @note added in 2.4
+ */
 class QgsLayerTreeGroup : public QgsLayerTreeNode
 {
     Q_OBJECT

src/core/layertree/qgslayertreelayer.cpp

@@ -16,11 +16,15 @@
 #include "qgslayertreelayer.h"
 
 #include "qgslayertreeutils.h"
+#include "qgsmaplayer.h"
 #include "qgsmaplayerregistry.h"
 
 
 QgsLayerTreeLayer::QgsLayerTreeLayer( QgsMapLayer *layer )
-    : QgsLayerTreeNode( NodeLayer ), mLayerId( layer->id() ), mLayer( layer ), mVisible( Qt::Checked )
+    : QgsLayerTreeNode( NodeLayer )
+    , mLayerId( layer->id() )
+    , mLayer( layer )
+    , mVisible( Qt::Checked )
 {
   Q_ASSERT( QgsMapLayerRegistry::instance()->mapLayer( mLayerId ) == layer );
 }
@@ -63,6 +67,20 @@ void QgsLayerTreeLayer::attachToLayer()
   }
 }
 
+
+QString QgsLayerTreeLayer::layerName() const
+{
+  return mLayer ? mLayer->name() : mLayerName;
+}
+
+void QgsLayerTreeLayer::setLayerName( const QString& n )
+{
+  if ( mLayer )
+    mLayer->setLayerName( n );
+  else
+    mLayerName = n;
+}
+
 void QgsLayerTreeLayer::setVisible( Qt::CheckState state )
 {
   if ( mVisible == state )

src/core/layertree/qgslayertreelayer.h

@@ -18,16 +18,25 @@
 
 #include "qgslayertreenode.h"
 
+class QgsMapLayer;
+
 /**
- * Layer Node
+ * Layer tree node points to a map layer.
+ *
+ * When using with existing QgsMapLayer instance, it is expected that the layer
+ * has been registered in QgsMapLayerRegistry earlier.
  *
- * It is expected that the layer is registered in QgsMapLayerRegistry.
+ * 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, the node will start listening to map layer
+ * registry updates in expectation that the layer (identified by its ID) will
+ * be loaded later.
  *
- * One layer is supposed to be present in one layer tree just once. It is possible that temporarily a layer
- * temporarily exists in one tree more than once, e.g. while reordering items.
+ * 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.
  *
- * Can exist also without a valid instance of a layer (just ID),
- * so that referenced layer does not need to be loaded in order to use it in layer tree.
+ * @note added in 2.4
  */
 class QgsLayerTreeLayer : public QgsLayerTreeNode
 {
@@ -42,8 +51,8 @@ class QgsLayerTreeLayer : public QgsLayerTreeNode
 
     QgsMapLayer* layer() const { return mLayer; }
 
-    QString layerName() const { return mLayer ? mLayer->name() : mLayerName; }
-    void setLayerName( const QString& n ) { if ( mLayer ) mLayer->setLayerName( n ); else mLayerName = n; }
+    QString layerName() const;
+    void setLayerName( const QString& n );
 
     Qt::CheckState isVisible() const { return mVisible; }
     void setVisible( Qt::CheckState visible );

src/core/layertree/qgslayertreenode.cpp

@@ -18,6 +18,9 @@
 #include "qgslayertree.h"
 #include "qgslayertreeutils.h"
 
+#include <QDomElement>
+#include <QStringList>
+
 
 QgsLayerTreeNode::QgsLayerTreeNode( QgsLayerTreeNode::NodeType t )
     : mNodeType( t )
@@ -39,6 +42,11 @@ QgsLayerTreeNode::QgsLayerTreeNode( const QgsLayerTreeNode& other )
   insertChildren( -1, clonedChildren );
 }
 
+QgsLayerTreeNode::~QgsLayerTreeNode()
+{
+  qDeleteAll( mChildren );
+}
+
 QgsLayerTreeNode* QgsLayerTreeNode::readXML( QDomElement& element )
 {
   QgsLayerTreeNode* node = 0;
@@ -83,11 +91,6 @@ void QgsLayerTreeNode::writeCommonXML( QDomElement& element )
   mProperties.writeXml( element, doc );
 }
 
-void QgsLayerTreeNode::addChild( QgsLayerTreeNode *node )
-{
-  insertChild( -1, node );
-}
-
 void QgsLayerTreeNode::insertChild( int index, QgsLayerTreeNode *node )
 {
   QList<QgsLayerTreeNode*> nodes;

src/core/layertree/qgslayertreenode.h

@@ -18,37 +18,76 @@
 
 #include <QObject>
 
-#include "qgsmaplayer.h"
+#include "qgsobjectcustomproperties.h"
+
+class QDomElement;
 
 /**
- * One node of the layer tree - group or layer.
+ * This class is a base class for nodes in a layer tree.
+ * Layer tree is a hierarchical structure consisting of group and layer nodes:
+ * - group nodes are containers and may contain children (layer and group nodes)
+ * - layer nodes point to map layers, they do not contain further children
+ *
+ * Layer trees may be used for organization of layers, typically a layer tree
+ * is exposed to the user using QgsLayerTreeView widget which shows the tree
+ * and allows manipulation with the tree.
+ *
+ * Ownership of nodes: every node is owned by its parent. Therefore once node
+ * is added to a layer tree, it is the responsibility of the parent to delete it
+ * when the node is not needed anymore. Deletion of root node of a tree will
+ * delete all nodes of the tree.
+ *
+ * Signals: signals are propagated from children to parent. That means it is
+ * sufficient to connect to root node in order to get signals about updates
+ * in the whole layer tree. When adding or removing a node that contains further
+ * children (i.e. a whole subtree), the addition/removal signals are emitted
+ * only for the root node of the subtree that is being added or removed.
+ *
+ * Custom properties: Every node may have some custom properties assigned to it.
+ * This mechanism allows third parties store additional data with the nodes.
+ * The properties are used within QGIS code (whether to show layer in overview,
+ * whether the node is embedded from another project etc), 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.
  *
- * Once added to the tree, nodes are owned by their parent.
+ * @see also QgsLayerTree, QgsLayerTreeLayer, QgsLayerTreeGroup
+ * @note added in 2.4
  */
 class CORE_EXPORT QgsLayerTreeNode : public QObject
 {
     Q_OBJECT
   public:
+
+    //! Enumeration of possible tree node types
     enum NodeType
     {
-      NodeGroup,
-      NodeLayer
+      NodeGroup,   //!< container of other groups and layers
+      NodeLayer    //!< leaf node pointing to a layer
     };
 
-    ~QgsLayerTreeNode() { qDeleteAll( mChildren ); }
+    ~QgsLayerTreeNode();
 
+    //! Find out about type of the node. It is usually shorter to use convenience functions from QgsLayerTree namespace for that
     NodeType nodeType() { return mNodeType; }
+    //! Get pointer to the parent. If parent is a null pointer, the node is a root node
     QgsLayerTreeNode* parent() { return mParent; }
+    //! Get list of children of the node. Children are owned by the parent
     QList<QgsLayerTreeNode*> children() { return mChildren; }
 
+    //! Read layer tree from XML. Returns new instance
     static QgsLayerTreeNode* readXML( QDomElement& element );
+    //! Write layer tree to XML
     virtual void writeXML( QDomElement& parentElement ) = 0;
 
+    //! Return string with layer tree structure. For debug purposes only
     virtual QString dump() const = 0;
 
+    //! Create a copy of the node. Returns new instance
     virtual QgsLayerTreeNode* clone() const = 0;
 
+    //! Return whether the node should be shown as expanded or collapsed in GUI
     bool isExpanded() const { return mExpanded; }
+    //! Set whether the node should be shown as expanded or collapsed in GUI
     void setExpanded( bool expanded ) { mExpanded = expanded; }
 
     /** 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
 
   signals:
 
-    // low-level signals (mainly for the model)
-
+    //! Emitted when one or more nodes will be added to a node within the tree
     void willAddChildren( QgsLayerTreeNode* node, int indexFrom, int indexTo );
+    //! Emitted when one or more nodes have been added to a node within the tree
     void addedChildren( QgsLayerTreeNode* node, int indexFrom, int indexTo );
-
+    //! Emitted when one or more nodes will be removed from a node within the tree
     void willRemoveChildren( QgsLayerTreeNode* node, int indexFrom, int indexTo );
+    //! Emitted when one or more nodes has been removed from a node within the tree
     void removedChildren( QgsLayerTreeNode* node, int indexFrom, int indexTo );
-
+    //! Emitted when check state of a node within the tree has been changed
     void visibilityChanged( QgsLayerTreeNode* node, Qt::CheckState state );
-
+    //! Emitted when a custom property of a node within the tree has been changed or removed
     void customPropertyChanged( QgsLayerTreeNode* node, QString key );
 
   protected:
@@ -85,18 +125,22 @@ class CORE_EXPORT QgsLayerTreeNode : public QObject
     void writeCommonXML( QDomElement& element );
 
     // the child must not be in any tree yet!
-    void addChild( QgsLayerTreeNode* node );
     void insertChildren( int index, QList<QgsLayerTreeNode*> nodes );
     void insertChild( int index, QgsLayerTreeNode* node );
     void removeChildAt( int i );
     void removeChildrenRange( int from, int count );
 
 
   protected:
+    //! type of the node - determines which subclass is used
     NodeType mNodeType;
+    //! pointer to the parent node - null in case of root node
     QgsLayerTreeNode* mParent;
+    //! list of children - node is responsible for their deletion
     QList<QgsLayerTreeNode*> mChildren;
+    //! whether the node should be shown in GUI as expanded
     bool mExpanded;
+    //! custom properties attached to the node
     QgsObjectCustomProperties mProperties;
 };
 

src/core/layertree/qgslayertreeregistrybridge.h

@@ -25,7 +25,16 @@ class QgsLayerTreeNode;
 class QgsMapLayer;
 
 /**
- * Listens to the updates in map layer registry and does changes in layer tree
+ * Listens to the updates in map layer registry and does changes in layer tree.
+ *
+ * When connected to a layer tree, any layers added to the map layer registry
+ * will be also added to the layer tree. Similarly, map layers that are removed
+ * from registry will be removed from the layer tree.
+ *
+ * If a layer is completely removed from the layer tree, it will be also removed
+ * from the map layer registry.
+ *
+ * @note added in 2.4
  */
 class CORE_EXPORT QgsLayerTreeRegistryBridge : public QObject
 {

src/core/layertree/qgslayertreeutils.h

@@ -25,13 +25,18 @@ class QStringList;
 class QgsLayerTreeGroup;
 class QgsLayerTreeLayer;
 
+/**
+ * Assorted functions for dealing with layer trees.
+ *
+ * @note added in 2.4
+ */
 class CORE_EXPORT QgsLayerTreeUtils
 {
   public:
 
-    // return a new instance - or null on error
+    //! Try to load layer tree from <legend> tag from project files from QGIS 2.2 and below
     static bool readOldLegend( QgsLayerTreeGroup* root, const QDomElement& legendElem );
-
+    //! Try to load custom layer order from <legend> tag from project files from QGIS 2.2 and below
     static bool readOldLegendLayerOrder( const QDomElement& legendElem, bool& hasCustomOrder, QStringList& order );
 
     static QString checkStateToXml( Qt::CheckState state );

src/gui/layertree/qgslayertreemapcanvasbridge.cpp

@@ -17,6 +17,7 @@
 
 #include "qgslayertree.h"
 #include "qgslayertreeutils.h"
+#include "qgsmaplayer.h"
 
 #include "qgsmapcanvas.h"
 

src/gui/layertree/qgslayertreemodel.cpp

@@ -622,7 +622,6 @@ QMimeData* QgsLayerTreeModel::mimeData( const QModelIndexList& indexes ) const
   QString txt = doc.toString();
 
   mimeData->setData( "application/qgis.layertreemodeldata", txt.toUtf8() );
-  qDebug( "%s", txt.toUtf8().data() );
   return mimeData;
 }
 

src/gui/layertree/qgslayertreeview.cpp

@@ -18,6 +18,7 @@
 #include "qgslayertree.h"
 #include "qgslayertreemodel.h"
 #include "qgslayertreeviewdefaultactions.h"
+#include "qgsmaplayer.h"
 
 #include <QMenu>
 #include <QContextMenuEvent>
@@ -141,7 +142,6 @@ void QgsLayerTreeView::onCurrentChanged( QModelIndex current, QModelIndex previo
   if ( layerPrevious == layerCurrent )
     return;
 
-  qDebug( "current layer changed!" );
   emit currentLayerChanged( layerCurrent );
 }