forge-draggable-windows

Add draggable windows with z-ordering and collapse/expand to any application that uses ForgeUiContext. Based on UI Lesson 10.

When to use

• You need draggable floating panels that users can rearrange
• You need z-ordering so overlapping windows draw and receive input correctly
• You need a collapse toggle to let users minimize windows to their title bar
• You want deferred draw ordering (per-window draw lists sorted by z at frame end)
• You need input routing that respects z-order (foreground windows block clicks to background windows in overlap regions)

Key API calls

• forge_ui_wctx_init(wctx, ctx) -- initialize a window context wrapping an existing ForgeUiContext
• forge_ui_wctx_free(wctx) -- free per-window draw list buffers
• forge_ui_wctx_begin(wctx) -- begin a frame (determines hovered window from previous frame data, resets per-frame state)
• forge_ui_wctx_end(wctx) -- end a frame (sorts draw lists by z_order, appends to main buffers in back-to-front order)
• forge_ui_wctx_window_begin(wctx, id, title, state) -- begin a window (returns true if expanded, false if collapsed or invalid)
• forge_ui_wctx_window_end(wctx) -- end a window (computes content height, draws scrollbar, restores main buffers)

Correct order

1. Initialize a ForgeUiWindowContext wrapping your ForgeUiContext
2. Each frame: call forge_ui_ctx_begin(), then forge_ui_wctx_begin()
3. Declare windows: window_begin / widgets / window_end blocks
4. End frame: call forge_ui_wctx_end(), then forge_ui_ctx_end()

Widget IDs must be unique and each window reserves three IDs: id for the window/drag handle, id+1 for the scrollbar, id+2 for the collapse toggle.

When window_begin returns false (collapsed or invalid), skip all child widgets and do not call window_end.

Key concepts

1. ForgeUiWindowState -- application-owned persistent state: rect (position/size, updated by drag), scroll_y (content scroll offset), collapsed (toggled by clicking the collapse button), z_order (draw priority, higher = on top, updated on click)
2. Grab offset -- stored on the press frame as (mouse - rect.origin); used during drag to maintain the relative click position
3. Bring-to-front -- on any mouse press inside a window, set z_order = max(all z) + 1
4. Deferred draw -- per-window vertex/index buffers assembled at frame end in back-to-front z-order
5. Input routing pre-pass -- wctx_begin scans previous frame's window rects to find the topmost window under the mouse; widgets in other windows silently fail hit tests
6. Keyboard suppression -- widgets in covered windows preserve visual focus but do not process keyboard input (games can suppress window input for game controls without the window appearing unfocused)

Common mistakes

1. Forgetting wctx_end() -- without it, per-window draw lists are never appended to the main buffer and nothing renders
2. Calling window_end when collapsed -- window_begin returns false for collapsed windows; calling window_end in that case corrupts state
3. ID collisions -- each window needs 3 contiguous IDs (id, id+1, id+2); overlapping ranges cause unpredictable hot/active behavior
4. Not checking wctx_init return -- returns false if the context pointer is null or allocation fails
5. Resetting grab offset -- the ForgeUiWindowContext grab offset must persist across frames (not reset by wctx_begin) because drags span multiple frames
6. Ignoring one-frame lag -- hovered_window_id uses previous frame data; z-order changes take effect on the next frame's input routing

Ready-to-use template

Three overlapping windows

#include "ui/forge_ui.h"
#include "ui/forge_ui_window.h"

/* Window IDs (each reserves id, id+1, id+2) */
#define ID_WIN_A  100
#define ID_WIN_B  200
#define ID_WIN_C  300

/* Widget IDs inside windows */
#define ID_CB_1   110
#define ID_SLIDER 120

/* Widget dimensions */
#define LABEL_HEIGHT     26.0f
#define CHECKBOX_HEIGHT  28.0f
#define SLIDER_HEIGHT    30.0f
#define SLIDER_MIN        0.0f
#define SLIDER_MAX      100.0f

/* Application-owned window state (persists across frames) */
ForgeUiWindowState win_a = {
    .rect = { 30.0f, 30.0f, 260.0f, 280.0f },
    .scroll_y = 0.0f,
    .collapsed = false,
    .z_order = 0
};
ForgeUiWindowState win_b = {
    .rect = { 200.0f, 80.0f, 260.0f, 200.0f },
    .scroll_y = 0.0f,
    .collapsed = false,
    .z_order = 1
};

/* Application-owned widget state */
bool option_a = true;
float slider_val = 50.0f;

/* --- Frame loop --- */

ForgeUiContext ctx;
forge_ui_ctx_init(&ctx, &atlas);

ForgeUiWindowContext wctx;
forge_ui_wctx_init(&wctx, &ctx);

/* Each frame: */
forge_ui_ctx_begin(&ctx, mouse_x, mouse_y, mouse_down);
ctx.scroll_delta = scroll_delta;
forge_ui_wctx_begin(&wctx);

/* Window A: settings */
if (forge_ui_wctx_window_begin(&wctx, ID_WIN_A, "Settings", &win_a)) {
    (void)forge_ui_ctx_checkbox_layout(
        wctx.ctx, ID_CB_1, "Option A", &option_a, CHECKBOX_HEIGHT);
    (void)forge_ui_ctx_slider_layout(
        wctx.ctx, ID_SLIDER, &slider_val,
        SLIDER_MIN, SLIDER_MAX, SLIDER_HEIGHT);
    forge_ui_wctx_window_end(&wctx);
}

/* Window B: status */
if (forge_ui_wctx_window_begin(&wctx, ID_WIN_B, "Status", &win_b)) {
    forge_ui_ctx_label_layout(wctx.ctx, "Hello, windows!",
                              LABEL_HEIGHT, 0.9f, 0.9f, 0.9f, 1.0f);
    forge_ui_wctx_window_end(&wctx);
}

forge_ui_wctx_end(&wctx);   /* sorts and assembles draw lists */
forge_ui_ctx_end(&ctx);      /* finalizes hot/active state */

/* Use ctx.vertices, ctx.indices, ctx.vertex_count, ctx.index_count
 * for rendering — vertices are in correct z-sorted draw order. */

Key observations

• Pass wctx.ctx (not &ctx) to widget functions inside a window -- the window context redirects the vertex/index pointers
• window_begin returns false for both collapsed windows and validation failures -- never call window_end when it returns false
• Widget return values (checkbox_layout, slider_layout) indicate whether the value changed, not success/failure -- (void) cast is fine when the result is not needed
• Set ctx.scroll_delta before wctx_begin so the input routing pre-pass can associate the scroll with the correct window

Reference

• UI Lesson 10 -- Windows -- full walkthrough with diagrams and 12-frame demo
• UI Lesson 09 -- Panels and Scrolling -- the panel infrastructure that windows extend
• UI Lesson 08 -- Layout -- the layout system used for widget positioning inside windows
• common/ui/forge_ui_window.h -- window system implementation
• common/ui/forge_ui_ctx.h -- the underlying immediate-mode UI context