window

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 _got COMES 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
  • sized n dpi COALESCE, 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_sizedwidthheight
gui_event_dpidpiscale
gui_event_dismissthe popup
gui_event_tween_donethe repaint control, may be nullthe 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 _hwnd just stops the posting, the queue still fills n gui_event_next still drains it, which is how a caller that polls rather than waits uses this
  • every out on gui_event_next is optional except _got, pass null for the slots a kind does not use
  • _got of 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 _ctrl handle 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

On this page