Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Added some doxygen documentation and minor code cleanups
  • Loading branch information
wonder-sk committed May 21, 2014
1 parent e92ff00 commit 0b072e6
Show file tree
Hide file tree
Showing 12 changed files with 145 additions and 33 deletions.
14 changes: 14 additions & 0 deletions src/core/layertree/qgslayertree.h
Expand Up @@ -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 );
Expand Down
8 changes: 6 additions & 2 deletions src/core/layertree/qgslayertreegroup.cpp
Expand Up @@ -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 )
Expand Down Expand Up @@ -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 )
Expand Down
6 changes: 6 additions & 0 deletions src/core/layertree/qgslayertreegroup.h
Expand Up @@ -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
Expand Down
20 changes: 19 additions & 1 deletion src/core/layertree/qgslayertreelayer.cpp
Expand Up @@ -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 );
}
Expand Down Expand Up @@ -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 )
Expand Down
25 changes: 17 additions & 8 deletions src/core/layertree/qgslayertreelayer.h
Expand Up @@ -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
{
Expand All @@ -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 );
Expand Down
13 changes: 8 additions & 5 deletions src/core/layertree/qgslayertreenode.cpp
Expand Up @@ -18,6 +18,9 @@
#include "qgslayertree.h"
#include "qgslayertreeutils.h"

#include <QDomElement>
#include <QStringList>


QgsLayerTreeNode::QgsLayerTreeNode( QgsLayerTreeNode::NodeType t )
: mNodeType( t )
Expand All @@ -39,6 +42,11 @@ QgsLayerTreeNode::QgsLayerTreeNode( const QgsLayerTreeNode& other )
insertChildren( -1, clonedChildren );
}

QgsLayerTreeNode::~QgsLayerTreeNode()
{
qDeleteAll( mChildren );
}

QgsLayerTreeNode* QgsLayerTreeNode::readXML( QDomElement& element )
{
QgsLayerTreeNode* node = 0;
Expand Down Expand Up @@ -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;
Expand Down
68 changes: 56 additions & 12 deletions src/core/layertree/qgslayertreenode.h
Expand Up @@ -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. */
Expand All @@ -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:
Expand All @@ -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;
};

Expand Down
11 changes: 10 additions & 1 deletion src/core/layertree/qgslayertreeregistrybridge.h
Expand Up @@ -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
{
Expand Down
9 changes: 7 additions & 2 deletions src/core/layertree/qgslayertreeutils.h
Expand Up @@ -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 );
Expand Down
1 change: 1 addition & 0 deletions src/gui/layertree/qgslayertreemapcanvasbridge.cpp
Expand Up @@ -17,6 +17,7 @@

#include "qgslayertree.h"
#include "qgslayertreeutils.h"
#include "qgsmaplayer.h"

#include "qgsmapcanvas.h"

Expand Down
1 change: 0 additions & 1 deletion src/gui/layertree/qgslayertreemodel.cpp
Expand Up @@ -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;
}

Expand Down
2 changes: 1 addition & 1 deletion src/gui/layertree/qgslayertreeview.cpp
Expand Up @@ -18,6 +18,7 @@
#include "qgslayertree.h"
#include "qgslayertreemodel.h"
#include "qgslayertreeviewdefaultactions.h"
#include "qgsmaplayer.h"

#include <QMenu>
#include <QContextMenuEvent>
Expand Down Expand Up @@ -141,7 +142,6 @@ void QgsLayerTreeView::onCurrentChanged( QModelIndex current, QModelIndex previo
if ( layerPrevious == layerCurrent )
return;

qDebug( "current layer changed!" );
emit currentLayerChanged( layerCurrent );
}

Expand Down

0 comments on commit 0b072e6

Please sign in to comment.