Add onKeyEvent and onPreviewKeyEvent parameters to TrayApp for custom key event handling

- Introduced `onKeyEvent` and `onPreviewKeyEvent` parameters to `TrayApp` and related methods, allowing more customizable key event handling.
- Updated `DialogWindow` and platform-specific implementations to support the new key event callbacks.
- Documented the new parameters with usage examples for enhanced flexibility.

Author: kdroidFilter

src/commonMain/kotlin/com/kdroid/composetray/tray/api/TrayApp.kt

@@ -16,6 +16,7 @@ import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.ColorFilter
 import androidx.compose.ui.graphics.painter.Painter
 import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.input.key.KeyEvent
 import androidx.compose.ui.unit.DpSize
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.window.ApplicationScope
@@ -43,24 +44,29 @@ import java.awt.EventQueue.invokeLater
 import java.awt.event.WindowEvent
 import java.awt.event.WindowFocusListener
 
+
 /**
- * TrayApp – state-preserving tray popup with platform-tuned anchoring.
- *
- * Linux and macOS behave differently on initial placement:
- *  - macOS/Windows: the original logic (delayed first frame + polling until a non-default
- *    anchor) works reliably with NSStatusItem and Win tray.
- *  - Linux (GNOME/KDE/etc.): the newer approach (pre-seed DialogState.position, re-apply
- *    right before show, and re-anchor while visible) is more robust against KWin/GNOME races.
+ * Creates a tray-based desktop application with support for customizable icons, tooltips, menus,
+ * and composable content. The application integrates with the system's tray or menu bar and
+ * supports optional window functionality.
  *
- * This file keeps one public API but internally routes to platform-specific implementations:
- *  - Linux  -> ImplLinux (new logic)
- *  - mac/Win -> ImplOriginal (previous logic)
- *
- * All code comments are in English by user preference.
+ * @param icon The primary icon to display in the system tray or menu bar.
+ * @param tint Optional color tint for the icon. Defaults to null, using the appropriate dark or light mode color.
+ * @param iconRenderProperties Properties for rendering the icon, with defaults based on the operating system.
+ * @param tooltip Text to be displayed as a tooltip when hovering over the tray icon.
+ * @param state Optional state for managing the tray application's properties or lifecycle.
+ * @param windowSize Optional initial size of the window, if a window is displayed.
+ * @param visibleOnStart Whether the application's window should be visible on startup. Defaults to false.
+ * @param fadeDurationMs Duration in milliseconds for fade animations. Defaults to 200ms.
+ * @param animationSpec Animation specification for fading effects. Defaults to a smooth easing with the specified duration.
+ * @param transparent Whether the application's window should be transparent. Defaults to true.
+ * @param windowsTitle Title of the window for Windows operating systems. Defaults to an empty string.
+ * @param windowIcon Optional icon to be used for the application's window.
+ * @param onPreviewKeyEvent Handler for previewing key events before they are processed. Returns `true` if the event is consumed.
+ * @param onKeyEvent Handler for processing key events. Returns `true` if the event is consumed.
+ * @param menu Optional builder block for defining the application's tray menu. Defaults to null if no menu is needed.
+ * @param content Composable content to be displayed within the application's window.
  */
