Merge https://gitlab.com/inkscape/inkscape into selectable-knots

1 files changed, 80 insertions, 11 deletions

diff --git a/src/libavoid/viscluster.h b/src/libavoid/viscluster.h
index 5827e5070..f5ddadc80 100644
--- a/src/libavoid/viscluster.h
+++ b/src/libavoid/viscluster.h
@@ -19,9 +19,11 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  
  *
- * Author(s):   Michael Wybrow <mjwybrow@users.sourceforge.net>
+ * Author(s):   Michael Wybrow
 */
 
+//! @file    viscluster.h
+//! @brief   Contains the interface for the ClusterRef class.
 
 #ifndef AVOID_CLUSTER_H
 #define AVOID_CLUSTER_H
@@ -29,7 +31,7 @@
 #include <list>
 
 #include "libavoid/geometry.h"
-
+#include "libavoid/dllexport.h"
 
 namespace Avoid {
 
@@ -38,24 +40,91 @@ class ClusterRef;
 typedef std::list<ClusterRef *> ClusterRefList;
 
 
-class ClusterRef
+//! @brief   The ClusterRef class represents a cluster object.
+//!
+//! Cluster are boundaries around groups of shape objects.  Ideally, only
+//! connectors with one endpoint inside the cluster and one endpoint outside
+//! the cluster will cross the cluster boundary. Connectors that begin and 
+//! end inside a cluster will not route outside it, and connectors that begin 
+//! and end outside the cluster will not enter the cluster.
+//! 
+//! @note   While the functionality of this class works, it is currently 
+//!         experimental you will likely suffer a large performance hit
+//!         when using it.
+//!
+class AVOID_EXPORT ClusterRef
 {
     public:
-        ClusterRef(Router *router, unsigned int id, Polygon& poly);
+        //! @brief  Cluster reference constructor.
+        //!
+        //! Creates a cluster object reference, but does not yet place it 
+        //! into the Router scene.  You can add or remove the cluster to/from 
+        //! the scene with Router::addCluster() and Router::delCluster().  The 
+        //! cluster can effectively be moved with ClusterRef::setNewPoly() 
+        //! method.
+        //!
+        //! The poly argument should be used to specify a polygon boundary.
+        //! The rectangular boundary will be automatically generated from this.
+        //! The polygon boundary could be a convex hull consisting of points
+        //! from the boundaries of shapes.
+        //!
+        //! @note Regarding IDs:
+        //!       You can let libavoid manually handle IDs by not specifying
+        //!       them.  Alternatively, you can specify all IDs yourself, but 
+        //!       you must be careful to makes sure that each object in the 
+        //!       scene (shape, connector, cluster, etc) is given a unique, 
+        //!       positive ID.  This uniqueness is checked if assertions are
+        //!       enabled, but if not and there are clashes then strange 
+        //!       things can happen.
+        //!
+        //! @param[in]  router  The router scene to place the cluster into.
+        //! @param[in]  poly    A Polygon representing the boundary of the 
+        //!                     cluster.
+        //! @param[in]  id      Optionally, a positive integer ID unique
+        //!                     among all objects.
+        //!
+        ClusterRef(Router *router, Polygon& poly, const unsigned int id = 0);
+
+// To prevent C++ objects from being destroyed in garbage collected languages
+// when the libraries are called from SWIG, we hide the declarations of the
+// destructors and prevent generation of default destructors.
+#ifndef SWIG
+        //! @brief  Cluster reference destructor.
         ~ClusterRef();
+#endif
+        //! @brief   Update the polygon boundary for this cluster.
+        //!
+        //! You should specify a polygon boundary.  The rectangular one will
+        //! be generated automatically from this.
+        //!
+        //! @param[in]  poly    A Polygon representing the boundary of the 
+        //!                     cluster.
         void setNewPoly(Polygon& poly);
-        unsigned int id(void);
+        //! @brief   Returns the ID of this cluster.
+        //! @returns The ID of the cluster. 
+        unsigned int id(void) const;
+        //! @brief   Returns a reference to the polygon boundary of this 
+        //!          cluster.
+        //! @returns A reference to the polygon boundary of the cluster.
         ReferencingPolygon& polygon(void);
-        Router *router(void);
+        //! @brief   Returns a reference to the rectangular boundary of this 
+        //!          cluster.
+        //! @returns A reference to the rectangular boundary of the cluster.
+        Polygon& rectangularPolygon(void);
+        //! @brief   Returns a pointer to the router scene this cluster is in.
+        //! @returns A pointer to the router scene for this cluster.
+        Router *router(void) const;
+        
         void makeActive(void);
         void makeInactive(void);
 
     private:
-        Router *_router;
-        unsigned int _id;
-        ReferencingPolygon _poly;
-        bool _active;
-        ClusterRefList::iterator _pos;
+        Router *m_router;
+        unsigned int m_id;
+        ReferencingPolygon m_polygon;
+        Polygon m_rectangular_polygon;
+        bool m_active;
+        ClusterRefList::iterator m_clusterrefs_pos;
 };