Refactor tray icon event handler setup and cleanup

lijy91 · lijy91 · commit 89e2b1b7ac68 · 2025-10-23T21:33:13.000+08:00
Introduces StartEventListening and StopEventListening methods to manage platform-specific event handler setup and cleanup for tray icons on macOS and Windows. Event handlers and monitoring are now initialized only when listeners are present, improving resource management and preventing unnecessary callbacks after destruction. Property and method names are updated for clarity and consistency.
diff --git a/src/platform/macos/tray_icon_macos.mm b/src/platform/macos/tray_icon_macos.mm
@@ -21,9 +21,9 @@
 static const void* kTrayIconIdKey = &kTrayIconIdKey;
 
 @interface NSStatusBarButtonTarget : NSObject
-@property(nonatomic, copy) TrayIconClickedBlock leftClickedBlock;
-@property(nonatomic, copy) TrayIconRightClickedBlock rightClickedBlock;
-@property(nonatomic, copy) TrayIconDoubleClickedBlock doubleClickedBlock;
+@property(nonatomic, copy) TrayIconClickedBlock left_clicked_callback;
+@property(nonatomic, copy) TrayIconRightClickedBlock right_clicked_callback;
+@property(nonatomic, copy) TrayIconDoubleClickedBlock double_clicked_callback;
 - (void)handleStatusItemEvent:(id)sender;
 @end
 
@@ -37,7 +37,8 @@ - (void)handleStatusItemEvent:(id)sender;
   Impl(NSStatusItem* status_item)
       : ns_status_item_(status_item),
         ns_status_bar_button_target_(nil),
-        menu_closed_listener_id_(0) {
+        menu_closed_listener_id_(0),
+        click_handler_setup_(false) {
     if (status_item) {
       // Check if ID already exists in the associated object
       NSNumber* allocated_id = objc_getAssociatedObject(status_item, kTrayIconIdKey);
@@ -50,16 +51,6 @@ - (void)handleStatusItemEvent:(id)sender;
         objc_setAssociatedObject(status_item, kTrayIconIdKey, [NSNumber numberWithLong:id_],
                                  OBJC_ASSOCIATION_RETAIN_NONATOMIC);
       }
-
-      // Create and set up button target
-      ns_status_bar_button_target_ = [[NSStatusBarButtonTarget alloc] init];
-
-      // Set up event handlers
-      [status_item.button setTarget:ns_status_bar_button_target_];
-      [status_item.button setAction:@selector(handleStatusItemEvent:)];
-
-      // Enable right-click handling
-      [status_item.button sendActionOn:NSEventMaskLeftMouseUp | NSEventMaskRightMouseUp];
     }
   }
 
@@ -70,21 +61,13 @@ - (void)handleStatusItemEvent:(id)sender;
       menu_closed_listener_id_ = 0;
     }
 
-    // Clean up blocks first
-    if (ns_status_bar_button_target_) {
-      ns_status_bar_button_target_.leftClickedBlock = nil;
-      ns_status_bar_button_target_.rightClickedBlock = nil;
-      ns_status_bar_button_target_.doubleClickedBlock = nil;
-      ns_status_bar_button_target_ = nil;
+    // Clean up event handlers if they were set up
+    if (click_handler_setup_) {
+      CleanupEventHandlers();
     }
 
     // Then clean up the status item
     if (ns_status_item_) {
-      // Remove target and action to prevent callbacks after destruction
-      if (ns_status_item_.button) {
-        [ns_status_item_.button setTarget:nil];
-        [ns_status_item_.button setAction:nil];
-      }
       // Clear menu reference
       ns_status_item_.menu = nil;
 
@@ -102,12 +85,57 @@ - (void)handleStatusItemEvent:(id)sender;
     }
   }
 
