window

the controls

how a control is built and what every one of them shares

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

the concrete control set ported off the ahk lib one at a time, panel n label n button through to the table n the code editor, each shipping a themed default paint you override only when the shape differs

links into window.widgets, which is the half that draws. nothing in window.core may reference anything in here

filewhat
controls.cppa placeholder translation unit so the project archives a real .lib, phase 7 fills it
countdown.hP1.14 n P1.15, the countdown bar, the day count n the layout n the paint
clickable.hP1.27, the press state every interactive control carries
icon_draw.hP1.27, one icon onto a renderer, i.e. the call icon_ts cache exists for
panel.hP1.27, a backing, a fill n a border n nothing else
label.hP1.27, one run of text
button.hP1.27, a label n a reacting backing, with an optional leading icon
icon_button.hP1.27, the square one where the icon IS the control
checkbox.hP1.27, a tick box n an optional label
toggle.hP1.27, a pill track n a sliding knob
list.hP1.28, a row per item, one pill n one callback
table.hP1.28, a pinned header over a body of scrolling rows
tab_bar.hP1.28, a strip of tabs over one visible page
dropdown.hP1.28, a header n a popup list that opens into the overlay slot
text_input.hP1.29 n P1.38, the field, the caret n the selection n the patch undo
text_area.hP1.29 n P1.38, the LINE MODEL, logical lines against drawn rows, n wrap
code_editor.hP1.29, monospace metrics, a gutter, the current line band n auto indent
animate.hP1.30, drive one of a controls floats, or snap it when nothing can drive it
tone.hP1.30, tone_t n the semantic colour a status control wears
badge.hP1.30, a tinted status pill, a marker n never a target
progress.hP1.30, a track with a fill up to value over max
key_value.hP1.30, a muted key n a bright value pinned to opposite edges
icon_view.hP1.30, one icon fit square in a box, the picture to icon_button.hs target
radio.hP1.30, radio_group_t n radio_t, the group owns the pick
segmented.hP1.30, a raised track with n equal segments, a radio group wearing a strip
stepper.hP1.30, the stacked up n down pair, it steps on the PRESS
slider.hP1.30, a value dragged along an inset track
toast.hP1.30, toast_t n toast_host_t, cards stacked into a corner with a lifecycle
nav_list.hP1.30, the sidebar spelling of list_t, sections n all
window_chrome.hP1.39, the hover revealed strip, the folded pill n the fold itself
menu_item.hP1.F.2, the menu item TREE, plain data with nothing that draws in it
menu.hP1.F.2, menu_row_t n menu_t, the popup every menu shape reuses

the menu, P1.F.2

menu_t is a vertical run of items in a floating panel, opened at a point n dismissed by a press outside or escape, n it is the ONE control P1.F.3 to P1.F.5 all reuse. they differ in what opens them n what they are anchored to n not in what they are

it is a port of D:/documents/AutoHotkey/tools/shell/menu/ with the nodes menu merged into it, finns call 2026-09-12, so the structure n the names n the decl api come from that tool n apps/nodes/src/menu.cpp was MINED for the four things it had already proved on these headers, the placement, the search filter, the scroll n the painted search field

the tree is data, menu_item.h

nothing in that file includes control.h n nothing in it draws, which is what lets a second view over the same tree exist later. six kinds, action submenu separator header toggle radio, built through statics n chainable setters

menu.set_items({
    menu_item_t::header("edit"),
    menu_item_t::action("Copy", copy_tag, "ctrl+c").with_icon(&glyph),
    menu_item_t::sep(),
    menu_item_t::toggle("Snap to grid", snap_tag, true),
    menu_item_t::submenu("Recent", { menu_item_t::action("one", one_tag) })
});

menu_normalise fills the derived fields, the depth n a path id slugged off the label under its parents id, so a copy under file is file/copy n cannot collide with a copy elsewhere in the tree. that id is what P1.F.6 reports across the abi, where tag is the callers own number n we never read it

a row is a control, n it is deliberately NOT interactive

every row is a menu_row_t that measures n paints itself, the ahk shape, while the menu owns the list n drives the selection. what it does not do is take the mouse, bc the router hands focus to whatever was pressed n drops it on anything that does not take focus, so a row taking the press would kill the menus keyboard the moment you clicked a submenu or a header, i.e. the two rows that leave the menu up. the menu hit tests its own rows instead, which is what the ahk popup does anyway through its on_hover hook

