window

using Kit

the whole wrapper surface from a stock ahk v2 script

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

the window lib from an ahk v2 script, over window.abi.dll. you never write a DllCall, never read a status code n never hardcode an ordinal

#Include <path to window>\ahk\Kit.ahk

ahk\demo.ahk is the smallest whole script, run it n then read it, n ahk\demo-flow.ahk is the same window with every bound taken out

the one global

everything is nested under Kit. that is on purpose n it is the only name this lib adds. the ahk gui/ lib defines Window, Control, Button, Theme n Icon at global scope n stays there til parity, so both can be #Included in one script n neither stands on the other

what loads, n from where

four lines at the top of Kit.ahk say the lot, set any of them before your first call

Kit.Dllwindow.abi.dll, ONE constant, the tools swap is this line n nothing else, see below
Kit.Dir..\cpp\bin\x64_Debug relative to Kit.ahk, where the dll n its dependencies sit
Kit.AbiVersionthe abi this lib is written against, the dll is checked against it on load
Kit.PumpMs16, how often a shown window pumps

the dll loads lazily on the first call n the version is checked there. a mismatch throws, bc the enum values moved at abi 2 n an old dll would fill every one of them with something else

a window

app := Kit.Window("title", 420, 260)
app.Root(tree).Show()

a fresh window is chromed n opaque, i.e. a real resizable app window, which is not what a bare desc defaults to. pass an options object to change it

app := Kit.Window("popup", 300, 180, { kind: Kit.Kind.Popup, present: Kit.Present.Layered, on_top: true })

x n y place it, leave them off n it centres. frame takes { border, caption, min_w, min_h }

Show starts the pump, a SetTimer that calls gui_host_pump n drains the event queue. the script keeps its own thread n its hotkeys n every other gui it already has, n nothing in the lib ever loops or blocks. Run() is the one call that does block, it is there for a window that IS the program

Kit.Window.Spawn(root, ...) puts the window on a thread of its own. its desc n its root go in at spawn n cannot be handed over later, n a host call that touches win32 from your thread comes back gui_err_thread rather than breaking quietly

a tree

every control is a Kit.Control whatever it is, containers included, so every call in control.ahk works on any of them

theme := Kit.Theme()
root  := Kit.Blank()
root.Theme(theme)

row := Kit.Row(8, 12)
row.Add(Kit.Label("name")).Add(Kit.TextInput("", "who are you"))

root.Add(row)

the makers are Kit.Label Kit.Button Kit.Badge Kit.Checkbox Kit.Toggle Kit.Panel Kit.Progress Kit.Slider Kit.Stepper Kit.KeyValue Kit.Clickable Kit.IconButton Kit.IconView Kit.List Kit.NavList Kit.Dropdown Kit.Segmented Kit.Table Kit.TextInput Kit.TextArea Kit.CodeEditor, n the containers are Kit.Blank Kit.Column Kit.Row Kit.Child Kit.Columns

ownership, the one thing to keep straight

  • a control you make is LOOSE n the dll owns it. Add hands it to a tree, Remove hands it back
  • Destroy is for a loose control only. a tree owned one comes back gui_err_owned, take it out first. this is the mistake you will make, the demo makes it in its own history
  • a host BORROWS its root, so the tree is still yours n outlives the window
  • a theme n an icon are borrowed by everything pointed at them, so Destroy on either is refused while a live control still is
  • destroy stays explicit, ahk frees objects when it feels like it n __Delete order is not a thing to build on

errors

every export hands back a status n the wrapper throws on anything but ok, so there is no silent 0 to check for

try
    ctrl.Destroy()
catch Kit.AbiError as e
    MsgBox(e.Export . " gave " . e.Code . ", " . e.Message)

e.Code is a Kit.Err, e.Export is the export that produced it n e.Message is what the dll itself calls that code

events

every kind starts OFF. Show turns on Closed, Click, Select n Value, bc those four are what the wrapper reads itself, n On(kind, fn) turns on whatever else you ask for

