From d075bdedade63f909702f7e2db81517e90588384 Mon Sep 17 00:00:00 2001
From: Tats <info@sofianaudry.com>
Date: Thu, 23 Oct 2014 14:02:49 +0000
Subject: [PATCH] Added detailed comments (documentation) in MapperGlCanvas.

---
 MapperGLCanvas.h | 49 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/MapperGLCanvas.h b/MapperGLCanvas.h
index 360022d..a1a1704 100644
--- a/MapperGLCanvas.h
+++ b/MapperGLCanvas.h
@@ -32,28 +32,48 @@
 class MainWindow;
 
 /**
- * Qt GUI widget that draws a mapper, which is a shape with some paint.
+ * Mother class for OpenGL canvases that allow the display and controls of shapes and vertices.
+ * Provides common functionality to both main sublasses: SourceGLCanvas and DestinationGLCanvas.
  */
 class MapperGLCanvas: public QGLWidget
 {
   Q_OBJECT
 
 public:
+  /// Constructor.
   MapperGLCanvas(MainWindow* mainWindow, QWidget* parent = 0, const QGLWidget* shareWidget = 0);
   virtual ~MapperGLCanvas() {}
 
+  /// Returns shape associated with mapping id.
   virtual Shape* getShapeFromMappingId(uid mappingId) = 0;
 
-  void switchImage(int imageId);
 //  QSize sizeHint() const;
 //  QSize minimumSizeHint() const;
+
+  /// Returns current shape.
   Shape* getCurrentShape();
+
+  /**
+   * Stick vertex p of Shape orig to another Shape's vertex, if the 2 vertices are
+   * close enough. The distance per coordinate is currently set in dist_stick
+   * variable.
+   */
+  // TODO: Perhaps the sticky-sensitivity should be configurable through GUI
   void glueVertex(Shape *, QPointF *);
 
+  /// Returns pointer to main window.
   MainWindow* getMainWindow() const { return _mainWindow; }
+
+  /// Returns true iff we should display the controls.
   bool displayControls() const { return _displayControls; }
+
+  /// Returns true iff we want vertices to stick to each other.
   bool stickyVertices() const { return _stickyVertices; }
+
+  /// Returns true iff one of the vertices is currently active.
   bool hasActiveVertex() const { return _activeVertex != NO_VERTEX; }
+
+  /// Returns the currently active (ie. selected) vertex, or NO_VERTEX if none is currently active.
   int getActiveVertexIndex() const { return _activeVertex; }
 
 protected:
@@ -68,12 +88,27 @@ protected:
   void paintEvent(QPaintEvent* event);
 
 protected:
+  /**
+   * Draws the shapes and controls over the canvas. This method calls:
+   * <code>
+   * enterDraw(painter);
+   * doDraw(painter);
+   * exitDraw(painter);
+   * </code>
+   */
   void draw(QPainter* painter);
+
+  /// Performs initalizations before drawing.
   void enterDraw(QPainter* painter);
+
+  /// Performs the drawing (implemented by subclasses).
   virtual void doDraw(QPainter* painter) = 0;
+
+  /// Performs last drawing actions before exiting draw(QPainter*).
   void exitDraw(QPainter* painter);
 
 private:
+  // Pointer to main window.
   MainWindow* _mainWindow;
 
   // Last point pressed.
@@ -81,10 +116,20 @@ private:
 
   // Mouse currently pressed inside a vertex.
   bool _mousePressedOnVertex;
+
+  // Index of currently active vertex.
   int _activeVertex;
+
+  // True iff current shape is grabbed.
   bool _shapeGrabbed;
+
+  // True iff current shape is grabbed (first step).
   bool _shapeFirstGrab;
+
+  // True iff we are displaying the controls.
   bool _displayControls;
+
+  // True iff we want vertices to stick to each other.
   bool _stickyVertices;
 
 signals: