flutter_tray_icon_example: popup mode, and the Omarchy theme's colour for Auto

Properties -> Popup (or TRAY_POPUP=1) makes the window behave like a tray utility's: no
title bar, a click on the icon shows it or hides it, losing the focus hides it. On
Wayland the compositor places it; the README gives the Hyprland window rule that puts
it under the icon, and tools/gui/flutter_tray_popup_test_hyprland.py checks the whole
sequence with a real click in Omarchy's bar. On Omarchy the Auto icon colour is the
desktop theme's foreground and follows a theme switch.

tools/gui/README.md also lists core's window_shadow_remap_linux_test.

Author: lijy91

examples/flutter_tray_icon_example/README.md

@@ -53,7 +53,46 @@ What a platform cannot do is not offered, and its checklist items step aside:
 
 macOS shows tray images as 18 pt templates, so there the colour row only changes the
 preview's alpha shape and the menu bar picks the tint; resolution still matters (1x / 2x
-/ 3x pixels for the same 18 pt).
+/ 3x pixels for the same 18 pt). On Omarchy the *Auto* colour is the desktop theme's
+foreground, like the bar's own icons, and follows a theme switch; since the asset
+still is a fixed white image, an icon showing it switches to the drawn star there.
+
+## Popup mode
+
+*Properties → Popup* (or `TRAY_POPUP=1` in the environment) makes the window behave like
+a tray utility's: no title bar, a click on the icon shows it, a click while it shows
+hides it, and losing the focus hides it (`WindowBlurredEvent` → `hide()`). Every show is
+a fresh `show()` after a `hide()`, not a raise.
+
+Where the window appears is the platform's business. On macOS and Windows *Window to
+icon* places it next to the icon from `getBounds`. On Wayland the app can neither read
+the icon's position nor place its own window, so the compositor has to do it. On
+Hyprland (0.56+, Lua config) a window rule evaluated when the window maps does — the
+cursor is still on the icon at that moment:
+
+```lua
+-- ~/.config/hypr/hyprland.lua: right edge 20 px right of the click, top 20 px below it
+hl.window_rule({
+  match = { class = "^com\\.example\\.tray_icon_example$" },
+  float = true,
+  pin = true,
+  no_anim = true,
+  move = { "(cursor_x-window_w+20)", "(cursor_y+20)" },
+})
+```
+
+The example sizes the window itself (400 × 640), so the rule needs no `size`. Static
+rules run once per map, which is why popup mode hides the window instead of
+lowering it. `tools/gui/flutter_tray_popup_test_hyprland.py` installs this rule for a run
+and checks the whole sequence with a real click in Omarchy's bar.
+
+What it looks like there: about 150 ms from the click to the first frame, which is
+already the final layout. With a title bar it would re-lay out once more: Hyprland
+reports every toplevel as tiled and maximized, floating or not, so that it draws no
+client-side shadow, and GTK maps a decorated window with its CSD shadow margins first
+and drops them when those states arrive. Without the title bar core suppresses GTK's
+decoration margin as well, and never adds its own shadow gutter before the compositor
+has answered (`core/tests/window_shadow_remap_linux_test.cpp`).
 
 ## Files
 

examples/flutter_tray_icon_example/lib/checklist.dart

@@ -71,6 +71,11 @@ class Checklist extends ChangeNotifier {
     CheckItem('m.still', 'Icon swaps: asset, drawn, base64', manual: true),
     CheckItem('m.animation', 'Tray animation matches preview', manual: true),
     CheckItem('m.three', 'Three icons animate at once', manual: true),
+    CheckItem(
+      'm.popup',
+      'Popup: a click shows the window, losing focus hides it',
+      manual: true,
+    ),
     if (!Platform.isWindows)
       CheckItem(
         'm.title',

examples/flutter_tray_icon_example/lib/tabs/animate_tab.dart

@@ -137,10 +137,9 @@ class _AnimateTabState extends State<AnimateTab>
               for (final MapEntry(:key, :value) in _colors.entries)
                 OptionChip(
                   label: key,
-                  selected:
-                      animator.color == (value ?? TrayController.autoColor),
+                  selected: animator.color == (value ?? controller.autoColor),
                   onTap: () =>
-                      controller.setColor(value ?? TrayController.autoColor),
+                      controller.setColor(value ?? controller.autoColor),
                 ),
               if (Platform.isMacOS) const Hint('macOS tints it itself'),
             ],

examples/flutter_tray_icon_example/lib/tabs/properties_tab.dart

@@ -118,6 +118,21 @@ class PropertiesTab extends StatelessWidget {
               ),
           ],
         ),
