window

containers

the overlay slot, the containers, the flow cursor and scrolling

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 overlay, one detached popup a root holds

painted above the tree n hit tested before it

int32_t gui_control_set_overlay(gui_control_t* _root, gui_control_t* _popup, gui_control_t* _owner);
int32_t gui_control_clear_overlay(gui_control_t* _root);
int32_t gui_control_overlay(gui_control_t* _root, gui_control_t** _out);
  • the popup is BORROWED n stays yours, it is not added to the tree n it is not freed with it
  • _owner is optional, a press on the owner swallows the dismiss, see control.h
  • a press outside closes the overlay, n the dismiss callback is P1.24, so today you poll gui_control_overlay to learn it went, a null out meaning it has

the containers

a cursor that places children, see layout.h. every container is also a control, so every generic call above works on one

int32_t gui_column_create(float _gap, float _pad, gui_control_t** _out);
int32_t gui_row_create(float _gap, float _pad, gui_control_t** _out);
int32_t gui_child_create(float _w, float _h, float _gap, float _pad, gui_control_t** _out);
int32_t gui_columns_create(int32_t _n, float _gap, float _pad, gui_control_t** _out);
int32_t gui_columns_col(gui_control_t* _cols, int32_t _i, gui_control_t** _out);
callwhat it is
gui_column_createa vertical flow
gui_row_createa horizontal one
gui_child_createa sized nested region, 0 on an axis fills the parent
gui_columns_create_n equal columns
gui_columns_colthe i th column, null past the end, n gui_err_kind on a plain container

gui_err_kind is the one to expect across this whole section, every container call on a control that is not a container comes back with it rather than doing nothing

the cursor nudges

int32_t gui_container_same_line(gui_control_t* _ctrl);
int32_t gui_container_new_line(gui_control_t* _ctrl);
int32_t gui_container_spacing(gui_control_t* _ctrl, float _n);

each one stamps onto the NEXT add then clears itself, so they are set n forget rather than a mode you have to turn back off

the flow settings

int32_t gui_container_set_flow(gui_control_t* _ctrl, int32_t _flow);
int32_t gui_container_set_gap(gui_control_t* _ctrl, float _gap);
int32_t gui_container_set_pad(gui_control_t* _ctrl, float _pad);
int32_t gui_container_relayout(gui_control_t* _ctrl);

each of the three setters re-flows on its own, relayout is for a hint changed after the add, which does not. _flow is a gui_flow_t, gui_flow_vertical, gui_flow_horizontal or gui_flow_none

scrolling

int32_t gui_container_set_scroll(gui_control_t* _ctrl, int32_t _on);
int32_t gui_container_scroll_to(gui_control_t* _ctrl, float _y);
int32_t gui_container_scroll_by(gui_control_t* _ctrl, float _dy);
int32_t gui_container_scroll_y(gui_control_t* _ctrl, float* _out);
int32_t gui_container_max_scroll(gui_control_t* _ctrl, float* _out);
int32_t gui_container_content_h(gui_control_t* _ctrl, float* _out);
  • set_scroll builds or drops the containers bar, so it is a real change n not a flag
  • both scroll calls are clamped, so an over-scroll is a no-op n not an error, n positive runs down the content

On this page