window

scene

the control tree, layout, theme, tween and the overlay slot

mirrored from window/cpp/window.core/scene/README.md, which is the only copy of this text. edits made here are overwritten the next time the site builds

control_t n the tree, the containers n layout, theme_t n its tokens, tween over one shared ticker, n the overlay slot

links into window.core. control_t issues no draw call of its own, thats what keeps the core from drawing n what makes the dependency direction hold

fileitemwhat it is
control.hP1.18control_t, paint_ctx_t n the tree, header only
theme.hP1.20theme_t, the token set, header only
layout.hP1.19the containers, the flow cursor n scrollbar_t, header only
tween.hP1.22tweens_t, the curves n the one shared ticker, header only
scroll_view.hP1.36scroll_view_t, the second scroll model, header only

the overlay slot, P1.21, is in control.h rather than a file of its own, it is a slot n a paint order n not a type, n P1.F.1 let one popup nest inside another without the slot moving at all

scroll_view_t, P1.36, the SECOND scroll model

there are two scroll models in here on purpose n the item says outright they stay separate. this is the one that scrolls one offset over content a subclass paints itself, no child controls, nothing flowed, nothing placed. that is a list of ten thousand rows, a text document, a waveform, anything where a control per item would be absurd

container_t, P1.19scroll_view_t, P1.36
what scrollsreal child controlswhatever the subclass paints
howtheir boxes moveone offset handed to a hook
the barscrollbar_t, a real control, draggabledrawn in paint, an indicator, not draggable
inputevery child routes on its ownthe wheel n whatever the subclass takes
the cullthe dirty box, through viewport()the subclass skips, off the top it was handed

folding them into one type would mean the half you were not using is dead weight in every instance of it, n the two have almost no code in common once you look, one moves boxes n the other moves a float

the hook, n why the top is handed rather than read

draw_content(_ctx, _top) is the one thing a subclass has to write, n content_height() is the other. the top is handed in rather than read off the view, so the hook is a pure function of what it was given, n so a subclass can SKIP anything landing outside _ctx.clip instead of drawing ten thousand rows for the twenty you can see

the box it is handed is the content box, i.e. the bar strip is already off the width, so content never runs under the indicator. the clip is narrowed to the viewport, n the empty clip means the whole frame trap P1.19 already walked into is handled the same way here

the clip is pushed by us n not left to the subclass, bc a subclass that forgot would draw over whatever sits beside it n the bug would read as a layout fault somewhere else entirely. checked as PIXELS, the hook draws a slab five times the height of the view n a pixel below the edge has to survive it, bc a hook that ran says nothing about where its ink landed

the bar is an indicator n is deliberately not draggable

it is drawn straight in paint rather than being a control, so there is nothing in the tree to hit test, nothing to hover n nothing to drag. a draggable bar wants container_ts scrollbar_t, which is a real control n already exists, n having both would be two answers to one question

it draws nothing at all when it all fits, n the strip goes back to the content, which is the whole difference between an indicator n a decoration. the 24px thumb floor is kept but the reason changes, container_t wants it so a thumb stays grabbable where ours is never grabbed n wants it so a two pixel sliver over a very long document is still visible

not interactive, n the wheel reaching it anyway

interactive() is left false, the same call container_t makes, so a view laid over something eats nothing meant for it. the wheel still arrives, bc P1.19 widened hit_node to push a node that CONTAINED the point either way, which is the exact bug that change fixed. that is checked here as well as there, a scroller with nothing clickable anywhere in its tree still takes the wheel

on_wheel returns false when it could not move, so a view at either end hands the wheel back to whatever is around it, which is P1.19s rule read the same way by both models

the re-clamp

on_resized calls refresh, which re-reads content_height() n clamps the offset. growing the view shrinks the overflow, n an offset left where it was would sit past the end n leave blank space under the content, which looks like the content failed to load rather than like a scroll bug

content_height() is asked on every clamp rather than being pushed in through a setter, so content that changed under the view cannot leave a stale height behind. a subclass whose height is expensive to work out caches it itself. refresh() is public for exactly the case where content changed n no resize happened to notice

tween, P1.22