+        OptionRow(
+          label: 'Popup',
+          children: [
+            OptionChip(
+              label: 'Off',
+              selected: !controller.popupMode,
+              onTap: () => controller.setPopupMode(false),
+            ),
+            OptionChip(
+              label: 'Click shows, blur hides',
+              selected: controller.popupMode,
+              onTap: () => controller.setPopupMode(true),
+            ),
+          ],
+        ),
         OptionRow(
           label: 'Menu',
           children: [

examples/flutter_tray_icon_example/lib/tray_controller.dart

@@ -3,6 +3,7 @@ import 'dart:convert';
 import 'dart:io';
 import 'dart:ui' as ui;
 
+import 'package:dazzui_host/dazzui_host.dart' show OmarchyTheme;
 import 'package:flutter/widgets.dart';
 import 'package:nativeapi/nativeapi.dart' as na;
 import 'package:flutter/services.dart';
@@ -58,7 +59,15 @@ class TrayController extends ChangeNotifier {
     } else {
       checklist.fail(Checklist.supported, 'false');
     }
+    _omarchy = OmarchyTheme.start();
+    _omarchy?.addListener(_onThemeChanged);
     addIcon();
+    _windowListener = WindowManager.instance.addListener(_onWindowEvent);
+    if (_popupMode) {
+      WidgetsBinding.instance.addPostFrameCallback(
+        (_) => _applyPopupWindowStyle(),
+      );
+    }
     _sceneTimer = Timer.periodic(
       const Duration(milliseconds: 250),
       (_) => _driveScenes(),
@@ -81,6 +90,16 @@ class TrayController extends ChangeNotifier {
   MenuBackend get menuBackend => _menuBackend;
   MenuBackend _menuBackend = MenuBackend.native;
 
+  /// Popup behaviour, the way a tray utility has it: a click on the icon shows
+  /// the window (and hides it again), losing the focus hides it. `TRAY_POPUP=1`
+  /// in the environment turns it on from the start, for scripts. Where the
+  /// window ends up is the platform's business: on Wayland the app cannot place
+  /// it, a compositor rule can (see the example's README for Hyprland).
+  bool get popupMode => _popupMode;
+  bool _popupMode = Platform.environment['TRAY_POPUP'] == '1';
+  late final ListenerId _windowListener;
+  DateTime _popupHiddenAt = DateTime(0);
+
   int _nextNumber = 1;
   late final Timer _sceneTimer;
 
@@ -101,9 +120,14 @@ class TrayController extends ChangeNotifier {
   static bool get openMenuSupported => !Platform.isLinux;
 
   /// Icon colour when the user picks "Auto". On macOS that means a template
-  /// image, which the menu bar tints itself; elsewhere the tray is usually dark.
-  static Color get autoColor =>
-      Platform.isMacOS ? const Color(0xFF000000) : const Color(0xFFFFFFFF);
+  /// image, which the menu bar tints itself. On Omarchy it is the desktop
+  /// theme's foreground, light or dark, like the bar's own icons; elsewhere the
+  /// tray is usually dark, so white.
+  Color get autoColor => _autoColor;
+  Color _autoColor = Platform.isMacOS
+      ? const Color(0xFF000000)
+      : const Color(0xFFFFFFFF);
+  OmarchyTheme? _omarchy;
 
   // ---------------------------------------------------------------------
   // Icons
@@ -238,10 +262,34 @@ class TrayController extends ChangeNotifier {
 
   @override
   void dispose() {
+    WindowManager.instance.removeListener(_windowListener);
+    _omarchy?.dispose();
     disposeIcons();
     super.dispose();
   }
 
+  /// The desktop theme changed (or was first read): icons on the "Auto" colour
+  /// take its foreground. The asset still is a fixed white image, which a
+  /// light bar would swallow, so an icon showing it switches to the drawn one.
+  void _onThemeChanged() {
+    final foreground = _omarchy?.data?.vars.colorContent;
+    if (foreground == null || foreground == _autoColor) return;
+    final previous = _autoColor;
+    _autoColor = foreground;
+    for (final entry in entries) {
+      if (entry.animator.color != previous) continue;
+      entry.animator.setColor(foreground);
+      final still = entry.still;
+      if (still == StillIcon.asset) {
+        setStill(StillIcon.drawn, entry, true);
+      } else if (still != null) {
+        setStill(still, entry, true);
+      }
+    }
+    _log('auto colour ← ${_omarchy?.name ?? 'theme'} foreground');
+    notifyListeners();
+  }
+
   void _refreshManager() {
     managerCount = TrayManager.instance.getAll().length;
   }
@@ -528,6 +576,68 @@ class TrayController extends ChangeNotifier {
     notifyListeners();
   }
 
+  // ---------------------------------------------------------------------
+  // Popup: click shows, blur hides
+  // ---------------------------------------------------------------------
+
+  void setPopupMode(bool on) {
+    if (_popupMode == on) return;
+    _popupMode = on;
+    _applyPopupWindowStyle();
+    _log('popup mode ← ${on ? 'on' : 'off'}');
+    notifyListeners();
+  }
+
+  /// A popup has no title bar. On Linux that also keeps every show a single
+  /// layout: a decorated GTK window maps with its CSD shadow margins and drops
+  /// them when the compositor's states arrive, and Flutter re-lays out at each
+  /// size - a visible "grow in". Without the header bar there is nothing to
+  /// drop.
+  void _applyPopupWindowStyle() {
+    final window = WindowManager.instance.getCurrent();
+    if (window == null) return;
+    window.titleBarStyle = _popupMode
+        ? TitleBarStyle.hidden
+        : TitleBarStyle.normal;
+  }
+
+  void _onWindowEvent(WindowEvent event) {
+    if (!_popupMode || event is! WindowBlurredEvent) return;
+    final window = WindowManager.instance.getCurrent();
+    if (window == null || event.windowId != window.id || !window.isVisible) {
+      return;
+    }
+    window.hide();
+    _popupHiddenAt = DateTime.now();
+    _popup('hidden (blur)');
+  }
+
+  /// A click on the icon shows the window, or hides it when it is showing. A
+  /// click that arrives right after a blur hid the window is the same gesture
+  /// (the press took the focus away first), so it leaves the window hidden.
+  void _togglePopup() {
+    final window = WindowManager.instance.getCurrent();
+    if (window == null) return;
+    if (window.isVisible) {
+      window.hide();
+      _popupHiddenAt = DateTime.now();
+      _popup('hidden (click)');
+    } else if (DateTime.now().difference(_popupHiddenAt) <
+        const Duration(milliseconds: 400)) {
+      _popup('stays hidden');
+    } else {
+      window.show();
+      window.focus();
+      _popup('shown');
+    }
+  }
+
+  // Also on stdout, where a script can read it without the UI probe.
+  void _popup(String what) {
+    _log('popup $what');
+    debugPrint('[popup] $what');
+  }
+
   // ---------------------------------------------------------------------
   // Scenes: one click, a complete picture for the camera
   // ---------------------------------------------------------------------
@@ -612,6 +722,7 @@ class TrayController extends ChangeNotifier {
       checklist.count(Checklist.clicked);
       _noteTrayEvent(ContextMenuTrigger.clicked);
       _event('Clicked', entry);
+      if (_popupMode) _togglePopup();
     } else if (event is TrayIconRightClickedEvent) {
       entry.rightClicks++;
       checklist.count(Checklist.rightClicked);

tools/gui/README.md

@@ -30,6 +30,8 @@ runner) lives in [`.agents/skills/`](../../.agents/skills); read
 | `core_drag_drop_test.py` / `.ps1` | core `drag_drop_example` (C++) | macOS / Windows | `DragSource` → `DropTarget` across two windows: enter / move / drop events, dropped file path and text, drop position in content coordinates, source reports `copy`; a drag released where nothing accepts it reports exit and `none` |
 | `flutter_drag_drop_test.py` / `.ps1` | `drag_drop_example` | macOS / Windows | `DragOutArea` → `DropRegion` in one window: a file and a text drop arrive, the source sees `copy`, the highlight clears, a second drag works after the first |
 | `flutter_tray_icon_test.py` / `.ps1` / `_linux.py` | `tray_icon_example` | macOS / Windows (WinUI 3 and Native menu backends) / Linux | animated tray icons: frames really are rendered and pushed (counter, 30 and 60 fps, no dropped frames, Pause / Step / Resume, 3x resolution), a live widget captured into frames, the Download scene driving the title, three icons animating at once; title / tooltip / visibility / trigger / bounds read back from the native getters; the menu opened from code shows its items and states, an item click arrives, `closeContextMenu` closes it; "Window to icon" puts the window below the icon on macOS and above it on Windows, centred on it; the example's own checklist has no unexpected failures. Windows tray icons have no title, so the title checks become one no-op check there. On Linux the icon is a StatusNotifierItem: no bounds and no menu opened from code, so the test checks the example does not offer them; the frame pipeline is asserted at 10 fps (what 30 fps gives on the host is printed), and the icons are counted where the shell counts them: `RegisteredStatusNotifierItems` lists one, then three, then one again after two are removed. Not covered: clicks on the tray icon itself — the input driver refuses the menu-bar layer, those stay manual items of the example's Checklist tab |
+| `flutter_tray_popup_test_hyprland.py` | `tray_icon_example` | Linux (Hyprland, the Omarchy laptop) | the example's popup mode (`TRAY_POPUP=1`, or Properties → Popup) together with a Hyprland window rule placed by `cursor_x`/`cursor_y`: a real left click on the tray icon in the bar (located by diffing two `grim` captures of the bar, pressed through `wlpointer`, the kit's zwlr_virtual_pointer tool) maps the window floating and pinned with its right edge 20 px right of the click and its top 20 px below it, under the bar, focused; focusing another window hides it (`[popup] hidden (blur)` on stdout); `Activate` over D-Bus with the cursor in the middle of the screen maps it there (the rule is re-evaluated on every map because the example hides instead of lowering); a click while it shows hides it. The rule is installed into `~/.config/hypr/hyprland.lua` for the run (a marked `require` line plus a file next to it) and removed again, both checked with `hyprctl configerrors`. Needs the item pinned in Omarchy's tray (new items sit in a collapsed drawer) and a Lua-config Hyprland (0.56+: `hyprctl dispatch` takes `hl.dsp.*` calls) |
+| `core/tests/window_shadow_remap_linux_test` (in core) | core hidden-title-bar shadow | Linux (Hyprland; any compositor) | no-input regression, run floating (`hl.window_rule` for its class on Hyprland): a window whose title bar is hidden keeps its content size across hide and show whatever xdg states the compositor sends - Hyprland reports every window tiled and maximized, and GDK takes no resize while they stand, so core must not add its shadow gutter before the compositor has answered. Three timings of hiding the title bar; exact content size once settled, no gutter band and no growth across shows in all of them |
 | `core_tray_icon_events_test_linux.sh` | core `tray_icon_example` (C++) | Linux | the tray icon's menu export and events, driven over D-Bus the way the shell drives a StatusNotifierItem (the input driver may not press the top bar): with the `RightClicked` trigger the menu is exported (`Menu`, its items in `GetLayout`) without `ItemIsMenu`; `WindowId` is an int32, as gnome-shell reads it; the host's dbusmenu events come back as menu events (`opened` / `closed` on the root once each however often they come, `clicked` on an item); from a host other than gnome-shell `Activate` is a click, a second one within the double-click time a double click (a third starts a new pair, two slow ones are two clicks), `ContextMenu` a right click; `SecondaryActivate` and `Scroll` report nothing yet. Not covered: gnome-shell's own `Activate` (a double click) and a real host's menu, which only real clicks in the top bar show — checked by hand on GNOME 46 and in KDE Plasma 6 |
 | `flutter_launch_at_startup_test.py` | `launch_at_startup`'s own example, in a leanflutter checkout (`$LEANFLUTTER_DIR`, default `~/Projects/leanflutter`; see `common.py`) | macOS | the 0.5.x compatible API on nativeapi: Enable registers an `SMAppService` login item, `isEnabled` reads it back, Disable removes it, and `setup(args:)` neither throws nor leaves an entry behind. Always leaves the login item off, including on a failure. Written but not yet run — the display was asleep; the same sequence was verified headlessly instead |
 | `flutter_detachable_window_and_browser_tabs_demo.py` / `.ps1` | both Flutter examples | macOS / Windows | the demo video scenarios; also the only coverage of `browser_tabs_example` (reorder, tear off, merge, move by the strip; its log ends with the preserved page state, no PASS/FAIL checks) |
@@ -96,6 +98,8 @@ $R linux desktop tools/gui/flutter_floating_toolbar_test_linux.py 120   # no inp
 $R linux desktop tools/gui/flutter_tray_icon_test_linux.py 300   # example built in the host's checkout
 $R linux run tools/gui/build_core_example_linux.sh tray_icon_example
 $R linux desktop tools/gui/core_tray_icon_events_test_linux.sh 60
+$R omarchy setup                                                 # Hyprland laptop: pushes wlpointer's sources with the kit
+$R omarchy desktop tools/gui/flutter_tray_popup_test_hyprland.py 240   # example built in the host's staged workspace
 $R linux desktop tools/gui/flutter_window_shape_demo_linux.py 240   # dry run: no recorder
 .agents/skills/record-demo/scripts/record_remote_linux.sh linux \
     tools/gui/flutter_window_shape_demo_linux.py tools/gui/output   # the take