.. _stdlib_imgui_boost_v2:

============================================================
Boost macro layer — DSL for declarative widget composition
============================================================

.. das:module:: imgui_boost_v2

The boost DSL spine — ``[widget]`` and ``[container]`` function annotations.
Mark ``def myWidget(var state : ST, …)`` with ``[widget]`` and the macro
injects a ``widget_ident`` parameter, idempotently emits ``IDENT`` as a
module-scope state global at the first call site, parses the dotted-suffix
flag chain (``SAVE_BTN.PUBLIC``, ``RPS.NOTLIVE``), and rewrites the call to
``myWidget(IDENT, "IDENT", …)``. ``[container]`` is the block-arg sibling: same
identifier auto-emit, plus ``container_path_push(widget_ident)`` /
``container_path_pop()`` around ``invoke(blk)`` so leaf telemetry paths nest
into ``MAIN_WIN/SETTINGS_TAB/RPS``. UPPER_SNAKE_CASE identifiers by convention
(API_REWORK §4.5); auto-emit is module-scope only.

Begin/End pairing — which call paints always vs only-on-true — is NOT
abstracted; each container def authors its own ``Begin → invoke(blk) → End``
sequence so the imgui-irregular rules stay visible at the call site.



++++++++++++++++++++
Function annotations
++++++++++++++++++++

.. _handle-imgui_boost_v2-container:

.. das:attribute:: container

``[container]`` annotation — block-arg sibling of ``[widget]``; same identifier auto-emit, plus ``container_path_push``/``pop`` around ``invoke(blk)`` so leaf telemetry paths nest correctly.


.. _handle-imgui_boost_v2-edit_widget:

.. das:attribute:: edit_widget

``[edit_widget]`` annotation — registers an external-pointer widget. First parameter is the user-owned pointer (``T?``); macro injects ``widget_ident : string`` at index 1 and installs a call_macro that requires an explicit ``id="..."`` literal at the call site.


.. _handle-imgui_boost_v2-widget_dispatch:

.. das:attribute:: widget_dispatch