a tween walks a float from where it is now to where you want it, over a duration, through an easing curve, n fires once when it lands. that is the whole product, n every slide n fade n smooth value in phase 7 is made of it. ported from ../../../gui/tween.ahk, which is the specification n not the source

one ticker over a registry n not a timer per tween, which is the item saying so. every live tween sits in one list n one tick steps the lot, so "is anything still running" is a question with one answer rather than one per animation, n that answer is running()

the parking half, which is the criterion n the bit worth reading twice

the ticker parks itself when the last tween lands. an idle widget sitting on a live timer is exactly the cost this whole lib exists to avoid, n in the ahk lib it was worse than a cost, a self scheduling SetTimer made win.dump() hang outright

park() asks the LIST rather than being told, so every path that empties it parks for free n none of them can forget, a natural landing, a cancel, a finish, cancel_all, finish_all, cancel_for, the enabled switch going off, n the dtor. all eight are checked

we do not own the timer n never reach for one. arming n parking are two callbacks a driver fills in, the same bargain the P1.11 router made with SetCapture, so a check drives the whole of this with no window n no clock anywhere near it, n a real host hangs SetTimer n KillTimer off the pair

the park is the LAST thing tick does, after the on_done callbacks fire. that is not tidiness, a chain (an on_done starting the next leg) would otherwise park the ticker n arm it again a line later, which on a real host is a genuine KillTimer n SetTimer pair for nothing. checked as a park count of zero across the join

the tick order, n why it is that order

  1. the walk writes values n flags the landed ones, n fires nothing, so a callback cannot reach in n resize the list being walked
  2. the compact drops the flagged ones
  3. the callbacks fire, so the manager is settled when one asks it a question
  4. the park, last, see above

the four places this goes past the ahk source, n why

  • a caller gets an ID back n not a pointer. the ahk one hands out a TweenHandle n gets away with it bc ahk refcounts, where a handle to a thing that frees itself the instant it lands is a dangling read waiting. a stale id is simply not found n every call taking one is a no-op on it
  • one invalidate after the write n not one either side. the ahk _apply wrote a controls y straight onto the object so the write itself moved the box n the spot it left needed asking for too. a box here only ever moves through set_bounds, n that already invalidates the one it left n the one it landed on, so the second one would be a repeat of the same box
  • the delta is clamped n the first tick is a zero. a stall (a breakpoint, a big load, a monitor change) comes back with a huge delta, n without the clamp every live tween teleports to its end at once, which reads as the animation never having run. the seed is the same trap at the other end, a manager built at 0 n first ticked with a real clock would be handed the whole uptime of the machine
  • it is an instance n not a static class. Tween being global in ahk is ahk having no other option, n a global here would carry state from one check in the runner into the next

time arrives as a parameter

tick(_now_ms) is handed the drivers clock, which it already has. that keeps a check deterministic with no sleeping n no flake, n it is still the real wall clock, so the ahk files own warning still holds, ticks do not land dead on 16ms n a tween counting them rather than measuring them runs long

what a tween does not do is keep its target alive

it holds a float* n a borrowed control_t*, so whatever owns those has to outlive the tween or kill it on the way out, same deal as the theme pointer n the overlay slot in control.h. cancel_for is the one line version of that n a control taking its float with it is expected to call it

colour_t::mixed already lives in core/colour.h, so the ahk Tween.mix was not ported. a colour crossfade is a tween on a 0..1 float n a mixed in the paint, which is one concept instead of two

the overlay slot, P1.21

one detached control a root holds, painted after its whole tree n hit tested before it. that is the dropdown popup, the tooltip, the toast, anything that has to float over the window without being part of the layout underneath it

detached means out of m_children. layout never sees it, the subtree walk never reaches it as a child, nothing frees it with the tree, n whoever opened it owns it. the ONE thing it does get is the roots parent pointer, without going into the children list, bc a popup with no root has nowhere to send an invalidate n no theme to resolve against. that is the only place in control.h where a control has a parent it is not a child of, n both ends are handed back, clear_overlay takes it n so does the roots dtor, which is why that dtor has a body at all

paint_tree n paint_subtree are split for it. paint_subtree is the recursive walk n children only ever call that one, paint_tree is what a frame calls n it does the subtree then the overlay. so the slot is ROOT ONLY structurally rather than by a flag, a slot set on a child is simply never read, n the popup is painted OUTSIDE the walk so the trees dirty box skip cannot take it down with it

