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
| rule | what it means for a caller |
|---|---|
a null out pointer is gui_err_arg | never a crash, so a wrapper can be sloppy n still find out |
| strings in are utf8, null terminated, BORROWED for the call only | copy it yourself if you need it after, n there are no strings OUT in this half |
bools are int32_t, 0 n not 0 | a DllCall has no bool |
a handle is pointer sized, "ptr" to a DllCall | opaque, never dereferenced by you |
| the abi is VERSIONED n free to move | GUI_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
| status | when |
|---|---|
gui_ok | 0, the only success |
gui_err_arg | a null out pointer, or a value out of range |
gui_err_handle | not a live handle of the kind the call wanted |
gui_err_create | the window could not be made |
gui_err_closed | the window has gone n the call needed it |
gui_err_thread | a host call from a thread that did not make the window |
gui_err_owned | the call wanted a loose control n got an owned one, or the reverse |
gui_err_kind | a control, but not the kind this call works on, i.e. not a container |
gui_err_in_use | a theme a live control still points at |
gui_err_internal | something 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
| thing | who owns it |
|---|---|
| a host | owns its window n its tweens, gui_host_destroy frees them |
| a control you create | LOOSE, the dll owns it, until you add it to a tree |
| a control in a tree | the tree owns it n it dies with its parent, gui_control_destroy on it is gui_err_owned |
| a control removed from a tree | loose again n yours to destroy or re-add |
| a hosts root | BORROWED, gui_host_set_root never takes it, so the root outlives the host |
| a theme | BORROWED 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_tvalue 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>_createin their own file once the widgets settle, every one hands back agui_control_tn 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