WindowScreen & UIComponent: Improve key input handling

api/Elementa.api

@@ -4,6 +4,7 @@ public final class gg/essential/elementa/ElementaVersion : java/lang/Enum {
 	public static final field V1 Lgg/essential/elementa/ElementaVersion;
 	public static final field V10 Lgg/essential/elementa/ElementaVersion;
 	public static final field V11 Lgg/essential/elementa/ElementaVersion;
+	public static final field V12 Lgg/essential/elementa/ElementaVersion;
 	public static final field V2 Lgg/essential/elementa/ElementaVersion;
 	public static final field V3 Lgg/essential/elementa/ElementaVersion;
 	public static final field V4 Lgg/essential/elementa/ElementaVersion;
@@ -89,6 +90,8 @@ public abstract class gg/essential/elementa/UIComponent : java/util/Observable,
 	protected final fun getMousePosition ()Lkotlin/Pair;
 	public final fun getMouseReleaseListeners ()Ljava/util/List;
 	public final fun getMouseScrollListeners ()Ljava/util/List;
+	public final fun getOnCharTyped ()Ljava/util/List;
+	public final fun getOnKeyPressed ()Ljava/util/List;
 	public fun getParent ()Lgg/essential/elementa/UIComponent;
 	public fun getRadius ()F
 	public fun getRight ()F
@@ -243,7 +246,7 @@ public final class gg/essential/elementa/VanillaFontRenderer : gg/essential/elem
 public final class gg/essential/elementa/VanillaFontRenderer$Companion {
 }
 
-public abstract class gg/essential/elementa/WindowScreen : gg/essential/universal/UScreen {
+public abstract class gg/essential/elementa/WindowScreen : gg/essential/universal/UScreen, gg/essential/universal/UScreen$InputHandler {
 	public fun <init> ()V
 	public fun <init> (Lgg/essential/elementa/ElementaVersion;)V
 	public fun <init> (Lgg/essential/elementa/ElementaVersion;Z)V
@@ -278,6 +281,11 @@ public abstract class gg/essential/elementa/WindowScreen : gg/essential/universa
 	public fun onMouseScrolled (DDDD)V
 	public fun onScreenClose ()V
 	public final fun stopAnimating (Lkotlin/reflect/KMutableProperty0;)V
+	public fun uCharTyped (I)Z
+	public fun uKeyPressed (IILgg/essential/universal/UKeyboard$Modifiers;)Z
+	public fun uMouseClicked (DDILgg/essential/universal/UKeyboard$Modifiers;)Z
+	public fun uMouseReleased (DDILgg/essential/universal/UKeyboard$Modifiers;)Z
+	public fun uMouseScrolled (DDDD)Z
 }
 
 public class gg/essential/elementa/components/GradientComponent : gg/essential/elementa/components/UIBlock {
@@ -756,6 +764,7 @@ public final class gg/essential/elementa/components/Window : gg/essential/elemen
 	public final fun addFloatingComponent (Lgg/essential/elementa/UIComponent;)V
 	public fun afterInitialization ()V
 	public fun animationFrame ()V
+	public final fun charTyped (Lgg/essential/elementa/events/UICharEvent;)Z
 	public fun draw (Lgg/essential/universal/UMatrixStack;)V
 	public final fun drawFloatingComponents ()V
 	public final fun drawFloatingComponents (Lgg/essential/universal/UMatrixStack;)V
@@ -775,6 +784,7 @@ public final class gg/essential/elementa/components/Window : gg/essential/elemen
 	public fun hitTest (FF)Lgg/essential/elementa/UIComponent;
 	public final fun invalidateCachedConstraints ()V
 	public final fun isAreaVisible (DDDD)Z
+	public final fun keyPressed (Lgg/essential/elementa/events/UIKeyEvent;)Z
 	public fun keyType (CI)V
 	public fun mouseClick (DDI)V
 	public fun mouseRelease ()V
@@ -938,7 +948,8 @@ public abstract class gg/essential/elementa/components/input/AbstractTextInput :
 	public final fun isActive ()Z
 	protected fun isBreakingCharacter (C)Z
 	public final fun onActivate (Lkotlin/jvm/functions/Function1;)Lgg/essential/elementa/components/input/AbstractTextInput;
-	protected abstract fun onEnterPressed ()V
+	protected fun onEnterPressed ()V
+	protected abstract fun onEnterPressed (Lgg/essential/universal/UKeyboard$Modifiers;)V
 	public final fun onUpdate (Lkotlin/jvm/functions/Function1;)Lgg/essential/elementa/components/input/AbstractTextInput;
 	protected fun recalculateAllVisualLines ()V
 	protected abstract fun recalculateDimensions ()V
@@ -1119,7 +1130,7 @@ public class gg/essential/elementa/components/input/UITextInput : gg/essential/e
 	protected final fun getPlaceholderWidth ()F
 	public fun getText ()Ljava/lang/String;
 	protected fun getTextForRender ()Ljava/lang/String;
-	protected fun onEnterPressed ()V
+	protected fun onEnterPressed (Lgg/essential/universal/UKeyboard$Modifiers;)V
 	protected fun recalculateDimensions ()V
 	protected fun screenPosToVisualPos (FF)Lgg/essential/elementa/components/input/AbstractTextInput$LinePosition;
 	protected fun scrollIntoView (Lgg/essential/elementa/components/input/AbstractTextInput$LinePosition;)V
@@ -2717,6 +2728,12 @@ public final class gg/essential/elementa/effects/StencilEffect$Companion {
 	public final fun enableStencil ()V
 }
 
+public final class gg/essential/elementa/events/UICharEvent {
+	public fun <init> (I)V
+	public final fun getCodepoint ()I
+	public final fun getString ()Ljava/lang/String;
+}
+
 public final class gg/essential/elementa/events/UIClickEvent : gg/essential/elementa/events/UIEvent {
 	public fun <init> (FFILgg/essential/elementa/UIComponent;Lgg/essential/elementa/UIComponent;I)V
 	public final fun component1 ()F
@@ -2750,6 +2767,16 @@ public abstract class gg/essential/elementa/events/UIEvent {
 	public final fun stopPropagation ()V
 }
 
+public final class gg/essential/elementa/events/UIKeyEvent {
+	public fun <init> (IILgg/essential/universal/UKeyboard$Modifiers;)V
+	public final fun getKey ()I
+	public final fun getModifiers ()Lgg/essential/universal/UKeyboard$Modifiers;
+	public final fun getScanCode ()I
+	public final fun isCopy ()Z
+	public final fun isCut ()Z
+	public final fun isPaste ()Z
+}
+
 public final class gg/essential/elementa/events/UIScrollEvent : gg/essential/elementa/events/UIEvent {
 	public fun <init> (DDLgg/essential/elementa/UIComponent;Lgg/essential/elementa/UIComponent;)V
 	public fun <init> (DLgg/essential/elementa/UIComponent;Lgg/essential/elementa/UIComponent;)V

gradle/libs.versions.toml

@@ -2,7 +2,7 @@
 kotlin = "1.9.25"
 kotlinx-coroutines = "1.5.2"
 jetbrains-annotations = "23.0.0"
-universalcraft = "466"
+universalcraft = "485+feature-em-1645-closing-uscreen-via-esc-on-119-puts-you-in-the-menu-rather"
 commonmark = "0.17.1"
 dom4j = "2.1.1"
 

src/main/kotlin/gg/essential/elementa/ElementaVersion.kt

@@ -7,6 +7,7 @@ import gg.essential.elementa.components.Window
 import gg.essential.elementa.constraints.SuperConstraint
 import gg.essential.elementa.constraints.animation.AnimationComponent
 import gg.essential.elementa.effects.Effect
+import gg.essential.universal.UScreen
 import gg.essential.universal.render.URenderPipeline
 import gg.essential.universal.shader.BlendState
 
@@ -204,8 +205,31 @@ enum class ElementaVersion {
      *
      * See [UniversalCraft#128](https://github.com/SparkUniverse/UniversalCraft/pull/128) for the underlying changes.
      */
+    @Deprecated(DEPRECATION_MESSAGE)
     V11,
 
+    /**
+     * Improvements for key press inputs.
+     *
+     * WindowScreen now implements [UScreen.InputHandler] which provides new functions for key and mouse inputs that
+     * follow more modern Minecraft input method conventions, most notably allowing us to mark an input as handled to
+     * prevent followup execution in Minecraft itself.
+     *
+     * As of V12 the key & character input events have been split up and moved to these new methods.
+     * `keyType(typedChar: Char, keyCode: Int)` in [Window] has been split into:
+     *  - keyPressed(keyEvent: UIKeyEvent)
+     *  - charTyped(charEvent: UICharEvent)
+     * With the backing list for the new listeners now requiring manual modification to set up.
+     * E.G. `UIComponent.onKeyPressed.add { }` & `UIComponent.onCharTyped.add { }` replace the old `UIComponent.onKeyType { }`
+     *
+     * Also see [gg.essential.elementa.events.UIKeyEvent] & [gg.essential.elementa.events.UICharEvent].
+     *
+     * Note: The other improved inputs provided by [UScreen.InputHandler] have not been implemented by V12. (e.g. mouse inputs)
+     *
+     * See [UniversalCraft#125](https://github.com/SparkUniverse/UniversalCraft/pull/125) for the underlying changes.
+     */
+    V12,
+
     ;
 
     /**
@@ -258,14 +282,18 @@ Be sure to read through all the changes between your current version and your ne
         internal val v9 = V9
         @Suppress("DEPRECATION")
         internal val v10 = V10
+        @Suppress("DEPRECATION")
         internal val v11 = V11
+        internal val v12 = V12
 
         internal val atLeastV9Active: Boolean
             get() = active >= v9
         internal val atLeastV10Active: Boolean
             get() = active >= v10
         internal val atLeastV11Active: Boolean
             get() = active >= v11
+        internal val atLeastV12Active: Boolean
+            get() = active >= v12
 
         @PublishedApi
         internal var active: ElementaVersion = v0

src/main/kotlin/gg/essential/elementa/UIComponent.kt

@@ -13,7 +13,9 @@ import gg.essential.elementa.dsl.animate
 import gg.essential.elementa.dsl.toConstraint
 import gg.essential.elementa.effects.Effect
 import gg.essential.elementa.effects.ScissorEffect
+import gg.essential.elementa.events.UICharEvent
 import gg.essential.elementa.events.UIClickEvent
+import gg.essential.elementa.events.UIKeyEvent
 import gg.essential.elementa.events.UIScrollEvent
 import gg.essential.elementa.font.FontProvider
 import gg.essential.elementa.state.v2.ReferenceHolder
@@ -119,7 +121,12 @@ abstract class UIComponent : Observable(), ReferenceHolder {
         get() = field.also { ownFlags += Flags.RequiresMouseMove }
     val mouseDragListeners = mutableListOf<UIComponent.(mouseX: Float, mouseY: Float, button: Int) -> Unit>()
         get() = field.also { ownFlags += Flags.RequiresMouseDrag }
+    @Deprecated("See [ElementaVersion.V12]. Replaced by either the `onKeyPressed` or `onCharTyped` listener lists.")
     val keyTypedListeners = mutableListOf<UIComponent.(typedChar: Char, keyCode: Int) -> Unit>()
+    // Requires ElementaVersion.V12
+    val onKeyPressed = mutableListOf<UIComponent.(keyEvent: UIKeyEvent) -> Boolean>()
+    // Requires ElementaVersion.V12
+    val onCharTyped = mutableListOf<UIComponent.(keyEvent: UICharEvent) -> Boolean>()
 
     private var currentlyHovered = false
     private val beforeHideAnimations = mutableListOf<AnimatingConstraints.() -> Unit>()
@@ -836,7 +843,9 @@ abstract class UIComponent : Observable(), ReferenceHolder {
         this.forEachChild { it.superCall() }
     }
 
+    @Deprecated("See [ElementaVersion.V12]. Listeners are now directly called from [Window].")
     open fun keyType(typedChar: Char, keyCode: Int) {
+        @Suppress("DEPRECATION")
         for (listener in keyTypedListeners)
             this.listener(typedChar, keyCode)
     }
@@ -1021,11 +1030,15 @@ abstract class UIComponent : Observable(), ReferenceHolder {
         mouseScrollListeners.add { method.accept(it) }
     }
 
+    @Deprecated("See [ElementaVersion.V12]. Replaced by either the `onKeyPressed` or `onCharTyped` listener lists.")
     fun onKeyType(method: UIComponent.(typedChar: Char, keyCode: Int) -> Unit) = apply {
+        @Suppress("DEPRECATION")
         keyTypedListeners.add(method)
     }
 
+    @Deprecated("See [ElementaVersion.V12]. Replaced by either the `onKeyPressed` or `onCharTyped` listener lists.")
     fun onKeyTypeConsumer(method: BiConsumer<Char, Int>) {
+        @Suppress("DEPRECATION")
         keyTypedListeners.add { t: Char, u: Int -> method.accept(t, u) }
     }
 

src/main/kotlin/gg/essential/elementa/WindowScreen.kt

@@ -2,6 +2,8 @@ package gg.essential.elementa
 
 import gg.essential.elementa.components.Window
 import gg.essential.elementa.constraints.animation.*
+import gg.essential.elementa.events.UICharEvent
+import gg.essential.elementa.events.UIKeyEvent
 import gg.essential.universal.UKeyboard
 import gg.essential.universal.UMatrixStack
 import gg.essential.universal.UMouse
@@ -21,7 +23,7 @@ abstract class WindowScreen @JvmOverloads constructor(
     private val drawDefaultBackground: Boolean = true,
     restoreCurrentGuiOnClose: Boolean = false,
     newGuiScale: Int = -1
-) : UScreen(restoreCurrentGuiOnClose, newGuiScale) {
+) : UScreen(restoreCurrentGuiOnClose, newGuiScale), UScreen.InputHandler {
     val window = Window(version)
     private var isInitialized = false
 
@@ -35,8 +37,22 @@ abstract class WindowScreen @JvmOverloads constructor(
     ) : this(ElementaVersion.v0, enableRepeatKeys, drawDefaultBackground, restoreCurrentGuiOnClose, newGuiScale)
 
     init {
-        window.onKeyType { typedChar, keyCode ->
-            defaultKeyBehavior(typedChar, keyCode)
+        if (version >= ElementaVersion.v12) {
+            window.onKeyPressed.add { keyEvent ->
+                super.uKeyPressed(keyEvent.key, keyEvent.scanCode, keyEvent.modifiers)
+            }
+            window.onCharTyped.add { charEvent ->
+                super.uCharTyped(charEvent.codepoint)
+            }
+        } else {
+            @Suppress("DEPRECATION")
+            window.onKeyType { typedChar, keyCode ->
+                defaultKeyBehavior(typedChar, keyCode)
+            }
+
+            // This will ensure that inputs go to the old `on*(): Unit` input functions
+            // rather than the V12+ `u*(): Boolean` functions
+            inputHandler = null
         }
     }
 
@@ -60,6 +76,8 @@ abstract class WindowScreen @JvmOverloads constructor(
         window.draw(matrixStack)
     }
 
+    @Deprecated("See [ElementaVersion.V12]")
+    @Suppress("DEPRECATION")
     override fun onMouseClicked(mouseX: Double, mouseY: Double, mouseButton: Int) {
         super.onMouseClicked(mouseX, mouseY, mouseButton)
 
@@ -79,13 +97,35 @@ abstract class WindowScreen @JvmOverloads constructor(
         window.mouseClick(adjustedMouseX, adjustedMouseY, mouseButton)
     }
 
+    // Called only when ElementaVersion >= V12
+    override fun uMouseClicked(x: Double, y: Double, button: Int, modifiers: UKeyboard.Modifiers): Boolean {
+        super.uMouseClicked(x, y, button, modifiers)
+
+        // We also need to pass along clicks
+        window.mouseClick(x, y, button)
+
+        return false // TODO returning implementation, see uKeyPressed()
+    }
+
+    @Deprecated("See [ElementaVersion.V12]")
+    @Suppress("DEPRECATION")
     override fun onMouseReleased(mouseX: Double, mouseY: Double, state: Int) {
         super.onMouseReleased(mouseX, mouseY, state)
 
         // We also need to pass along mouse releases
         window.mouseRelease()
     }
 
+    // Called only when ElementaVersion >= V12
+    override fun uMouseReleased(x: Double, y: Double, button: Int, modifiers: UKeyboard.Modifiers): Boolean {
+        super.uMouseReleased(x, y, button, modifiers)
+
+        // We also need to pass along mouse releases
+        window.mouseRelease()
+
+        return false // TODO returning implementation, see uKeyPressed()
+    }
+
     @Suppress("DEPRECATION")
     @Deprecated(
         "Provided `delta` values have different units depending on Minecraft versions. See ElementaVersion.V11 for details.",
@@ -100,6 +140,8 @@ abstract class WindowScreen @JvmOverloads constructor(
         }
     }
 
+    @Deprecated("See [ElementaVersion.V12]")
+    @Suppress("DEPRECATION")
     override fun onMouseScrolled(mouseX: Double, mouseY: Double, deltaHorizontal: Double, deltaVertical: Double) {
         super.onMouseScrolled(mouseX, mouseY, deltaHorizontal, deltaVertical)
 
@@ -108,11 +150,32 @@ abstract class WindowScreen @JvmOverloads constructor(
         }
     }
 
+    // Called only when ElementaVersion >= V12
+    override fun uMouseScrolled(x: Double, y: Double, scrollX: Double, scrollY: Double): Boolean {
+        super.uMouseScrolled(x, y, scrollX, scrollY)
+
+        window.mouseScroll(scrollX, scrollY)
+
+        return false // TODO returning implementation, see uKeyPressed()
+    }
+
+    @Suppress("DEPRECATION")
+    @Deprecated("Method is not called when ElementaVersion >= V12. See ElementaVersion.V12 for details.")
     override fun onKeyPressed(keyCode: Int, typedChar: Char, modifiers: UKeyboard.Modifiers?) {
         // We also need to pass along typed keys
         window.keyType(typedChar, keyCode)
     }
 
+    // Called only when ElementaVersion >= V12
+    override fun uKeyPressed(key: Int, scanCode: Int, modifiers: UKeyboard.Modifiers): Boolean {
+        return window.keyPressed(UIKeyEvent(key, scanCode, modifiers))
+    }
+
+    // Called only when ElementaVersion >= V12
+    override fun uCharTyped(codepoint: Int): Boolean {
+        return window.charTyped(UICharEvent(codepoint))
+    }
+
     override fun initScreen(width: Int, height: Int) {
         window.onWindowResize()
 
@@ -133,7 +196,9 @@ abstract class WindowScreen @JvmOverloads constructor(
             UKeyboard.allowRepeatEvents(false)
     }
 
+    @Deprecated("[See ElementaVersion.V12] This method is not called when ElementaVersion >= V12.")
     fun defaultKeyBehavior(typedChar: Char, keyCode: Int) {
+        @Suppress("DEPRECATION")
         super.onKeyPressed(keyCode, typedChar, UKeyboard.getModifiers())
     }
 

src/main/kotlin/gg/essential/elementa/components/ScrollComponent.kt

@@ -144,6 +144,7 @@ class ScrollComponent constructor(
     private val mouseScrollLambda: UIComponent.(UIScrollEvent) -> Unit = {
         if (Window.of(this).version >= ElementaVersion.v5) {
             // new behavior
+            @Suppress("DEPRECATION") // Modifiers not provided for mouse sroll events
             val scrollDirection = if (!UKeyboard.isShiftKeyDown()) primaryScrollDirection else secondaryScrollDirection
             if (scrollDirection != null) {
                 if (onScroll(it.delta.toFloat(), isHorizontal = scrollDirection == Direction.Horizontal) || !passthroughScroll) {
@@ -157,6 +158,7 @@ class ScrollComponent constructor(
             }
         } else {
             // old behavior
+            @Suppress("DEPRECATION") // Modifiers not provided for mouse sroll events
             if (UKeyboard.isShiftKeyDown() && horizontalScrollEnabled) {
                 onScroll(it.delta.toFloat(), isHorizontal = true)
             } else if (!UKeyboard.isShiftKeyDown() && verticalScrollEnabled) {

src/main/kotlin/gg/essential/elementa/components/TreeListComponent.kt

@@ -124,6 +124,7 @@ abstract class TreeNode {
 
             arrowComponent.onMouseClick { event ->
                 event.stopImmediatePropagation()
+                @Suppress("DEPRECATION") //TODO pass modifiers when they become available, see [ElementaVersion.V12]
                 val isRecursive = UKeyboard.isShiftKeyDown()
 
                 if (opened) {