no second flush pass, which is free rather than earned

the criterion says a popup over text renders with the text below it covered n needs no second flush. the ahk lib queued text n flushed it once a frame, bc gdi drew into the same dib outside gdi+, so an overlay had to force its own second flush or the trees text drew straight back over the popup

blend2d rasterises text through the same context as every other call, so paint order is draw order n the whole dance disappears. G-window-5 closed that off back in 2026-08-13 n renderer-b2d.ahk:451 already had flush_text as an empty body saying so. it is checked with real dwrite text under a real popup in ONE begin_frame / end_frame pair, n the check counts pixels rather than calls, the covered half has to come out perfectly uniform n the half beside it has to still have text in it

what it cost the router, two virtuals

input_target_t gained overlay() n dismiss_overlay(). the router asks the root for its popup the same way it asks for children, so it never learns what a popup IS

  • hit_test gives the overlay first refusal, n it lives in that one function so the press n the hover n the re-hover after a release all read the same rule from one place. a miss falls straight through to the tree, i.e. an overlay is not modal
  • mouse_wheel puts the overlays path on first, so a scrolling popup over a scrolling page scrolls the popup, n hands the wheel back to the page once it has hit its end, which is P1.19s rule unchanged
  • mouse_down dismisses on a press outside, n outside is measured against the popups box n not against what the hit test found, bc a popup with an inert background hit tests to nothing n a click on its own empty half would otherwise close it. any button does it, a right click away from a dropdown is still away from it. P1.F.1 moved the WHERE of that test into dismiss_overlay, see below, the rule n the reason are unchanged

the swallow, n why it is not optional

dismiss_overlay hands back whether the press was swallowed, n it is swallowed when it landed on the popups OWNER. without that, one click on a dropdown header closes the popup n then reaches the header, which reopens it, so the dropdown never appears to shut n the bug reads as the dismiss not working at all. the ahk lib carries the same rule n the same comment

opening one while another is up dismisses the old one, callback n all, rather than stacking, n that is still true after P1.F.1, see below for how a chain is built without touching it

nesting, P1.F.1, a popup inside another one

a menu with a flyout is two popups at once, n the way it is done here is that the slot never moved. finns call 2026-09-11, the alternative was making m_overlay a STACK n it lost bc gui_control_set_overlay already ships n already means REPLACE, so a stack changes what a shipped export does

a menu owns its submenus as ordinary CHILDREN, placed outside its own box. the root lends out exactly one slot, the chain lives inside that one overlay subtree, n a level deeper than the first is somebody elses child rather than a second slot. so the abi contract does not move, no export changes meaning, n a dismiss of the lot is still one operation

the cost is that a child outside its parents box was a thing the lib dropped in two places, n this is the three pieces that fixed it

reach(), the box a subtree can LAND in

a third virtual on input_target_t, n it answers bounds() for everything that does not opt in. a control that calls set_spills(true) answers its own box with every childs reach folded into it, recursively, so a chain of any depth is one rect by the time anything reads it

  • the hit walk descends on it n still lands on bounds(), so a control cannot grow a hit area by answering a bigger rect. hit_node walked on bounds() alone before, so it stopped at the menu n never looked at the flyout hanging past it
  • the paint cull reads it too, else a dirty box touching only the flyout skipped the pair, n the flyout is the half of the pair that is on screen
  • nothing caches it. a cached one would have to be pushed up the whole ancestry on every move, n a menu has a handful of children where a canvas has hundreds, which is the whole reason the flag is opt in rather than always on
  • a control that spills should not also be a viewport, the two say opposite things about where the children are allowed to be

nested() n close_nested(), the chain

a level answers with whichever of its children is open under it, n null when it is the deepest. a chain n not a list bc a level owns at most one open child, which is what tools/shell/menu/lib/popup.ahk landed on too. control_t never learns what a level IS, it walks what it is handed, the same bargain the router made with overlay()

the dismiss closes a DEPTH

dismiss_overlay walks the levels n closes what hangs under the deepest one holding the press, deepest bc levels are free to overlap n the deepest is the one painted on top. a press on none of them takes the whole chain

