implement left/right with callback
Signed-off-by: Peter Siegmund <developer@mars3142.org>
This commit is contained in:
@@ -1,21 +1,63 @@
|
||||
/**
|
||||
* @file Common.h
|
||||
* @brief Common definitions and types for the INSA component
|
||||
* @details This header file contains shared enumerations, type definitions, and
|
||||
* callback function types used throughout the INSA component system.
|
||||
* It provides the foundation for button handling and event management.
|
||||
* @author System Control Team
|
||||
* @date 2025-06-14
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include <functional>
|
||||
|
||||
// Enumeration defining the different types of buttons available in the system
|
||||
// NONE represents no button pressed or an invalid button state
|
||||
enum class ButtonType {
|
||||
NONE, // No button or invalid state
|
||||
UP, // Up directional button
|
||||
DOWN, // Down directional button
|
||||
LEFT, // Left directional button
|
||||
RIGHT, // Right directional button
|
||||
SELECT, // Select/confirm button
|
||||
BACK // Back/cancel button
|
||||
/**
|
||||
* @enum ButtonType
|
||||
* @brief Enumeration defining the different types of buttons available in the system
|
||||
* @details This enumeration represents all possible button types that can be handled
|
||||
* by the system's input management. NONE represents no button pressed or
|
||||
* an invalid button state, while the other values correspond to specific
|
||||
* directional and action buttons.
|
||||
*/
|
||||
enum class ButtonType
|
||||
{
|
||||
NONE, ///< No button pressed or invalid button state
|
||||
UP, ///< Up directional button for navigation
|
||||
DOWN, ///< Down directional button for navigation
|
||||
LEFT, ///< Left directional button for navigation
|
||||
RIGHT, ///< Right directional button for navigation
|
||||
SELECT, ///< Select/confirm button for accepting choices
|
||||
BACK ///< Back/cancel button for returning to previous state
|
||||
};
|
||||
|
||||
// Type alias for button event callback function
|
||||
// Parameters:
|
||||
// - uint8_t: Button identifier or additional data
|
||||
// - ButtonType: The type of button that was pressed
|
||||
typedef std::function<void(uint8_t, ButtonType)> ButtonCallback;
|
||||
// Forward declaration of MenuItem to avoid circular dependency
|
||||
class MenuItem;
|
||||
|
||||
/**
|
||||
* @typedef ButtonCallback
|
||||
* @brief Type alias for button event callback function
|
||||
* @details This function type is used to define callback functions that handle
|
||||
* button press events. The callback receives information about which
|
||||
* button was pressed and any additional context data.
|
||||
*
|
||||
* @param MenuItem menu item for the specific action
|
||||
* @param ButtonType The type of button that was pressed
|
||||
*
|
||||
* @note The first parameter can be used to distinguish between multiple instances
|
||||
* of the same button type or to pass additional event-specific data.
|
||||
*
|
||||
* @example
|
||||
* @code
|
||||
* ButtonCallback myCallback = [](const MenuItem& item, ButtonType type) {
|
||||
* if (type == ButtonType::SELECT) {
|
||||
* // Handle select button press
|
||||
* processSelection(item);
|
||||
* }
|
||||
* };
|
||||
* @endcode
|
||||
*/
|
||||
typedef std::function<void(MenuItem, ButtonType)> ButtonCallback;
|
||||
|
||||
// Include MenuItem.h after the typedef to avoid circular dependency
|
||||
#include "data/MenuItem.h"
|
||||
232
components/insa/include/common/Menu.h
Normal file
232
components/insa/include/common/Menu.h
Normal file
@@ -0,0 +1,232 @@
|
||||
/**
|
||||
* @file Menu.h
|
||||
* @brief Menu widget class for creating interactive menu systems
|
||||
* @details This header defines the Menu class which extends the Widget base class
|
||||
* to provide a comprehensive, customizable menu system supporting various
|
||||
* types of interactive menu items including text buttons, selections,
|
||||
* number inputs, and toggles. The menu supports navigation with directional
|
||||
* input and provides visual feedback through selection highlighting and scrollbars.
|
||||
* @author System Control Team
|
||||
* @date 2025-06-14
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "Common.h"
|
||||
#include "MenuOptions.h"
|
||||
#include "Widget.h"
|
||||
#include "data/MenuItem.h"
|
||||
|
||||
/**
|
||||
* @class Menu
|
||||
* @brief A comprehensive menu widget class for interactive user interfaces
|
||||
* @details This class extends the Widget base class to provide a customizable menu system
|
||||
* with support for various types of interactive menu items. It handles user input
|
||||
* through directional navigation and action buttons, provides visual feedback
|
||||
* through selection highlighting, and supports scrolling for long menu lists.
|
||||
*
|
||||
* The menu system supports four types of menu items:
|
||||
* - Text buttons: Simple selectable text items
|
||||
* - Selection items: Dropdown/list selection with multiple options
|
||||
* - Number inputs: Numeric value adjustment controls
|
||||
* - Toggle items: Boolean on/off switches
|
||||
*
|
||||
* @note Menu items are identified by unique IDs and can be dynamically added
|
||||
* after menu creation.
|
||||
*
|
||||
* @see Widget
|
||||
* @see MenuItem
|
||||
* @see menu_options_t
|
||||
*/
|
||||
class Menu : public Widget
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* @brief Constructs a new Menu instance with the specified configuration
|
||||
* @param options Pointer to menu configuration options structure
|
||||
*
|
||||
* @pre options must not be nullptr and must remain valid for the menu's lifetime
|
||||
* @post Menu is initialized with the provided configuration and ready for item addition
|
||||
*
|
||||
* @note The menu does not take ownership of the options structure and assumes
|
||||
* it remains valid throughout the menu's lifetime.
|
||||
*/
|
||||
explicit Menu(menu_options_t *options);
|
||||
|
||||
/**
|
||||
* @brief Destructor - Cleans up resources when menu is destroyed
|
||||
* @details Properly releases any allocated resources and ensures clean shutdown
|
||||
* of the menu system.
|
||||
*/
|
||||
~Menu() override;
|
||||
|
||||
/**
|
||||
* @brief Adds a text-based menu item (button) to the menu
|
||||
* @param id Unique identifier for this menu item (must be unique within the menu)
|
||||
* @param text Display text shown on the menu item
|
||||
*
|
||||
* @pre id must be unique within this menu instance
|
||||
* @post A new text menu item is added to the menu's item collection
|
||||
*
|
||||
* @note Text items act as buttons and generate selection events when activated
|
||||
*/
|
||||
void addText(uint8_t id, const std::string &text);
|
||||
|
||||
/**
|
||||
* @brief Adds a selection menu item (dropdown/list selection) to the menu
|
||||
* @param id Unique identifier for this menu item (must be unique within the menu)
|
||||
* @param text Display text/label for the selection item
|
||||
* @param values Vector of all available options to choose from
|
||||
* @param index Reference to current selected value (will be modified by user interaction)
|
||||
*
|
||||
* @pre id must be unique within this menu instance
|
||||
* @pre values vector must not be empty
|
||||
* @pre value must be one of the strings in the values vector
|
||||
* @post A new selection menu item is added with the specified options
|
||||
*
|
||||
* @note The value parameter is modified directly when the user changes the selection
|
||||
*/
|
||||
void addSelection(uint8_t id, const std::string &text, const std::vector<std::string> &values, int index);
|
||||
|
||||
/**
|
||||
* @brief Adds a toggle/checkbox menu item to the menu
|
||||
* @param id Unique identifier for this menu item (must be unique within the menu)
|
||||
* @param text Display text/label for the toggle item
|
||||
* @param selected Current state of the toggle (true = on/enabled, false = off/disabled)
|
||||
*
|
||||
* @pre id must be unique within this menu instance
|
||||
* @post A new toggle menu item is added with the specified initial state
|
||||
*
|
||||
* @note Toggle state can be changed through user interaction with select button
|
||||
*/
|
||||
void addToggle(uint8_t id, const std::string &text, bool selected);
|
||||
|
||||
protected:
|
||||
/**
|
||||
* @brief Virtual callback method for handling button press events on specific menu items
|
||||
* @param item The menu item that received the button press
|
||||
* @param button The type of button that was pressed
|
||||
*
|
||||
* @details This method can be overridden by derived classes to implement custom
|
||||
* button handling logic for specific menu items. The base implementation
|
||||
* is empty, allowing derived classes to selectively handle events.
|
||||
*
|
||||
* @note Override this method in derived classes to implement custom menu item
|
||||
* interaction behavior beyond the standard navigation and value modification.
|
||||
*/
|
||||
virtual void onButtonPressed(const MenuItem &item, const ButtonType button)
|
||||
{
|
||||
// Base implementation intentionally empty - override in derived classes as needed
|
||||
}
|
||||
|
||||
MenuItem getItem(int index);
|
||||
|
||||
[[nodiscard]] size_t getItemCount() const;
|
||||
|
||||
void setItemSize(size_t size);
|
||||
|
||||
void replaceItem(int index, const MenuItem &item);
|
||||
|
||||
private:
|
||||
/**
|
||||
* @brief Renders the entire menu on screen
|
||||
* @details Override from Widget base class. Handles the complete rendering process
|
||||
* including menu items, selection highlighting, and scroll indicators.
|
||||
*
|
||||
* @note This method is called during each frame's render cycle
|
||||
*/
|
||||
void render() override;
|
||||
|
||||
/**
|
||||
* @brief Handles button press events from the input system
|
||||
* @param button The button that was pressed
|
||||
* @details Override from Widget base class. Processes user input and delegates
|
||||
* to appropriate handler methods based on button type.
|
||||
*
|
||||
* @see ButtonType for available button types
|
||||
*/
|
||||
void onButtonClicked(ButtonType button) override;
|
||||
|
||||
// Navigation event handlers
|
||||
/**
|
||||
* @brief Handles down arrow/stick input - moves selection down in the menu
|
||||
* @details Moves the current selection to the next menu item, wrapping to the
|
||||
* beginning if at the end of the list.
|
||||
*/
|
||||
void onPressedDown();
|
||||
|
||||
/**
|
||||
* @brief Handles up arrow/stick input - moves selection up in the menu
|
||||
* @details Moves the current selection to the previous menu item, wrapping to the
|
||||
* end if at the beginning of the list.
|
||||
*/
|
||||
void onPressedUp();
|
||||
|
||||
/**
|
||||
* @brief Handles left arrow/stick input - decreases value for current item
|
||||
* @details For selection items: moves to previous option in the list
|
||||
* For number items: decreases the numeric value
|
||||
* For other items: no action
|
||||
*/
|
||||
void onPressedLeft() const;
|
||||
|
||||
/**
|
||||
* @brief Handles right arrow/stick input - increases value for current item
|
||||
* @details For selection items: moves to next option in the list
|
||||
* For number items: increases the numeric value
|
||||
* For other items: no action
|
||||
*/
|
||||
void onPressedRight() const;
|
||||
|
||||
/**
|
||||
* @brief Handles select/confirm button press
|
||||
* @details Activates the currently selected menu item:
|
||||
* - Text items: triggers selection event
|
||||
* - Toggle items: toggles the boolean state
|
||||
* - Other items: context-dependent behavior
|
||||
*/
|
||||
void onPressedSelect() const;
|
||||
|
||||
/**
|
||||
* @brief Handles back/cancel button press
|
||||
* @details Typically used to exit the menu or return to a previous screen.
|
||||
* The specific behavior depends on the menu configuration.
|
||||
*/
|
||||
void onPressedBack() const;
|
||||
|
||||
// Rendering helper methods
|
||||
/**
|
||||
* @brief Draws the scroll bar indicating position in long menus
|
||||
* @details Renders a visual scroll indicator when the menu contains more items
|
||||
* than can be displayed on screen simultaneously.
|
||||
*/
|
||||
void drawScrollBar() const;
|
||||
|
||||
/**
|
||||
* @brief Draws the selection highlight box around current menu item
|
||||
* @details Renders visual feedback showing which menu item is currently selected
|
||||
* and will respond to user input.
|
||||
*/
|
||||
void drawSelectionBox() const;
|
||||
|
||||
/**
|
||||
* @brief Renders an individual menu item widget
|
||||
* @param item Pointer to the menu item to render (must not be nullptr)
|
||||
* @param font Font to use for rendering text
|
||||
* @param x X coordinate for rendering position
|
||||
* @param y Y coordinate for rendering position
|
||||
*
|
||||
* @pre item must not be nullptr
|
||||
* @pre font must be a valid u8g2 font
|
||||
* @pre x and y must be valid screen coordinates
|
||||
*
|
||||
* @details Handles the rendering of a single menu item based on its type,
|
||||
* including text, current values, and any type-specific visual elements.
|
||||
*/
|
||||
void renderWidget(const MenuItem *item, const uint8_t *font, int x, int y) const;
|
||||
|
||||
// Member variables
|
||||
size_t m_selected_item = 0; ///< Index of currently selected menu item (0-based)
|
||||
std::vector<MenuItem> m_items; ///< Collection of all menu items in display order
|
||||
menu_options_t *m_options; ///< Pointer to menu configuration options (not owned)
|
||||
};
|
||||
@@ -1,137 +0,0 @@
|
||||
#pragma once
|
||||
|
||||
#include <functional>
|
||||
|
||||
#include "Common.h"
|
||||
#include "MenuOptions.h"
|
||||
#include "Widget.h"
|
||||
#include "data/MenuItem.h"
|
||||
|
||||
/**
|
||||
* PSMenu - A menu widget class
|
||||
*
|
||||
* This class extends the Widget base class to provide a customizable menu system
|
||||
* with various types of interactive menu items including text buttons, selections,
|
||||
* number inputs, and toggles.
|
||||
*/
|
||||
class PSMenu : public Widget
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* Constructor - Creates a new PSMenu instance
|
||||
* @param options Pointer to menu configuration options
|
||||
*/
|
||||
explicit PSMenu(menu_options_t *options);
|
||||
|
||||
/**
|
||||
* Destructor - Cleans up resources when menu is destroyed
|
||||
*/
|
||||
~PSMenu() override;
|
||||
|
||||
/**
|
||||
* Adds a text-based menu item (button) to the menu
|
||||
* @param id Unique identifier for this menu item
|
||||
* @param text Display text shown on the menu
|
||||
* @param callback Function to call when this item is selected
|
||||
*/
|
||||
void addText(uint8_t id, const std::string &text, const ButtonCallback &callback);
|
||||
|
||||
/**
|
||||
* Adds a selection menu item (dropdown/list selection)
|
||||
* @param id Unique identifier for this menu item
|
||||
* @param text Display text/label for the selection
|
||||
* @param value Reference to current selected value (will be modified)
|
||||
* @param values Vector of all available options to choose from
|
||||
* @param callback Function to call when selection changes
|
||||
*/
|
||||
void addSelection(uint8_t id, const std::string &text, std::string &value, const std::vector<std::string>& values,
|
||||
const ButtonCallback &callback);
|
||||
|
||||
/**
|
||||
* Adds a numeric input menu item
|
||||
* @param id Unique identifier for this menu item
|
||||
* @param text Display text/label for the number input
|
||||
* @param value Reference to current numeric value as string (will be modified)
|
||||
* @param callback Function to call when value changes
|
||||
*/
|
||||
void addNumber(uint8_t id, const std::string &text, std::string &value, const ButtonCallback &callback);
|
||||
|
||||
/**
|
||||
* Adds a toggle/checkbox menu item
|
||||
* @param id Unique identifier for this menu item
|
||||
* @param text Display text/label for the toggle
|
||||
* @param selected Current state of the toggle (true = on, false = off)
|
||||
* @param callback Function to call when toggle state changes
|
||||
*/
|
||||
void addToggle(uint8_t id, const std::string &text, bool selected, const ButtonCallback &callback);
|
||||
|
||||
private:
|
||||
/**
|
||||
* Renders the entire menu on screen
|
||||
* Override from Widget base class
|
||||
*/
|
||||
void render() override;
|
||||
|
||||
/**
|
||||
* Handles button press events from the controller/input system
|
||||
* @param button The button that was pressed
|
||||
* Override from Widget base class
|
||||
*/
|
||||
void onButtonClicked(uint8_t button) override;
|
||||
|
||||
// Navigation event handlers
|
||||
/**
|
||||
* Handles down arrow/stick input - moves selection down
|
||||
*/
|
||||
void onPressedDown();
|
||||
|
||||
/**
|
||||
* Handles up arrow/stick input - moves selection up
|
||||
*/
|
||||
void onPressedUp();
|
||||
|
||||
/**
|
||||
* Handles left arrow/stick input - decreases value for current item
|
||||
*/
|
||||
void onPressedLeft() const;
|
||||
|
||||
/**
|
||||
* Handles right arrow/stick input - increases value for current item
|
||||
*/
|
||||
void onPressedRight() const;
|
||||
|
||||
/**
|
||||
* Handles select/confirm button (X on PlayStation controller)
|
||||
*/
|
||||
void onPressedSelect() const;
|
||||
|
||||
/**
|
||||
* Handles back/cancel button (Circle on PlayStation controller)
|
||||
*/
|
||||
void onPressedBack() const;
|
||||
|
||||
// Rendering helper methods
|
||||
/**
|
||||
* Draws the scroll bar indicating position in long menus
|
||||
*/
|
||||
void drawScrollBar() const;
|
||||
|
||||
/**
|
||||
* Draws the selection highlight box around current menu item
|
||||
*/
|
||||
void drawSelectionBox() const;
|
||||
|
||||
/**
|
||||
* Renders an individual menu item widget
|
||||
* @param item Pointer to the menu item to render
|
||||
* @param font Font to use for rendering text
|
||||
* @param x X coordinate for rendering position
|
||||
* @param y Y coordinate for rendering position
|
||||
*/
|
||||
void renderWidget(const MenuItem *item, const uint8_t *font, int x, int y) const;
|
||||
|
||||
// Member variables
|
||||
size_t m_selected_item = 0; ///< Index of currently selected menu item
|
||||
std::vector<MenuItem> m_items; ///< Collection of all menu items
|
||||
menu_options_t *m_options; ///< Pointer to menu configuration options
|
||||
};
|
||||
@@ -1,52 +1,106 @@
|
||||
/**
|
||||
* @file ScrollBar.h
|
||||
* @brief Vertical scrollbar widget for indicating scroll position in long content
|
||||
* @details This header defines the ScrollBar class which provides a visual scrollbar
|
||||
* widget for indicating the current position within scrollable content.
|
||||
* The scrollbar displays a thumb that moves proportionally to represent
|
||||
* the current scroll position and visible area relative to the total content.
|
||||
* @author System Control Team
|
||||
* @date 2025-06-14
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "MenuOptions.h"
|
||||
#include "Widget.h"
|
||||
|
||||
/**
|
||||
* ScrollBar class that represents a vertical scrollbar widget
|
||||
* Inherits from Widget base class and provides scrolling functionality
|
||||
* @class ScrollBar
|
||||
* @brief A vertical scrollbar widget that represents scroll position and range
|
||||
* @details This final class inherits from Widget and provides visual feedback for
|
||||
* scrollable content. It displays a vertical track with a movable thumb
|
||||
* that indicates the current position within a scrollable range. The thumb
|
||||
* size is proportional to the visible area relative to the total content,
|
||||
* and its position reflects the current scroll offset.
|
||||
*
|
||||
* The scrollbar automatically calculates thumb dimensions and position based on
|
||||
* the provided scroll values (current, minimum, maximum). It is designed to be
|
||||
* used alongside scrollable content like menus or lists to provide visual
|
||||
* feedback about scroll state.
|
||||
*
|
||||
* @note This class is marked as final and cannot be inherited from.
|
||||
*
|
||||
* @see Widget
|
||||
* @see menu_options_t
|
||||
*/
|
||||
class ScrollBar final : public Widget
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* Constructor for ScrollBar
|
||||
* @param options Pointer to menu options configuration
|
||||
* @param x X coordinate position of the scrollbar
|
||||
* @param y Y coordinate position of the scrollbar
|
||||
* @param width Width of the scrollbar
|
||||
* @param height Height of the scrollbar
|
||||
* @brief Constructs a ScrollBar with specified position and dimensions
|
||||
* @param options Pointer to menu options configuration structure
|
||||
* @param x X coordinate position of the scrollbar on screen
|
||||
* @param y Y coordinate position of the scrollbar on screen
|
||||
* @param width Width of the scrollbar in pixels
|
||||
* @param height Height of the scrollbar in pixels
|
||||
*
|
||||
* @pre options must not be nullptr and must remain valid for the scrollbar's lifetime
|
||||
* @pre width and height must be greater than 0
|
||||
* @pre x and y must be valid screen coordinates
|
||||
* @post ScrollBar is initialized with the specified geometry and ready for use
|
||||
*
|
||||
* @note The scrollbar does not take ownership of the options structure and
|
||||
* assumes it remains valid throughout the scrollbar's lifetime.
|
||||
*/
|
||||
ScrollBar(const menu_options_t *options, size_t x, size_t y, size_t width, size_t height);
|
||||
|
||||
/**
|
||||
* Renders the scrollbar to the screen
|
||||
* Overrides the base Widget render method
|
||||
* @brief Renders the scrollbar to the screen
|
||||
* @details Overrides the base Widget render method to draw the scrollbar track
|
||||
* and thumb. The appearance is determined by the current scroll state
|
||||
* and the menu options configuration.
|
||||
*
|
||||
* @pre u8g2 display context must be initialized and ready for drawing
|
||||
* @post Scrollbar's visual representation is drawn to the display buffer
|
||||
*
|
||||
* @note This method is called during each frame's render cycle. The scrollbar
|
||||
* track and thumb are drawn based on the current scroll values set by refresh().
|
||||
*/
|
||||
void render() override;
|
||||
|
||||
/**
|
||||
* Updates the scrollbar state with new values
|
||||
* @param value Current scroll position value
|
||||
* @param max Maximum scroll value
|
||||
* @param min Minimum scroll value (default: 0)
|
||||
* @brief Updates the scrollbar state with new scroll values
|
||||
* @param value Current scroll position value (must be between min and max)
|
||||
* @param max Maximum scroll value (total content size)
|
||||
* @param min Minimum scroll value (default: 0, typically the start of content)
|
||||
*
|
||||
* @pre value must be between min and max (inclusive)
|
||||
* @pre max must be greater than or equal to min
|
||||
* @post Scrollbar thumb position and size are recalculated based on new values
|
||||
*
|
||||
* @details This method recalculates the thumb's height and vertical position
|
||||
* based on the provided scroll range and current position. The thumb
|
||||
* height represents the proportion of visible content to total content,
|
||||
* while its position represents the current scroll offset within the range.
|
||||
*
|
||||
* @note Call this method whenever the scroll state changes to keep the
|
||||
* scrollbar visualization synchronized with the actual content position.
|
||||
*/
|
||||
void refresh(size_t value, size_t max, size_t min = 0);
|
||||
|
||||
private:
|
||||
// Position and dimensions
|
||||
size_t m_x; // X coordinate of the scrollbar
|
||||
size_t m_y; // Y coordinate of the scrollbar
|
||||
size_t m_width; // Width of the scrollbar
|
||||
size_t m_height; // Height of the scrollbar
|
||||
size_t m_x; ///< X coordinate of the scrollbar's left edge
|
||||
size_t m_y; ///< Y coordinate of the scrollbar's top edge
|
||||
size_t m_width; ///< Width of the scrollbar track in pixels
|
||||
size_t m_height; ///< Height of the scrollbar track in pixels
|
||||
|
||||
// Scroll state values
|
||||
size_t m_value; // Current scroll position
|
||||
size_t m_max; // Maximum scroll value
|
||||
size_t m_min; // Minimum scroll value
|
||||
size_t m_value; ///< Current scroll position within the range [m_min, m_max]
|
||||
size_t m_max; ///< Maximum scroll value representing the end of content
|
||||
size_t m_min; ///< Minimum scroll value representing the start of content
|
||||
|
||||
// Calculated thumb properties
|
||||
size_t m_thumbHeight; // Height of the scroll thumb
|
||||
size_t m_thumbY; // Y position of the scroll thumb
|
||||
// Calculated thumb properties (updated by refresh())
|
||||
size_t m_thumbHeight; ///< Calculated height of the scroll thumb in pixels
|
||||
size_t m_thumbY; ///< Calculated Y position of the scroll thumb relative to track
|
||||
};
|
||||
@@ -1,52 +1,114 @@
|
||||
/**
|
||||
* @file Widget.h
|
||||
* @brief Base widget class for UI components in the INSA system
|
||||
* @details This header defines the Widget base class that serves as the foundation
|
||||
* for all UI components in the system. It provides a standardized interface
|
||||
* for rendering, updating, and handling user input using the u8g2 graphics library.
|
||||
* @author System Control Team
|
||||
* @date 2025-06-14
|
||||
*/
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "u8g2.h"
|
||||
|
||||
#include "common/Common.h"
|
||||
|
||||
/**
|
||||
* Base class for UI widgets that can be rendered and interact with user input.
|
||||
* This class provides a common interface for all widgets in the system.
|
||||
* @class Widget
|
||||
* @brief Base class for UI widgets that can be rendered and interact with user input
|
||||
* @details This abstract base class provides a common interface for all widgets in the system.
|
||||
* It manages the u8g2 display context and defines the core methods that all widgets
|
||||
* must implement or can override. The class follows the template method pattern,
|
||||
* allowing derived classes to customize behavior while maintaining a consistent
|
||||
* interface for the UI system.
|
||||
*
|
||||
* @note All widgets should inherit from this class to ensure compatibility with
|
||||
* the UI management system.
|
||||
*
|
||||
* @see u8g2_t
|
||||
* @see ButtonType
|
||||
*/
|
||||
class Widget
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* Constructs a widget with the given u8g2 display context.
|
||||
* @param u8g2 Pointer to the u8g2 display context used for rendering
|
||||
* @brief Constructs a widget with the given u8g2 display context
|
||||
* @param u8g2 Pointer to the u8g2 display context used for rendering operations
|
||||
*
|
||||
* @pre u8g2 must not be nullptr
|
||||
* @post Widget is initialized with the provided display context
|
||||
*
|
||||
* @note The widget does not take ownership of the u8g2 context and assumes
|
||||
* it remains valid for the lifetime of the widget.
|
||||
*/
|
||||
explicit Widget(u8g2_t *u8g2);
|
||||
|
||||
/**
|
||||
* Virtual destructor to ensure proper cleanup of derived classes.
|
||||
* @brief Virtual destructor to ensure proper cleanup of derived classes
|
||||
* @details Ensures that derived class destructors are called correctly when
|
||||
* a widget is destroyed through a base class pointer.
|
||||
*/
|
||||
virtual ~Widget() = default;
|
||||
|
||||
/**
|
||||
* Updates the widget's internal state based on elapsed time.
|
||||
* This method is called once per frame to handle animations,
|
||||
* timers, or other time-dependent behavior.
|
||||
* @param dt Delta time in milliseconds since last update
|
||||
* @brief Updates the widget's internal state based on elapsed time
|
||||
* @param dt Delta time in milliseconds since the last update call
|
||||
*
|
||||
* @details This method is called once per frame by the UI system to handle
|
||||
* animations, timers, state transitions, or other time-dependent behavior.
|
||||
* The base implementation is empty, allowing derived classes to override
|
||||
* only if time-based updates are needed.
|
||||
*
|
||||
* @note Override this method in derived classes to implement time-based behavior
|
||||
* such as animations, blinking effects, or timeout handling.
|
||||
*/
|
||||
virtual void update(uint64_t dt);
|
||||
|
||||
/**
|
||||
* Renders the widget to the display.
|
||||
* This method should be overridden by derived classes to implement
|
||||
* their specific rendering logic using the u8g2 display context.
|
||||
* @brief Renders the widget to the display
|
||||
* @details This method should be overridden by derived classes to implement
|
||||
* their specific rendering logic using the u8g2 display context.
|
||||
* The base implementation is empty, requiring derived classes to
|
||||
* provide their own rendering code.
|
||||
*
|
||||
* @pre u8g2 context must be initialized and ready for drawing operations
|
||||
* @post Widget's visual representation is drawn to the display buffer
|
||||
*
|
||||
* @note This method is called during the rendering phase of each frame.
|
||||
* Derived classes should use the u8g2 member variable to perform
|
||||
* drawing operations.
|
||||
*/
|
||||
virtual void render();
|
||||
|
||||
/**
|
||||
* Handles button click events.
|
||||
* This method is called when a button is pressed and allows
|
||||
* the widget to respond to user input.
|
||||
* @param button The identifier of the button that was clicked
|
||||
* @brief Handles button press events
|
||||
* @param button The type of button that was pressed
|
||||
*
|
||||
* @details This method is called when a button press event occurs and allows
|
||||
* the widget to respond to user input. The base implementation is empty,
|
||||
* allowing derived classes to override only if input handling is needed.
|
||||
*
|
||||
* @note Override this method in derived classes to implement button-specific
|
||||
* behavior such as navigation, selection, or state changes.
|
||||
*
|
||||
* @see ButtonType for available button types
|
||||
*/
|
||||
virtual void onButtonClicked(uint8_t button);
|
||||
virtual void onButtonClicked(ButtonType button);
|
||||
|
||||
protected:
|
||||
/**
|
||||
* Pointer to the u8g2 display context used for rendering operations.
|
||||
* This provides access to drawing functions for text, graphics, and other UI elements.
|
||||
* @brief Pointer to the u8g2 display context used for rendering operations
|
||||
* @details This member provides access to the u8g2 graphics library functions
|
||||
* for drawing text, shapes, bitmaps, and other UI elements. It is
|
||||
* initialized during construction and remains valid for the widget's lifetime.
|
||||
*
|
||||
* @note This member is protected to allow derived classes direct access while
|
||||
* preventing external modification. Derived classes should use this
|
||||
* context for all rendering operations.
|
||||
*
|
||||
* @warning Do not modify or delete this pointer. The widget does not own
|
||||
* the u8g2 context and assumes it is managed externally.
|
||||
*/
|
||||
u8g2_t *u8g2;
|
||||
};
|
||||
Reference in New Issue
Block a user