.. _stdlib_imgui_layout_builtin:

====================================================
Layout helpers — splits, columns, docking, spacing
====================================================

.. das:module:: imgui_layout_builtin

Stateful layout helpers — splits, columns, and a fixed-orientation sidebar —
plus thin wrappers around ImGui's column primitives. ``split_h`` / ``split_v``
divide the available region between two ``BeginChild`` panes separated by a
draggable handle, with the split ratio persisted in ``SliderStateFloat``.
``dock_left`` is a stable-position left sidebar (not real docking — that lives
in ``imgui_internal.h`` and is off-limits) with a draggable right edge. The
``columns(N, ${col0}, ${col1}, …)`` call_macro expands to
``columns_open(N)`` / ``next_col()`` / ``columns_close()`` with one block
literal per column, so the column count must match the block-arg count
statically.



+++++++++++
Call macros
+++++++++++

.. _call-macro-imgui_layout_builtin-columns:

.. das:attribute:: columns

Function annotation columns

.. _call-macro-imgui_layout_builtin-split_v:

.. das:attribute:: split_v

Function annotation split_v

.. _call-macro-imgui_layout_builtin-dock_left:

.. das:attribute:: dock_left

Function annotation dock_left

.. _call-macro-imgui_layout_builtin-split_h:

.. das:attribute:: split_h

Function annotation split_h


+++++++
Columns
+++++++

  *  :ref:`columns_close () <function-imgui_layout_builtin_columns_close>`
  *  :ref:`columns_open (n: int; id: string = ""; border: bool = true) <function-imgui_layout_builtin_columns_open_int_string_bool>`
  *  :ref:`next_col () <function-imgui_layout_builtin_next_col>`

.. _function-imgui_layout_builtin_columns_close:

.. das:function:: columns_close()

Close a columns block (return to single-column layout). Underlying primitive emitted by the ``columns(N, …)`` call_macro.


.. _function-imgui_layout_builtin_columns_open_int_string_bool:

.. das:function:: columns_open(n: int; id: string = ""; border: bool = true)

Open an N-column block. `id` (default empty) is the ImGui id-stack tag for column-width persistence;
`border` (default on) draws the vertical dividers. Primitive emitted by the ``columns(N, …)``
call_macro; callable directly when the column count or shape is dynamic.


:Arguments: * **n** : int

            * **id** : string

            * **border** : bool

.. _function-imgui_layout_builtin_next_col:

.. das:function:: next_col()

Advance to the next column. Underlying primitive emitted by the ``columns(N, …)`` call_macro.



+++++
Trees
+++++

  *  :ref:`tree_node_open (text: string; flags: ImGuiTreeNodeFlags = imgui::ImGuiTreeNodeFlags.None) : bool <function-imgui_layout_builtin_tree_node_open_string_ImGuiTreeNodeFlags>`
  *  :ref:`tree_pop () <function-imgui_layout_builtin_tree_pop>`

.. _function-imgui_layout_builtin_tree_node_open_string_ImGuiTreeNodeFlags:

.. das:function:: tree_node_open(text: string; flags: ImGuiTreeNodeFlags = imgui::ImGuiTreeNodeFlags.None) : bool

`TreeNodeEx(label, flags) : bool` — open form WITHOUT auto-pair TreePop (use when the body renders
outside the conditional, e.g. ``same_line()`` after the header). Caller MUST invoke ``tree_pop()`` when the
return is true AND ``NoTreePushOnOpen`` was NOT set (that flag skips TreePush, so a TreePop would underflow).


:Arguments: * **text** : string

            * **flags** :  :ref:`ImGuiTreeNodeFlags <enum-imgui-ImGuiTreeNodeFlags>`

.. _function-imgui_layout_builtin_tree_pop:

.. das:function:: tree_pop()

Pair with `tree_node_open` (or the leaf-bool TreeNodeEx overload) when the return is true AND
`NoTreePushOnOpen` was NOT set. The `tree_node` container auto-pairs TreePop; this covers the manual case.



+++++++++++++
List clipping
+++++++++++++

  *  :ref:`list_clipper (items_count: int; body: block\<(start:int;end_:int):void\>) <function-imgui_layout_builtin_list_clipper_int_block_ls_start_c_int;end__c_int_c_void_gr_>`

.. _function-imgui_layout_builtin_list_clipper_int_block_ls_start_c_int;end__c_int_c_void_gr_:

.. das:function:: list_clipper(items_count: int; body: block<(start:int;end_:int):void>)

Cull a virtual list of `items_count` items to the visible region.
The block fires once per visible chunk with `[start, end_)` indices;
render exactly those rows inside the block.


:Arguments: * **items_count** : int

            * **body** : block<(start:int;end_:int):void>