Squash of branch setup

main/ui/ui_app.h

@@ -0,0 +1,98 @@
+#pragma once
+
+#include "lvgl.h"
+#include "esp_err.h"
+#include <string>
+
+/**
+ * @brief Base class for all UI applications
+ *
+ * All UI applications (apps) must inherit from this class.
+ * Each app is responsible for managing its own widgets within
+ * the provided LVGL container. The UIHandler will manage the
+ * lifecycle of apps and event routing.
+ */
+class UIApp {
+public:
+  virtual ~UIApp() = default;
+
+  /**
+   * @brief Initialize the app with the given container
+   *
+   * The app should create all its widgets as children of the
+   * provided container. The container is already positioned
+   * between the header and navigation bar.
+   *
+   * @param container LVGL container object for this app
+   * @return ESP_OK on success, error code otherwise
+   */
+  virtual esp_err_t init(lv_obj_t* container) = 0;
+
+  /**
+   * @brief Deinitialize and clean up app resources
+   *
+   * The app should delete all widgets and release any resources.
+   * The container itself will be handled by UIHandler.
+   *
+   * @return ESP_OK on success, error code otherwise
+   */
+  virtual esp_err_t deinit(void) = 0;
+
+  /**
+   * @brief Get the display name of this app
+   *
+   * Used for logging and potentially showing in navigation.
+   *
+   * @return std::string app name
+   */
+  virtual std::string get_name(void) const = 0;
+
+  /**
+   * @brief Handle system events passed from UIHandler
+   *
+   * System events include network status changes, storage ready,
+   * display refresh, and other system-level events.
+   *
+   * @param event_type Type/ID of the event
+   * @param event_data Optional event data payload
+   */
+  virtual void handle_event(uint32_t event_type, void* event_data = nullptr) { }
+
+  virtual bool on_back_button_pressed(void) {
+    return false; // default: not handled
+  }
+
+  /**
+   * @brief Get the app's root container
+   *
+   * @return lv_obj_t* pointer to the app's container
+   */
+  lv_obj_t* get_container(void) const {
+    return _container;
+  }
+
+protected:
+  lv_obj_t* _container = nullptr;  ///< LVGL container provided by UIHandler
+};
+
+
+class AppDescriptor {
+public:
+  virtual ~AppDescriptor() = default;
+  virtual void draw_icon(lv_obj_t* parent) = 0;
+
+  std::string get_name() const {
+    return _name;
+  }
+
+  UIApp* get_app_instance() const {
+    return _app_instance;
+  }
+
+protected:
+  AppDescriptor(std::string name, UIApp* app_instance)
+    : _name(name), _app_instance(app_instance) { }
+
+  std::string _name;
+  UIApp* _app_instance;
+};