events
the queue, the three rules that bite, and which slots carry what
the WHY is not on this page. how the abi got this shape lives in how the abi is designed, and what a wrapped call MEANS is answered by the c++ header underneath it
the events
the dll never calls you, there is no function pointer anywhere in this abi. an event is queued inside the dll n your window is posted a message to say the queue is not empty, which is the one thing win32 promises is safe from any thread, n you drain it on your own thread whenever it suits
int32_t gui_event_set_target(gui_host_t* _host, void* _hwnd, uint32_t _msg);
int32_t gui_event_set_enabled(gui_host_t* _host, int32_t _kind, int32_t _on);
int32_t gui_event_next(gui_host_t* _host, int32_t* _kind, gui_control_t** _ctrl, int64_t* _i0, int64_t* _i1, float* _f0, int32_t* _got);
int32_t gui_event_pending(gui_host_t* _host, int32_t* _out);
int32_t gui_event_clear(gui_host_t* _host);the shape on the ahk side is OnMessage(msg, handler) n a handler that loops on gui_event_next
the three rules that bite
- every kind is OFF until you turn it on, so a script that reads no events queues none n pays nothing, n a kind added in a later abi version cannot start filling an old scripts queue
- DRAIN UNTIL
_gotCOMES BACK 0, the dll posts one wake n does not post another until the queue has gone empty, bc a post per event floods the message queue on a window drag, so a handler that reads one event n returns goes back to sleep with the rest still sitting there sizedndpiCOALESCE, a newer one overwrites the older one still waiting rather than queuing behind it, so what you read is always the current size, every other kind queues in full
the kinds, n which slots carry what
| kind | _ctrl | _i0 | _i1 | _f0 |
|---|---|---|---|---|
gui_event_closed | ||||
gui_event_sized | width | height | ||
gui_event_dpi | dpi | scale | ||
gui_event_dismiss | the popup | |||
gui_event_tween_done | the repaint control, may be null | the tween id |
sized is logical px, n closed is a transition said exactly once, not once per pump
the rest of the contract
- a null
_hwndjust stops the posting, the queue still fills ngui_event_nextstill drains it, which is how a caller that polls rather than waits uses this - every out on
gui_event_nextis optional except_got, pass null for the slots a kind does not use _gotof 0 is not an error, it is what ends a drain loop- turning a kind off DROPS what it already queued, on the grounds that a caller who has just said it does not want these is not coming back for the backlog
- the
_ctrlhandle is re-checked against the registry on the way out, so a popup destroyed between the dismiss landing n you reading it comes back null rather than dangling - the queue is drained on the thread that made the window, same as every other host call