it scrolls by placing a window of rows, never by a viewport()

a viewport confines children to the parents box n set_spills says the opposite, n P1.F.3 hangs a flyout outside us, so the two cannot both be true of one menu. the rows outside the scroll window are simply not visible, which the paint walk n the hit test n reach() all already understand

typing splits on whether there is a field to put it in

a menu wearing a search field filters as you type, three match bands, n one without it does type-ahead, jumping to the next row starting with what was typed n cycling on a repeat. both are in the item n only one of them can have the letter. the search field is PAINTED n never a text_input_t child, which is the one piece of the nodes shape that survived whole

an on_target row, i.e. one that acts on what was right clicked rather than being a thing to add, drops out the moment a term is typed. typing means you are hunting n a Delete sat among the matches is one keystroke from something nobody asked for

the hover revealed chrome n the folded pill, P1.39

three types in one header bc they only mean anything together, window_chrome_t the strip of buttons that is not on screen while you are reading the card, shrink_pill_t the thing the card folds down to, n shrink_t the fold. ported off ../../../gui/controls/window-chrome.ahk n window.ahk:525

this is the FLOATING CARD case n never the full width titlebar, which is the chromed host n P1.13. a bar the width of the window lands on top of whatever the card already draws up there n reads as the window drawing over itself rather than as chrome arriving, so the strip is only as wide as its own buttons n it tucks into the corner

the hover is a WINDOW level one

that is the whole point of it n it is the distinction P1.11 already drew. reaching for the close button leaves the body n every control on the way, so anything hiding itself on a control leave starts hiding exactly as you go to press it

the ahk original polls the cursor against the window rect on a SetTimer bc it has no other signal, where input_router_t already keeps one, so window_hover is wired to set_window_hover_fn n there is no timer anywhere in the port. it still only acts on a CHANGE, so a poll is just as correct a driver as the routers edge is, n that is exactly why a dismiss has to clear the flag, the cursor is still on the window n a flag left set reads as nothing changed

the window arrives as two callbacks

shrink_t takes a "where is the window" n a "put it here", the same bargain tweens_t makes with its ticker n the P1.11 router makes with SetCapture, so the whole fold is drivable with no window anywhere near it. the cursor arrives as a parameter for the same reason, the ahk one reads MouseGetPos n a check cannot argue with one

the traps

  • what is remembered is the fold DELTA n not the old corner, so an unfold works off wherever the pill is NOW. a pill left alone grows back exactly where the card was n a pill you dragged across the screen takes the card with it. the delta is read back AFTER the place, so a clamp at the edge of a monitor is folded into it rather than lost
  • a strip that stopped taking presses the moment it started leaving would be wrong on screen, so the visibility only drops on the tweens done callback. the paint bails before re-placing its buttons once the slide reads zero, which is what leaves stale boxes there for the flag to cover
  • the strip places itself in the reveal as well as in the paint. a control whose box is empty misses the dirty test in paint_subtree n is skipped, so one that only ever placed itself in a paint would be waiting forever on the frame it cannot be given, same trap as tab_bar.h
  • shrink_t has to outlive the pill it was given, it hands one a drag callback holding its own this, same borrowed bargain as the theme pointer n the same declaration order trap as a radio group
  • the pill draws NO backing of its own, same as the ahk original. a folded layered window is 260 by 36 of whatever the card already paints, so the pill SHAPE is the windows own rounded fill n this control is the title n the one button sat on it

the remaining controls, P1.30

ten of them, n the shape of the batch is three groups rather than one

  • four take no input at all, badge n progress n key value n icon view, so they come straight off control_t n a press over one carries on to whatever is underneath, the bargain panel_t makes
  • four take a press, radio n segmented n stepper n slider, so they come off clickable_t
  • two carry more than a control, toast owns a LIFECYCLE n nav list owns a data shape

