UIComponent: Rewrite floating API

The old API is difficult to work with because it will continue to render
floating components even if they've been removed from the component
tree. Additionally it can CME if components are removed from the
floating list during rendering, further complicating the workarounds
required.

This new API fixes the issue by tracking when components are
removed/added from/to the tree and updating its internal floating list
accordingly.
It also allows setting the floating state at any time, even before the
component has a parent, another thing the old API did not support.

The order in which floating components appear also differs in the new
API. While the old API showed floating components in the order in which
they were set to be floating, this often isn't all too useful when the
order in which components are added/removed to/from the tree is not
particularly well defined. As such, the new API chooses to instead order
floating components in exactly the same way as they appear in the
component tree (pre-order tree traversal, i.e. first parent, then
children). This results in consistent ordering and is generally the
order you want for nested floating components to behave in a useful way.

This has been implemented as a new, completely separate API instead of
an ElementaVersion primarily to easy migration (the new API can be used
even with Windows still on older ElementaVersions; both APIs can be used
at the same time) but also because there isn't anything reasonable the
old-API methods in `Window` could do in the new version, they really
should have been internal to begin with.

GitHub: #154

Author: Johni0702

api/Elementa.api

@@ -100,6 +100,7 @@ public abstract class gg/essential/elementa/UIComponent : java/util/Observable,
 	public fun insertChildAt (Lgg/essential/elementa/UIComponent;I)Lgg/essential/elementa/UIComponent;
 	public fun insertChildBefore (Lgg/essential/elementa/UIComponent;Lgg/essential/elementa/UIComponent;)Lgg/essential/elementa/UIComponent;
 	public fun isChildOf (Lgg/essential/elementa/UIComponent;)Z
+	public final fun isFloating ()Z
 	public fun isHovered ()Z
 	protected final fun isInitialized ()Z
 	public fun isPointInside (FF)Z
@@ -144,6 +145,7 @@ public abstract class gg/essential/elementa/UIComponent : java/util/Observable,
 	public final fun setFontProvider (Lgg/essential/elementa/font/FontProvider;)Lgg/essential/elementa/UIComponent;
 	public final fun setHeight (Lgg/essential/elementa/constraints/HeightConstraint;)Lgg/essential/elementa/UIComponent;
 	protected final fun setInitialized (Z)V
+	public final fun setIsFloating (Z)V
 	public final fun setLastDraggedMouseX (Ljava/lang/Double;)V
 	public final fun setLastDraggedMouseY (Ljava/lang/Double;)V
 	public final fun setMouseScrollListeners (Ljava/util/List;)V
@@ -1150,7 +1152,6 @@ public final class gg/essential/elementa/components/inspector/Inspector : gg/ess
 	public fun <init> (Lgg/essential/elementa/UIComponent;Ljava/awt/Color;Ljava/awt/Color;F)V
 	public fun <init> (Lgg/essential/elementa/UIComponent;Ljava/awt/Color;Ljava/awt/Color;FLgg/essential/elementa/constraints/HeightConstraint;)V
 	public synthetic fun <init> (Lgg/essential/elementa/UIComponent;Ljava/awt/Color;Ljava/awt/Color;FLgg/essential/elementa/constraints/HeightConstraint;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public fun animationFrame ()V
 	public fun draw (Lgg/essential/universal/UMatrixStack;)V
 }
 

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

