Improved the documentation of GridView

docs/doxygen.conf

@@ -74,7 +74,7 @@ BRIEF_MEMBER_DESC      = YES
 # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
 # brief descriptions will be completely suppressed.
 
-REPEAT_BRIEF           = NO
+REPEAT_BRIEF           = YES
 
 # This tag implements a quasi-intelligent brief description abbreviator
 # that is used to form the text in various listings. Each string

include/gridview.hpp

@@ -29,74 +29,71 @@ Cette classe représente le widget utilisé pour l'affichage et l'interaction av
 
 namespace detail
 {
-
-// based on https://stackoverflow.com/questions/19113532/qgraphicsview-zooming-in-and-out-under-mouse-position-using-mouse-wheel
-class Graphics_view_zoom : public QObject {
-    Q_OBJECT
-public:
-    Graphics_view_zoom(QGraphicsView* view);
-    void gentle_zoom(double factor);
-    void set_zoom_factor_base(double value);
-
-private:
-    QGraphicsView* _view;
-    double _zoom_factor_base;
-    QPointF target_scene_pos, target_viewport_pos;
-    bool eventFilter(QObject* object, QEvent* event);
-
-signals:
-    void zoomed();
-};
+class Graphics_view_zoom;
 }
-
-
 class GridItem;
 class GridView;
-class GridGraphicsView : public QGraphicsView
-{
-public:
-    GridGraphicsView(GridView& gridview, QWidget* parent)
-        : QGraphicsView(parent), m_gridview(gridview)
-    {
-        setAcceptDrops(true);
-    }
-
-protected:
-    void mousePressEvent(QMouseEvent* event);
-    void mouseMoveEvent(QMouseEvent* event);
-
-private:
-    GridView& m_gridview;
-};
+class GridGraphicsView;
 
