From e137786e93f0cf6b2c5e38149c05176f1eb97146 Mon Sep 17 00:00:00 2001 From: Aditya Agarwal Date: Sun, 24 Mar 2024 20:59:40 +0530 Subject: [PATCH] docs: Document pensizeselector.h and pensizeselector.cpp files and their entities Signed-off-by: Aditya Agarwal --- lib/gui/include/widgets/pensizeselector.h | 120 ++++++++++++++++++++-- lib/gui/src/widgets/pensizeselector.cpp | 21 ++-- 2 files changed, 124 insertions(+), 17 deletions(-) diff --git a/lib/gui/include/widgets/pensizeselector.h b/lib/gui/include/widgets/pensizeselector.h index cfda025..96adb68 100644 --- a/lib/gui/include/widgets/pensizeselector.h +++ b/lib/gui/include/widgets/pensizeselector.h @@ -1,9 +1,20 @@ +/** + * @file pensizeselector.h + * @author Aditya Agarwal (aditya.agarwal@dumblebots.com) + * @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 *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); }; diff --git a/lib/gui/src/widgets/pensizeselector.cpp b/lib/gui/src/widgets/pensizeselector.cpp index cd60e3c..8c632a1 100644 --- a/lib/gui/src/widgets/pensizeselector.cpp +++ b/lib/gui/src/widgets/pensizeselector.cpp @@ -1,3 +1,10 @@ +/** + * @file pensizeselector.cpp + * @author Aditya Agarwal (aditya.agarwal@dumblebots.com) + * @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; }