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;
@@ -70,6 +71,7 @@ public abstract class gg/essential/elementa/UIComponent : java/util/Observable,
 	protected final fun fireScrollEvent (Lgg/essential/elementa/events/UIScrollEvent;)V
 	public final fun focus ()V
 	public fun getBottom ()F
+	public final fun getCharTypedEventListeners ()Ljava/util/List;
 	public fun getChildren ()Lgg/essential/elementa/utils/ObservableList;
 	public fun getColor ()Ljava/awt/Color;
 	public final fun getComponentName ()Ljava/lang/String;
@@ -78,6 +80,7 @@ public abstract class gg/essential/elementa/UIComponent : java/util/Observable,
 	public fun getFontProvider ()Lgg/essential/elementa/font/FontProvider;
 	public fun getHasParent ()Z
 	public fun getHeight ()F
+	public final fun getKeyPressedEventListeners ()Ljava/util/List;
 	public final fun getKeyTypedListeners ()Ljava/util/List;
 	public final fun getLastDraggedMouseX ()Ljava/lang/Double;
 	public final fun getLastDraggedMouseY ()Ljava/lang/Double;
@@ -120,8 +123,10 @@ public abstract class gg/essential/elementa/UIComponent : java/util/Observable,
 	public fun mouseRelease ()V
 	public fun mouseScroll (D)V
 	public fun mouseScroll (DD)V
+	public final fun onCharTyped (Lkotlin/jvm/functions/Function2;)Lgg/essential/elementa/UIComponent;
 	public final fun onFocus (Lkotlin/jvm/functions/Function1;)Lgg/essential/elementa/UIComponent;
 	public final fun onFocusLost (Lkotlin/jvm/functions/Function1;)Lgg/essential/elementa/UIComponent;
+	public final fun onKeyPressed (Lkotlin/jvm/functions/Function2;)Lgg/essential/elementa/UIComponent;
 	public final fun onKeyType (Lkotlin/jvm/functions/Function3;)Lgg/essential/elementa/UIComponent;
 	public final fun onKeyTypeConsumer (Ljava/util/function/BiConsumer;)V
 	public final fun onMouseClick (Lkotlin/jvm/functions/Function2;)Lgg/essential/elementa/UIComponent;
@@ -243,7 +248,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 +283,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 +766,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 +786,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
@@ -2717,6 +2729,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 +2768,13 @@ 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 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 = "474+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,29 @@ 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)
+     * As well as all related setup functions. E.G. `onKeyType { }`
+     * For now any key listeners setup via the old methods will still be called.
+     *
+     * Also see [gg.essential.elementa.events.UIKeyEvent] & [gg.essential.elementa.events.UICharEvent].
+     *
+     * See [UniversalCraft#125](https://github.com/SparkUniverse/UniversalCraft/pull/125) for the underlying changes.
+     */
+    V12,
+
     ;
 
     /**
@@ -258,14 +280,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].")
     val keyTypedListeners = mutableListOf<UIComponent.(typedChar: Char, keyCode: Int) -> Unit>()
+    // Requires ElementaVersion.V12
+    val keyPressedEventListeners = mutableListOf<UIComponent.(keyEvent: UIKeyEvent) -> Boolean>()
+    // Requires ElementaVersion.V12
+    val charTypedEventListeners = 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,23 @@ abstract class UIComponent : Observable(), ReferenceHolder {
         mouseScrollListeners.add { method.accept(it) }
     }
 
+    @Deprecated("See [ElementaVersion.V12].")
     fun onKeyType(method: UIComponent.(typedChar: Char, keyCode: Int) -> Unit) = apply {
+        @Suppress("DEPRECATION")
         keyTypedListeners.add(method)
     }
 
+    fun onKeyPressed(method: UIComponent.(keyEvent: UIKeyEvent) -> Boolean) = apply {
+        keyPressedEventListeners.add(method)
+    }
+
+    fun onCharTyped(method: UIComponent.(keyEvent: UICharEvent) -> Boolean) = apply {
+        charTypedEventListeners.add(method)
+    }
+
+    @Deprecated("See [ElementaVersion.V12].")
     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 { keyEvent ->
+                super.uKeyPressed(keyEvent.key, keyEvent.scanCode, keyEvent.modifiers)
+            }
+            window.onCharTyped { 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,34 @@ 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 {
+        uSuperInputHandler().uMouseClicked(x, y, button, modifiers)
+
+        // We also need to pass along clicks
+        window.mouseClick(x, y, button)
+
+        return false // TODO returning implementation, see uKeyPressed()
+    }
+
+    @Suppress("DEPRECATION", "OVERRIDE_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 {
+        uSuperInputHandler().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 +139,7 @@ abstract class WindowScreen @JvmOverloads constructor(
         }
     }
 
+    @Suppress("DEPRECATION", "OVERRIDE_DEPRECATION")
     override fun onMouseScrolled(mouseX: Double, mouseY: Double, deltaHorizontal: Double, deltaVertical: Double) {
         super.onMouseScrolled(mouseX, mouseY, deltaHorizontal, deltaVertical)
 
@@ -108,11 +148,32 @@ abstract class WindowScreen @JvmOverloads constructor(
         }
     }
 
+    // Called only when ElementaVersion >= V12
+    override fun uMouseScrolled(x: Double, y: Double, scrollX: Double, scrollY: Double): Boolean {
+        uSuperInputHandler().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 +194,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())
     }