/** * @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" /** * @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: /** * @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); /** * @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; /** * @brief Called when the widget becomes active or enters the foreground * @details This method is invoked when the widget transitions from inactive * to active state, such as when it becomes the current screen or * gains focus. Derived classes can override this method to perform * initialization tasks, reset state, or prepare for user interaction. * * @note The base implementation is empty, allowing derived classes to override * only if entry behavior is needed. * @note This method is typically called by the UI management system during * screen transitions or focus changes. */ virtual void enter(); /** * @brief Called when the widget is temporarily paused or loses focus * @details This method is invoked when the widget needs to suspend its * operations temporarily, such as when another widget takes focus * or the system enters a paused state. Derived classes can override * this method to pause animations, save state, or reduce resource usage. * * @note The base implementation is empty, allowing derived classes to override * only if pause behavior is needed. * @note The widget should be prepared to resume from this state when resume() is called. */ virtual void pause(); /** * @brief Called when the widget resumes from a paused state * @details This method is invoked when the widget transitions from paused * to active state, typically after a previous pause() call. Derived * classes can override this method to restore animations, reload * resources, or continue interrupted operations. * * @note The base implementation is empty, allowing derived classes to override * only if resume behavior is needed. * @note This method should restore the widget to the state it was in before pause() was called. */ virtual void resume(); /** * @brief Called when the widget is being destroyed or exits the system * @details This method is invoked when the widget is about to be removed * from the system or transitions to an inactive state permanently. * Derived classes can override this method to perform cleanup tasks, * save final state, or release resources that are not automatically freed. * * @note The base implementation is empty, allowing derived classes to override * only if exit behavior is needed. * @note This method is called before the widget's destructor and provides * an opportunity for controlled shutdown of widget-specific resources. */ virtual void exit(); /** * @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); /** * @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(); /** * @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(ButtonType button); protected: /** * @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; };