three things worth not relitigating

  • nav_list_t IS a list_t. the ahk pair are two classes n NavItem._draw is a line for line copy of the list row, same pill n same hover backing n same four row_* tokens, so porting them apart would have been two copies of one row to keep in step forever. the one thing a nav had that a list did not was the SECTION HEADER, n that went into list.h as a flag on the item
  • the toast dwell is a TWEEN n not a timer. the ahk version ramps a 0 to 255 alpha off its own 16ms SetTimer, where P1.22 already owns the clock in here, so a second ticker beside it would be two answers to one question. the fade is one float n the dwell is a float driven over the visible time whose done callback starts the fade out
  • a finished toast is reaped by the HOST in its own paint n never removes itself from inside a tween callback, bc a tween holds a raw float* into the control it drives. the flag is the durable half n the card is invisible for the frame it waits

--dump widgets renders all ten into one card, the router hover included, so the look is something you LOOK at rather than something the checks describe to you

out of scope, the mac skin variants on radio n stepper n slider, n the tone default glyphs on a toast, which the ahk version loads off disk per tone where an icon in here is borrowed

the tier one controls, P1.27

six of them, ported off ../../../gui/controls/, which is the specification n not the source. every one is header only for the same reason countdown.h is, cpp/BUILD.md says an agent touches no .vcxproj n none of them wants a translation unit anyway

--dump controls renders all six into one card, hover included, so the look is something you LOOK at rather than something the checks describe to you

clickable_t is the base n it is not the base of everything

hovered n pressed n the hover fade n the click callback, i.e. exactly what the ahk Control base carries n what control_t deliberately does not. the core owns the tree n the router interface, this is what a WIDGET does with the events coming off it

a panel n a label derive straight off control_t, so the four that take a press are the four that pay for the state. clicked() is virtual n it is the one place a click fires, which is how a checkbox flips itself before the callback reads it without re-writing on_release

a leave drops the PRESS as well as the hover, so a drag off a control cancels rather than arming a click that lands whenever the cursor wanders back

the one float rule

every animated bit of these is ONE float with the whole drawing read off it, the hover fade, the tick reveal, the knob slide. two numbers would let the track finish crossfading before the knob arrived, n that drift is invisible in a check n obvious on screen

they all BOOT PARKED at whatever state they were built in, so a checkbox that starts checked is checked on its first frame rather than ticking itself on while somebody is looking at it

the traps

  • disabled beats a half faded hover, n it is read BEFORE the mix n not after. folding it in after lands on the same colour for a cold button n only goes wrong mid fade, i.e. exactly when nobody is looking. set_enabled(false) while m_hot is still ramping is the case
  • the press SNAPS n the hover FADES, deliberately n not by accident, a click that eased in feels soft where a hover that snapped feels twitchy
  • a panel is NOT interactive, so one laid over a button lets the click through to it. that is checked through the real router finding the button, n never as the flag reading false
  • a run cannot be measured without a renderer, n a renderer only exists inside a frame. holding the POINTER was the first thing tried n it is a dangling read the moment the frame ends, which crashed the runner. the MEASUREMENT is the durable half, so it is taken during paint n kept, n a control whose text changed is one frame behind until it has been drawn once
  • the ring on a checkbox goes as soon as the fill starts arriving, under 0.05, else it sits under the accent coming in n reads as an edge the box does not have

what is deliberately not in here

the mac (aqua) skin variants, which the item says outright, so there is one look per control n no branch on a style string that only ever has one value. focus, n these are not focusable either, tab traversal has no plan item yet

the collection controls, P1.28

four of them, ported off the same ../../../gui/controls/ originals, n every one header only for the same reason the tier one six are. a list n a table n a tab bar n a dropdown, n the dropdown is in this item rather than a later one bc it is mostly a list_t in the P1.21 overlay slot

every row is a real control

that is the shape all four share n it is what makes hover n press n the click route through the P1.11 router with no special case anywhere. list_row_t n table_row_t both derive clickable_t, so the press state n the hover fade n the one clicked hook come for free n a row only writes what a ROW does with them, which is pick itself

a container_t n never a scroll_view_t. the rows are controls whose BOXES move when it scrolls, which is the container model, where the other one owns nothing n paints its own content. a list of ten thousand rows really does want that other one, n the item puts virtualised rows out of scope

the table is two containers n that is the point