app.OnClose(Closed)              ; also OnSize, OnDpi, OnDismiss, OnTweenDone
btn.OnClick(Pressed)             ; a click goes to the CONTROL, not the window
list.OnSelect(Picked)            ; (ctrl, index)
sld.OnValue(Moved)               ; (ctrl, value)

a click, a select n a value are all handed to the CONTROL, the click handler taking it alone n the other two taking it plus the index or the number. every other handler is called with the window n an event object carrying i0, i1 n f0, see the table in window_abi.h

the dll posts one wake n does not post another til the queue empties, which the timer makes moot, but EventTarget(hwnd, msg) is there if you would rather have OnMessage than our timer

flow just works, you do not size anything by hand

Kit.Column().Add(Kit.Label("hi")) places the label at the width of the run, on the add, with nothing painted yet. same for a button, a checkbox, a badge, a dropdown, a tab n the rest of the text controls

this used to bite n it is worth knowing it stopped. a label measured itself on the way through a paint n a paint was the only place a font lived, so a flow before the first frame laid out a stack of nothing n you got an empty window, n the fix was to set bounds yourself. P1.42 gave the tree its own measurer. an older script that sizes by hand is still correct, an explicit size is an override n not a workaround, which is why demo.ahk keeps its own, it is absolute on purpose. demo-flow.ahk is the other half of that, the same window with not one SetBounds in it

the one thing still on you is a control you take OUT of a flow, Absolute() means you place it

clicks come off any pressable control

every control that takes a press reports one, Kit.Button Kit.Checkbox Kit.Toggle Kit.Slider Kit.Stepper Kit.IconButton Kit.Dropdown n Kit.Clickable, all through OnClick

Kit.Button("ok", Kit.Btn.Primary).OnClick(Pressed)
Kit.Checkbox("wrap lines", true).OnClick(Toggled)

a checkbox n a toggle flip themselves BEFORE the handler runs, so the state you read off the control you were handed is the one the user just chose n not the one before it

a pick n a number, P1.43

there are no getters, the queue is the whole channel, so OnSelect n OnValue are how you learn what a control now holds n there is nothing to poll instead

Kit.List(Kit.Items("one", "two")).OnSelect((c, i) => MsgBox("row " . i))
Kit.Slider(0, 0, 100).OnValue((c, v) => MsgBox("at " . v))

OnSelect is Kit.List Kit.NavList Kit.Dropdown Kit.Segmented n Kit.Table, n it hands you the 0 based index. OnValue is Kit.Slider n Kit.Stepper, n it hands you the number

a strip only fires on a real CHANGE where a list n a table fire on every pick, so pressing the segment that is already active says nothing through OnSelect

a row is not a control you own, a list builds its own, so At(i) on a list hands back nothing n a row press arrives as a plain Click with no control on it. OnRowClick on the WINDOW is where those land, _ev.i0 carrying the index, n it is the one thing that still fires on a press that moved no pick

At(i) past the last child THROWS where a row comes back falsy, n the two are meant to read differently. a row is an answer, there is a control there n it is simply not yours, where an index off the end is a bug in the calling script n Kit.Err.Arg is the wrapper saying so instead of handing back a nothing that looks exactly like the row case. check Count() first if the index came from anywhere you do not control

app.OnRowClick((w, ev) => MsgBox("pressed row " . ev.i0))   ; i0 is -1 when it was not one of a set

the tools dll, P1.41

there are two dlls, window.abi.dll n window.abi.tools.dll. they are the same lib, the second one carrying an inspection surface for somebody DEVELOPING against it. the swap is one line

Kit.Dll := "window.abi.tools.dll"   ; before your first call, n change nothing else

the shipping dll carries no trace of the tools. the file they are compiled from was never handed to the release build at all, so its export table has no gui_tools_* in it n there is no flag to turn them back on. that is why Available asks the export table rather than comparing a version