the router stopped deciding what outside means at P1.F.1, it hands every press over n reads the same swallow answer back. that is not a widening for its own sake, a chain has no one box to be outside of, n the union of the levels has corners no level actually fills, so an L shaped menu n flyout had a dead patch that closed nothing

layout, P1.19

an imgui shaped layout on a retained tree, which sounds like a contradiction n is not. a container_t carries a CURSOR, add drops a child where the cursor is n advances it, n same_line n spacing n new_line nudge it in between. what makes it retained is that the hints each add consumed are stamped onto the child, flow_hints_t over in control.h, so a relayout replays the same flow off the tree with nobody calling anything again

column_t n row_t n child_t n columns_t are all thin things on top of that, a flow direction n a couple of defaults each, n columns_t is the only one that overrides anything. that override is a sizing pass n never a placing one, it settles every columns width n hands the placing straight back to the base, where the ahk version copies the whole cursor loop n gets to disagree with what it copied

the three things worth knowing before you touch it

there is ONE flow pass n not two. the ahk lib places a child incrementally inside add n then replays the whole thing inside relayout, which is two bodies of the same arithmetic that can drift. run_flow is the only one here, add gets its placement by relayouting, n the SAME function measures without placing when it is asked to. so a container cannot measure one way n place another, which is the failure the two body shape has waiting in it

a RESIZE drives it n a MOVE never does, through control_t::on_resized, the hook P1.18 left the hole for. a move already carried every descendant through offset_tree so re-placing them is the same answer at a cost, where a resize is the case where the children stayed put n the box around them changed shape. the pair is checked by changing what a child MEASURES first, bc a re-flow landing on the same answer looks exactly like no re-flow at all

the scroller culls through the DIRTY BOX n not through a cull of its own. viewport narrows the box paint_tree hands the children, so a child scrolled fully out fails the skip that was already there for a subtree outside the frame. one test doing both jobs, rather than two that can fall out of step. the trap in it is that an EMPTY clip means the whole frame n not nothing, so intersecting a viewport with one has to take the viewport whole or a scroller reads as skip every child

the four places this goes past the ahk source, n why

  • fixed_w n fixed_h are a size OVERRIDE n not the current box. the ahk _place asks the child what its width is n falls back on measure, so the width layout wrote LAST time is the answer THIS time n a control whose measure changed keeps a stale box forever. a separate field cannot go stale
  • the viewport keeps the bar strip in it, so scrollbar_t is inside the clip n paints like any other child. the ahk one clips to the content box, which puts the bar outside it, so it is skipped in the loop n painted again unclipped after, i.e. a second paint path for no gain
  • measure adds the pad on BOTH edges, the ahk one adds a single pad n leaves the far side short
  • flow_t::none really does nothing, where the ahk add skips the flow on it n relayout places anyway, so a manual container re-flowed itself the moment its bounds moved

the wheel, n why input.cpp moved

the criterion is that the wheel finds the scrollable under the cursor, n the router already walks the hit path deepest first offering on_wheel out until something takes it. what it did not do is put a node on that path when nothing interactive was found under it, n a scrolling container is deliberately not interactive (it must not eat a click meant for a button inside it), so a wheel over a gap in its content reached nothing

so hit_node now pushes a node that CONTAINED the point either way. the return value is untouched, so hover n press n focus route exactly as they did n only the wheel reads the path, n the root only case that used to sit under the loop is gone bc the root is on the path whenever it contained the point

container_t::on_wheel returns false when it could not move, which is the other half. that is what lets a list that has hit its end give the wheel back to the page around it, n it is checked with a real scroller inside a real scroller rather than as a return value on its own

scrollbar_t, n why it is in window.core

BUILD.md says the core does not draw a widget, n this draws. it is not a widget though, it is a PART of the scroller, it is only ever built by a container, it draws nothing that is not that containers own overflow, n a scroller that could not draw its own bar would be a container missing half of itself. the ahk lib put it in the same file for the same reason, controls/container.ahk:483

it is a real control n not a painted decoration, which the item says outright, so it is in the tree, the plain P1.11 hit test finds it n a drag on it arrives through the router with no special case anywhere. the thumb is the viewports share of the content with a 24px floor, bc a thumb thinner than a fingertip is a bar you can see n cannot grab, n a press OFF the thumb jumps it to the click n then grabs it centred where a press ON it keeps the offset so it never leaps out from under the cursor

