Add context menu trigger support for tray icons

Introduces the ContextMenuTrigger enum and related logic to control how tray icon context menus are triggered (manual, left click, right click, double click). Updates bindings and UI to allow configuration and propagation of the trigger mode, improving flexibility for different desktop environments.

Author: lijy91

examples/tray_icon_example/lib/main.dart

@@ -16,6 +16,7 @@ class TrayIconData {
   bool isVisible;
   String title;
   String tooltip;
+  ContextMenuTrigger contextMenuTrigger;
   AnimatedIconGenerator? animatedIconGenerator;
 
   TrayIconData({
@@ -28,6 +29,7 @@ class TrayIconData {
     this.isVisible = true,
     this.title = '',
     this.tooltip = '',
+    this.contextMenuTrigger = ContextMenuTrigger.none,
   });
 
   void dispose() {
@@ -149,6 +151,7 @@ class _TrayIconExamplePageState extends State<TrayIconExamplePage> {
       // trayIcon.title = trayIconData.title; // Set via UI
       // trayIcon.tooltip = trayIconData.tooltip; // Set via UI
       trayIcon.isVisible = trayIconData.isVisible;
+      trayIcon.contextMenuTrigger = trayIconData.contextMenuTrigger;
 
       _trayIcons.add(trayIconData);
 
@@ -300,6 +303,30 @@ class _TrayIconExamplePageState extends State<TrayIconExamplePage> {
     _addToHistory('Tooltip updated for tray icon $id: $tooltip');
   }
 
+  void _updateTrayIconContextMenuTrigger(int id, ContextMenuTrigger trigger) {
+    final trayIconData = _trayIcons.firstWhere(
+      (trayIconData) => trayIconData.id == id,
+      orElse: () => throw Exception('Tray icon not found'),
+    );
+    trayIconData.trayIcon.contextMenuTrigger = trigger;
+    trayIconData.contextMenuTrigger = trigger;
+    final triggerName = _getTriggerName(trigger);
+    _addToHistory('Context menu trigger updated for tray icon $id: $triggerName');
+  }
+
+  String _getTriggerName(ContextMenuTrigger trigger) {
+    switch (trigger) {
+      case ContextMenuTrigger.none:
+        return 'None (Manual)';
+      case ContextMenuTrigger.clicked:
+        return 'Left Click';
+      case ContextMenuTrigger.rightClicked:
+        return 'Right Click';
+      case ContextMenuTrigger.doubleClicked:
+        return 'Double Click';
+    }
+  }
+
   void _toggleTrayIconVisibility(int id) {
     final trayIconData = _trayIcons.firstWhere(
       (trayIconData) => trayIconData.id == id,
@@ -834,6 +861,73 @@ class _TrayIconExamplePageState extends State<TrayIconExamplePage> {
             ),
             const SizedBox(height: 12),
 
+            // Context Menu Trigger Section
+            const Text(
+              'Context Menu Trigger',
+              style: TextStyle(fontSize: 12, fontWeight: FontWeight.bold, color: Colors.grey),
+            ),
+            const SizedBox(height: 8),
+            Container(
+              decoration: BoxDecoration(
+                border: Border.all(color: Colors.grey.shade400),
+                borderRadius: BorderRadius.circular(4),
+              ),
+              padding: const EdgeInsets.symmetric(horizontal: 12),
+              child: DropdownButton<ContextMenuTrigger>(
+                value: trayIconData.contextMenuTrigger,
+                isExpanded: true,
+                underline: const SizedBox(),
+                items: [
+                  DropdownMenuItem(
+                    value: ContextMenuTrigger.none,
+                    child: Row(
+                      children: [
+                        const Icon(Icons.touch_app, size: 16),
+                        const SizedBox(width: 8),
+                        const Text('None (Manual)'),
+                      ],
+                    ),
+                  ),
+                  DropdownMenuItem(
+                    value: ContextMenuTrigger.clicked,
+                    child: Row(
+                      children: [
+                        const Icon(Icons.mouse, size: 16),
+                        const SizedBox(width: 8),
+                        const Text('Left Click'),
+                      ],
+                    ),
+                  ),
+                  DropdownMenuItem(
+                    value: ContextMenuTrigger.rightClicked,
+                    child: Row(
+                      children: [
+                        const Icon(Icons.mouse_outlined, size: 16),
+                        const SizedBox(width: 8),
+                        const Text('Right Click'),
+                      ],
+                    ),
+                  ),
+                  DropdownMenuItem(
+                    value: ContextMenuTrigger.doubleClicked,
+                    child: Row(
+                      children: [
+                        const Icon(Icons.double_arrow, size: 16),
+                        const SizedBox(width: 8),
+                        const Text('Double Click'),
+                      ],
+                    ),
+                  ),
+                ],
+                onChanged: (value) {
+                  if (value != null) {
+                    _updateTrayIconContextMenuTrigger(trayIconData.id, value);
+                  }
+                },
+              ),
+            ),
+            const SizedBox(height: 12),
+            
             // Icon Management Section
             const Text(
               'Icon Management',

packages/cnativeapi/lib/src/bindings_generated.dart

@@ -3128,6 +3128,45 @@ class CNativeApiBindings {
       _native_tray_icon_get_context_menuPtr
           .asFunction<native_menu_t Function(native_tray_icon_t)>();
 
+  /// Set the context menu trigger behavior
+  /// @param tray_icon The tray icon
+  /// @param trigger The desired trigger behavior
+  void native_tray_icon_set_context_menu_trigger(
+    native_tray_icon_t tray_icon,
+    native_context_menu_trigger_t trigger,
+  ) {
+    return _native_tray_icon_set_context_menu_trigger(tray_icon, trigger.value);
+  }
+
+  late final _native_tray_icon_set_context_menu_triggerPtr =
+      _lookup<
+        ffi.NativeFunction<
+          ffi.Void Function(native_tray_icon_t, ffi.UnsignedInt)
+        >
+      >('native_tray_icon_set_context_menu_trigger');
+  late final _native_tray_icon_set_context_menu_trigger =
+      _native_tray_icon_set_context_menu_triggerPtr
+          .asFunction<void Function(native_tray_icon_t, int)>();
+
+  /// Get the current context menu trigger behavior
+  /// @param tray_icon The tray icon
+  /// @return The current trigger behavior
+  native_context_menu_trigger_t native_tray_icon_get_context_menu_trigger(
+    native_tray_icon_t tray_icon,
+  ) {
+    return native_context_menu_trigger_t.fromValue(
+      _native_tray_icon_get_context_menu_trigger(tray_icon),
+    );
+  }
+
+  late final _native_tray_icon_get_context_menu_triggerPtr =
+      _lookup<ffi.NativeFunction<ffi.UnsignedInt Function(native_tray_icon_t)>>(
+        'native_tray_icon_get_context_menu_trigger',
+      );
+  late final _native_tray_icon_get_context_menu_trigger =
+      _native_tray_icon_get_context_menu_triggerPtr
+          .asFunction<int Function(native_tray_icon_t)>();
+
   /// Get the screen bounds of the tray icon
   /// @param tray_icon The tray icon
   /// @param bounds Pointer to store the bounds (caller allocated)
@@ -3913,6 +3952,35 @@ enum native_tray_icon_event_type_t {
   };
 }
 
+/// Context menu trigger modes
+/// Defines how the context menu is triggered for a tray icon
+enum native_context_menu_trigger_t {
+  /// Manual control only
+  NATIVE_CONTEXT_MENU_TRIGGER_NONE(0),
+
+  /// Left click triggers menu
+  NATIVE_CONTEXT_MENU_TRIGGER_CLICKED(1),
+
+  /// Right click triggers menu
+  NATIVE_CONTEXT_MENU_TRIGGER_RIGHT_CLICKED(2),
+
+  /// Double click triggers menu
+  NATIVE_CONTEXT_MENU_TRIGGER_DOUBLE_CLICKED(3);
+
+  final int value;
+  const native_context_menu_trigger_t(this.value);
+
+  static native_context_menu_trigger_t fromValue(int value) => switch (value) {
+    0 => NATIVE_CONTEXT_MENU_TRIGGER_NONE,
+    1 => NATIVE_CONTEXT_MENU_TRIGGER_CLICKED,
+    2 => NATIVE_CONTEXT_MENU_TRIGGER_RIGHT_CLICKED,
+    3 => NATIVE_CONTEXT_MENU_TRIGGER_DOUBLE_CLICKED,
+    _ => throw ArgumentError(
+      "Unknown value for native_context_menu_trigger_t: $value",
+    ),
+  };
+}
+
 /// Opaque handle for tray icon objects
 typedef native_tray_icon_t = ffi.Pointer<ffi.Void>;
 

packages/cnativeapi/src/libnativeapi

@@ -9,6 +9,71 @@ import 'package:nativeapi/src/image.dart';
 import 'package:nativeapi/src/menu.dart';
 import 'package:nativeapi/src/tray_icon_event.dart';
 
+/// Defines how the context menu is triggered for a tray icon.
+///
+/// This enum specifies which mouse interactions should display the tray icon's
+/// context menu. The values align with tray icon event types for consistency.
+enum ContextMenuTrigger {
+  /// Context menu is not automatically triggered by mouse events.
+  ///
+  /// The application must call [TrayIcon.openContextMenu] explicitly to display
+  /// the menu. Use this when you want full control over when the menu appears.
+  none,
+
+  /// Context menu is triggered on [TrayIconClickedEvent].
+  ///
+  /// Automatically opens the context menu when the tray icon is left-clicked.
+  /// This is common on some Linux desktop environments.
+  clicked,
+
+  /// Context menu is triggered on [TrayIconRightClickedEvent].
+  ///
+  /// Automatically opens the context menu when the tray icon is right-clicked.
+  /// This follows the convention on Windows and most desktop environments.
+  rightClicked,
+
+  /// Context menu is triggered on [TrayIconDoubleClickedEvent].
+  ///
+  /// Automatically opens the context menu when the tray icon is double-clicked.
+  /// Less common but useful for applications that use single-click for another action.
+  doubleClicked,
+}
+
+/// Extension methods for ContextMenuTrigger conversion
+extension ContextMenuTriggerExtension on ContextMenuTrigger {
+  /// Convert this ContextMenuTrigger to a native enum value.
+  native_context_menu_trigger_t toNative() {
+    switch (this) {
+      case ContextMenuTrigger.none:
+        return native_context_menu_trigger_t.NATIVE_CONTEXT_MENU_TRIGGER_NONE;
+      case ContextMenuTrigger.clicked:
+        return native_context_menu_trigger_t.NATIVE_CONTEXT_MENU_TRIGGER_CLICKED;
+      case ContextMenuTrigger.rightClicked:
+        return native_context_menu_trigger_t
+            .NATIVE_CONTEXT_MENU_TRIGGER_RIGHT_CLICKED;
+      case ContextMenuTrigger.doubleClicked:
+        return native_context_menu_trigger_t
+            .NATIVE_CONTEXT_MENU_TRIGGER_DOUBLE_CLICKED;
+    }
+  }
+
+  /// Convert a native enum value to ContextMenuTrigger.
+  static ContextMenuTrigger fromNative(native_context_menu_trigger_t native) {
+    switch (native) {
+      case native_context_menu_trigger_t.NATIVE_CONTEXT_MENU_TRIGGER_NONE:
+        return ContextMenuTrigger.none;
+      case native_context_menu_trigger_t.NATIVE_CONTEXT_MENU_TRIGGER_CLICKED:
+        return ContextMenuTrigger.clicked;
+      case native_context_menu_trigger_t
+            .NATIVE_CONTEXT_MENU_TRIGGER_RIGHT_CLICKED:
+        return ContextMenuTrigger.rightClicked;
+      case native_context_menu_trigger_t
+            .NATIVE_CONTEXT_MENU_TRIGGER_DOUBLE_CLICKED:
+        return ContextMenuTrigger.doubleClicked;
+    }
+  }
+}
+
 class TrayIcon
     with EventEmitter, CNativeApiBindingsMixin
     implements NativeHandleWrapper<native_tray_icon_t> {
@@ -220,6 +285,48 @@ class TrayIcon
     );
   }
 
+  /// Get the current context menu trigger behavior.
+  ///
+  /// Returns the current [ContextMenuTrigger] setting that determines
+  /// which mouse interactions will automatically display the context menu.
+  ContextMenuTrigger get contextMenuTrigger {
+    final native = bindings.native_tray_icon_get_context_menu_trigger(
+      _nativeHandle,
+    );
+    return ContextMenuTriggerExtension.fromNative(native);
+  }
+
+  /// Set the context menu trigger behavior.
+  ///
+  /// Determines which mouse interactions will automatically display the
+  /// context menu. By default, the trigger is set to [ContextMenuTrigger.none],
+  /// requiring explicit control via [openContextMenu] or by setting a trigger mode.
+  ///
+  /// Example:
+  /// ```dart
+  /// // Right click shows menu (common on Windows/Linux)
+  /// trayIcon.contextMenuTrigger = ContextMenuTrigger.rightClicked;
+  ///
+  /// // Left click shows menu (common on some Linux environments and macOS)
+  /// trayIcon.contextMenuTrigger = ContextMenuTrigger.clicked;
+  ///
+  /// // Double click shows menu
+  /// trayIcon.contextMenuTrigger = ContextMenuTrigger.doubleClicked;
+  ///
+  /// // Manual control (default) - handle events yourself
+  /// trayIcon.contextMenuTrigger = ContextMenuTrigger.none;
+  /// trayIcon.addListener<TrayIconRightClickedEvent>((event) {
+  ///   // Custom logic before showing menu
+  ///   trayIcon.openContextMenu();
+  /// });
+  /// ```
+  set contextMenuTrigger(ContextMenuTrigger trigger) {
+    bindings.native_tray_icon_set_context_menu_trigger(
+      _nativeHandle,
+      trigger.toNative(),
+    );
+  }
+
   Rect? get bounds {
     final boundsPtr = ffi.calloc<native_rectangle_t>();
     final success = bindings.native_tray_icon_get_bounds(