if (Kit.Tools.Available)
{
    doc := Kit.Tools.Tree(root)         ; one json document, every node with its real box
    fr  := Kit.Tools.Frame(win)         ; the frame count, the dirty box n what the last frame did
    tail:= Kit.Tools.Events(win)        ; the last few events, including ones nothing subscribed to

    Kit.Tools.Snap(win, A_Temp . "\w.png")        ; the window redrawn into a png
    Kit.Tools.Overlay(win, A_Temp . "\o.png")     ; the same plus the dirty box n every bounds
}
Kit.Tools.Availableis the loaded dll the tools one, a GetProcAddress question, never throws
Kit.Tools.Which()which tools surface it speaks, or 0 when it is not the tools dll
Kit.Tools.Require()the same, but THROWS, for a script that only makes sense on the tools dll
Kit.Tools.Tree(ctrl)the control tree under the given control, as one json document
Kit.Tools.Frame(win)what the windows frames are doing, as one json document
Kit.Tools.Events(win)the last few events on the window, oldest first, as one json document
Kit.Tools.Snap(win, path)the window redrawn into a png, returns the path
Kit.Tools.Overlay(win, path)the same png with the dirty box n every controls bounds over it

a node is {"h":,"type":,"box":[x,y,w,h],"vis":,"en":,"kids":[]}. type is the real c++ class name, box is the LOGICAL px box the layout put it in, n a control the dll never made carries "h":null, which is every row of every list. so a row you cannot get a handle to is still in the document with its box on it, which is usually the thing you wanted to know

Frame answers {"frames":,"paced":,"dirty":{...},"last":{...}} n every box in it is SURFACE px, which is the logical box times the scale on a hidpi monitor n the same number on a normal one. dirty is what the NEXT frame owes n last is what the last one that landed really did, null until one has

Events answers {"seen":,"events":[...]}, oldest first, n it is not the queue. it reads a ring the dll keeps for itself, so calling it never costs you an event Kit.Window.Next was going to hand you, n it carries events nothing ever subscribed to, which is the whole reason to reach for it when a click went somewhere you did not expect. the ring is 64 across every window, seq is what tells you it wrapped

Snap n Overlay redraw the tree into memory n write that out, they are not a screenshot. so they touch no window n work on a spawned one too, but anything the desktop did after the present is not in the png. the folder has to already exist, the dll will not make one

every tool only ever READS, none of them moves a control, sets a value or forces a frame, so a tool call can never be the reason a bug went away

what each one costs an agents context is in cpp/abi/tools/README.md, under what each one costs you in context, n the short of it is that Frame n both pngs are free to call, Events is capped, n Tree is the only unbounded one, so hand it a control rather than the root when you can

the export table

Kit\abi.ahk names every export in exactly one place, the Sigs map, so the debug dll swap is one constant rather than an edit per call. "Str" in a row is ours n not a DllCall type, it means a utf8 const char* n the wrapper converts, bc ahk strings are utf16 n AStr would hand the dll the ansi codepage

the table cannot drift off the header on its own, window.test.exe checks it on every run, under P1.25, the ahk export table against window_abi.h. add an export n you add a row, or the suite says so

the files

filewhat
Kit.ahkthe one global, the four load constants, n the includes that nest the rest into it
Kit\abi.ahkthe export table, the dll load n version check, the utf8 conversion, the throw
Kit\enums.ahkevery enum in the header mirrored, Kit.Btn, Kit.Col, Kit.Num n the rest
Kit\control.ahkKit.Control, i.e. every generic n container call over a handle
Kit\theme.ahkKit.Theme, Kit.Icon, Kit.Items, Kit.Cols, Kit.Rows
Kit\window.ahkKit.Window, the pump, the event drain n the tweens
Kit\make.ahkone call per concrete control, each handing back a Kit.Control
Kit ools.ahkKit.Tools, the inspection surface, present ONLY on window.abi.tools.dll
demo.ahkthe smallest whole script, a window n controls n a click
demo-flow.ahkthe same window flowed by a Kit.Column, nothing in it sizes anything

On this page