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.ahkahk\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.Dll | window.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.AbiVersion | the abi this lib is written against, the dll is checked against it on load |
Kit.PumpMs | 16, 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.
Addhands it to a tree,Removehands it back Destroyis for a loose control only. a tree owned one comes backgui_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
Destroyon either is refused while a live control still is - destroy stays explicit, ahk frees objects when it feels like it n
__Deleteorder 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 setthe 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 elsethe 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.Available | is 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
| file | what |
|---|---|
Kit.ahk | the one global, the four load constants, n the includes that nest the rest into it |
Kit\abi.ahk | the export table, the dll load n version check, the utf8 conversion, the throw |
Kit\enums.ahk | every enum in the header mirrored, Kit.Btn, Kit.Col, Kit.Num n the rest |
Kit\control.ahk | Kit.Control, i.e. every generic n container call over a handle |
Kit\theme.ahk | Kit.Theme, Kit.Icon, Kit.Items, Kit.Cols, Kit.Rows |
Kit\window.ahk | Kit.Window, the pump, the event drain n the tweens |
Kit\make.ahk | one call per concrete control, each handing back a Kit.Control |
Kit ools.ahk | Kit.Tools, the inspection surface, present ONLY on window.abi.tools.dll |
demo.ahk | the smallest whole script, a window n controls n a click |
demo-flow.ahk | the same window flowed by a Kit.Column, nothing in it sizes anything |