-
-// --------------------- Overloads (public API kept stable) ---------------------
-
 @ExperimentalTrayAppApi
 @Composable
 fun ApplicationScope.TrayApp(
@@ -76,6 +82,8 @@ fun ApplicationScope.TrayApp(
     transparent: Boolean = true,
     windowsTitle: String = "",
     windowIcon: Painter? = null,
+    onPreviewKeyEvent: (KeyEvent) -> Boolean = { false },
+    onKeyEvent: (KeyEvent) -> Boolean = { false },
     menu: (TrayMenuBuilder.() -> Unit)? = null,
     content: @Composable () -> Unit,
 ) {
@@ -101,11 +109,32 @@ fun ApplicationScope.TrayApp(
         transparent = transparent,
         windowsTitle = windowsTitle,
         windowIcon = windowIcon,
+        onPreviewKeyEvent = onPreviewKeyEvent,
+        onKeyEvent = onKeyEvent,
         menu = menu,
         content = content,
     )
 }
 
+/**
+ * Creates a system tray application with the provided configuration.
+ *
+ * @param icon The icon displayed in the system tray for this application.
+ * @param iconRenderProperties The properties defining how the icon is rendered. Default is based on the current operating system.
+ * @param tooltip The tooltip text displayed when hovering over the tray icon.
+ * @param state The state of the tray app, which can be used to manage its visibility and behavior. Defaults to `null`.
+ * @param windowSize The size of the application window when displayed. Defaults to `null`.
+ * @param visibleOnStart Determines whether the application window is visible when the app starts. Defaults to `false`.
+ * @param fadeDurationMs The duration of the fade animation (in milliseconds) when showing or hiding the window. Defaults to `200`.
+ * @param animationSpec The animation specification used for window fade transitions. Defaults to an easing `tween` animation.
+ * @param transparent Indicates if the application window background should be transparent. Defaults to `true`.
+ * @param windowsTitle The title of the window displayed in the task manager or window list on Windows systems. Defaults to an empty string.
+ * @param windowIcon The icon displayed for the application window (if any). Can be `null`.
+ * @param onPreviewKeyEvent A callback invoked before key events are dispatched. It can intercept and handle key events. Defaults to returning `false`.
+ * @param onKeyEvent A callback invoked to handle key events. Defaults to returning `false`.
+ * @param menu An optional builder block to define the tray menu items.
+ * @param content The content displayed in the tray application's main window.
+ */
 @ExperimentalTrayAppApi
 @Composable
 fun ApplicationScope.TrayApp(
@@ -120,6 +149,8 @@ fun ApplicationScope.TrayApp(
     transparent: Boolean = true,
     windowsTitle: String = "",
     windowIcon: Painter? = null,
+    onPreviewKeyEvent: (KeyEvent) -> Boolean = { false },
+    onKeyEvent: (KeyEvent) -> Boolean = { false },
     menu: (TrayMenuBuilder.() -> Unit)? = null,
     content: @Composable () -> Unit,
 ) {
@@ -138,11 +169,35 @@ fun ApplicationScope.TrayApp(
         transparent = transparent,
         windowsTitle = windowsTitle,
         windowIcon = windowIcon,
+        onPreviewKeyEvent = onPreviewKeyEvent,
+        onKeyEvent = onKeyEvent,
         menu = menu,
         content = content,
     )
 }
 
+/**
+ * Composable function for displaying a system tray application with a GUI window.
+ * This function differs behavior based on the user's operating system.
+ *
+ * @param windowsIcon Icon displayed in the system tray on Windows systems.
+ * @param macLinuxIcon Icon displayed in the system tray on macOS and Linux systems.
+ * @param tint Optional tint applied to the macOS and Linux tray icon.
+ * @param iconRenderProperties Properties determining how the icon should be rendered.
+ * @param tooltip Text displayed as a tooltip when hovering over the tray icon.
+ * @param state Optional state for managing the tray application window (visibility, etc.).
+ * @param windowSize Desired size of the window when opened, if applicable.
+ * @param visibleOnStart Whether the window should be visible immediately after starting the app.
+ * @param fadeDurationMs Duration of the fade-in and fade-out animations for showing/hiding the window, in milliseconds.
+ * @param animationSpec Animation specification for fade effects.
+ * @param transparent Whether the window's background should be transparent.
+ * @param windowsTitle Title of the GUI window on Windows.
+ * @param windowIcon Icon displayed in the top-left corner of the window on Windows.
+ * @param onPreviewKeyEvent Lambda for handling preview key events invoked before onKeyEvent. Defaults to ignoring key events.
+ * @param onKeyEvent Lambda for handling key events when the window has focus. Defaults to ignoring key events.
+ * @param menu Optional lambda for building the context menu attached to the tray icon.
+ * @param content Composable content displayed within the GUI window.
+ */
 @ExperimentalTrayAppApi
 @Composable
 fun ApplicationScope.TrayApp(
@@ -159,6 +214,8 @@ fun ApplicationScope.TrayApp(
     transparent: Boolean = true,
     windowsTitle: String = "",
     windowIcon: Painter? = null,
+    onPreviewKeyEvent: (KeyEvent) -> Boolean = { false },
+    onKeyEvent: (KeyEvent) -> Boolean = { false },
     menu: (TrayMenuBuilder.() -> Unit)? = null,
     content: @Composable () -> Unit,
 ) {
@@ -175,6 +232,8 @@ fun ApplicationScope.TrayApp(
             transparent = transparent,
             windowsTitle = windowsTitle,
             windowIcon = windowIcon,
+            onPreviewKeyEvent = onPreviewKeyEvent,
+            onKeyEvent = onKeyEvent,
             menu = menu,
             content = content,
         )
@@ -183,6 +242,8 @@ fun ApplicationScope.TrayApp(
             icon = macLinuxIcon,
             tint = tint,
             iconRenderProperties = iconRenderProperties,
+            onPreviewKeyEvent = onPreviewKeyEvent,
+            onKeyEvent = onKeyEvent,
             tooltip = tooltip,
             state = state,
             windowSize = windowSize,
@@ -198,6 +259,7 @@ fun ApplicationScope.TrayApp(
     }
 }
 
+
 @ExperimentalTrayAppApi
 @Composable
 fun ApplicationScope.TrayApp(
@@ -212,6 +274,8 @@ fun ApplicationScope.TrayApp(
     transparent: Boolean = true,
     windowsTitle: String = "",
     windowIcon: Painter? = null,
+    onPreviewKeyEvent: (KeyEvent) -> Boolean = { false },
+    onKeyEvent: (KeyEvent) -> Boolean = { false },
     menu: (TrayMenuBuilder.() -> Unit)? = null,
     content: @Composable () -> Unit,
 ) {
@@ -232,6 +296,7 @@ fun ApplicationScope.TrayApp(
     )
 }
 
+
 @ExperimentalTrayAppApi
 @Composable
 fun ApplicationScope.TrayApp(
@@ -248,6 +313,8 @@ fun ApplicationScope.TrayApp(
     transparent: Boolean = true,
     windowsTitle: String = "",
     windowIcon: Painter? = null,
+    onPreviewKeyEvent: (KeyEvent) -> Boolean = { false },
+    onKeyEvent: (KeyEvent) -> Boolean = { false },
     menu: (TrayMenuBuilder.() -> Unit)? = null,
     content: @Composable () -> Unit,
 ) {
@@ -264,6 +331,8 @@ fun ApplicationScope.TrayApp(
         transparent = transparent,
         windowsTitle = windowsTitle,
         windowIcon = windowIcon,
+        onPreviewKeyEvent = onPreviewKeyEvent,
+        onKeyEvent = onKeyEvent,
         menu = menu,
         content = content,
     )
@@ -272,6 +341,8 @@ fun ApplicationScope.TrayApp(
             icon = macLinuxIcon,
             tint = tint,
             iconRenderProperties = iconRenderProperties,
+            onPreviewKeyEvent = onPreviewKeyEvent,
+            onKeyEvent = onKeyEvent,
             tooltip = tooltip,
             state = state,
             windowSize = windowSize,
@@ -303,17 +374,19 @@ fun ApplicationScope.TrayApp(
     transparent: Boolean = true,
     windowsTitle: String = "",
     windowIcon: Painter? = null,
+    onPreviewKeyEvent: (KeyEvent) -> Boolean = { false },
+    onKeyEvent: (KeyEvent) -> Boolean = { false },
     menu: (TrayMenuBuilder.() -> Unit)? = null,
     content: @Composable () -> Unit,
 ) {
     when (getOperatingSystem()) {
         OperatingSystem.LINUX -> TrayAppImplLinux(
             iconContent, iconRenderProperties, tooltip, state, windowSize,
-            visibleOnStart, fadeDurationMs, animationSpec, transparent, windowsTitle, windowIcon, menu, content
+            visibleOnStart, fadeDurationMs, animationSpec, transparent, windowsTitle, windowIcon, onPreviewKeyEvent, onKeyEvent, menu, content
         )
         else -> TrayAppImplOriginal(
             iconContent, iconRenderProperties, tooltip, state, windowSize,
-            visibleOnStart, fadeDurationMs, animationSpec, transparent, windowsTitle, windowIcon, menu, content
+            visibleOnStart, fadeDurationMs, animationSpec, transparent, windowsTitle, windowIcon, onPreviewKeyEvent, onKeyEvent, menu, content
         )
     }
 }
@@ -333,6 +406,8 @@ private fun ApplicationScope.TrayAppImplOriginal(
     transparent: Boolean,
     windowsTitle: String,
     windowIcon: Painter?,
+    onPreviewKeyEvent: (KeyEvent) -> Boolean,
+    onKeyEvent: (KeyEvent) -> Boolean,
     menu: (TrayMenuBuilder.() -> Unit)?,
     content: @Composable () -> Unit,
 ) {
@@ -476,6 +551,8 @@ private fun ApplicationScope.TrayAppImplOriginal(
         transparent = transparent,
         visible = shouldShowWindow,
         state = dialogState,
+        onPreviewKeyEvent = onPreviewKeyEvent,
+        onKeyEvent = onKeyEvent,
     ) {
         DisposableEffect(shouldShowWindow, dismissMode) {
             if (!shouldShowWindow) return@DisposableEffect onDispose { }
@@ -550,6 +627,8 @@ private fun ApplicationScope.TrayAppImplLinux(
     transparent: Boolean,
     windowsTitle: String,
     windowIcon: Painter?,
+    onPreviewKeyEvent: (KeyEvent) -> Boolean,
+    onKeyEvent: (KeyEvent) -> Boolean,
     menu: (TrayMenuBuilder.() -> Unit)?,
     content: @Composable () -> Unit,
 ) {
@@ -668,6 +747,8 @@ private fun ApplicationScope.TrayAppImplLinux(
         transparent = transparent,
         visible = shouldShowWindow,
         state = dialogState,
+        onPreviewKeyEvent = onPreviewKeyEvent,
+        onKeyEvent = onKeyEvent,
     ) {
         DisposableEffect(shouldShowWindow, dismissMode) {
             if (!shouldShowWindow) return@DisposableEffect onDispose { }