the header has to STAY PUT while the rows scroll under it, so the body is the scroller n the table is not, n the header is simply a child of ours the body never reaches. the tables own flow is none bc a header pinned above a scroller is not a thing a cursor can express

a column resize is a drag on the header n never a splitter control. the header hit tests its whole strip n works out which edge the press landed within reach of, which keeps a five column table at two controls instead of nine

the underline is one float

the tab bars sliding underline reads BOTH its x n its width off one m_ul_t, where the ahk original drives an x tween n a w tween side by side. two tweens over one duration land a frame apart often enough to see, which shows up as the pill arriving at the new tab still wearing the old tabs width. one float cannot come apart from itself, n the check asserts the two fractions are the same number mid slide

the traps

  • a rebuild must NOT call clear_children. container_t holds a borrowed pointer to the scrollbar it built n clear_children frees that bar without telling it, so the next place_scrollbar writes through a dangling pointer n the crash lands nowhere near the rebuild that caused it. remove the rows one at a time n the bar is left alone
  • a zero wide control is never painted, so it can never measure itself. a tab button with no measured run has no width, n a zero wide box misses the dirty test in paint_subtree n is skipped, i.e. it would be waiting forever on the one frame it cannot be given. the BAR measures the whole strip out of its own paint instead, which works bc a parent paints before its children
  • rows go in through add_child n not through container_t::add. add re-flows the whole container per row, so a rebuild of a hundred rows is a hundred flow passes for one answer. the only thing add does beyond ownership is stamp the pending cursor nudges, n none of these want any
  • a new column width is stamped as a HINT n not as a box. writing the box straight lasts until the next flow overwrites it, so the column springs back the moment anything relayouts
  • a dropdown does NOT close on losing focus, deliberately, where the ahk one does. P1.21 already dismisses on a press outside the popup n swallows that press when it landed on the owner, n closing on blur as well would fire FIRST, bc focus moves on the press n a list row takes no focus, so a click on the popup would shut it before the row it landed on had been told anything

a list caps to its own box now, P1.E.5, and the default CHANGED

this is a behaviour change to every existing list_t, said loudly bc there is no changelog to put it in. set_view_h used to be the only thing that could turn a list into a scroller, and a list nobody had called it on read m_view_h == 0 as infinitely tall, so a box shorter than the rows drew them straight out the bottom, no bar and no clip, and the tail of the list was simply gone. the box height was sitting right there the whole time. the first app built on this lib lost the bottom of a 30 row palette to it and the fix on their side was one line they had no way to know they needed

the cap in force is now the explicit one when a caller set one, else our own box. set_view_h is unchanged and still wins, it is the override for the case where the two genuinely differ

what did NOT change is measure, and that is the careful half. capped_h() still answers off m_view_h alone, bc a measure says how tall we WANT to be and capping that to the box we already have is circular, a list in a column would ask for its current height and could never grow to fit its rows. the box only ever decides whether we OVERFLOW, never what we ask for. mutant 277 is exactly that circular version and the column case kills it

the 0 guard survived the change and matters more than it looks. a bare ctor never calls refresh_scroll at all, so the reachable zero-box paths are rebuild and on_resized, i.e. filling a pane or laying it out before anything has measured it, and without the guard both turn a list into a scroller before it has a height. a check written against a freshly constructed list proves nothing here, which is how mutant 278 survived its first run

what is deliberately not in here

multi select, sorting, column reorder, closable or reorderable tabs, a type to search dropdown, n virtualised rows, which the item says outright. focus traversal too, so tab cannot REACH a dropdown, only a click can, n that is a missing plan item rather than a decision taken here

the text controls, P1.29

three of them n each one derives the last, text_input_t the field, text_area_t the same editing core in two dimensions, n code_editor_t the area wearing a monospace face. header only like the rest, n the editor reaches into nothing, its four features all land through hooks the area already had, inner for the gutter n paint_backing for the current line band n paint_overlay for the numbers n paint_row_text for the colours

every offset is a byte offset

stepped a whole utf8 sequence at a time through core/utf8.h, where the ahk counts CHARACTERS n gets away with it bc an ahk string is utf16. insert n delete n selection n the clipboard n undo are all byte based, which is exactly why the area could inherit the whole editing core untouched, not one of them cares that a newline is in the buffer