+  void SetupEventHandlers() {
+    if (click_handler_setup_) {
+      return;  // Already set up
+    }
+
+    if (!ns_status_item_ || !ns_status_item_.button) {
+      return;
+    }
+
+    // Create and set up button target
+    ns_status_bar_button_target_ = [[NSStatusBarButtonTarget alloc] init];
+
+    // Set up event handlers
+    [ns_status_item_.button setTarget:ns_status_bar_button_target_];
+    [ns_status_item_.button setAction:@selector(handleStatusItemEvent:)];
+
+    // Enable right-click handling
+    [ns_status_item_.button sendActionOn:NSEventMaskLeftMouseUp | NSEventMaskRightMouseUp];
+
+    click_handler_setup_ = true;
+  }
+
+  void CleanupEventHandlers() {
+    if (!click_handler_setup_) {
+      return;  // Not set up
+    }
+
+    // Clean up blocks first
+    if (ns_status_bar_button_target_) {
+      ns_status_bar_button_target_.left_clicked_callback = nil;
+      ns_status_bar_button_target_.right_clicked_callback = nil;
+      ns_status_bar_button_target_.double_clicked_callback = nil;
+      ns_status_bar_button_target_ = nil;
+    }
+
+    // Remove target and action to prevent callbacks after destruction
+    if (ns_status_item_ && ns_status_item_.button) {
+      [ns_status_item_.button setTarget:nil];
+      [ns_status_item_.button setAction:nil];
+    }
+
+    click_handler_setup_ = false;
+  }
+
   NSStatusItem* ns_status_item_;
   NSStatusBarButtonTarget* ns_status_bar_button_target_;
 
   TrayIconId id_;
   std::shared_ptr<Menu> context_menu_;
   size_t menu_closed_listener_id_;
+  bool click_handler_setup_;
 };
 
 TrayIcon::TrayIcon() : TrayIcon(nullptr) {}
@@ -126,23 +154,38 @@ - (void)handleStatusItemEvent:(id)sender;
   // Initialize the Impl with the status item
   pimpl_ = std::make_unique<Impl>(status_item);
 