+/**
+ * \class GridView
+ * \brief Widget affichant la grille en cours
+ *
+ * Cette classe, hérité de QFrame, représente l'état de la grille à l'instant actuel. Il affiche les différentes cellules avec la couleur choisie par l'alphabet,
+ * permet l'édition, la suppression, le copier-couper-coller, et le glisser-déposer de structures depuis d'autres widget.
+ */
 class GridView : public QFrame
 {
     Q_OBJECT
 public:
+    //! \brief Initialise le GridView comme n'importe quel autre QWidget avec son parent.
     GridView(QWidget *parent = nullptr);
 public:
+    //! \brief Associe l'alphabet alph à l'objet GridView afin d'afficher les bonnes couleurs et étiquettes.
+    //! \param alph L'alphabet à associer.
     void set_alphabet(const Alphabet& alph);
+    //! \brief Retourne l'alphabet actuel utilisé par le GridView.
+    //! \returns L'alphabet actuellement utilisé
     const Alphabet& alphabet() const;
 
+    //! \brief Paramètre l'état à assigner aux cellules lors de l'édition (le 'stylo' actuel)
+    //! \param state L'état à assigner à chaque cellule éditée.
     void set_current_pen(unsigned state);
+    //! \brief Retoure l'état actuel du stylo.
+    //! \returns L'état actuel de l'édition.
     unsigned current_pen() const;
 
+    //! \brief Insère une structure à une position donnée.
+    //! \param origin La coordonnée où placer la structure.
+    //! \param s La structure à placer.
     void paste_structure_at(Coord origin, const Structure& s);
 
+    //! \brief Utilise une structure passée en argument comme structure à coller lors d'une opération de collage, par exemple avec Ctrl+V.
+    //! \param s La structure désirée.
     void set_clipboard(const Structure& s);
 
-    //! Retourne la taille du côté en pixels d'une cellule au niveau de zoom actuel
+    //! \brief Retourne la taille du côté en pixels d'une cellule au niveau de zoom actuel.
+    //! \returns Taille en pixel du côté d'une cellule.
     unsigned cell_pixel_size() const;
 
+    //! \brief Charge la Grid grid dans le GridView afin de l'afficher et de pouvoir l'éditer.
+    //! \param grid La Grid à copier vers l'affichage du GridView.
     void copy_grid(const Grid& grid);
+    //! \brief Retourne une Grid représentant l'état actuel affiché par la GridView.
+    //! \returns Une Grid correspondante.
     Grid get_grid() const;
 
+    //! \brief Réinitialise la sélection.
     void clear_selection();
+    //! \brief Remplit les cellules sélectionnées avec un état choisi.
+    //! \param state L'état à assigner.
     void fill_selection(unsigned state);
+    //! \brief Retourne une structure représentant la sélection actuelle.
+    //! \returns Une structure représentant la sélection actuelle.
     Structure selected_cells() const;
 
 signals:
-    //! Emis quand le zoom change
+    //! \brief Signal émis quand le zoom change.
     //! \param cell_size la nouvelle taille à l'écran en pixels d'une cellule
     void zoom_changed(unsigned cell_size);
 

src/gridview.cpp

@@ -28,11 +28,82 @@ Cette classe représente le widget utilisé pour l'affichage et l'interaction av
 
 #include "structurereader.hpp"
 
+//! Permet de convertir un stateColor vers un QColor.
+//! Détail d'implémentation.
 static QColor stateColor_to_QColor(const stateColor& sc)
 {
     return QColor::fromRgb(sc.getRed(), sc.getGreen(), sc.getBlue());
 }
 
+
+namespace detail
+{
+
+//! \class Graphics_view_zoom
+//! Classe permettant l'implémentation d'un zoom au travers d'un event filter.
+//! Détail d'implémentation.
+//! based on https://stackoverflow.com/questions/19113532/qgraphicsview-zooming-in-and-out-under-mouse-position-using-mouse-wheel
+class Graphics_view_zoom : public QObject {
+    Q_OBJECT
+public:
+    Graphics_view_zoom(QGraphicsView* view);
+    void gentle_zoom(double factor);
+    void set_zoom_factor_base(double value);
+
+private:
+    QGraphicsView* _view;
+    double _zoom_factor_base;
+    QPointF target_scene_pos, target_viewport_pos;
+    bool eventFilter(QObject* object, QEvent* event);
+
+signals:
+    void zoomed();
+};
+Graphics_view_zoom::Graphics_view_zoom(QGraphicsView* view)
+    : QObject(view), _view(view)
+{
+    _view->viewport()->installEventFilter(this);
+    _view->setMouseTracking(true);
+    _zoom_factor_base = 1.0015;
+}
+
+void Graphics_view_zoom::gentle_zoom(double factor) {
+    _view->scale(factor, factor);
+    _view->centerOn(target_scene_pos);
+    QPointF delta_viewport_pos = target_viewport_pos - QPointF(_view->viewport()->width() / 2.0,
+                                                               _view->viewport()->height() / 2.0);
+    QPointF viewport_center = _view->mapFromScene(target_scene_pos) - delta_viewport_pos;
+    _view->centerOn(_view->mapToScene(viewport_center.toPoint()));
+    emit zoomed();
+}
+
+void Graphics_view_zoom::set_zoom_factor_base(double value) {
+    _zoom_factor_base = value;
+}
+
+bool Graphics_view_zoom::eventFilter(QObject *object, QEvent *event) {
+    if (event->type() == QEvent::MouseMove) {
+        QMouseEvent* mouse_event = static_cast<QMouseEvent*>(event);
+        QPointF delta = target_viewport_pos - mouse_event->pos();
+        if (qAbs(delta.x()) > 5 || qAbs(delta.y()) > 5) {
+            target_viewport_pos = mouse_event->pos();
+            target_scene_pos = _view->mapToScene(mouse_event->pos());
+        }
+    } else if (event->type() == QEvent::Wheel) {
+        QWheelEvent* wheel_event = static_cast<QWheelEvent*>(event);
+        if (wheel_event->angleDelta().y() != 0) {
+            double angle = wheel_event->angleDelta().y();
+            double factor = qPow(_zoom_factor_base, angle);
+            gentle_zoom(factor);
+            return true;
+        }
+    }
+    Q_UNUSED(object)
+    return false;
+}
+
+}
+
 class GridItem : public QGraphicsRectItem
 {
 public:
@@ -142,6 +213,30 @@ private:
     GridView& m_grid_view;
 };
 
+/**
+ * \class GridGraphicsView
+ *
+ * Classe héritée de GraphicsView permettant les manipulations à la souris et de drag-and-drop.
+ * Détail d'implémentation.
+ */
+class GridGraphicsView : public QGraphicsView
+{
+public:
+    GridGraphicsView(GridView& gridview, QWidget* parent)
+        : QGraphicsView(parent), m_gridview(gridview)
+    {
+        setAcceptDrops(true);
+    }
+
+protected:
+    void mousePressEvent(QMouseEvent* event);
+    void mouseMoveEvent(QMouseEvent* event);
+
+private:
+    GridView& m_gridview;
+};
+
+
 void GridGraphicsView::mousePressEvent(QMouseEvent *event)
 {
     QGraphicsItem* gitem_ptr = itemAt(event->pos());
@@ -466,45 +561,3 @@ void GridView::keyReleaseEvent(QKeyEvent *event)
     return QFrame::keyReleaseEvent(event);
 }
 
-detail::Graphics_view_zoom::Graphics_view_zoom(QGraphicsView* view)
-    : QObject(view), _view(view)
-{
-    _view->viewport()->installEventFilter(this);
-    _view->setMouseTracking(true);
-    _zoom_factor_base = 1.0015;
-}
-
-void detail::Graphics_view_zoom::gentle_zoom(double factor) {
-    _view->scale(factor, factor);
-    _view->centerOn(target_scene_pos);
-    QPointF delta_viewport_pos = target_viewport_pos - QPointF(_view->viewport()->width() / 2.0,
-                                                               _view->viewport()->height() / 2.0);
-    QPointF viewport_center = _view->mapFromScene(target_scene_pos) - delta_viewport_pos;
-    _view->centerOn(_view->mapToScene(viewport_center.toPoint()));
-    emit zoomed();
-}
-
-void detail::Graphics_view_zoom::set_zoom_factor_base(double value) {
-    _zoom_factor_base = value;
-}
-
-bool detail::Graphics_view_zoom::eventFilter(QObject *object, QEvent *event) {
-    if (event->type() == QEvent::MouseMove) {
-        QMouseEvent* mouse_event = static_cast<QMouseEvent*>(event);
-        QPointF delta = target_viewport_pos - mouse_event->pos();
-        if (qAbs(delta.x()) > 5 || qAbs(delta.y()) > 5) {
-            target_viewport_pos = mouse_event->pos();
-            target_scene_pos = _view->mapToScene(mouse_event->pos());
-        }
-    } else if (event->type() == QEvent::Wheel) {
-        QWheelEvent* wheel_event = static_cast<QWheelEvent*>(event);
-        if (wheel_event->angleDelta().y() != 0) {
-            double angle = wheel_event->angleDelta().y();
-            double factor = qPow(_zoom_factor_base, angle);
-            gentle_zoom(factor);
-            return true;
-        }
-    }
-    Q_UNUSED(object)
-    return false;
-}