window

the call shape

the one shape every export takes, the statuses, and the handles

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 one shape every call takes

every export returns an int32_t status n every value comes back through an out pointer. so a caller checks one thing after every call n a 0 is never ambiguous between a value n a success

gui_host_t* host = 0;
if (gui_host_create(desc, &host) != gui_ok)
	return;

the two exceptions are gui_abi_version n gui_err_text, neither of which can fail, so both return their value directly

rulewhat it means for a caller
a null out pointer is gui_err_argnever a crash, so a wrapper can be sloppy n still find out
strings in are utf8, null terminated, BORROWED for the call onlycopy it yourself if you need it after, n there are no strings OUT in this half
bools are int32_t, 0 n not 0a DllCall has no bool
a handle is pointer sized, "ptr" to a DllCallopaque, never dereferenced by you
the abi is VERSIONED n free to moveGUI_ABI_VERSION is what you compiled against, gui_abi_version() is what you loaded

a stale handle is gui_err_handle n not a crash, every handle the dll hands out is registered n checked on the way in. the one hole is an address reused by a new object of the same kind, which a registry cannot tell apart, so do not keep handles past their destroy n expect the error to save you

a window belongs to the thread that made it, win32s rule not this libs, so every host call from another thread is gui_err_thread rather than left to break quietly

gui_err_t, the statuses

statuswhen
gui_ok0, the only success
gui_err_arga null out pointer, or a value out of range
gui_err_handlenot a live handle of the kind the call wanted
gui_err_createthe window could not be made
gui_err_closedthe window has gone n the call needed it
gui_err_threada host call from a thread that did not make the window
gui_err_ownedthe call wanted a loose control n got an owned one, or the reverse
gui_err_kinda control, but not the kind this call works on, i.e. not a container
gui_err_in_usea theme a live control still points at
gui_err_internalsomething threw inside the dll n was stopped at the boundary, the state it left is best effort

gui_err_text(int32_t _err) gives a static string for any of them, "unknown" off the list. it cannot fail n the string is not yours to free

the handles, n who owns what

typedef struct gui_desc_tag     gui_desc_t;
typedef struct gui_host_tag     gui_host_t;
typedef struct gui_control_tag  gui_control_t;
typedef struct gui_theme_tag    gui_theme_t;

this is the half a signature cannot tell you, so read it before you write anything

thingwho owns it
a hostowns its window n its tweens, gui_host_destroy frees them
a control you createLOOSE, the dll owns it, until you add it to a tree
a control in a treethe tree owns it n it dies with its parent, gui_control_destroy on it is gui_err_owned
a control removed from a treeloose again n yours to destroy or re-add
a hosts rootBORROWED, gui_host_set_root never takes it, so the root outlives the host
a themeBORROWED by every control pointing at it, gui_theme_destroy refuses while one does

so a tree can be built before its window exists n kept after it closes, which is the point of the root being borrowed rather than owned

gui_shutdown() frees the lot in the right order, hosts then controls then themes then descs, n every handle is dead after it. call it last or not at all

the dll itself

int32_t     gui_abi_version(void);
const char* gui_err_text(int32_t _err);
int32_t     gui_shutdown(void);

gui_abi_version cannot fail, compare what it says against GUI_ABI_VERSION from the header you built against. 1 is the current one

out of scope, n said so

none of this is missing by accident

  • a click event, not for want of a mechanism, the concrete controls that fire one do not exist yet, it lands as a new gui_event_t value n moves nothing else
  • spawn_ui_thread, still not exposed. the queue is ready for it, but the loose list is deliberately single thread, so that is what has to move first
  • the concrete controls, button, label, list n the rest. they arrive as gui_<control>_create in their own file once the widgets settle, every one hands back a gui_control_t n every call on this page already works on it
  • synthesised input, a scripted mouse move through the router, nothing has asked for it
  • scroll_view_t, it needs a subclass to draw its content, which is a callback
  • strings out, there are none in this half of the abi at all

On this page