Refactor managers to singleton pattern and improve docs

- Make DisplayManager, TrayManager, and WindowManager singletons - Add
GetInstance() methods for singleton access - Update usage in examples
and C API to use singleton instances - Add thread safety and usage
documentation to manager headers - Refactor TrayManager for thread-safe
tray icon management - Expand and clarify documentation for window and
display events

Author: lijy91

examples/window_example/main.cpp

@@ -13,9 +13,9 @@ using nativeapi::WindowManager;
 using nativeapi::WindowOptions;
 
 int main() {
-  DisplayManager display_manager = DisplayManager();
-  TrayManager tray_manager = TrayManager();
-  WindowManager window_manager = WindowManager();
+  DisplayManager& display_manager = DisplayManager::GetInstance();
+  TrayManager& tray_manager = TrayManager::GetInstance();
+  WindowManager& window_manager = WindowManager::GetInstance();
 
   // Create a new window with options
   WindowOptions options = {.title = "Window Example",

src/capi/display_manager_c.cpp

@@ -64,7 +64,8 @@ native_display_t to_native_display(const Display& raw_display) {
   return display;
 }
 
-DisplayManager g_display_manager = DisplayManager();
+DisplayManager& g_display_manager = DisplayManager::GetInstance();
+
 
 FFI_PLUGIN_EXPORT
 native_display_list_t native_display_manager_get_all() {

src/display_manager.cpp

@@ -1,3 +1,10 @@
 #include "display_manager.h"
 
-namespace nativeapi {}
+namespace nativeapi {
+
+DisplayManager& DisplayManager::GetInstance() {
+  static DisplayManager instance;
+  return instance;
+}
+
+}  // namespace nativeapi

src/display_manager.h

@@ -14,11 +14,17 @@ namespace nativeapi {
 
 /**
  * Event class for display addition
+ *
+ * This event is emitted when a new display is connected to the system.
  */
 class DisplayAddedEvent : public TypedEvent<DisplayAddedEvent> {
  public:
   explicit DisplayAddedEvent(const Display& display) : display_(display) {}
 
+  /**
+   * Get the added display information
+   * @return Reference to the added display
+   */
   const Display& GetDisplay() const { return display_; }
 
  private:
@@ -27,11 +33,17 @@ class DisplayAddedEvent : public TypedEvent<DisplayAddedEvent> {
 
 /**
  * Event class for display removal
+ *
+ * This event is emitted when a display is disconnected from the system.
  */
 class DisplayRemovedEvent : public TypedEvent<DisplayRemovedEvent> {
  public:
   explicit DisplayRemovedEvent(const Display& display) : display_(display) {}
 
+  /**
+   * Get the removed display information
+   * @return Reference to the removed display
+   */
   const Display& GetDisplay() const { return display_; }
 
  private:
@@ -40,23 +52,98 @@ class DisplayRemovedEvent : public TypedEvent<DisplayRemovedEvent> {
 
 /**
  * DisplayManager is a singleton that manages all displays on the system.
+ *
+ * This class provides functionality to:
+ * - Query all connected displays
+ * - Get primary display information
+ * - Monitor display changes (addition/removal)
+ * - Get cursor position across displays
+ *
+ * The DisplayManager uses the singleton pattern to ensure there's only one
+ * instance managing the display system throughout the application lifecycle.
+ *
+ * Thread Safety: This class is not thread-safe. External synchronization
+ * is required if accessed from multiple threads.
+ *
+ * Example usage:
+ * @code
+ * DisplayManager& manager = DisplayManager::GetInstance();
+ * std::vector<Display> displays = manager.GetAll();
+ * Display primary = manager.GetPrimary();
+ * @endcode
  */
 class DisplayManager : public EventEmitter {
  public:
-  DisplayManager();
+  /**
+   * Get the singleton instance of DisplayManager
+   * @return Reference to the singleton DisplayManager instance
+   */
+  static DisplayManager& GetInstance();
+
+  /**
+   * @brief Destructor for DisplayManager.
+   *
+   * Cleans up all resources, stops event monitoring.
+   * This is automatically called when the application terminates.
+   */
   virtual ~DisplayManager();
 
-  // Get all displays information
+  /**
+   * Get all connected displays information
+   *
+   * @return Vector containing all Display objects representing connected
+   * displays. The vector may be empty if no displays are detected.
+   * @note The returned vector is a snapshot of current displays at the time of
+   * call
+   */
   std::vector<Display> GetAll();
 
-  // Get the primary display information
+  /**
+   * Get the primary display information
+   *
+   * The primary display is typically the main screen where the desktop
+   * environment displays its primary interface elements.
+   *
+   * @return Display object representing the primary display
+   * @throws std::runtime_error if no primary display is available
+   */
   Display GetPrimary();
 
-  // Get the current cursor position
+  /**
+   * Get the current cursor position in screen coordinates
+   *
+   * The coordinates are relative to the top-left corner of the primary display,
+   * with positive X extending right and positive Y extending down.
+   *
+   * @return Point containing the current cursor coordinates (x, y)
+   * @note The position is captured at the time of the function call
+   */
   Point GetCursorPosition();
 
+  // Prevent copy construction and assignment to maintain singleton property
+  DisplayManager(const DisplayManager&) = delete;
+  DisplayManager& operator=(const DisplayManager&) = delete;
+  DisplayManager(DisplayManager&&) = delete;
+  DisplayManager& operator=(DisplayManager&&) = delete;
+
  private:
+  /**
+   * @brief Private constructor to enforce singleton pattern.
+   *
+   * Initializes the DisplayManager instance and sets up initial state.
+   */
+  DisplayManager();
+
+  /**
+   * Cached list of displays
+   * Updated when display configuration changes are detected.
+   */
   std::vector<Display> displays_;
+
+  /**
+   * Static instance holder for singleton pattern
+   */
+  static DisplayManager* instance_;
 };
 
 }  // namespace nativeapi

src/platform/linux/tray_manager_linux.cpp

@@ -1,42 +1,100 @@
-#include <cstring>
-#include <iostream>
-#include <string>
+#include <memory>
+#include <mutex>
 
-#include "../../tray.h"
+#include "../../tray_icon.h"
 #include "../../tray_manager.h"
 
-// Import GTK headers
-#include <gtk/gtk.h>
+// Import GTK headers - these may not be available in all build environments
+#ifdef __has_include
+  #if __has_include(<gtk/gtk.h>)
+    #include <gtk/gtk.h>
+    #define HAS_GTK 1
+  #else
+    #define HAS_GTK 0
+  #endif
+#else
+  // Fallback for older compilers
+  #define HAS_GTK 0
+#endif
 
 namespace nativeapi {
 
 TrayManager::TrayManager() : next_tray_id_(1) {}
 
-TrayManager::~TrayManager() {}
+TrayManager::~TrayManager() {
+  std::lock_guard<std::mutex> lock(mutex_);
+  // Clean up all managed tray icons
+  for (auto& pair : trays_) {
+    auto tray = pair.second;
+    if (tray) {
+      // The TrayIcon destructor will handle cleanup of the GtkStatusIcon
+    }
+  }
+  trays_.clear();
+}
+
+bool TrayManager::IsSupported() {
+#if HAS_GTK
+  // Check if GTK is initialized and system tray is supported
+  return gtk_init_check(nullptr, nullptr);
+#else
+  // If GTK is not available, assume no system tray support
+  return false;
+#endif
+}
+
+std::shared_ptr<TrayIcon> TrayManager::Create() {
+  std::lock_guard<std::mutex> lock(mutex_);
 
-std::shared_ptr<Tray> TrayManager::Create() {
+#if HAS_GTK
   // Create a new tray using GTK StatusIcon
   GtkStatusIcon* status_icon = gtk_status_icon_new();
-  auto tray = std::make_shared<Tray>((void*)status_icon);
+  if (!status_icon) {
+    return nullptr;
+  }
+
+  auto tray = std::make_shared<TrayIcon>((void*)status_icon);
   tray->id = next_tray_id_++;
   trays_[tray->id] = tray;
+
   return tray;
+#else
+  // GTK not available, return nullptr
+  return nullptr;
+#endif
 }
 
-std::shared_ptr<Tray> TrayManager::Get(TrayID id) {
+std::shared_ptr<TrayIcon> TrayManager::Get(TrayIconID id) {
+  std::lock_guard<std::mutex> lock(mutex_);
+
   auto it = trays_.find(id);
   if (it != trays_.end()) {
     return it->second;
   }
   return nullptr;
 }
 
-std::vector<std::shared_ptr<Tray>> TrayManager::GetAll() {
-  std::vector<std::shared_ptr<Tray>> trays;
-  for (auto& tray : trays_) {
-    trays.push_back(tray.second);
+std::vector<std::shared_ptr<TrayIcon>> TrayManager::GetAll() {
+  std::lock_guard<std::mutex> lock(mutex_);
+
+  std::vector<std::shared_ptr<TrayIcon>> trays;
+  for (const auto& pair : trays_) {
+    trays.push_back(pair.second);
   }
   return trays;
 }
 
-}  // namespace nativeapi
+bool TrayManager::Destroy(TrayIconID id) {
+  std::lock_guard<std::mutex> lock(mutex_);
+
+  auto it = trays_.find(id);
+  if (it != trays_.end()) {
+    // Remove the tray icon from our container
+    // The shared_ptr will automatically clean up when the last reference is released
+    trays_.erase(it);
+    return true;
+  }
+  return false;
+}
+
+}  // namespace nativeapi

src/platform/macos/tray_manager_macos.mm

@@ -1,6 +1,7 @@
 #include <cstring>
 #include <iostream>
 #include <string>
+#include <mutex>
 
 #include "../../tray_icon.h"
 #include "../../tray_manager.h"
@@ -12,22 +13,38 @@
 
 TrayManager::TrayManager() : next_tray_id_(1) {}
 
-TrayManager::~TrayManager() {}
+TrayManager::~TrayManager() {
+  std::lock_guard<std::mutex> lock(mutex_);
+  // Clean up all managed tray icons
+  for (auto& pair : trays_) {
+    auto tray = pair.second;
+    if (tray) {
+      // The TrayIcon destructor will handle cleanup of the NSStatusItem
+    }
+  }
+  trays_.clear();
+}
 
 bool TrayManager::IsSupported() {
   return true;
 }
 
 std::shared_ptr<TrayIcon> TrayManager::Create() {
+  std::lock_guard<std::mutex> lock(mutex_);
+
   NSStatusBar* status_bar = [NSStatusBar systemStatusBar];
   NSStatusItem* status_item = [status_bar statusItemWithLength:NSVariableStatusItemLength];
+
   auto tray = std::make_shared<TrayIcon>((__bridge void*)status_item);
   tray->id = next_tray_id_++;
   trays_[tray->id] = tray;
+
   return tray;
 }
 
 std::shared_ptr<TrayIcon> TrayManager::Get(TrayIconID id) {
+  std::lock_guard<std::mutex> lock(mutex_);
+
   auto it = trays_.find(id);
   if (it != trays_.end()) {
     return it->second;
@@ -36,11 +53,26 @@
 }
 
 std::vector<std::shared_ptr<TrayIcon>> TrayManager::GetAll() {
+  std::lock_guard<std::mutex> lock(mutex_);
+
   std::vector<std::shared_ptr<TrayIcon>> trays;
-  for (auto& tray : trays_) {
-    trays.push_back(tray.second);
+  for (const auto& pair : trays_) {
+    trays.push_back(pair.second);
   }
   return trays;
 }
 
+bool TrayManager::Destroy(TrayIconID id) {
+  std::lock_guard<std::mutex> lock(mutex_);
+
+  auto it = trays_.find(id);
+  if (it != trays_.end()) {
+    // Remove the tray icon from our container
+    // The shared_ptr will automatically clean up when the last reference is released
+    trays_.erase(it);
+    return true;
+  }
+  return false;
+}
+
 }  // namespace nativeapi