-  // Set up click handlers
+  // Event handlers will be set up automatically when first listener is added
+  // via StartEventListening() override
+}
+
+TrayIcon::~TrayIcon() = default;
+
+void TrayIcon::StartEventListening() {
+  // Called automatically when first listener is added
+  // Set up platform event monitoring
+  pimpl_->SetupEventHandlers();
+
+  // Set up click handler blocks
   if (pimpl_->ns_status_bar_button_target_) {
-    pimpl_->ns_status_bar_button_target_.leftClickedBlock = ^{
+    pimpl_->ns_status_bar_button_target_.left_clicked_callback = ^{
       Emit<TrayIconClickedEvent>(pimpl_->id_);
     };
 
-    pimpl_->ns_status_bar_button_target_.rightClickedBlock = ^{
+    pimpl_->ns_status_bar_button_target_.right_clicked_callback = ^{
       Emit<TrayIconRightClickedEvent>(pimpl_->id_);
     };
 
-    pimpl_->ns_status_bar_button_target_.doubleClickedBlock = ^{
+    pimpl_->ns_status_bar_button_target_.double_clicked_callback = ^{
       Emit<TrayIconDoubleClickedEvent>(pimpl_->id_);
     };
   }
 }
 
-TrayIcon::~TrayIcon() = default;
+void TrayIcon::StopEventListening() {
+  // Called automatically when last listener is removed
+  // Clean up platform event monitoring
+  pimpl_->CleanupEventHandlers();
+}
 
 TrayIconId TrayIcon::GetId() {
   return pimpl_->id_;
@@ -350,18 +393,18 @@ - (void)handleStatusItemEvent:(id)sender {
       (event.type == NSEventTypeLeftMouseUp &&
        (event.modifierFlags & NSEventModifierFlagControl))) {
     // Right click or Ctrl+Left click
-    if (_rightClickedBlock) {
-      _rightClickedBlock();
+    if (_right_clicked_callback) {
+      _right_clicked_callback();
     }
   } else if (event.type == NSEventTypeLeftMouseUp) {
     // Check for double click
     if (event.clickCount == 2) {
-      if (_doubleClickedBlock) {
-        _doubleClickedBlock();
+      if (_double_clicked_callback) {
+        _double_clicked_callback();
       }
     } else {
-      if (_leftClickedBlock) {
-        _leftClickedBlock();
+      if (_left_clicked_callback) {
+        _left_clicked_callback();
       }
     }
   }
diff --git a/src/platform/windows/tray_icon_windows.cpp b/src/platform/windows/tray_icon_windows.cpp
@@ -33,7 +33,7 @@ class TrayIcon::Impl {
   using RightClickedCallback = std::function<void(TrayIconId)>;
   using DoubleClickedCallback = std::function<void(TrayIconId)>;
 
-  Impl() : hwnd_(nullptr), icon_handle_(nullptr) {
+  Impl() : hwnd_(nullptr), icon_handle_(nullptr), window_proc_handle_id_(-1), event_monitoring_setup_(false) {
     tray_icon_id_ = IdAllocator::Allocate<TrayIcon>();
   }
 
@@ -43,9 +43,11 @@ class TrayIcon::Impl {
        DoubleClickedCallback double_clicked_callback)
       : hwnd_(hwnd),
         icon_handle_(nullptr),
+        window_proc_handle_id_(-1),
         clicked_callback_(std::move(clicked_callback)),
         right_clicked_callback_(std::move(right_clicked_callback)),
-        double_clicked_callback_(std::move(double_clicked_callback)) {
+        double_clicked_callback_(std::move(double_clicked_callback)),
+        event_monitoring_setup_(false) {
     tray_icon_id_ = IdAllocator::Allocate<TrayIcon>();
     // Initialize NOTIFYICONDATA structure
     ZeroMemory(&nid_, sizeof(NOTIFYICONDATAW));
@@ -55,16 +57,14 @@ class TrayIcon::Impl {
     nid_.uFlags = NIF_MESSAGE | NIF_ICON | NIF_TIP;
     nid_.uCallbackMessage = WM_USER + 1;  // Custom message for tray icon events
 
-    window_proc_handle_id_ = WindowMessageDispatcher::GetInstance().RegisterHandler(
-        hwnd, [this](HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam) {
-          return HandleWindowProc(hwnd, message, wparam, lparam);
-        });
+    // Event monitoring will be set up when first listener is added
+    // via StartEventListening() override
   }
 
   ~Impl() {
-    // Unregister window procedure handler
-    if (window_proc_handle_id_ != -1) {
-      WindowMessageDispatcher::GetInstance().UnregisterHandler(window_proc_handle_id_);
+    // Clean up event monitoring if it was set up
+    if (event_monitoring_setup_) {
+      CleanupEventMonitoring();
     }
 
     if (hwnd_) {
@@ -105,12 +105,45 @@ class TrayIcon::Impl {
     return std::nullopt;  // Let default window procedure handle it
   }
 
+  void SetupEventMonitoring() {
+    if (event_monitoring_setup_) {
+      return;  // Already set up
+    }
+
+    if (!hwnd_) {
+      return;
+    }
+
+    // Register window procedure handler
+    window_proc_handle_id_ = WindowMessageDispatcher::GetInstance().RegisterHandler(
+        hwnd_, [this](HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam) {
+          return HandleWindowProc(hwnd, message, wparam, lparam);
+        });
+
+    event_monitoring_setup_ = true;
+  }
+
+  void CleanupEventMonitoring() {
+    if (!event_monitoring_setup_) {
+      return;  // Not set up
+    }
+
+    // Unregister window procedure handler
+    if (window_proc_handle_id_ != -1) {
+      WindowMessageDispatcher::GetInstance().UnregisterHandler(window_proc_handle_id_);
+      window_proc_handle_id_ = -1;
+    }
+
+    event_monitoring_setup_ = false;
+  }
+
   int window_proc_handle_id_;
   HWND hwnd_;
   NOTIFYICONDATAW nid_;
   std::shared_ptr<Menu> context_menu_;
   HICON icon_handle_;
   TrayIconId tray_icon_id_;
+  bool event_monitoring_setup_;
 
   // Callback functions for event emission
   ClickedCallback clicked_callback_;
@@ -158,6 +191,18 @@ TrayIcon::TrayIcon(void* native_tray_icon) {
 
 TrayIcon::~TrayIcon() {}
 
+void TrayIcon::StartEventListening() {
+  // Called automatically when first listener is added
+  // Set up platform event monitoring
+  pimpl_->SetupEventMonitoring();
+}
+
+void TrayIcon::StopEventListening() {
+  // Called automatically when last listener is removed
+  // Clean up platform event monitoring
+  pimpl_->CleanupEventMonitoring();
+}
+
 TrayIconId TrayIcon::GetId() {
   return pimpl_->tray_icon_id_;
 }
diff --git a/src/tray_icon.h b/src/tray_icon.h
@@ -333,6 +333,24 @@ class TrayIcon : public EventEmitter<TrayIconEvent>, public NativeObjectProvider
   bool CloseContextMenu();
 
  protected:
+  /**
+   * @brief Called when the first listener is added.
+   *
+   * Subclasses can override this to start platform-specific event monitoring.
+   * This is called automatically by the EventEmitter when transitioning from
+   * 0 to 1+ listeners.
+   */
+  void StartEventListening() override;
+
+  /**
+   * @brief Called when the last listener is removed.
+   *
+   * Subclasses can override this to stop platform-specific event monitoring.
+   * This is called automatically by the EventEmitter when transitioning from
+   * 1+ to 0 listeners.
+   */
+  void StopEventListening() override;
+
   /**
    * @brief Internal method to get the platform-specific native tray icon object.
    *
