feat: add onMenuOpened callback to Tray composable (#233)

Add a callback invoked when the tray menu is about to be shown,
allowing apps to refresh state on demand. Implemented via the
DBusMenu AboutToShow protocol on Linux; noop on Windows/macOS.

Includes LayoutUpdated-based suppression to prevent feedback loops
when the callback mutates menu state, and build script cache
invalidation to avoid stale native library issues.

Author: kdroidFilter

demo/src/jvmMain/kotlin/com/kdroid/composetray/demo/DynamicIconsDemo.kt

@@ -56,16 +56,19 @@ fun main() = application {
 
     // Basic state for tray icon
     var currentTrayIcon by remember { mutableStateOf(Icons.Default.Notifications) }
-    
+
     // States for menu item icons
     var weatherIcon by remember { mutableStateOf(Icons.Default.WbSunny) }
     var musicIcon by remember { mutableStateOf(Icons.Default.MusicNote) }
     var settingsIcon by remember { mutableStateOf(Icons.Default.Settings) }
-    
+
     // States for theme and features
     var isDarkTheme by remember { mutableStateOf(false) }
     var isWeatherEnabled by remember { mutableStateOf(true) }
     var isMusicEnabled by remember { mutableStateOf(true) }
+
+    // Counter to demonstrate onMenuOpened callback
+    var menuOpenCount by remember { mutableIntStateOf(0) }
 
     // Always create the Tray composable, but make it conditional on visibility
     val showTray = alwaysShowTray || !isWindowVisible
@@ -77,7 +80,11 @@ fun main() = application {
             primaryAction = {
                 isWindowVisible = true
                 println("$logTag: Primary action clicked")
-            }
+            },
+            onMenuOpened = {
+                menuOpenCount++
+                println("$logTag: Menu opened (count: $menuOpenCount)")
+            },
         ) {
             // Weather submenu with dynamic icon
             SubMenu(label = "Weather", icon = weatherIcon) {
@@ -249,6 +256,12 @@ fun main() = application {
 
                     Text(
                         "This demo showcases dynamic icon changes in the system tray menu.",
+                        modifier = Modifier.padding(bottom = 8.dp)
+                    )
+
+                    Text(
+                        "Tray menu opened $menuOpenCount times",
+                        style = MaterialTheme.typography.bodyMedium,
                         modifier = Modifier.padding(bottom = 24.dp)
                     )
 

src/jvmMain/kotlin/com/kdroid/composetray/lib/linux/LinuxNativeBridge.kt

@@ -65,6 +65,12 @@ internal object LinuxNativeBridge {
         callback: Runnable?,
     )
 
+    /** Register a callback invoked when the menu is about to be shown. */
+    @JvmStatic external fun nativeSetMenuOpenedCallback(
+        handle: Long,
+        callback: Runnable?,
+    )
+
     // -- Click position ----------------------------------------------------------
 
     /** Writes [x, y] into outXY. */

src/jvmMain/kotlin/com/kdroid/composetray/lib/linux/LinuxTrayManager.kt

@@ -23,6 +23,7 @@ internal class LinuxTrayManager(
     private var iconPath: String,
     private var tooltip: String = "",
     private var onLeftClick: (() -> Unit)? = null,
+    private var onMenuOpened: (() -> Unit)? = null,
 ) {
     companion object {
         // Ensures only one systray runtime is active at a time
@@ -99,6 +100,7 @@ internal class LinuxTrayManager(
         newTooltip: String,
         newOnLeftClick: (() -> Unit)?,
         newMenuItems: List<MenuItem>?,
+        newOnMenuOpened: (() -> Unit)? = null,
     ) {
         val iconChanged: Boolean
         val tooltipChanged: Boolean
@@ -109,6 +111,7 @@ internal class LinuxTrayManager(
             iconPath = newIconPath
             tooltip = newTooltip
             onLeftClick = newOnLeftClick
+            onMenuOpened = newOnMenuOpened
             if (newMenuItems != null) {
                 menuItems.clear()
                 menuItems.addAll(newMenuItems)
@@ -174,6 +177,12 @@ internal class LinuxTrayManager(
                 },
             )
 
+            // Set menu-opened callback
+            native.nativeSetMenuOpenedCallback(
+                trayHandle,
+                JniRunnable { onMenuOpened?.invoke() },
+            )
+
             // Build menu before starting the loop
             rebuildMenu()
 

src/jvmMain/kotlin/com/kdroid/composetray/tray/api/NativeTray.kt

@@ -56,6 +56,7 @@ internal class NativeTray {
         tooltip: String,
         primaryAction: (() -> Unit)?,
         menuContent: (TrayMenuBuilder.() -> Unit)?,
+        onMenuOpened: (() -> Unit)? = null,
     ) {
         if (!initialized) {
             initializeTray(iconPath, windowsIconPath, tooltip, primaryAction, menuContent)
@@ -65,16 +66,17 @@ internal class NativeTray {
 
         try {
             when (os) {
-                LINUX -> LinuxTrayInitializer.update(instanceId, iconPath, tooltip, primaryAction, menuContent)
+                LINUX -> LinuxTrayInitializer.update(instanceId, iconPath, tooltip, primaryAction, menuContent, onMenuOpened)
                 WINDOWS ->
                     WindowsTrayInitializer.update(
                         instanceId,
                         windowsIconPath,
                         tooltip,
                         primaryAction,
                         menuContent,
+                        onMenuOpened,
                     )
-                MACOS -> MacTrayInitializer.update(instanceId, iconPath, tooltip, primaryAction, menuContent)
+                MACOS -> MacTrayInitializer.update(instanceId, iconPath, tooltip, primaryAction, menuContent, onMenuOpened)
                 UNKNOWN -> {
                     AwtTrayInitializer.update(iconPath, tooltip, primaryAction, menuContent)
                     awtTrayUsed.set(true)
@@ -103,6 +105,7 @@ internal class NativeTray {
         backoffMs: Long = 200,
         lightIconContent: (@Composable () -> Unit)? = null,
         darkIconContent: (@Composable () -> Unit)? = null,
+        onMenuOpened: (() -> Unit)? = null,
     ) {
         trayScope.launch {
             val rendered = renderIconsWithRetry(iconContent, iconRenderProperties, maxAttempts, backoffMs)
@@ -117,7 +120,7 @@ internal class NativeTray {
             val (pngIconPath, windowsIconPath) = rendered
 
             if (!initialized) {
-                initializeTray(pngIconPath, windowsIconPath, tooltip, primaryAction, menuContent)
+                initializeTray(pngIconPath, windowsIconPath, tooltip, primaryAction, menuContent, onMenuOpened)
                 initialized = true
             } else {
                 try {
@@ -129,6 +132,7 @@ internal class NativeTray {
                                 tooltip,
                                 primaryAction,
                                 menuContent,
+                                onMenuOpened,
                             )
                         WINDOWS ->
                             WindowsTrayInitializer.update(
@@ -137,8 +141,9 @@ internal class NativeTray {
                                 tooltip,
                                 primaryAction,
                                 menuContent,
+                                onMenuOpened,
                             )
-                        MACOS -> MacTrayInitializer.update(instanceId, pngIconPath, tooltip, primaryAction, menuContent)
+                        MACOS -> MacTrayInitializer.update(instanceId, pngIconPath, tooltip, primaryAction, menuContent, onMenuOpened)
                         UNKNOWN -> {
                             AwtTrayInitializer.update(pngIconPath, tooltip, primaryAction, menuContent)
                             awtTrayUsed.set(true)
@@ -241,6 +246,7 @@ internal class NativeTray {
         tooltip: String = "",
         primaryAction: (() -> Unit)?,
         menuContent: (TrayMenuBuilder.() -> Unit)? = null,
+        onMenuOpened: (() -> Unit)? = null,
     ) {
         trayScope.launch {
             var trayInitialized = false
@@ -249,7 +255,7 @@ internal class NativeTray {
                 when (os) {
                     LINUX -> {
                         debugln { "[NativeTray] Initializing Linux tray with icon path: $iconPath" }
-                        LinuxTrayInitializer.initialize(instanceId, iconPath, tooltip, primaryAction, menuContent)
+                        LinuxTrayInitializer.initialize(instanceId, iconPath, tooltip, primaryAction, menuContent, onMenuOpened)
                         trayInitialized = true
                     }
                     WINDOWS -> {
@@ -260,12 +266,13 @@ internal class NativeTray {
                             tooltip,
                             primaryAction,
                             menuContent,
+                            onMenuOpened,
                         )
                         trayInitialized = true
                     }
                     MACOS -> {
                         debugln { "[NativeTray] Initializing macOS tray with icon path: $iconPath" }
-                        MacTrayInitializer.initialize(instanceId, iconPath, tooltip, primaryAction, menuContent)
+                        MacTrayInitializer.initialize(instanceId, iconPath, tooltip, primaryAction, menuContent, onMenuOpened)
                         trayInitialized = true
                     }
                     else -> {}
@@ -301,13 +308,15 @@ internal class NativeTray {
         tooltip: String = "",
         primaryAction: (() -> Unit)?,
         menuContent: (TrayMenuBuilder.() -> Unit)? = null,
+        onMenuOpened: (() -> Unit)? = null,
     ) {
         updateComposable(
             iconContent = iconContent,
             iconRenderProperties = iconRenderProperties,
             tooltip = tooltip,
             primaryAction = primaryAction,
             menuContent = menuContent,
+            onMenuOpened = onMenuOpened,
         )
     }
 }
@@ -325,6 +334,7 @@ fun ApplicationScope.Tray(
     windowsIconPath: String = iconPath,
     tooltip: String,
     primaryAction: (() -> Unit)? = null,
+    onMenuOpened: (() -> Unit)? = null,
     menuContent: (TrayMenuBuilder.() -> Unit)? = null,
 ) {
     val absoluteIconPath = remember(iconPath) { extractToTempIfDifferent(iconPath)?.absolutePath.orEmpty() }
@@ -344,7 +354,7 @@ fun ApplicationScope.Tray(
 
     // Update when params change, including menuHash
     LaunchedEffect(absoluteIconPath, absoluteWindowsIconPath, tooltip, primaryAction, menuContent, menuHash) {
-        tray.update(absoluteIconPath, absoluteWindowsIconPath, tooltip, primaryAction, menuContent)
+        tray.update(absoluteIconPath, absoluteWindowsIconPath, tooltip, primaryAction, menuContent, onMenuOpened)
     }
 
     // Dispose only when Tray is removed from composition
@@ -362,6 +372,7 @@ fun ApplicationScope.Tray(
     iconRenderProperties: IconRenderProperties = IconRenderProperties.forCurrentOperatingSystem(),
     tooltip: String,
     primaryAction: (() -> Unit)? = null,
+    onMenuOpened: (() -> Unit)? = null,
     menuContent: (TrayMenuBuilder.() -> Unit)? = null,
 ) {
     val isDark = isMenuBarInDarkMode() // Observe menu bar theme to trigger recomposition on changes
@@ -384,6 +395,7 @@ fun ApplicationScope.Tray(
             menuContent = menuContent,
             maxAttempts = 3,
             backoffMs = 200,
+            onMenuOpened = onMenuOpened,
         )
     }
 
@@ -402,6 +414,7 @@ fun ApplicationScope.Tray(
     iconRenderProperties: IconRenderProperties = IconRenderProperties.forCurrentOperatingSystem(),
     tooltip: String,
     primaryAction: (() -> Unit)? = null,
+    onMenuOpened: (() -> Unit)? = null,
     menuContent: (TrayMenuBuilder.() -> Unit)? = null,
 ) {
     val isDark = isMenuBarInDarkMode()
@@ -477,6 +490,7 @@ fun ApplicationScope.Tray(
             backoffMs = 200,
             lightIconContent = lightIconContent,
             darkIconContent = darkIconContent,
+            onMenuOpened = onMenuOpened,
         )
     }
 
@@ -494,6 +508,7 @@ fun ApplicationScope.Tray(
     iconRenderProperties: IconRenderProperties = IconRenderProperties.forCurrentOperatingSystem(),
     tooltip: String,
     primaryAction: (() -> Unit)? = null,
+    onMenuOpened: (() -> Unit)? = null,
     menuContent: (TrayMenuBuilder.() -> Unit)? = null,
 ) {
     val isDark = isMenuBarInDarkMode() // Included for consistency, even if not used in rendering
@@ -527,6 +542,7 @@ fun ApplicationScope.Tray(
             menuContent = menuContent,
             maxAttempts = 3,
             backoffMs = 200,
+            onMenuOpened = onMenuOpened,
         )
     }
 
@@ -549,6 +565,7 @@ fun ApplicationScope.Tray(
     iconRenderProperties: IconRenderProperties = IconRenderProperties.forCurrentOperatingSystem(),
     tooltip: String,
     primaryAction: (() -> Unit)? = null,
+    onMenuOpened: (() -> Unit)? = null,
     menuContent: (TrayMenuBuilder.() -> Unit)? = null,
 ) {
     val os = getOperatingSystem()
@@ -560,6 +577,7 @@ fun ApplicationScope.Tray(
             iconRenderProperties = iconRenderProperties,
             tooltip = tooltip,
             primaryAction = primaryAction,
+            onMenuOpened = onMenuOpened,
             menuContent = menuContent,
         )
     } else {
@@ -570,6 +588,7 @@ fun ApplicationScope.Tray(
             iconRenderProperties = iconRenderProperties,
             tooltip = tooltip,
             primaryAction = primaryAction,
+            onMenuOpened = onMenuOpened,
             menuContent = menuContent,
         )
     }
@@ -584,6 +603,7 @@ fun ApplicationScope.Tray(
     iconRenderProperties: IconRenderProperties = IconRenderProperties.forCurrentOperatingSystem(),
     tooltip: String,
     primaryAction: (() -> Unit)? = null,
+    onMenuOpened: (() -> Unit)? = null,
     menuContent: (TrayMenuBuilder.() -> Unit)? = null,
 ) {
     // Convert DrawableResource to Painter and delegate to the Painter overload
@@ -593,6 +613,7 @@ fun ApplicationScope.Tray(
         iconRenderProperties = iconRenderProperties,
         tooltip = tooltip,
         primaryAction = primaryAction,
+        onMenuOpened = onMenuOpened,
         menuContent = menuContent,
     )
 }
@@ -605,6 +626,7 @@ fun ApplicationScope.Tray(
     iconRenderProperties: IconRenderProperties = IconRenderProperties.forCurrentOperatingSystem(),
     tooltip: String,
     primaryAction: (() -> Unit)? = null,
+    onMenuOpened: (() -> Unit)? = null,
     menuContent: (TrayMenuBuilder.() -> Unit)? = null,
 ) {
     val os = getOperatingSystem()
@@ -617,6 +639,7 @@ fun ApplicationScope.Tray(
             iconRenderProperties = iconRenderProperties,
             tooltip = tooltip,
             primaryAction = primaryAction,
+            onMenuOpened = onMenuOpened,
             menuContent = menuContent,
         )
     } else {
@@ -627,6 +650,7 @@ fun ApplicationScope.Tray(
             iconRenderProperties = iconRenderProperties,
             tooltip = tooltip,
             primaryAction = primaryAction,
+            onMenuOpened = onMenuOpened,
             menuContent = menuContent,
         )
     }