controls
the generic half, the box, the tree, layout hints and theming one
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 controls, the generic half
every call here works on any control handle whatever made it, so a concrete control added later needs nothing rewritten
bounds are WINDOW coords in logical px n not parent relative, same as the c++ side. so a move carries the children n a resize does not, layout is what re-places them
int32_t gui_control_create(gui_control_t** _out);
int32_t gui_control_destroy(gui_control_t* _ctrl);
int32_t gui_control_add(gui_control_t* _parent, gui_control_t* _child);
int32_t gui_control_remove(gui_control_t* _parent, gui_control_t* _child);
int32_t gui_control_clear(gui_control_t* _ctrl);creategives a bare invisible control that draws nothing at all, for a root or a grouping boxdestroyfrees a LOOSE control n its whole subtree, a tree owned or host borrowed one isgui_err_owned, remove it firstaddneeds a loose child n runs it through the containers flow when the parent is one, the tree owns it afterremovehands it back loose, ngui_err_ownedwhen it is not that parents childcleardrops every child n their subtrees, n every one of those handles is dead after, which is the easiest way to leak a dangling handle in a wrapper
the box n the flags
int32_t gui_control_set_bounds(gui_control_t* _ctrl, float _x, float _y, float _w, float _h);
int32_t gui_control_move(gui_control_t* _ctrl, float _x, float _y);
int32_t gui_control_bounds(gui_control_t* _ctrl, float* _x, float* _y, float* _w, float* _h);
int32_t gui_control_set_visible(gui_control_t* _ctrl, int32_t _on);
int32_t gui_control_set_enabled(gui_control_t* _ctrl, int32_t _on);
int32_t gui_control_visible(gui_control_t* _ctrl, int32_t* _out);
int32_t gui_control_enabled(gui_control_t* _ctrl, int32_t* _out);an invisible subtree is neither drawn nor hit tested, n a disabled control is still drawn but takes no input, those are two different things
the tree n the rest
int32_t gui_control_parent(gui_control_t* _ctrl, gui_control_t** _out);
int32_t gui_control_count(gui_control_t* _ctrl, int32_t* _out);
int32_t gui_control_at(gui_control_t* _ctrl, int32_t _i, gui_control_t** _out);
int32_t gui_control_invalidate(gui_control_t* _ctrl);
int32_t gui_control_measure(gui_control_t* _ctrl, float _avail_w, float _avail_h, float* _w, float* _h);parentis null at a root, n null again for a child that was not made through this dll, same hole as the input queriesinvalidategoes into nothing when the control is not under a host, quietly n without failingmeasureis logical px, how big it would like to be given the room, n a bare control just answers its own box
the layout hints
these are read off a child by its container, see flow_hints_t. none of them repaint or re-place
anything on their own, the next relayout is what moves things, so a hint set after the add wants a
gui_container_relayout
int32_t gui_control_set_fill(gui_control_t* _ctrl, int32_t _fill_w, int32_t _fill_h);
int32_t gui_control_set_fixed(gui_control_t* _ctrl, float _w, float _h);
int32_t gui_control_set_absolute(gui_control_t* _ctrl, int32_t _on);
int32_t gui_control_set_anchor(gui_control_t* _ctrl, int32_t _anchor);| hint | what it does |
|---|---|
set_fill | stretch to whatever width or height is left where it lands |
set_fixed | an exact size, 0 on an axis means ask measure instead |
set_absolute | the flow steps straight over it n it keeps whatever box it was given |
set_anchor | a gui_anchor_t, gui_anchor_bottom pins it to the containers bottom edge, vertical flow only |
the theme on a control
int32_t gui_control_set_theme(gui_control_t* _ctrl, gui_theme_t* _theme);BORROWED, n null goes back to inheriting from the parent. it repaints everything that resolves to it