[ui] add documentation to new delayed tooltip rendering, clean up and…

… improve implementation of handled screen changes

src/main/java/io/wispforest/owo/ui/base/BaseOwoHandledScreen.java

@@ -267,6 +267,63 @@ public void dispose() {
     @Override
     protected void drawBackground(DrawContext context, float delta, int mouseX, int mouseY) {}
 
+    @Override
+    protected void drawSlotHighlightBack(DrawContext context) {
+        context.push().translate(0, 0, this.getLayerZOffset(HandledScreenLayer.SLOT));
+        super.drawSlotHighlightBack(context);
+    }
+
+    @Override
+    protected void drawSlotHighlightFront(DrawContext context) {
+        super.drawSlotHighlightFront(context);
+        context.pop();
+    }
+
+    @Override
+    protected void drawItem(DrawContext context, ItemStack stack, int x, int y, @Nullable String amountText) {
+        context.push().translate(0, 0, this.getLayerZOffset(HandledScreenLayer.CURSOR_ITEM));
+        super.drawItem(context, stack, x, y, amountText);
+        context.pop();
+    }
+
+    @Override
+    protected void drawMouseoverTooltip(DrawContext context, int x, int y) {
+        context.push().translate(0, 0, this.getLayerZOffset(HandledScreenLayer.ITEM_TOOLTIP));
+        super.drawMouseoverTooltip(context, x, y);
+        context.pop();
+    }
+
+    /**
+     * Return the z-offset to apply to rendering the given {@code layer}
+     */
+    protected int getLayerZOffset(HandledScreenLayer layer) {
+        return layer == HandledScreenLayer.CURSOR_ITEM ? -6900 : 300;
+    }
+
+    /**
+     * Different layers of handled screen rendering, the z-offset
+     * of which can be adjusted in an owo screen using {@link #getLayerZOffset(HandledScreenLayer)}
+     */
+    protected enum HandledScreenLayer {
+        /**
+         * The items in all slots, along with the highlight
+         * of the hovered slot
+         */
+        SLOT,
+
+        /**
+         * The item currently held by the cursor. More specifically, any item
+         * rendered through the {@link #drawItem(DrawContext, ItemStack, int, int, String)} method
+         */
+        CURSOR_ITEM,
+
+        /**
+         * The tooltip of an item in a slot. More specifically, any tooltip
+         * rendered through {@link #drawMouseoverTooltip(DrawContext, int, int)}
+         */
+        ITEM_TOOLTIP
+    }
+
     public class SlotComponent extends BaseComponent {
 
         protected final Slot slot;
@@ -331,44 +388,4 @@ public void updateY(int y) {
             ((SlotAccessor) this.slot).owo$setY(y - BaseOwoHandledScreen.this.y);
         }
     }
-
-    @Override
-    protected void drawSlotHighlightBack(DrawContext context) {
-        context.translate(0, 0, getOffsetAmount(true));
-
-        super.drawSlotHighlightBack(context);
-    }
-
-    @Override
-    protected void drawSlotHighlightFront(DrawContext context) {
-        super.drawSlotHighlightFront(context);
-
-        context.translate(0, 0, -getOffsetAmount(true));
-    }
-
-    @Override
-    protected void drawItem(DrawContext context, ItemStack stack, int x, int y, @Nullable String amountText) {
-        var offset = getOffsetAmount(false);
-
-        context.translate(0, 0, offset);
-
-        super.drawItem(context, stack, x, y, amountText);
-
-        context.translate(0, 0, -offset);
-    }
-
-    @Override
-    protected void drawMouseoverTooltip(DrawContext context, int x, int y) {
-        var offset = getOffsetAmount(false);
-
-        context.translate(0, 0, offset);
-
-        super.drawMouseoverTooltip(context, x, y);
-
-        context.translate(0, 0, offset);
-    }
-
-    protected int getOffsetAmount(boolean slotRendering) {
-        return 300;
-    }
-}
+}

src/main/java/io/wispforest/owo/ui/core/OwoUIAdapter.java

@@ -26,6 +26,12 @@
  * even if you choose to not use {@link io.wispforest.owo.ui.base.BaseOwoScreen}
  * you can always simply add it as a widget and get most of the functionality
  * working out of the box
+ * <p>
+ * To draw the UI tree managed by this adapter, call {@link OwoUIAdapter#render(DrawContext, int, int, float)}.
+ * Note that this does not draw the current tooltip of the UI - this must be done separately
+ * by invoking {@link #drawTooltip(DrawContext, int, int, float)}. If in a scenario with multiple adapters
+ * or other sources rendering UI elements to the screen, it is generally desirable to delay tooltip
+ * drawing until after all UI is drawn to avoid layering issues.
  *
  * @see io.wispforest.owo.ui.base.BaseOwoScreen
  */
@@ -198,6 +204,13 @@ public void render(DrawContext context, int mouseX, int mouseY, float partialTic
         }
     }
 
+    /**
+     * Draw the current tooltip of the UI managed by this adapter. This method
+     * must not be called without a previous, corresponding call to {@link #render(DrawContext, int, int, float)}
+     *
+     *
+     * @since 0.12.19
+     */
     public void drawTooltip(DrawContext context, int mouseX, int mouseY, float partialTicks) {
         if (!(context instanceof OwoUIDrawContext)) context = OwoUIDrawContext.of(context);
         var owoContext = (OwoUIDrawContext) context;