docs: Document pensizeselector.h and pensizeselector.cpp files and th…

…eir entities

Signed-off-by: Aditya Agarwal <[email protected]>

lib/gui/include/widgets/pensizeselector.h

@@ -1,9 +1,20 @@
+/**
+ * @file                    pensizeselector.h
+ * @author                  Aditya Agarwal ([email protected])
+ * @brief                   File that declares the `PenSizeSelector` class, which is used to create row of pen-sizes to pick from from
+ *
+ */
+
 #ifndef __ARDUINO_WIFI_TFT_LCD_CANVAS_APP_WIDGETS_PEN_SIZE_SELECTOR_H__
 #define __ARDUINO_WIFI_TFT_LCD_CANVAS_APP_WIDGETS_PEN_SIZE_SELECTOR_H__
 
 #include "widget.h"
 #include "frame.h"
 
+/**
+ * @brief                   Class that implements a widget which is used to create row of pen-sizes to pick from from
+ *
+ */
 class PenSizeSelector : public BasicWidget, public InteractiveWidget {
 
 protected:
@@ -13,46 +24,127 @@ class PenSizeSelector : public BasicWidget, public InteractiveWidget {
     constexpr static unsigned WIDTH = 8 * H_PAD;
     constexpr static unsigned HEIGHT = 29;
 
+    /** Reference to parent frame */
     Frame *parent {nullptr};
 
+    /** Flag that indicates if the bitmap is dirty or not */
     bool dirty {false};
+    /** Flag that indicates if the bitmap's visibility has been changed or not */
     bool visibility_changed {false};
-
+    /** Flag to indicate if the bitmap is hidden or visible */
     bool visible {true};
+    /** Flag to indicate if the bitmap is in a pressed state or not */
     bool pressed {false};
+    /** Flag to indicate if interacting with the bitmap is enabled or disabled */
     bool enabled {true};
 
-    unsigned widget_x {0};
-    unsigned widget_y {0};
+    /** X-coordinate of the color selector relative to its parent (offset from left-edge) */
+    unsigned widget_x;
+    /** Y-coordinate of the color selector relative to its parent (offset from top-edge) */
+    unsigned widget_y;
 
-    unsigned widget_absolute_x {0};
-    unsigned widget_absolute_y {0};
+    /** X-coordinate of the color selector relative to the display (offset from left-edge) */
+    unsigned widget_absolute_x;
+    /** Y-coordinate of the color selector relative to the display (offset from top-edge) */
+    unsigned widget_absolute_y;
 
+    /** Color of the spots */
     uint16_t color {};
+    /** Radii of the available options */
     uint16_t sizes[4] {};
 
-    unsigned active_size {0};
+    /** Selected size */
+    unsigned selected_size {};
 
+    /** Function to call when the bitmap is pressed */
     callback_t on_press {nullptr};
+    /** Function to call when the bitmap is released */
     callback_t on_release {nullptr};
 
+    /** Pointer to arguments passed to callbacks */
+    unsigned *args {nullptr};
+
+    /** Reference to event queue for posting events */
     RingQueueInterface<callback_event_t> *event_queue {nullptr};
 
-    unsigned *args {nullptr};
+    /** The epoch when the widget was last pressed */
+    unsigned last_press_epoch {0};
 
 public:
 
+    /**
+     * @brief               Default constructor disabled (use the `create` method)
+     *
+     */
     PenSizeSelector() = delete;
 
+    /**
+     * @brief               Dynamically create a new pen size selector instance
+     *
+     * @warning             This method returns a nullptr if a color selector instance could not be created
+     *
+     * @param parent        The frame that should own this pen size selector
+     * @param x             X-coordinate of the pen size selector, within `parent` (offset from left-edge)
+     * @param y             Y-coordinate of the pen size selector, within `parent` (offset from top-edge)
+     *
+     * @return
+     *
+     */
     static PenSizeSelector *create(Frame *parent, unsigned x, unsigned y);
 
+    /**
+     * @brief               Set the size at a position
+     *
+     * @param pos           Position of the new size (from left to right in increasing order)
+     * @param new_size      Radius
+     *
+     * @return              Pointer to the pen size selector (allows chaining method calls)
+     *
+     */
     PenSizeSelector *set_size(unsigned pos, uint16_t new_size);
-    uint16_t get_size(unsigned pos) const;
 
-    PenSizeSelector *set_active_size(unsigned pos);
-    uint16_t get_active_size() const;
+    /**
+     * @brief               Get the size at a position
+     *
+     * @param pos           Position to get from (from left to right in increasing order)
+     *
+     * @return              Radius
+     *
+     */
+    uint16_t get_size(unsigned pos) const;
 
+    /**
+     * @brief               Set the selected size
+     *
+     * @param pos           Position of the size which should be selected
+     *
+     * @return              Pointer to the pen size selector (allows chaining method calls)
+     *
+     */
+    PenSizeSelector *set_selected_size(unsigned pos);
+
+    /**
+     * @brief               Get the selected size
+     *
+     * @return              Radius
+     */
+    uint16_t get_selected_size() const;
+
+    /**
+     * @brief               Set the color of the size selection spots
+     *
+     * @param new_color     16-bit color
+     *
+     * @return              Pointer to the pen size selector (allows for chaining method calls)
+     *
+     */
     PenSizeSelector *set_color(uint16_t new_color);
+
+    /**
+     * @brief               Get the color of the size selection spots
+     *
+     * @return              Pointer to the pen size selector (allows for chaining method calls)
+     */
     uint16_t get_color() const;
 
     // BasicWidget overrides
@@ -108,6 +200,14 @@ class PenSizeSelector : public BasicWidget, public InteractiveWidget {
 
 protected:
 
+    /**
+     * @brief               Construct a new Pen Size Selector object
+     *
+     * @param parent        The frame that should own this pen size selector
+     * @param x             X-coordinate of the pen size selector, within `parent` (offset from left-edge)
+     * @param y             Y-coordinate of the pen size selector, within `parent` (offset from top-edge)
+     *
+     */
     PenSizeSelector(Frame *parent, unsigned x, unsigned y);
 };
 

lib/gui/src/widgets/pensizeselector.cpp

@@ -1,3 +1,10 @@
+/**
+ * @file                    pensizeselector.cpp
+ * @author                  Aditya Agarwal ([email protected])
+ * @brief                   This file implements the methods of the `PenSizeSelector` class
+ *
+ */
+
 #include "widgets/pensizeselector.h"
 
 PenSizeSelector::PenSizeSelector(Frame *parent, unsigned x, unsigned y)
@@ -34,16 +41,16 @@ uint16_t PenSizeSelector::get_size(unsigned pos) const {
     return sizes[pos];
 }
 
-PenSizeSelector *PenSizeSelector::set_active_size(unsigned pos) {
+PenSizeSelector *PenSizeSelector::set_selected_size(unsigned pos) {
     if (pos > sizeof(sizes) / sizeof(sizes[0])) {
         return this;
     }
 
     dirty = true;
-    active_size = pos;
+    selected_size = pos;
     return this;
 }
-uint16_t PenSizeSelector::get_active_size() const { return sizes[active_size]; }
+uint16_t PenSizeSelector::get_selected_size() const { return sizes[selected_size]; }
 
 PenSizeSelector *PenSizeSelector::set_color(uint16_t new_color) {
     if (new_color == color) {
@@ -96,7 +103,7 @@ void PenSizeSelector::draw() {
                                         ? (blend_color(blend_color(BLACK, WHITE, 12), BLUE, 10))
                                         : (color));
 
-        parent->draw_circle(x, y, s + 3, (c == active_size)
+        parent->draw_circle(x, y, s + 3, (c == selected_size)
                                             ? WHITE
                                             : BLACK);
     }
@@ -180,7 +187,7 @@ bool PenSizeSelector::propagate_press(unsigned x, unsigned y) {
         }
 
         if (event_queue != nullptr && on_press != nullptr) {
-            event_queue->push({on_press, (unsigned *)&sizes[active_size]});
+            event_queue->push({on_press, (unsigned *)&sizes[selected_size]});
         }
         break;
     }
@@ -218,9 +225,9 @@ bool PenSizeSelector::propagate_release(unsigned x, unsigned y) {
             continue;
         }
 
-        set_active_size(c);
+        set_selected_size(c);
         if (event_queue != nullptr && on_release != nullptr) {
-            event_queue->push({on_release, (unsigned *)&sizes[active_size]});
+            event_queue->push({on_release, (unsigned *)&sizes[selected_size]});
         }
         break;
     }