theme_t, P1.20

a plain struct of tokens, no resolve step n no lookup by name, a control reads ctx.theme.accent n that is the whole api. ported from ../../../gui/theme.ahk with the names kept, so a control ported from the ahk lib reads the token it always did

the DEFAULTS are the dark theme, so nothing is selected or loaded for a window to look right, same bargain the ahk file made

the mac aqua skin n its mac_* tokens are out of scope per the item. the traffic light tl_* family is IN though, finn asked for it by name 2026-08-28, n the split holds up on its own, a close n minimise n maximise dot is window chrome any titlebar can wear, where mac_* is a whole control look that only means something once there is a control to put it on

the field paint_ctx_t existed for

paint_ctx_t gained a theme field n paints signature did not move, which is the P1.18 promise being spent for the first time n the reason that struct is a struct

a theme is inherited down the tree with a per-control override, bc the criterion says a swap repaints every control that USES it n that only means something if some controls do not. a subtree carrying its own theme does not resolve to the swapped one so it is not repainted, n an invisible subtree is never painted so it is owed nothing, both checked as negatives rather than only as a count

the resolve happens on the way down inside paint_tree, one compare per node, which is why that function grew a parameter where paint did not. theme() does walk up, but only for a question asked from outside a frame, a paint reads ctx.theme which was already resolved

control_t, P1.18

a control owns a box, some state, a parent, its children, a measure n a paint. it derives from input_target_t bc P1.11 built the router against that interface on purpose n said so in the header, so the whole of the input half arrived already done n the router was not touched

the three things that go wrong if you write it by feel

bounds are in WINDOW coords n not parent relative. that is inherited from input_target_t n from the ahk lib before it, n it is what makes a hit test a plain containment test rather than a walk down the tree accumulating an offset. the price is that a move has to shift every descendant, offset_tree is that price paid in one place

n a resize does NOT move children, only a move does. placing children inside a box that changed size is layout n that is P1.19, so a bare control_t resizing is never secretly doing a layout. both halves are checked, bc a tree that moved children on a resize would look right until the first real container

every state change routes through invalidate, n a move invalidates TWO boxes, the one it left n the one it landed on. doing only the second still looks right on a flat background, the stale block only shows once there is something underneath it, which is the same bargain host_t::invalidate_move made

the callback lives on the ROOT n invalidate walks up to find it. a child holding one would have to be re-plumbed every time a subtree moved between parents, n a subtree built before it is added to anything would have nowhere to hold one. a control with no root callback invalidates into nothing, which is what every control in a headless check does n is not an error

paint n paint_ctx_t

paint is virtual n takes a paint_ctx_t&, n the criterion is that its signature never has to move again. a phase 7 control wanting something nobody thought of today gets a new FIELD on that struct, every existing override carries on compiling n nothing is swept. theme_t is the first one queued up

control_t::paint is EMPTY n that is the criterion, not tidiness. a bare control issues no draw call at all, so a container is invisible for free, n window.core never draws a widget. it is checked as PIXELS rather than as a call count, a bare control is painted straight over a patch of known ink n the ink has to survive it, bc that is the only version of the claim that cannot be fooled

paint_tree is the walk n it is deliberately not virtual, so a control can change what it looks like n never what painting a subtree MEANS. it skips two ways, an invisible subtree goes entirely n so does one that does not touch the dirty box, which is where the P1.12 model starts paying for itself

what the struct grew at P1.E.2, and the one thing to get right about visible()

delta, visible(box), px(v) and snapped(v) all landed together, and the promise above is exactly what paid for it, three of those are pure additions and the fourth is a field, so not one override moved

visible() IS NOT the version the deleted render/paint_ctx.h was carrying. that one read !clip.empty() && clip.hits(box), which culls everything when the clip is empty. an empty clip in this lib means the whole frame and not nothing, the rule paint_subtree walks the tree on and the rule scroll_view_t narrows a viewport on, so the live one reads clip.empty() || clip.hits(box). copy the dead spelling back in and every control vanishes on precisely the frames that repaint the lot, which is the quietest possible way to be wrong, mutant 261 is that exact copy and the empty clip check kills it

