Add event listening lifecycle hooks to EventEmitter

Introduces StartEventListening() and StopEventListening() virtual hooks to EventEmitter, called automatically when the first listener is added and the last is removed. This enables lazy initialization and cleanup of platform-specific event monitoring, improving resource efficiency and simplifying management for subclasses.

Author: lijy91

.cursor/rules/event-system.mdc

@@ -150,3 +150,188 @@ emitter.AddListener<WindowEvent>([](const WindowEvent& event) {
     }
 });
 ```
+
+### Event Listening Lifecycle Management
+
+Managers can efficiently manage platform-specific event monitoring by overriding `StartEventListening()` and `StopEventListening()` hooks. These hooks are automatically called when the first listener is added and when the last listener is removed, respectively.
+
+#### Purpose
+
+This pattern allows managers to:
+- **Lazy initialization** - Only start platform event monitoring when needed
+- **Resource efficiency** - Stop monitoring when no listeners exist
+- **Automatic management** - No manual tracking of listener count required
+
+#### Implementation Pattern
+
+```cpp
+// tray_icon.h
+class TrayIcon : public EventEmitter<TrayIconEvent>, public NativeObjectProvider {
+public:
+    TrayIcon();
+    virtual ~TrayIcon();
+    
+    // ... public API ...
+
+protected:
+    // Override these to control platform event monitoring
+    void StartEventListening() override;
+    void StopEventListening() override;
+
+private:
+    class Impl;
+    std::unique_ptr<Impl> pimpl_;
+};
+
+// tray_icon.cpp
+TrayIcon::TrayIcon() : pimpl_(std::make_unique<Impl>()) {
+    // DON'T call SetupEventMonitoring() here anymore!
+    // It will be called automatically when first listener is added
+}
+
+void TrayIcon::StartEventListening() {
+    // Called automatically when first listener is added
+    pimpl_->SetupEventMonitoring();
+}
+
+void TrayIcon::StopEventListening() {
+    // Called automatically when last listener is removed
+    pimpl_->CleanupEventMonitoring();
+}
+```
+
+#### Platform Implementation Example
+
+```objc
+// platform/macos/tray_icon_macos.mm
+class TrayIcon::Impl {
+public:
+    Impl(NSStatusItem* status_item) 
+        : ns_status_item_(status_item), 
+          ns_status_bar_button_target_(nil),
+          click_handler_setup_(false) {}
+    
+    void SetupEventMonitoring() {
+        if (click_handler_setup_) {
+            return;  // Already monitoring
+        }
+        
+        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 click handling
+        [ns_status_item_.button sendActionOn:NSEventMaskLeftMouseUp | NSEventMaskRightMouseUp];
+        
+        click_handler_setup_ = true;
+    }
+    
+    void CleanupEventMonitoring() {
+        if (!click_handler_setup_) {
+            return;  // Not monitoring
+        }
+        
+        // Remove event handlers
+        if (ns_status_item_ && ns_status_item_.button) {
+            [ns_status_item_.button setTarget:nil];
+            [ns_status_item_.button setAction:nil];
+        }
+        
+        // Clean up button target
+        ns_status_bar_button_target_ = nil;
+        
+        click_handler_setup_ = false;
+    }
+
+private:
+    NSStatusItem* ns_status_item_;
+    NSStatusBarButtonTarget* ns_status_bar_button_target_;
+    bool click_handler_setup_;
+};
+```
+
+#### Usage Flow
+
+```cpp
+// Application code
+auto tray_icon = std::make_shared<TrayIcon>();
+tray_icon->SetIcon(icon);
+tray_icon->SetTooltip("My Application");
+
+// At this point, NO platform event monitoring is active
+// (saves system resources)
+
+// Add first listener - triggers StartEventListening()
+auto listener_id = tray_icon->AddListener<TrayIconClickedEvent>(
+    [](const TrayIconClickedEvent& event) {
+        std::cout << "Tray icon clicked: " << event.GetTrayIconId() << std::endl;
+    }
+);
+
+// Platform event monitoring is now ACTIVE
+
+// Add more listeners - StartEventListening() NOT called again
+auto right_click_id = tray_icon->AddListener<TrayIconRightClickedEvent>(
+    [](const TrayIconRightClickedEvent& event) {
+        std::cout << "Tray icon right clicked" << std::endl;
+    }
+);
+
+// Remove one listener - StopEventListening() NOT called (still have listeners)
+tray_icon->RemoveListener(right_click_id);
+
+// Remove last listener - triggers StopEventListening()
+tray_icon->RemoveListener(listener_id);
+
+// Platform event monitoring is now STOPPED
+// (saves system resources again)
+```
+
+#### Important Considerations
+
+1. **Mutex Held**: `StartEventListening()` and `StopEventListening()` are called while holding `listeners_mutex_`. Keep the implementation fast and avoid acquiring other locks that could cause deadlocks.
+
+2. **Default Implementation**: The default implementations are empty, so existing subclasses don't need to change unless they want to use this feature.
+
+3. **Transitional Calls**: These methods are only called on transitions (0 → 1+ listeners and 1+ → 0 listeners), not on every add/remove operation.
+
+4. **Destructor Cleanup**: If the emitter is destroyed while listeners exist, `StopEventListening()` is NOT called. Clean up resources in the destructor if needed.
+
+5. **Idempotent Operations**: Implement setup/cleanup methods to be safe to call multiple times without side effects.
+
+#### Migration from Old Pattern
+
+##### Before (Always Monitoring)
+
+```cpp
+TrayIcon::TrayIcon() : pimpl_(std::make_unique<Impl>()) {
+    SetupEventMonitoring();  // Always monitoring
+}
+
+TrayIcon::~TrayIcon() {
+    CleanupEventMonitoring();
+}
+```
+
+##### After (Lazy Monitoring)
+
+```cpp
+TrayIcon::TrayIcon() : pimpl_(std::make_unique<Impl>()) {
+    // No need to call SetupEventMonitoring()
+}
+
+void TrayIcon::StartEventListening() {
+    pimpl_->SetupEventMonitoring();  // Called when first listener added
+}
+
+void TrayIcon::StopEventListening() {
+    pimpl_->CleanupEventMonitoring();  // Called when last listener removed
+}
+```

src/foundation/event_emitter.h

@@ -154,6 +154,17 @@ class EventEmitter {
 
       if (it != listeners.end()) {
         listeners.erase(it);
+
+        // Clean up empty vector
+        if (listeners.empty()) {
+          listeners_.erase(type);
+        }
+
+        // Check if this was the last listener
+        if (GetTotalListenerCountUnlocked() == 0) {
+          StopEventListening();
+        }
+
         return true;
       }
     }
@@ -177,7 +188,14 @@ class EventEmitter {
    */
   void RemoveAllListeners() {
     std::lock_guard<std::mutex> lock(listeners_mutex_);
+
+    bool had_listeners = GetTotalListenerCountUnlocked() > 0;
+
     listeners_.clear();
+
+    if (had_listeners) {
+      StopEventListening();
+    }
   }
 
   /**
@@ -196,13 +214,7 @@ class EventEmitter {
    */
   size_t GetTotalListenerCount() const {
     std::lock_guard<std::mutex> lock(listeners_mutex_);
-
-    size_t count = 0;
-    for (const auto& [type, listeners] : listeners_) {
-      count += listeners.size();
-    }
-
-    return count;
+    return GetTotalListenerCountUnlocked();
   }
 
   /**
@@ -292,6 +304,20 @@ class EventEmitter {
   }
 
  protected:
+  /**
+   * Called when the first listener is added.
+   * Subclasses can override this to start platform-specific event monitoring.
+   * This is called while holding the listeners_mutex_ lock.
+   */
+  virtual void StartEventListening() {}
+
+  /**
+   * Called when the last listener is removed.
+   * Subclasses can override this to stop platform-specific event monitoring.
+   * This is called while holding the listeners_mutex_ lock.
+   */
+  virtual void StopEventListening() {}
+
   /**
    * Emit an event synchronously using perfect forwarding.
    * This creates the event object and emits it immediately.
@@ -356,9 +382,15 @@ class EventEmitter {
   size_t AddListener(std::type_index event_type, std::unique_ptr<EventListenerBase> listener) {
     std::lock_guard<std::mutex> lock(listeners_mutex_);
 
+    bool was_empty = GetTotalListenerCountUnlocked() == 0;
+
     size_t listener_id = next_listener_id_.fetch_add(1);
     listeners_[event_type].push_back({std::move(listener), listener_id});
 
+    if (was_empty) {
+      StartEventListening();
+    }
+
     return listener_id;
   }
 
@@ -368,6 +400,11 @@ class EventEmitter {
     auto it = listeners_.find(event_type);
     if (it != listeners_.end()) {
       listeners_.erase(it);
+
+      // Check if this was the last listener
+      if (GetTotalListenerCountUnlocked() == 0) {
+        StopEventListening();
+      }
     }
   }
 
@@ -382,6 +419,14 @@ class EventEmitter {
     return 0;
   }
 
+  size_t GetTotalListenerCountUnlocked() const {
+    size_t count = 0;
+    for (const auto& [type, listeners] : listeners_) {
+      count += listeners.size();
+    }
+    return count;
+  }
+
   // Background thread function for processing async events
   void ProcessAsyncEvents() {
     while (true) {