the hard part is MEASUREMENT n not editing

a renderer only exists inside a frame, so a click cannot measure anything, where the ahk original calls measure_text live out of on_press bc an ahk window hands a renderer out whenever it is asked. the answer is a PREFIX WIDTH CACHE, adv[i] being the width of the first i bytes, rebuilt on the way through a paint n only when the run or the font moved under it, n every click n caret n selection reads out of that instead

a cold control answers 0 to every measurement, which is the honest state n is checked as one, i.e. a field that has never painted knows nothing about where its glyphs sit n says so rather than guessing

note: P1.42 is a DIFFERENT problem n did not touch this. that one is a control knowing its own SIZE before its first paint, where this is a control knowing where inside itself a given byte lands, n measure_prefixes still takes a renderer_t& n still runs from paint n nowhere else

the area keeps two layers apart

a line_span_t is a LOGICAL line, a byte range between newlines, n it is what an offset n a prefix cache n the text itself are indexed by. a visual_row_t is a DRAWN row, a slice of one logical line, n it is what up n down n home n end n a click n the vertical scroll all move by

with wrap off the two are one to one n the whole thing collapses back to what the ahk does, so it is one code path with the interesting case switched on rather than two that have to agree

the area scrolls for real, P1.A.2

the wheel and the every frame re-clamp were here from P1.29, what P1.A.2 added is the api under them, scroll_to and scroll_by and max_scroll, and the wheel goes through the same scroll_by a caller gets rather than moving the offset itself. m_max_scroll is STAMPED every layout rather than worked out where it is needed, bc max_scroll and the bar and inner all want that one answer and only a layout knows the row count, so a read before the first paint is zero and says so

the bar takes its width out of inner and not off the control, so a wrapped row breaks before the bar rather than running under it. that is what makes a layout TWO PASSES on the frame a bar appears, one to find out there is overflow and one to rebuild the rows against the narrower box. two settles it, bc a narrower content only ever makes MORE rows, so a bar that went on cannot come back off in the same frame, and a frame that wanted no bar never asks for the second pass. code_editor_t takes the same strip out of its own inner override through the shared bar_strip, so the two boxes cannot disagree about how wide a bar is

the bar is DRAWN and is not a control, the same call scroll_view_t makes, so there is nothing in the tree to hit test and nothing to grab. it is a position indicator on purpose, a draggable one wants container_ts scrollbar_t which already exists

page up and page down are move_row with a bigger step, which is why that function takes a count now instead of a direction, and the step is read off the box every time, the whole rows that fit less one of overlap. off the box and never a stored number bc an area is resizable and a fixed count is wrong the moment somebody drags an edge

a seeded area opens at offset 0. a FIELD opens at the end bc a one line value is there to be appended to, a DOCUMENT opens at the top bc that is where you read from, so the area undoes what the field ctor did. this is the change that reached furthest, eleven checks were quietly leaning on the old caret

undo holds patches n not snapshots

the range that moved plus both spellings of it, n the diff runs when a step CLOSES, so a run of typing collapsing into one undo is free rather than something to detect. one full copy is held while a step is open, m_before, n that is the only copy anywhere in here

the traps

  • text_input_t derives control_t n NOT clickable_t. a field has no click callback n no hover fade, which is the two things clickable_t exists to carry, n it wants a press flag of its OWN as the guard a drag select reads. so it takes the four router calls straight n owns m_pressed
  • an edit THROWS THE ROW LIST AWAY rather than leaving it to rebuild, bc a stale row is an index into a line that is no longer there, n an empty list is the state every lookup already answers safely for
  • wrap takes a LIMIT n not a mode, a column count or a width, i.e. one walk asking a different question. a column limit costs nothing, n a WIDTH limit is the one spelling that measures the whole document
  • the up/down goal column is in PX n not in characters, which is where this leaves the ahk. a column is right for monospace n makes the caret wander sideways in anything proportional

two places this beats the ahk on purpose

  • ctrl arrow uses THREE CLASSES, whitespace n word (alnum plus underscore plus anything non ascii) n punctuation, n it stops on every change, where the ahks _word_left runs to the nearest space so foo.bar(baz) is one word. finns call, n the plan item was amended to say so. the P1.38 ctrl backspace eats off the SAME walk, so the jump n the delete read as one key with a different verb
  • escape only COLLAPSES the selection where the ahk drops focus, finns call, bc focus lives on the router n a control has no way to reach it

