Compose Native Tray Documentation

The macOS implementation of the transparent tray popup uses an NSPanel to mirror the Windows UX.

Key Technical Details:

• Window Style: Uses .nonactivatingPanel style with level = .statusBar to ensure it stays topmost above normal applications without activating the app when interacting with it.
• Transparency: Uses a transparent CAMetalLayer via TaoPopupSceneLayer for rendering.
• Input Handling:
  • Outside Clicks: Uses a combination of NSEvent.addGlobalMonitorForEvents (for clicks outside the app) and a local monitor (for clicks inside) to handle dismissal.
  • Keyboard: Overrides canBecomeKeyWindow = true to allow the panel to take key focus. Keyboard events (keyDown/keyUp) are forwarded using the dispatchNativeKeyEvent wire format.
• Rendering: Uses the Metal render path (Skia DirectContext per host) rather than the EGL path used on other platforms.

The library supports Compose recomposition for all aspects of the system menu. You can use standard Compose state (e.g., mutableStateOf) to dynamically change icon, labels, item visibility, and item states (like isEnabled or checked) without manually recreating the menu. This allows for seamless UI updates when application state changes.

// Example: Fully reactive menu
application {
  var darkMode by remember { mutableStateOf(false) }
  var showAdvancedOptions by remember { mutableStateOf(false) }
  var notificationsEnabled by remember { mutableStateOf(true) }
  var isConfigAvailable by remember { mutableStateOf(false) }

  Tray(
    icon = if (darkMode) Icons.Default.DarkMode else Icons.Default.LightMode,
    tooltip = "My Application"
  ) {
    Item(
      label = if (darkMode) "Switch to Light Mode" else "Switch to Dark Mode",
      icon = if (darkMode) Icons.Default.LightMode else Icons.Default.DarkMode
    ) { 
      darkMode = !darkMode 
    }

    CheckableItem(
      label = "Notifications",
      checked = notificationsEnabled,
      onCheckedChange = { notificationsEnabled = it }
    )

    if (showAdvancedOptions) {
      Divider()
      SubMenu(label = "Advanced Options") {
        Item(
          label = "Configuration", 
          isEnabled = isConfigAvailable
        ) { /* action */ }
        
        Item(label = "Check Configuration Availability") { 
          isConfigAvailable = true 
        }
      }
    }

    Divider()

    Item(label = if (showAdvancedOptions) "Hide Advanced Options" else "Show Advanced Options") {
      showAdvancedOptions = !showAdvancedOptions
    }
  }
}

On Linux, the transparent tray popup is implemented as a raw X11 override-redirect ARGB32 window rather than a GTK window. This allows the panel to function as an independent X client that works even if the main application is a native Wayland client (via XWayland).

Key Technical Details:

• Visuals: It queries EGL for alpha-capable desktop-GL configurations (EGL_NATIVE_VISUAL_ID) to ensure transparency is preserved.
• Threading: Uses two X connections: one for commands (owned by the Tao main thread) and one for events (owned by a dedicated per-panel thread).
• Input:
  • Mouse: Uses XI2 raw ButtonPress on the root window to detect outside clicks (similar to Windows WH_MOUSE_LL).
  • Keyboard: Sends raw X keysyms as vkCode and Unicode codePoints. A translation layer (linuxNativeKeyToAwt) converts these to AWT VK codes.
• Focus: Uses XSetInputFocus(RevertToParent) on click to allow the panel to take keyboard focus without a full window grab.

The TrayApp API (found in dev.nucleusframework.composenativetray.tray.api.TrayApp) routes its implementation based on the host platform to provide a consistent user experience.

• Windows: Uses TrayAppImplPanel, which renders into a TaoStandalonePopup. This is a top-level, ownerless, topmost, non-activating native panel with per-pixel transparency. It does not appear in the taskbar, Alt-Tab, or task view. It supports slide and fade animations.
• macOS: Uses TrayAppImplPanel (via NSPanel). It is an ownerless, non-activating panel with .statusBar level (topmost), transparent background, and supports keyboard focus without activating the main application.
• Linux: Uses TrayAppImplPanel (via a raw X11 override-redirect window) when isTaoStandalonePopupAvailable() is true. This works on GNOME Wayland via XWayland. If a native Wayland/layer-shell environment is required but unavailable, it falls back to TrayAppImplWindow, which is an opaque, focus-based DecoratedWindow.

Note on Linux Fallback: If the environment is X-server-less (pure Wayland without XWayland support), the system falls back to the opaque TrayAppImplWindow implementation.

The TrayApp component provides a system tray/menu-bar icon and a popup window for quick actions. It is ideal for mini-dashboards or control centers.

Key features:

• rememberTrayAppState: Manages the state of the popup window, including size and visibility.
• TrayApp parameters:
  • state: The TrayAppState instance.
  • icon: The icon to display in the tray (required).
  • tooltip: The tooltip text (required).
  • transparent / undecorated: Visual styles (defaults to true).
  • menu: A lambda to build a standard system menu.
• Dismiss Modes:
  • TrayWindowDismissMode.AUTO (default): Closes when clicking outside or losing focus.
  • TrayWindowDismissMode.MANUAL: The window stays open until you explicitly call hide() or toggle().

application {
    val trayAppState = rememberTrayAppState(
        initialWindowSize = DpSize(300.dp, 420.dp),
        initiallyVisible = true
    )

    TrayApp(
        state = trayAppState,
        icon = Icons.Default.Dashboard,
        tooltip = "My Tray App",
        transparent = true,
        undecorated = true,
        menu = {
            Item("Toggle popup") { trayAppState.toggle() }
            Divider()
            Item("Quit") { exitApplication() }
        }
    ) {
        MaterialTheme {
            Text("Quick Settings")
            Button(onClick = { trayAppState.hide() }) { Text("Close") }
        }
    }
}

Use SingleInstanceManager to prevent multiple instances of your application from running. This is useful for restoring a minimized application via the tray icon instead of opening a new window.

• isSingleInstance(...): Checks if an instance is already running. If it is, the onRestoreRequest handler is triggered.
• onRestoreFileCreated: A handler used to pass data (like deep links) from a new instance attempt to the existing main instance by writing to a temporary file.
• Configuration: Allows customizing the lockFilesDir and appIdentifier to control the scope of the single instance management.

import dev.nucleusframework.core.runtime.SingleInstanceManager

var isWindowVisible by remember { mutableStateOf(true) }

// Check for single instance and restore window if found
val isSingleInstance = SingleInstanceManager.isSingleInstance(
  onRestoreRequest = {
    isWindowVisible = true
  }
)

if (!isSingleInstance) {
  exitApplication()
  return@application
}

// Passing data between instances
SingleInstanceManager.isSingleInstance(
    onRestoreFileCreated = {
        args.firstOrNull()?.let(::writeText)
    },
    onRestoreRequest = {
        val data = readText()
        // restore window with data
    }
)

// Custom configuration
SingleInstanceManager.configuration = Configuration(
  lockFilesDir = Paths.get("path/to/your/app/data/dir/single_instance_manager"),
  appIdentifier = "app_id"
)