the window
making one, painting it, the three pumps, and reading it back
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 desc, i.e. what to build
a bag of settings filled in by setters, so no struct layout ever crosses the boundary n a field added later moves nobodys call site
a fresh desc carries the lib defaults, a 480x320 popup, layered, on top, centred, so you only set what
you want different. it is only read by gui_host_create, so it can be reused for a second window or
dropped straight after
int32_t gui_desc_create(gui_desc_t** _out);
int32_t gui_desc_destroy(gui_desc_t* _desc);
int32_t gui_desc_set_title(gui_desc_t* _desc, const char* _utf8);
int32_t gui_desc_set_size(gui_desc_t* _desc, int32_t _w, int32_t _h);
int32_t gui_desc_set_pos(gui_desc_t* _desc, int32_t _x, int32_t _y);
int32_t gui_desc_set_on_top(gui_desc_t* _desc, int32_t _on);
int32_t gui_desc_set_kind(gui_desc_t* _desc, int32_t _kind);
int32_t gui_desc_set_present(gui_desc_t* _desc, int32_t _present);
int32_t gui_desc_set_frame(gui_desc_t* _desc, int32_t _border, int32_t _caption, int32_t _min_w, int32_t _min_h);set_sizeis LOGICAL px, i.e. at 96 dpi, the real window is this times the monitors scaleset_postakesGUI_UNSETon either axis to centre it on the primary monitor, that is what the default already isset_on_topis true by default even for a chromed host, seehost.hfor whyset_frameis ignored outright on a popup, it is the chrome metrics for a chromed one, in logical pxset_kindtakes agui_kind_t,set_presentagui_present_t, n chromed plus layered is refused bygui_host_createrather than quietly swapped
| enum | values |
|---|---|
gui_kind_t | gui_kind_popup, gui_kind_chromed |
gui_present_t | gui_present_layered, gui_present_opaque, gui_present_dcomp |
the host, one window n what draws into it
int32_t gui_host_create(const gui_desc_t* _desc, gui_host_t** _out);
int32_t gui_host_destroy(gui_host_t* _host);
int32_t gui_host_show(gui_host_t* _host, int32_t _on);
int32_t gui_host_close(gui_host_t* _host);
int32_t gui_host_move(gui_host_t* _host, int32_t _x, int32_t _y);
int32_t gui_host_resize(gui_host_t* _host, int32_t _w, int32_t _h);createleaves nothing half built when it comes backgui_err_createdestroyunhooks the root n leaves it alive, the host only borrowed it. the host handle is dead after- a layered window shows nothing until its first paint, so a
showon its own looks like it did nothing closeasks, the way alt f4 asks, n the host reads closed once the message lands, so it is not immediate.gui_host_closedis how you find outresizeis LOGICAL px n rebuilds the backing store, the root follows it. a false from the host underneath comes backgui_err_create
painting
int32_t gui_host_invalidate(gui_host_t* _host);
int32_t gui_host_invalidate_box(gui_host_t* _host, float _x, float _y, float _w, float _h);
int32_t gui_host_update(gui_host_t* _host, int32_t* _painted);
int32_t gui_host_paint(gui_host_t* _host);- both invalidates draw nothing themselves, they only mark,
_boxis logical px updatedraws n presents ONLY when something asked for a frame, n_paintedsays whether one happened, so a 0 there is the normal quiet case n not a failurepaintforces a full frame whatever the dirty box says
the pump, n there are THREE shapes of caller
int32_t gui_host_pump(gui_host_t* _host, int32_t* _alive);
int32_t gui_host_run(gui_host_t* _host);
int32_t gui_host_spawn(const gui_desc_t* _desc, gui_control_t* _root, gui_host_t** _out);all three drain the queue, tick the tweens, then update, in that order. the lib never repaints off a message on its own, so a hover fade only ever moves inside one of these, n a caller that never calls any of them has a window that never moves
pumpnever blocks, it does one lap n hands control straight back, which is what a script calls off a timer while its own hotkeys keep running._alivecomes back 0 once the window has gonerunblocks until the window closes, waiting on the queue when nothing animates, n nothing else in the caller runs while it is in therespawnblocks for neither, the window gets a thread of its own n the caller carries on, see below
the spawned path, a window on a thread of its own
int32_t gui_host_spawn(const gui_desc_t* _desc, gui_control_t* _root, gui_host_t** _out);
int32_t gui_host_stop(gui_host_t* _host);
int32_t gui_host_join(gui_host_t* _host);
int32_t gui_host_running(gui_host_t* _host, int32_t* _out);the desc n the root go in AT SPAWN n cannot be handed over later. a window belongs to the thread that
made it, this one is made on the far side, so every call in the host block above comes back gui_err_thread
from the moment the handle does. _root may be null, n it follows the same rule set_root does, it has to
be loose n not already some other windows
what you CAN still reach from your own thread
| block | why |
|---|---|
| every control call | the tree is under a lock both sides share, so build, add, move, restyle, animate |
| every tween call | a tween manager is abi state n not a win32 object |
| the whole event block | draining on your own thread is the entire point of the path |
gui_host_closed, gui_host_frames, gui_host_root, gui_host_running | they read abi state, not the window |
gui_host_frames answers off the FAR THREADS counter for a spawned window, bc its host is usually
gone by the time you ask n the count is the one thing that proves it really kept painting
stop asks n returns, join waits, n destroy does both for you before it frees anything, so a caller
that only ever destroys is already correct. join twice is fine. all four are refused from a thread that
did not make the handle, n stop, join on a window that was never spawned is gui_err_kind
the root comes back loose when the thread winds up, not at destroy, so it outlives its window the
same way it does on the pumped path, it is just handed back a step earlier. gui_host_root reads null
once that has happened
the root
int32_t gui_host_set_root(gui_host_t* _host, gui_control_t* _root);
int32_t gui_host_root(gui_host_t* _host, gui_control_t** _out);the root is BORROWED, pass a loose control, or null to unhook the one it has. gui_host_root
comes back null when there is none
the rest of the window
int32_t gui_host_set_opacity(gui_host_t* _host, int32_t _alpha);
int32_t gui_host_set_partial_present(gui_host_t* _host, int32_t _on);
int32_t gui_host_set_frame(gui_host_t* _host, int32_t _border, int32_t _caption, int32_t _min_w, int32_t _min_h);set_opacityis the whole window constant alpha, 0 clear to 255 solid, n it is best effort, a present path without one ignores it rather than failingset_partial_presentis OFF by default n unproven, seedirty.hset_frameis chromed only n takes effect on the next hit test
the getters
int32_t gui_host_hwnd(gui_host_t* _host, void** _out);
int32_t gui_host_size(gui_host_t* _host, int32_t* _w, int32_t* _h);
int32_t gui_host_logical(gui_host_t* _host, int32_t* _w, int32_t* _h);
int32_t gui_host_dpi(gui_host_t* _host, int32_t* _out);
int32_t gui_host_scale(gui_host_t* _host, float* _out);
int32_t gui_host_frames(gui_host_t* _host, int64_t* _out);
int32_t gui_host_closed(gui_host_t* _host, int32_t* _out);
int32_t gui_host_maximised(gui_host_t* _host, int32_t* _out);size is DEVICE px n logical is what you asked for, they differ by the monitors scale n mixing
them up is the easy bug here
the two checkers answer on a CLOSED host too, which is the whole reason they exist
input, read-only for now
int32_t gui_host_hit_test(gui_host_t* _host, float _x, float _y, gui_control_t** _out);
int32_t gui_host_hovered(gui_host_t* _host, gui_control_t** _out);
int32_t gui_host_captured(gui_host_t* _host, gui_control_t** _out);
int32_t gui_host_focused(gui_host_t* _host, gui_control_t** _out);
int32_t gui_host_set_focus(gui_host_t* _host, gui_control_t* _ctrl);hit_testtakes LOGICAL px n gives the topmost interactive control there, null when nothing wants it- the three queries each come back null when nobody is hovered, holding the press, or holding the keys
set_focustakes null to drop focus- a control that came out of the tree but was not made through this dll comes back null, a containers own scrollbar being the case that bites, so a null out is not an error n has to be handled
the events themselves are P1.24, so polling these is the only way to read input today