what is deliberately not in here

syntax highlighting, the item says so outright. the HOOK is ported bc paint_row_text was made virtual for exactly that, n a hook with no highlighter on it draws precisely what the area drew, so what is missing is a set of language rules n not the machinery to hang them off. the ahk json_highlight is not ported

the editor also keeps wrap OFF, the plans own call, bc a wrapped row is a slice of a line n code reads by line, so a long line running off the side with a horizontal scroll is the honest answer n the one the ahk gives. wrap still works when it is turned on, the gutter just numbers the first row of each line

the countdown bar

it was a standalone widget exe n it is not one any more, dropped 2026-08-27, finns call. what it was ever for was the proof, it is the one thing in the plan that exercises shaped drawing n click-through n a long lived idle cost all at once, n it is where the retained api model got its deciding argument. so the model n the paint live here, the runner drives them, n there is no process, no packaging n no config

header only for the same reason dpi.h n frame.h are, cpp/BUILD.md says an agent touches no .vcxproj n a new .cpp here would need one. it is not a workaround either, the whole thing is a handful of value types n one paint

the model knows nothing about a window. it takes a day number n a size, hands back boxes n a count, so every layout claim is a plain call n the only checks needing an hwnd are the two that are genuinely about the os

the day is a NUMBER, not a date. everything counts in days since 1970-01-01, bc a rollover is a subtraction n a date that has to survive a reboot is far better off as one integer than as three fields n a timezone argument. today_local is the only thing in the file that asks the os what day it is, which is what lets a check pass its own day n never race midnight

days_from_civil is Howard Hinnants, the standard answer n not worth deriving again. it shifts the year to start in march so the leap day lands at the END of one, n the whole thing falls out as arithmetic with no branches n no table. <chrono>s calendar would do it too n c++20 is on, it is just a heavy include for one subtraction

the four claims, n where each is proven

claimproven by
a stated total really splits across the windowblock() layout checks, n a pixel read off a real frame
it draws once then costs nothing while idleten thousand update()s that all refuse, frame count flat
it sits above other windows without stealing focusWS_EX_TOPMOST set n GetForegroundWindow unmoved
a click on a transparent pixel falls throughWindowFromPoint, conditional, see below

the click-through check does not always run n says so. WindowFromPoint answers about whatever is topmost at that point, so anything over us turns the pair into a claim about that window instead. the lit block is the control, it lands on us or the pair is not run, n the runner prints NOT CHECKED n names what was in the way. a locked session is the case that really happens, it puts a full screen topmost LockScreenBackstopFrame over the lot

the alpha itself is checked either way, the spent block reads 0 in the presented surface. what goes unproven when the desktop is covered is only that the os ROUTES a click on it, n G-window-3s probe is still the one a person clicks

the traps

  • the target is the day it hits ZERO, not the day it started. that is the number a person knows, n it makes the count a subtraction with nothing accumulated over it, so a bar reloaded after a month off cannot have drifted
  • a rollover unions a RUN of blocks, not one. a machine asleep over a weekend comes back three days on, n invalidating only the newest would leave two lit blocks that are no longer owed. it looks right on the frame you test it on bc the count is correct, only the pixels are wrong
  • a load is all or nothing. a half read that took the target n left the total would draw a plausible bar that counts wrong, which is worse than a load saying no n leaving the caller on its own numbers
  • the state file goes in %LOCALAPPDATA%, never beside the exe, an install dir gets replaced wholesale on an update n takes the count with it, n on a managed box it is not writable at all. the env var n not SHGetKnownFolderPath, which lives in shell32 n would be a new lib for one string
  • the spent-block alpha guard saves draw calls n nothing else, n no check proves it. a fill at alpha 0 over src-over changes no pixels, so removing it leaves every frame byte identical, which the mutation run reports as a survivor rather than hiding. dont go writing a check for it
  • float layout does not compare exactly. a width divided between n blocks cannot land on an exact float, so the runner compares to within a px hundredth, n asserting equality there would be a check about ieee754 rather than about the bar

On this page