delta arrives as a parameter the whole way down and nothing in the lib reads a clock for it, same deal tweens_t::tick already made. the abi frame path feeds it straight off tweens_t::delta(), i.e. the already clamped already zeroed-on-the-first step the tweens just took, so there is one clock per window and no second measurement to disagree with it. a caller painting a tree by hand gets 0, and 0 is the right answer, a frame with no clock behind it has no delta and an animation stepping by 0 holds still

tweens_t stores that step before its no-tweens-live early out, not after, bc a paint asks for the delta every frame and an idle window is the common case, so the other placement would freeze the number at whatever the last animated frame happened to take

children paint in order so the last one is on top, n input.h reads them BACKWARDS in the hit test for exactly that reason. those two agreeing is checked in one breath, bc the shape it goes wrong in is a control you can see n cannot click

ownership

children are std::unique_ptr<control_t>, so dropping a root frees the whole subtree on one line. remove_child hands the unique_ptr back OUT rather than destroying it, so a subtree can be re-parented without dying in between, n a caller that just wants it gone drops the return on the floor

the dtor is virtual, n it is not this file that makes it so, input_target_t declares one n that makes every dtor below it implicitly virtual. so dropping the override here changes NOTHING, measured, a mutation doing exactly that survived the whole suite bc it is a no-op

what the override actually buys is a gate. take the virtual off input_target_t n this file stops compiling, C3668, method with override specifier did not override any base class methods, n taking it off here as well only moves the same error onto the test controls dtor. so the slicing leak is a BUILD ERROR guarded two deep n never a runtime leak, which is worth more than a check

the live control counter is guarding a different leak, a subtree that is never freed at all. that one is real n it is caught, a mutation releasing the unique_ptr in remove_child takes the suite down rather than passing

the tween slots, P1.22s other half

two slots on the ROOT, set_tweens n set_leaving, both walked up to the same way m_invalidate is, so a child moving between parents is never re-plumbed. set_tweens hands back a tweens_t* a control can ask things of, n set_leaving fires from EVERY controls dtor so whatever was animating one can drop it

they are two slots n not one bc tween.h includes THIS file. tweens_t can only be forward declared here, so a dtor defined in this header can HOLD a tweens_t* but can never call a method on one. the callback is the way round that, n it costs a line of wiring at the call site

m_leaving is declared ABOVE m_children on purpose

moving it below them is a real bug n a quiet one. members destruct in REVERSE declaration order, so anything declared under the children is already gone by the time the children are destroyed, n every child dtor reaching up to the root would read a std::function whose lifetime had ended

m_invalidate sits BELOW the children n is only safe bc nothing reads it from a dtor. the three control teardown check is what pins this, it counts three reports off a root plus two descendants

the gap, n why it is a trade rather than a miss

automatic cleanup covers the whole TREE going, not one child being removed. remove_child sets m_parent to null before it hands the subtree back, so a child that is removed n then dropped has no root left to reach n reports nothing. cancelling for that one stays the callers cancel_for

it is that way bc the same call is what RE-PARENTS a subtree, n a re-parent must not cancel anything. firing on detach would kill the fade on a control that is only moving house. the common case, a window closing n taking its tree with it, is the one that works, n there is a check pinning the gap so it is recorded rather than folklore

the measurer slot, P1.42, i.e. what stopped a flow guessing

a THIRD root only slot, set_measurer, walked up to exactly like the two above so nothing is re-plumbed when a subtree moves. it holds a const text_measure_t* n never a whole renderer_t, see ../render/README.md for why that half is its own interface

it is the whole of the measure cliff. a run width comes off a FONT, the only thing holding one was the renderer, n a renderer only existed inside a frame, so label_t::measure had nothing to answer with n handed back its current box. a column flowing a fresh label placed it at nothing n caught up one frame later, n on tab_bar_t it was worse than late, a tab with no width is never painted n the paint was the only thing that could have measured it

null is the honest headless answer n not a fault. a tree in a check with nothing wired falls back on the box it already has, same as before, bc a guess off the character count is a number that looks measured n is not. hook_root in the abi hands over the windows own renderer, which has held a font cache since create, n unhook_root puts the slot back to null when that renderer dies with its window

On this page