Merge GSoC2009 Connectors into trunk

[inkscape.git] / src / libavoid / shape.h

diff --git a/src/libavoid/shape.h b/src/libavoid/shape.h
index b654c6eea159bf458694e998ce1c1f899d29b663..df4c98df14a70d20fbd832e776d2146e4fec90d2 100644 (file)
--- a/src/libavoid/shape.h
+++ b/src/libavoid/shape.h
@@ -2,24 +2,30 @@
  * vim: ts=4 sw=4 et tw=0 wm=0
  *
  * libavoid - Fast, Incremental, Object-avoiding Line Router
- * Copyright (C) 2004-2006  Michael Wybrow <mjwybrow@users.sourceforge.net>
+ *
+ * Copyright (C) 2004-2008  Monash University
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
  * version 2.1 of the License, or (at your option) any later version.
+ * See the file LICENSE.LGPL distributed with the library.
+ *
+ * Licensees holding a valid commercial license may use this file in
+ * accordance with the commercial license agreement provided with the 
+ * library.
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  
  *
+ * Author(s):   Michael Wybrow <mjwybrow@users.sourceforge.net>
 */
 
+//! @file    shape.h
+//! @brief   Contains the interface for the ShapeRef class.
+
+
 #ifndef AVOID_SHAPE_H
 #define AVOID_SHAPE_H
 
@@ -35,21 +41,64 @@ class ShapeRef;
 typedef std::list<ShapeRef *> ShapeRefList;
 
 
+//! @brief   The ShapeRef class represents a shape object.
+//!
+//! Shapes are obstacles that connectors must be routed around.  They can be 
+//! placed into a Router scene and can be repositioned or resized (via
+//! Router::moveShape()).
+//! 
+//! Usually, it is expected that you would create a ShapeRef for each shape 
+//! in your diagram and keep that reference in your own shape class.
+//!
 class ShapeRef
 {
     public:
-        ShapeRef(Router *router, unsigned int id, Polygn& poly);
-        virtual ~ShapeRef();
-        void setNewPoly(Polygn& poly);
+        //! @brief  Shape reference constructor.
+        //!
+        //! Creates a shape obect reference, but does not yet place it into the
+        //! Router scene.
+        //!
+        //! The poly argument will usually be the boundary of the shape in your 
+        //! application with additional buffer of several pixels on each side.
+        //! Specifying such a buffer results in connectors leaving a small 
+        //! amount of space around shapes, rather than touching them on the 
+        //! corners or edges.
+        //!
+        //! If an ID is not specified, then one will be assigned to the shape.
+        //! If assigning an ID yourself, note that it should be a unique 
+        //! positive integer.  Also, IDs are given to all objects in a scene,
+        //! so the same ID cannot be given to a shape and a connector for 
+        //! example.
+        //!
+        //! @param[in]  router  The router scene to place the shape into.
+        //! @param[in]  poly    A Polygon representing the boundary of the 
+        //!                     shape.
+        //! @param[in]  id      A unique positive integer ID for the shape.  
+        ShapeRef(Router *router, Polygon& poly, const unsigned int id = 0);
+        //! @brief  Shape reference destructor.
+        //!
+        //! This will call Router::removeShape() for this shape, if this has
+        //! not already be called.
+        ~ShapeRef();
+        
+        //! @brief   Returns the ID of this shape.
+        //! @returns The ID of the shape. 
+        unsigned int id(void) const;
+        //! @brief   Returns a reference to the polygon boundary of this shape.
+        //! @returns A reference to the polygon boundary of the shape.
+        const Polygon& polygon(void) const;
+        //! @brief   Returns a pointer to the router scene this shape is in.
+        //! @returns A pointer to the router scene for this shape.
+        Router *router(void) const;
+        
+        void setNewPoly(const Polygon& poly);
         VertInf *firstVert(void);
         VertInf *lastVert(void);
-        unsigned int id(void);
-        Polygn poly(void);
-        Router *router(void);
         void boundingBox(BBox& bbox);
 
         void makeActive(void);
         void makeInactive(void);
+        bool isActive(void) const;
 
         void removeFromGraph(void);
         void markForMove(void);
@@ -60,7 +109,7 @@ class ShapeRef
     private:
         Router *_router;
         unsigned int _id;
-        Polygn _poly;
+        Polygon _poly;
         bool _active;
         bool _inMoveList;
         ShapeRefList::iterator _pos;