window

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_size is LOGICAL px, i.e. at 96 dpi, the real window is this times the monitors scale
  • set_pos takes GUI_UNSET on either axis to centre it on the primary monitor, that is what the default already is
  • set_on_top is true by default even for a chromed host, see host.h for why
  • set_frame is ignored outright on a popup, it is the chrome metrics for a chromed one, in logical px
  • set_kind takes a gui_kind_t, set_present a gui_present_t, n chromed plus layered is refused by gui_host_create rather than quietly swapped
enumvalues
gui_kind_tgui_kind_popup, gui_kind_chromed
gui_present_tgui_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);
  • create leaves nothing half built when it comes back gui_err_create
  • destroy unhooks 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 show on its own looks like it did nothing
  • close asks, the way alt f4 asks, n the host reads closed once the message lands, so it is not immediate. gui_host_closed is how you find out
  • resize is LOGICAL px n rebuilds the backing store, the root follows it. a false from the host underneath comes back gui_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, _box is logical px
  • update draws n presents ONLY when something asked for a frame, n _painted says whether one happened, so a 0 there is the normal quiet case n not a failure
  • paint forces 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

  • pump never 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. _alive comes back 0 once the window has gone
  • run blocks until the window closes, waiting on the queue when nothing animates, n nothing else in the caller runs while it is in there
  • spawn blocks 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

blockwhy
every control callthe tree is under a lock both sides share, so build, add, move, restyle, animate
every tween calla tween manager is abi state n not a win32 object
the whole event blockdraining on your own thread is the entire point of the path
gui_host_closed, gui_host_frames, gui_host_root, gui_host_runningthey 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_opacity is the whole window constant alpha, 0 clear to 255 solid, n it is best effort, a present path without one ignores it rather than failing
  • set_partial_present is OFF by default n unproven, see dirty.h
  • set_frame is 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_test takes 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_focus takes 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

On this page