@@ -53,8 +53,11 @@ abstract class UIComponent : Observable(), ReferenceHolder {
 
     private var childrenLocked = 0
     init {
-        children.addObserver { _, _ -> requireChildrenUnlocked() }
-        children.addObserver { _, event -> setWindowCacheOnChangedChild(event) }
+        children.addObserver { _, event ->
+            requireChildrenUnlocked()
+            setWindowCacheOnChangedChild(event)
+            updateFloatingComponentsOnChangedChild(event)
+        }
     }
 
     open lateinit var parent: UIComponent
@@ -110,7 +113,7 @@ abstract class UIComponent : Observable(), ReferenceHolder {
     private var heldReferences = mutableListOf<Any>()
 
     protected var isInitialized = false
-    private var isFloating = false
+    private var isLegacyFloating = false
 
     private var didCallBeforeDraw = false
     private var warnedAboutBeforeDraw = false
@@ -479,7 +482,7 @@ abstract class UIComponent : Observable(), ReferenceHolder {
         val parentWindow = Window.of(this)
 
         this.forEachChild { child ->
-            if (child.isFloating) return@forEachChild
+            if (child.isLegacyFloating || child.isFloating) return@forEachChild
 
             // If the child is outside the current viewport, don't waste time drawing
             if (!this.alwaysDrawChildren() && !parentWindow.isAreaVisible(
@@ -980,8 +983,65 @@ abstract class UIComponent : Observable(), ReferenceHolder {
      * Floating API
      */
 
+    @set:JvmName("setIsFloating") // `setFloating` is taken by the old API
+    var isFloating: Boolean = false
+        set(value) {
+            if (value == field) return
+            field = value
+            recomputeFloatingComponents()
+        }
+
+    internal var floatingComponents: List<UIComponent>? = null // only allocated if used
+
+    private fun recomputeFloatingComponents() {
+        val result = mutableListOf<UIComponent>()
+        if (isFloating) {
+            result.add(this)
+        }
+        for (child in children) {
+            child.floatingComponents?.let { result.addAll(it) }
+        }
+        if ((floatingComponents ?: emptyList()) == result) {
+            return // unchanged
+        }
+        floatingComponents = result.takeUnless { it.isEmpty() }
+
+        if (this is Window) {
+            if (hoveredFloatingComponent !in result) {
+                hoveredFloatingComponent = null
+            }
+        } else if (hasParent) {
+            parent.recomputeFloatingComponents()
+        }
+    }
+
+    private fun updateFloatingComponentsOnChangedChild(possibleEvent: Any) {
+        @Suppress("UNCHECKED_CAST")
+        when (val event = possibleEvent as? ObservableListEvent<UIComponent> ?: return) {
+            is ObservableAddEvent -> {
+                val (_, child) = event.element
+                if (child.floatingComponents != null) {
+                    recomputeFloatingComponents()
+                }
+            }
+            is ObservableRemoveEvent -> {
+                val (_, child) = event.element
+                if (child.floatingComponents != null) {
+                    recomputeFloatingComponents()
+                }
+            }
+            is ObservableClearEvent -> {
+                if (floatingComponents != null) {
+                    recomputeFloatingComponents()
+                }
+            }
+        }
+    }
+
+    @Deprecated("The legacy floating API does not behave well when a component is removed from the tree.", ReplaceWith("isFloating = floating"))
+    @Suppress("DEPRECATION")
     fun setFloating(floating: Boolean) {
-        isFloating = floating
+        isLegacyFloating = floating
 
         if (floating) {
             Window.of(this).addFloatingComponent(this)

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

@@ -25,7 +25,7 @@ class Window @JvmOverloads constructor(
     private var systemTime = -1L
     private var currentMouseButton = -1
 
-    private var floatingComponents = mutableListOf<UIComponent>()
+    private var legacyFloatingComponents = mutableListOf<UIComponent>()
 
     var hoveredFloatingComponent: UIComponent? = null
     var focusedComponent: UIComponent? = null
@@ -98,7 +98,7 @@ class Window @JvmOverloads constructor(
 
             hoveredFloatingComponent = null
             val (mouseX, mouseY) = getMousePosition()
-            for (component in floatingComponents.reversed()) {
+            for (component in allFloatingComponentsInReverseOrder()) {
                 if (component.isPointInside(mouseX, mouseY)) {
                     hoveredFloatingComponent = component
                     break
@@ -159,7 +159,7 @@ class Window @JvmOverloads constructor(
     fun drawFloatingComponents(matrixStack: UMatrixStack) {
         requireMainThread()
 
-        val it = floatingComponents.iterator()
+        val it = legacyFloatingComponents.iterator()
         while (it.hasNext()) {
             val component = it.next()
             if (ofOrNull(component) == null) {
@@ -168,6 +168,9 @@ class Window @JvmOverloads constructor(
             }
             component.drawCompat(matrixStack)
         }
+        for (component in floatingComponents ?: emptyList()) {
+            component.drawCompat(matrixStack)
+        }
     }
 
     override fun mouseScroll(delta: Double) {
@@ -178,7 +181,7 @@ class Window @JvmOverloads constructor(
         requireMainThread()
 
         val (mouseX, mouseY) = getMousePosition()
-        for (floatingComponent in floatingComponents.reversed()) {
+        for (floatingComponent in allFloatingComponentsInReverseOrder()) {
             if (floatingComponent.isPointInside(mouseX, mouseY)) {
                 floatingComponent.mouseScroll(delta)
                 return
@@ -211,7 +214,7 @@ class Window @JvmOverloads constructor(
             }
         }
 
-        for (floatingComponent in floatingComponents.reversed()) {
+        for (floatingComponent in allFloatingComponentsInReverseOrder()) {
             if (floatingComponent.isPointInside(mouseX.toFloat(), mouseY.toFloat())) {
                 floatingComponent.mouseClick(mouseX, mouseY, button)
                 dealWithFocusRequests()
@@ -335,29 +338,36 @@ class Window @JvmOverloads constructor(
      * Floating API
      */
 
+    private fun allFloatingComponentsInReverseOrder(): Sequence<UIComponent> =
+        (floatingComponents ?: emptyList()).asReversed().asSequence() +
+                // Note: needs to be copied to guard against CME and for backwards compatibility
+                legacyFloatingComponents.reversed()
+
+    @Deprecated("Internal API.", replaceWith = ReplaceWith("component.setFloating(true)"))
     fun addFloatingComponent(component: UIComponent) {
         if (isInitialized) {
             requireMainThread()
         }
 
-        if (floatingComponents.contains(component)) return
+        if (legacyFloatingComponents.contains(component)) return
 
-        floatingComponents.add(component)
+        legacyFloatingComponents.add(component)
     }
 
+    @Deprecated("Internal API.", replaceWith = ReplaceWith("component.setFloating(false)"))
     fun removeFloatingComponent(component: UIComponent) {
         if (isInitialized) {
             requireMainThread()
         }
 
-        floatingComponents.remove(component)
+        legacyFloatingComponents.remove(component)
     }
 
     /**
      * Overridden to including floating components.
      */
     override fun hitTest(x: Float, y: Float): UIComponent {
-        for (component in floatingComponents.reversed()) {
+        for (component in allFloatingComponentsInReverseOrder()) {
             if (component.isPointInside(x, y)) {
                 return component.hitTest(x, y)
             }

src/main/kotlin/gg/essential/elementa/components/inspector/Inspector.kt

@@ -45,6 +45,8 @@ class Inspector @JvmOverloads constructor(
             height = ChildBasedSizeConstraint()
         }
 
+        isFloating = true
+
         container = UIBlock(backgroundColor).constrain {
             width = ChildBasedMaxSizeConstraint()
             height = ChildBasedSizeConstraint()
@@ -230,28 +232,7 @@ class Inspector @JvmOverloads constructor(
         }
     }
 
-    private fun UIComponent.isMounted(): Boolean =
-        parent == this || (this in parent.children && parent.isMounted())
-
-    override fun animationFrame() {
-        super.animationFrame()
-
-        // Make sure we are the top-most component (last to draw and first to receive input)
-        Window.enqueueRenderOperation {
-            setFloating(false)
-            if (isMounted()) { // only if we are still mounted
-                setFloating(true)
-            }
-        }
-    }
-
     override fun draw(matrixStack: UMatrixStack) {
-        // If we got removed from our parent, we need to un-float ourselves
-        if (!isMounted()) {
-            Window.enqueueRenderOperation { setFloating(false) }
-            return
-        }
-
         separator1.setWidth(container.getWidth().pixels())
         separator2.setWidth(container.getWidth().pixels())
 

unstable/layoutdsl/src/main/kotlin/gg/essential/elementa/layoutdsl/containers.kt

@@ -4,8 +4,6 @@ package gg.essential.elementa.layoutdsl
 
 import gg.essential.elementa.UIComponent
 import gg.essential.elementa.components.ScrollComponent
-import gg.essential.elementa.components.UIBlock
-import gg.essential.elementa.components.Window
 import gg.essential.elementa.constraints.ChildBasedMaxSizeConstraint
 import gg.essential.elementa.constraints.ChildBasedSizeConstraint
 import gg.essential.elementa.constraints.WidthConstraint
@@ -18,8 +16,6 @@ import gg.essential.elementa.common.HollowUIContainer
 import gg.essential.elementa.common.constraints.AlternateConstraint
 import gg.essential.elementa.common.constraints.SpacedCramSiblingConstraint
 import gg.essential.elementa.state.v2.*
-import gg.essential.universal.UMatrixStack
-import java.awt.Color
 import kotlin.contracts.ExperimentalContracts
 import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
@@ -168,80 +164,9 @@ fun LayoutScope.floatingBox(
         callsInPlace(block, InvocationKind.EXACTLY_ONCE)
     }
 
-    fun UIComponent.isMounted(): Boolean =
-        parent == this || (this in parent.children && parent.isMounted())
-
-    // Elementa's floating system is quite tricky to work with because components that are floating are added into a
-    // persistent list but will not automatically be removed from that list when they're removed from the component
-    // tree, and as such will continue to render.
-    // This class tries to work around that by canceling `draw` and automatically un-floating itself in such cases,
-    // as well as automatically adding itself back to the floating list when it is put back into the component tree.
-    class FloatableContainer : UIBlock(Color(0, 0, 0, 0)) {
-        val shouldBeFloating: Boolean
-            get() = floating.get()
-
-        // Keeps track of the current floating state because the parent field of the same name is private
-        @set:JvmName("setFloating_")
-        var isFloating: Boolean = false
-            set(value) {
-                if (field == value) return
-                field = value
-                setFloating(value)
-            }
-
-        override fun animationFrame() {
-            // animationFrame is called from the regular tree traversal, so it's safe to directly update the floating
-            // list from here
-            isFloating = shouldBeFloating
-
-            super.animationFrame()
-        }
-
-        override fun draw(matrixStack: UMatrixStack) {
-            // If we're no longer mounted in the component tree, we should no longer draw
-            if (!isMounted()) {
-                // and if we're still floating (likely the case because that'll be why we're still drawing), then
-                // we also need to un-float ourselves
-                if (isFloating) {
-                    // since this is likely called from the code that iterates over the floating list to draw each
-                    // component, modifying the floating list here would result in a CME, so we need to delay this.
-                    Window.enqueueRenderOperation {
-                        // Note: we must not assume that our shouldBe state hasn't changed since we scheduled this
-                        isFloating = shouldBeFloating && isMounted()
-                    }
-                }
-                return
-            }
-
-            // If we should be floating but aren't right now, then this isn't being called from the floating draw loop
-            // and it should be safe for us to immediately set us as floating.
-            // Doing so will add us to the floating draw loop and thereby allow us to draw later.
-            if (shouldBeFloating && !isFloating) {
-                isFloating = true
-                return
-            }
-
-            // If we should not be floating but are right now, then this is similar to the no-longer-mounted case above
-            // i.e. we want to un-float ourselves.
-            // Except we're still mounted so we do still want to draw the content (this means it'll be floating for one
-            // more frame than it's supposed to but there isn't anything we can really do about that because the regular
-            // draw loop has already concluded by this point).
-            if (!shouldBeFloating && isFloating) {
-                Window.enqueueRenderOperation { isFloating = shouldBeFloating }
-                super.draw(matrixStack)
-                return
-            }
-
-            // All as it should be, can just draw it
-            super.draw(matrixStack)
-        }
-    }
-
-    val container = FloatableContainer().apply {
-        componentName = "floatingBox"
-        setWidth(ChildBasedSizeConstraint())
-        setHeight(ChildBasedSizeConstraint())
+    val box = box(modifier, block)
+    effect(box) {
+        box.isFloating = floating()
     }
-    container.addChildModifier(Modifier.alignBoth(Alignment.Center))
-    return container(modifier = modifier, block = block)
+    return box
 }