``[widget_dispatch]`` annotation — registers a per-state-struct dispatcher for HTTP set/click/open/close actions. Required signature: ``def <name>(var state : T; action : string; payload : string)``. Keyed by ``T`` (first parameter's struct type); the function name is irrelevant. One body per state struct covers every kind whose state is ``T``. Renames the user function to private ``__dispatch_body_<T>`` (avoids collision with same-named ``[widget]`` defs), emits a type-erased wrapper ``__dispatch_wrap_<T>``, and pushes an init call to ``register_widget_dispatch_for_type`` so ``dispatch_or_err`` resolves via ``meta.ti.hash`` at runtime.


.. _handle-imgui_boost_v2-widget:

.. das:attribute:: widget

``[widget]`` annotation — registers ``def fn(var state : ST, ...)`` as a stateful widget. Auto-emits the state global, injects ``widget_ident``, and installs a per-kind call_macro for dotted-flag parsing.


.. _handle-imgui_boost_v2-drawlist_prim:

.. das:attribute:: drawlist_prim

``[drawlist_prim]`` — registers ``def fn(var dl, ...)`` as a drawlist
primitive. Injects ``widget_ident`` at position 0 and a per-kind
call_macro that prepends a synthesized ``<mod>:<line>:<col>`` path key.


.. _handle-imgui_boost_v2-edit_container:

.. das:attribute:: edit_container

``[edit_container]`` annotation — block-arg sibling of ``[edit_widget]``. First parameter is the user-owned pointer (``T?``); last parameter must be ``blk : block``. Macro injects ``widget_ident : string`` at index 1 and wraps the body with ``container_path_push``/``pop`` so leaves rendered inside ``invoke(blk)`` nest under the container's path key. Same ``id="..."`` literal requirement as ``[edit_widget]``.



+++++++
Classes
+++++++

.. _struct-imgui_boost_v2-WidgetFunctionMacro:

.. das:attribute:: WidgetFunctionMacro : AstFunctionAnnotation

class WidgetFunctionMacro

.. _function-imgui_boost_v2_WidgetFunctionMacro_rq_apply_WidgetFunctionMacro_FunctionPtr_ModuleGroup_AnnotationArgumentList_das_string_0x23:

.. das:function:: WidgetFunctionMacro.apply(func: FunctionPtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool

def apply : function<(var self:ast::AstFunctionAnnotation;var func:ast_core::Function? aka FunctionPtr -const;var group:rtti_core::ModuleGroup -const;args:rtti_core::AnnotationArgumentList const;var errors:$::das_string -const):bool>

:Arguments: * **func** :  :ref:`FunctionPtr <alias-FunctionPtr>`

            * **group** :  :ref:`ModuleGroup <handle-rtti-ModuleGroup>`

            * **args** :  :ref:`AnnotationArgumentList <handle-rtti-AnnotationArgumentList>`

            * **errors** :  :ref:`das_string <handle-builtin-das_string>`

.. _struct-imgui_boost_v2-ContainerFunctionMacro:

.. das:attribute:: ContainerFunctionMacro : AstFunctionAnnotation

class ContainerFunctionMacro

.. _function-imgui_boost_v2_ContainerFunctionMacro_rq_apply_ContainerFunctionMacro_FunctionPtr_ModuleGroup_AnnotationArgumentList_das_string_0x2e:

.. das:function:: ContainerFunctionMacro.apply(func: FunctionPtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool

def apply : function<(var self:ast::AstFunctionAnnotation;var func:ast_core::Function? aka FunctionPtr -const;var group:rtti_core::ModuleGroup -const;args:rtti_core::AnnotationArgumentList const;var errors:$::das_string -const):bool>

:Arguments: * **func** :  :ref:`FunctionPtr <alias-FunctionPtr>`

            * **group** :  :ref:`ModuleGroup <handle-rtti-ModuleGroup>`

            * **args** :  :ref:`AnnotationArgumentList <handle-rtti-AnnotationArgumentList>`

            * **errors** :  :ref:`das_string <handle-builtin-das_string>`

.. _struct-imgui_boost_v2-DrawlistPrimCallMacro:

.. das:attribute:: DrawlistPrimCallMacro : AstCallMacro

class DrawlistPrimCallMacro

.. _function-imgui_boost_v2_DrawlistPrimCallMacro_rq_visit_DrawlistPrimCallMacro_ProgramPtr_Module_q__ExprCallMacro_q__0x43:

.. das:function:: DrawlistPrimCallMacro.visit(prog: ProgramPtr; mod: Module?; expr: ExprCallMacro?) : ExpressionPtr

def visit : function<(var self:ast::AstCallMacro;prog:smart_ptr<rtti_core::Program> aka ProgramPtr const;mod:rtti_core::Module? const;expr:ast_core::ExprCallMacro? const):ast_core::Expression? aka ExpressionPtr>

:Arguments: * **prog** :  :ref:`ProgramPtr <alias-ProgramPtr>`

            * **mod** :  :ref:`Module <handle-rtti-Module>`?

            * **expr** :  :ref:`ExprCallMacro <handle-ast-ExprCallMacro>`?

.. _struct-imgui_boost_v2-DrawlistPrimFunctionMacro:

.. das:attribute:: DrawlistPrimFunctionMacro : AstFunctionAnnotation

class DrawlistPrimFunctionMacro

.. _function-imgui_boost_v2_DrawlistPrimFunctionMacro_rq_apply_DrawlistPrimFunctionMacro_FunctionPtr_ModuleGroup_AnnotationArgumentList_das_string_0x56:

.. das:function:: DrawlistPrimFunctionMacro.apply(func: FunctionPtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool

def apply : function<(var self:ast::AstFunctionAnnotation;var func:ast_core::Function? aka FunctionPtr -const;var group:rtti_core::ModuleGroup -const;args:rtti_core::AnnotationArgumentList const;var errors:$::das_string -const):bool>

:Arguments: * **func** :  :ref:`FunctionPtr <alias-FunctionPtr>`

            * **group** :  :ref:`ModuleGroup <handle-rtti-ModuleGroup>`

            * **args** :  :ref:`AnnotationArgumentList <handle-rtti-AnnotationArgumentList>`

            * **errors** :  :ref:`das_string <handle-builtin-das_string>`

.. _struct-imgui_boost_v2-WidgetCallMacro:

.. das:attribute:: WidgetCallMacro : AstCallMacro

class WidgetCallMacro

.. _function-imgui_boost_v2_WidgetCallMacro_rq_visit_WidgetCallMacro_ProgramPtr_Module_q__ExprCallMacro_q__0x175:

.. das:function:: WidgetCallMacro.visit(prog: ProgramPtr; mod: Module?; expr: ExprCallMacro?) : ExpressionPtr

def visit : function<(var self:ast::AstCallMacro;prog:smart_ptr<rtti_core::Program> aka ProgramPtr const;mod:rtti_core::Module? const;expr:ast_core::ExprCallMacro? const):ast_core::Expression? aka ExpressionPtr>

:Arguments: * **prog** :  :ref:`ProgramPtr <alias-ProgramPtr>`

            * **mod** :  :ref:`Module <handle-rtti-Module>`?

            * **expr** :  :ref:`ExprCallMacro <handle-ast-ExprCallMacro>`?

.. _function-imgui_boost_v2_WidgetCallMacro_rq_canVisitArgument_WidgetCallMacro_ExprCallMacro_q__int_0xbd:

.. das:function:: WidgetCallMacro.canVisitArgument(expr: ExprCallMacro?; argIndex: int) : bool

def canVisitArgument : function<(var self:ast::AstCallMacro;expr:ast_core::ExprCallMacro? const;argIndex:int const):bool>

:Arguments: * **expr** :  :ref:`ExprCallMacro <handle-ast-ExprCallMacro>`?

            * **argIndex** : int

.. _struct-imgui_boost_v2-EditWidgetFunctionMacro:

.. das:attribute:: EditWidgetFunctionMacro : AstFunctionAnnotation

class EditWidgetFunctionMacro

.. _function-imgui_boost_v2_EditWidgetFunctionMacro_rq_apply_EditWidgetFunctionMacro_FunctionPtr_ModuleGroup_AnnotationArgumentList_das_string_0x34c:

.. das:function:: EditWidgetFunctionMacro.apply(func: FunctionPtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool

def apply : function<(var self:ast::AstFunctionAnnotation;var func:ast_core::Function? aka FunctionPtr -const;var group:rtti_core::ModuleGroup -const;args:rtti_core::AnnotationArgumentList const;var errors:$::das_string -const):bool>

:Arguments: * **func** :  :ref:`FunctionPtr <alias-FunctionPtr>`

            * **group** :  :ref:`ModuleGroup <handle-rtti-ModuleGroup>`

            * **args** :  :ref:`AnnotationArgumentList <handle-rtti-AnnotationArgumentList>`

            * **errors** :  :ref:`das_string <handle-builtin-das_string>`

.. _struct-imgui_boost_v2-EditContainerFunctionMacro:

.. das:attribute:: EditContainerFunctionMacro : AstFunctionAnnotation

class EditContainerFunctionMacro

.. _function-imgui_boost_v2_EditContainerFunctionMacro_rq_apply_EditContainerFunctionMacro_FunctionPtr_ModuleGroup_AnnotationArgumentList_das_string_0x355:

.. das:function:: EditContainerFunctionMacro.apply(func: FunctionPtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool

def apply : function<(var self:ast::AstFunctionAnnotation;var func:ast_core::Function? aka FunctionPtr -const;var group:rtti_core::ModuleGroup -const;args:rtti_core::AnnotationArgumentList const;var errors:$::das_string -const):bool>

:Arguments: * **func** :  :ref:`FunctionPtr <alias-FunctionPtr>`

            * **group** :  :ref:`ModuleGroup <handle-rtti-ModuleGroup>`

            * **args** :  :ref:`AnnotationArgumentList <handle-rtti-AnnotationArgumentList>`

            * **errors** :  :ref:`das_string <handle-builtin-das_string>`

.. _struct-imgui_boost_v2-EditExternalCallMacro:

.. das:attribute:: EditExternalCallMacro : AstCallMacro

Call macro installed by ``[edit_widget]`` — recognizes ``edit_kind(ptr, (id="...", ...))``, requires an explicit ``id=`` string literal, destructures the rest of the named-tuple to positional args (source order), and rewrites to a direct renderer call.

:Fields: * **kind_name** : string - < Name of the ``[edit_widget]``-decorated function; the rewritten call's target and macro_error subject.

         * **render_fn** :  :ref:`FunctionPtr <alias-FunctionPtr>` - < Underlying ``[edit_widget]`` function pointer; lives in the user module, read at visit time.

         * **render_fn_args** : array< :ref:`VariablePtr <alias-VariablePtr>`> - < User-facing args (positions 2..N after ``ptr`` + ``widget_ident``); cloned from ``render_fn`` to preserve names/defaults.



.. _function-imgui_boost_v2_EditExternalCallMacro_rq_visit_EditExternalCallMacro_ProgramPtr_Module_q__ExprCallMacro_q__0x398:

.. das:function:: EditExternalCallMacro.visit(prog: ProgramPtr; mod: Module?; expr: ExprCallMacro?) : ExpressionPtr

def visit : function<(var self:ast::AstCallMacro;prog:smart_ptr<rtti_core::Program> aka ProgramPtr const;mod:rtti_core::Module? const;expr:ast_core::ExprCallMacro? const):ast_core::Expression? aka ExpressionPtr>

:Arguments: * **prog** :  :ref:`ProgramPtr <alias-ProgramPtr>`

            * **mod** :  :ref:`Module <handle-rtti-Module>`?

            * **expr** :  :ref:`ExprCallMacro <handle-ast-ExprCallMacro>`?

.. _struct-imgui_boost_v2-WidgetDispatchFunctionMacro:

.. das:attribute:: WidgetDispatchFunctionMacro : AstFunctionAnnotation

class WidgetDispatchFunctionMacro

.. _function-imgui_boost_v2_WidgetDispatchFunctionMacro_rq_apply_WidgetDispatchFunctionMacro_FunctionPtr_ModuleGroup_AnnotationArgumentList_das_string_0x3dd:

.. das:function:: WidgetDispatchFunctionMacro.apply(func: FunctionPtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string) : bool

def apply : function<(var self:ast::AstFunctionAnnotation;var func:ast_core::Function? aka FunctionPtr -const;var group:rtti_core::ModuleGroup -const;args:rtti_core::AnnotationArgumentList const;var errors:$::das_string -const):bool>

:Arguments: * **func** :  :ref:`FunctionPtr <alias-FunctionPtr>`

            * **group** :  :ref:`ModuleGroup <handle-rtti-ModuleGroup>`

            * **args** :  :ref:`AnnotationArgumentList <handle-rtti-AnnotationArgumentList>`

            * **errors** :  :ref:`das_string <handle-builtin-das_string>`