menu.lua

-- ============================================================================
-- NATIVE MENU ELEMENT TYPES
-- ============================================================================
-- These classes describe the low-level objects returned by `core.menu.*`.
-- They exist for old plugins and advanced custom-window code. For ordinary
-- plugin settings choose one of these higher-level surfaces:
--
-- * Recommended: `_G.menu` from .api/common/menu/api.lua. It owns rendering,
--   persistence, search, layout, modifier chords, permashow, and keybind modes.
-- * Compatibility: `require("common/menu/menu_api")` from
--   .api/common/menu/menu_api.lua. It keeps old imperative modules working and
--   translates their trees/elements into the modern retained menu.
--
-- Native elements are immediate-mode: create them once, render the same object
-- from a menu callback, and read it with get/get_state. Their constructor value
-- is the first-run/reset default and their id is the persistence key. Keep ids
-- stable and plugin-prefixed; labels may change.
--
-- The native keybind classes below expose their historical integer/boolean mode
-- model. They do not expose the modern exact `modes = {...}` whitelist or
-- `default_mods` chord declaration. Use `_G.menu` when users need configurable
-- hold/toggle/release choices, double-click mode switching, or WoW modifiers.
-- ============================================================================

---@class tree_node
---@field is_open fun():boolean
---@field get_type fun(self:tree_node):integer
-- [WOW ONLY] The recovered C++ binding returns the open/body-run boolean.
---@field render fun(self:tree_node, header:string, callback:function):boolean
-- [/WOW ONLY]
---@field get_widget_bounds fun(self:tree_node):table -- Returns a table with 2 elements, min and max. get_widget_bounds().min is the left border of the widget, and .max is the right border.
---@field set_open_state fun(self:tree_node, state:boolean):nil
---@field just_issued_state_change fun(self:tree_node):boolean -- Returns whether the open/close state just changed.
---@field get_label fun(self:tree_node):string -- The menu element needs to be rendered for this to return a string different than ""
---@field set fun(self:checkbox, nil):nil -- Dummy function. Do not use. This is for you to be able to loop menu elements and set them all to default without any LUA errors.
---@field get_default fun(self:tree_node):nil -- Dummy function. Do not use.
---@field get fun(self:checkbox):nil

---@class checkbox
---@field get_state fun():boolean
---@field get_type fun(self:checkbox)
---@field set fun(self: checkbox, new_state:boolean):nil
-- [WOW ONLY] The native fourth stack slot is the optional post-row separator.
---@field render fun(self:checkbox, label:string, tooltip:string|nil, add_separator:boolean|nil):nil
-- [/WOW ONLY]
---@field get_widget_bounds fun(self:checkbox):table -- Returns a table with 2 elements, min and max. get_widget_bounds().min is the left border of the widget, and .max is the right border.
---@field set fun(self:checkbox, val:boolean):nil
---@field get_default fun(self:checkbox):boolean
---@field get_label fun(self:checkbox):string -- The menu element needs to be rendered for this to return a string different than ""

---@class key_checkbox
---@field get_main_checkbox_state fun(self:key_checkbox):boolean
---@field get_key_code fun(self:key_checkbox):integer
---@field get_keybind_state fun(self:key_checkbox):boolean
---@field set_toggle_state fun(self:key_checkbox, state:boolean):nil
---@field set_key fun(self:key_checkbox, key:integer):nil
---@field set_mode fun(self:key_checkbox, mode:integer):nil
---@field should_show_on_control_panel fun(self:key_checkbox):boolean
---@field get_mode fun(self:key_checkbox):integer -- 0 is hold, 1 is toggle, 2 is always
---@field get_type fun(self:key_checkbox)
---@field render fun(self:key_checkbox, label:string, tooltip:string|nil):nil
---@field set_keybind_forced_state fun(self:key_checkbox, state:boolean):nil -- Forces the keybind to a specific state.
---@field stop_forcing_keybind_state fun(self:key_checkbox):nil -- Stops forcing the keybind state.
---@field get_label fun(self:key_checkbox):string -- The menu element needs to be rendered for this to return a string different than ""
---@field set fun(self:key_checkbox):nil -- Dummy function. Do not use.
---@field get_default fun(self:key_checkbox):nil -- Dummy function. Do not use.

---@class slider_int
---@field get fun():number
---@field get_type fun(self:slider_int)
---@field set fun(self:slider_int, new_value:integer):nil
---@field render fun(self:slider_int, label:string, tooltip:string|nil):nil
---@field get_widget_bounds fun(self:slider_int):table -- Returns a table with 2 elements, min and max. get_widget_bounds().min is the left border of the widget, and .max is the right border.
---@field set fun(self:slider_int, val:integer):nil
---@field get fun(self:slider_int):integer
---@field get_default fun(self:slider_int):integer
---@field get_label fun(self:slider_int):string -- The menu element needs to be rendered for this to return a string different than ""

---@class slider_float
---@field get fun():number
---@field get_type fun(self:slider_float)
---@field set fun(self:slider_float, new_value:number):nil
---@field render fun(self:slider_float, label:string, tooltip:string|nil):nil
---@field get_widget_bounds fun(self:slider_float):table -- Returns a table with 2 elements, min and max. get_widget_bounds().min is the left border of the widget, and .max is the right border.
---@field set fun(self:slider_float, val:number):nil
---@field get fun(self:slider_float):number
---@field get_default fun(self:slider_float):number
---@field get_label fun(self:slider_float):string -- The menu element needs to be rendered for this to return a string different than ""

---@class combobox
---@field get fun():number
---@field get_type fun(self:combobox)
---@field get_label fun(self:combobox):string -- The menu element needs to be rendered for this to return a string different than ""
---@field get_widget_bounds fun(self:combobox):table -- Returns a table with 2 elements, min and max. get_widget_bounds().min is the left border of the widget, and .max is the right border.
---@field set fun(self:combobox, new_value:number):nil
---@field is_showing_on_control_panel fun(self:combobox):boolean
---@field set_is_showing_on_control_panel fun(self:combobox):nil
---@field render fun(self:combobox, label:string, options:table, tooltip:string|nil):nil
---@field set fun(self:combobox, val:integer):nil
---@field get fun(self:combobox):integer
---@field get_default fun(self:combobox):integer -- Returns the default value (1-based index).
---@field set_draggable_state fun(self:combobox, state:boolean):nil -- Sets the draggable state for the combobox.
---@field set_items fun(self:combobox, items:string[]):nil -- Sets the items list (max 64 entries).
---@field get_items fun(self:combobox):string[] -- Returns the items list as a string array.

---@class combobox_reorderable
---@field get fun():number
---@field get_type fun(self:combobox_reorderable)
-- [WOW ONLY] Items are supplied by set_items; render takes label and tooltip.
---@field render fun(self:combobox_reorderable, label:string, tooltip:string|nil):nil
-- [/WOW ONLY]
---@field set fun(self:combobox_reorderable, val:integer):nil
---@field get fun(self:combobox_reorderable):integer
---@field get_item_at_index fun(self:combobox_reorderable, index:integer):string -- Gets the item name at a 1-based index.
---@field set_items fun(self:combobox_reorderable, items:string[]):nil -- Sets the items list.
---@field get_default fun(self:combobox_reorderable):integer -- Returns the default value (1-based index).

---@class combobox_reorderable_ow
---@field render fun(self:combobox_reorderable_ow, label:string, tooltip:string|nil):nil
---@field get fun(self:combobox_reorderable_ow):integer -- Returns the current value (1-based index).
---@field get_type fun(self:combobox_reorderable_ow):integer
---@field get_item_at_index fun(self:combobox_reorderable_ow, index:integer):string -- Gets the item name at a 1-based index.
---@field set_items fun(self:combobox_reorderable_ow, items:string[]):nil -- Sets the items list (must match original count).
---@field get_items fun(self:combobox_reorderable_ow):string[] -- Returns the items list as a string array.

---@class keybind
---@field get_type fun(self:keybind)
---@field get_label fun(self:keybind):string -- The menu element needs to be rendered for this to return a string different than ""
---@field get_state fun(self:keybind):boolean
---@field get_key_code fun(self:keybind):integer
---@field get_widget_bounds fun(self:keybind):table -- Returns a table with 2 elements, min and max. get_widget_bounds().min is the left border of the widget, and .max is the right border.
---@field get_toggle_state fun(self:keybind):boolean
---@field set_key fun(self:keybind, new_key:number):nil
---@field set_is_showing_on_control_panel fun(self:keybind):nil
---@field is_showing_on_control_panel fun(self:keybind):boolean
---@field set_toggle_state fun(self:keybind, new_state:boolean):nil
---@field render fun(self:keybind, label:string, tooltip:string|nil, add_separator:boolean|nil):nil
---@field set fun(self:keybind, val:integer):nil
---@field get fun(self:keybind):integer
---@field get_default fun(self:keybind):integer -- Returns the default key code.
---@field set_forced_state fun(self:keybind, state:boolean):nil -- Forces the keybind to a specific state.
---@field stop_forcing_state fun(self:keybind):nil -- Stops forcing the keybind state.
---@field get_forced_state fun(self:keybind):boolean -- Returns the current forced state.
---@field set_draggable_state fun(self:keybind, state:boolean):nil -- Sets whether the keybind is draggable.

---@class button
---@field get_type fun(self:button)
---@field is_clicked fun(self:button):boolean
---@field get_widget_bounds fun(self:button):table -- Returns a table with 2 elements, min and max. get_widget_bounds().min is the left border of the widget, and .max is the right border.
-- [WOW ONLY] Native button render returns the same frame-local click pulse.
---@field render fun(self:button, label:string, tooltip:string|nil):boolean
-- [/WOW ONLY]
---@field get_label fun(self:button):string -- The menu element needs to be rendered for this to return a string different than ""
---@field set fun(self:checkbox, nil):nil -- Dummy function. Do not use. This is for you to be able to loop menu elements and set them all to default without any LUA errors.
---@field get fun(self:checkbox):nil
---@field get_default fun(self:button):nil -- Dummy function. Do not use.

---@class text_input
---@field get_type fun(self:text_input)
---@field get_text fun(self:text_input):string
---@field get_widget_bounds fun(self:text_input):table -- Returns a table with 2 elements, min and max. get_widget_bounds().min is the left border of the widget, and .max is the right border.
---@field get_text_as_number fun(self:text_input):number
---@field render fun(self:text_input, label:string, tooltip:string|nil):nil
---@field render_custom fun(self:text_input, label:string, tooltip:string, frame_bg:color, border_color:color, text_selected_bg_col:color, text_color:color, width_offset:number, height_offset:number|nil):nil
---@field set fun(self:text_input, val:string):nil
---@field get fun(self:text_input):integer
---@field get_default fun(self:text_input):nil -- Dummy function. Do not use.
---@field is_reading_input fun(self:text_input):boolean -- Returns whether the text input is currently being edited/focused.
---@field set_buffer fun(self:text_input, text:string):nil -- Sets the text buffer content.
---@field copy_to_clipboard fun(self:text_input):nil -- Copies the current text to clipboard.
---@field get_label fun(self:text_input):string -- The menu element needs to be rendered for this to return a string different than ""

---@class color_picker
---@field get fun():color
---@field get_type fun(self:color_picker)
---@field get_widget_bounds fun(self:color_picker):table -- Returns a table with 2 elements, min and max. get_widget_bounds().min is the left border of the widget, and .max is the right border.
---@field render fun(self:color_picker, label:string, tooltip:string|nil):nil
---@field set fun(self:color_picker, val:color):nil
---@field get fun(self:color_picker):color
---@field get_default fun(self:color_picker):color
---@field get_label fun(self:color_picker):string -- The menu element needs to be rendered for this to return a string different than ""

---@class header
---@field get_type fun(self:header)
---@field render fun(self:header, label:string, color:color):nil
---@field get_label fun(self:header):string -- The menu element needs to be rendered for this to return a string different than ""
---@field set fun(self:checkbox, nil):nil -- Dummy function. Do not use. This is for you to be able to loop menu elements and set them all to default without any LUA errors.
---@field get fun(self:checkbox):nil

---@class window
---@field set_window_cross_round fun(self:window):nil
---@field set_initial_size fun(self:window, size:vec2):nil
---@field set_initial_position fun(self:window, pos:vec2):nil
---@field set_visibility fun(self:window, visibility:boolean):nil
---@field set_next_widget_width fun(self:window, width:number):nil
---@field set_next_window_padding fun(self:window, padding:vec2):nil
---@field set_next_window_min_size fun(self:window, min_size:vec2):nil
---@field set_next_window_items_spacing fun(self:window, spacing:vec2):nil
---@field set_next_window_items_inner_spacing fun(self:window, inner_spacing:vec2):nil
---@field set_corner_rounding fun(self:window, rounding:number):nil
---@field get_corner_rounding fun(self:window):number
---@field set_block_movement fun(self:window, block:boolean):nil
---@field set_draw_to_foreground fun(self:window, enabled:boolean):nil

---@class window
---@field get_size fun(self:window):vec2
---@field get_position fun(self:window):vec2
---@field get_mouse_pos fun(self:window):vec2
---@field get_mouse_pos_local fun(self:window):vec2
---@field get_text_size fun(self:window, text:string):vec2
---@field get_wrapped_text_size fun(self:window, text:string, width:number):vec2 -- Returns the size of the text when wrapped to the given width
---@field force_window_size fun(self:window, size:vec2):nil
---@field get_text_centered_x_pos fun(self:window, text:string):number
---@field set_current_context_dynamic_drawing_offset fun(self:window, offset:vec2):nil
---@field get_current_context_dynamic_drawing_offset fun(self:window):vec2
---@field add_artificial_item_bounds fun(self:window, bounds_start:vec2, bounds_end:vec2, id:string):nil
---@field get_available_region fun(self:window):vec2 -- Returns the available region size for content
---@field get_min_size fun(self:window):vec2 -- Returns the minimum size of the window
---@field get_scroll fun(self:window):vec2 -- Returns the current scroll position (x, y)
---@field get_max_scroll_y fun(self:window):number -- Returns the maximum scroll Y value
---@field set_scroll_y fun(self:window, scroll:number):nil -- Sets the scroll Y position
---@field center_text fun(self:window, text:string):nil -- Centers the text horizontally in the window

---@class window
---@field is_being_shown fun(self:window):boolean
---@field render_tooltip_default fun(self:window, text:string):nil
---@field is_animation_finished fun(self:window, id:integer):boolean
---@field is_mouse_button_pressed fun(self:window, button:integer):boolean
---@field is_mouse_button_clicked fun(self:window, button:integer):boolean
---@field is_rect_clicked fun(self:window, rect_min:vec2, rect_max:vec2):boolean
---@field push_item fun(self:window, label:string):nil
---@field pop_item fun(self:window):nil
---@field is_window_clicked fun(self:window):boolean
---@field is_window_hovered fun(self:window):boolean
---@field is_window_double_clicked fun(self:window):boolean
---@field is_window_focused fun(self:window):boolean -- Returns true if the window is currently focused
---@field is_any_item_active fun(self:window):boolean -- Returns true if any item is currently active
---@field stop_forcing_size fun(self:window):nil
---@field is_rect_pressed fun(self:window, rect_min:vec2, rect_max:vec2):boolean
---@field is_mouse_hovering_rect fun(self:window, rect_min:vec2, rect_max:vec2):boolean
---@field set_focus fun(self:window):nil -- Forces the window to be focused (when focused, a window will be rendered on top of all other windows and will begin accepting inputs)
---@field is_mouse_hovering_rect_block_movement fun(self:window, rect_min:vec2, rect_max:vec2):boolean -- Automatically blocks the window movement when true
---@field is_rect_double_clicked fun(self:window, rect_min:vec2, rect_max:vec2):boolean
---@field render_tooltip_text_only fun(self:window, text:string, text_color:color):nil
---@field render_tooltip_custom fun(self:window, text:string, text_color:color, background_color:color, border_color:color, faded_rects_color:color, x_text_offset:number, y_text_offset:number, faded_rects_y_thickness:number, faded_rects_x_thickness:number):nil

---@class window
---@field render_text fun(self:window, font_id:integer, pos_offset:vec2, col:color, text:string):nil
---@field render_text_custom_size fun(self:window, font_id:integer, pos_offset:vec2, col:color, font_size:number, text:string):nil -- Renders text with a custom font size
---@field render_text_wrapped fun(self:window, text:string, color:color, max_wrap_width:number):nil -- Renders text that wraps at the given width
--note: you can also pass special rect rounding flags after the thickness parameter (up to 4 flags, integers). Check enums to see what these flags mean.
---@field render_rect fun(self:window, pos_min_offset:vec2, pos_max_offset:vec2, col:color, rounding:number, thickness:number):nil
--note: you can also pass special rect rounding flags after the thickness parameter (up to 4 flags, integers). Check enums to see what these flags mean.
---@field render_rect_filled fun(self:window, pos_min_offset:vec2, pos_max_offset:vec2, col:color, rounding:number, flags:table|nil):nil
--note: you can also pass special rect rounding flags after the thickness parameter (up to 4 flags, integers). Check enums to see what these flags mean.
---@field render_rect_filled_multicolor fun(self:window, pos_min_offset:vec2, pos_max_offset:vec2, col_upr_left:color, col_upr_right:color, col_bot_right:color, col_bot_left:color, rounding:number, flags:table|nil):nil
---@field render_smooth_rect fun(self:window, p_min:vec2, p_max:vec2, col:color, rounding:number|nil, softness:number|nil):nil
---@field render_drop_shadow fun(self:window, p_min:vec2, p_max:vec2, col:color, offset_x:number, offset_y:number, element_width:number, element_height:number, rounding:number|nil, softness:number|nil, spread:number|nil):nil
---@field render_border_rect fun(self:window, p_min:vec2, p_max:vec2, fill:color, border:color, rounding:number|nil, softness:number|nil, thickness:number|nil):nil
---@field render_linear_gradient fun(self:window, p_min:vec2, p_max:vec2, color_start:color, color_end:color, angle:number|nil, rounding:number|nil, softness:number|nil):nil
---@field render_keybind_pill fun(self:window, p_min:vec2, p_max:vec2, base:color, elevated:color, accent:color, rounding:number|nil, hover:number|nil, listening:number|nil, time:number|nil, speed:number|nil):nil
---@field render_dropdown_field fun(self:window, p_min:vec2, p_max:vec2, base:color, elevated:color, accent:color, rounding:number|nil, hover:number|nil, open:number|nil, time:number|nil, speed:number|nil):nil
---@field render_section_header fun(self:window, p_min:vec2, p_max:vec2, primary:color, secondary:color, accent:color, head_split:number|nil, rounding:number|nil, hover:number|nil, open:number|nil, time:number|nil, speed:number|nil):nil
---@field render_slider_track fun(self:window, p_min:vec2, p_max:vec2, fill_low:color, fill_high:color, rail:color, fill_t:number, rounding:number|nil, hover:number|nil, time:number|nil, speed:number|nil):nil
---@field render_hover_pill fun(self:window, p_min:vec2, p_max:vec2, base:color, streak:color, rounding:number|nil, softness:number|nil, density:number|nil, time:number|nil, speed:number|nil):nil
---@field render_circle_percentage fun(self:window, p_min:vec2, p_max:vec2, bg_color:color, fill_start_color:color, fill_end_color:color, progress:number, start_angle_rad:number|nil, direction:number|nil, inner_norm:number|nil, outer_norm:number|nil, softness:number|nil):nil
---@field render_circle fun(self:window, center:vec2, radius:number, color:color, thickness:number):nil
---@field render_circle_filled fun(self:window, center:vec2, radius:number, color:color):nil
---@field render_bezier_quadratic fun(self:window, p1:vec2, p2:vec2, p3:vec2, color:color, thickness:number, num_segments:integer):nil
---@field render_bezier_cubic fun(self:window, p1:vec2, p2:vec2, p3:vec2, p4:vec2, color:color, thickness:number, num_segments:integer):nil
---@field render_triangle fun(self:window, p1:vec2, p2:vec2, p3:vec2, col:color, thickness:number):nil
---@field render_triangle_filled fun(self:window, p1:vec2, p2:vec2, p3:vec2, col:color):nil
---@field render_triangle_filled_multi_color fun(self:window, p1:vec2, p2:vec2, p3:vec2, col_1:color, col_2:color, col_3:color):nil
---@field render_line fun(self:window, p1:vec2, p2:vec2, col:color, thickness:number):nil
---@field render_polyline fun(self:window, points:number[], point_count:integer, col:color, thickness:number):nil
---@field render_gif fun(self:window, gif_id:integer, p_min:vec2, p_max:vec2, tint:color|nil, speed:number|nil):nil
---@field render_text_custom_size_xy fun(self:window, font_id:integer, x:number, y:number, col:integer, font_size:number, text:string):nil
---@field render_text_centered_outlined_xy fun(self:window, font_id:integer, min_x:number, min_y:number, max_x:number, max_y:number, fill_col:integer, font_size:number, text:string, border_px:number|nil, outline_col:integer|nil):nil
---@field render_line_xy fun(self:window, x1:number, y1:number, x2:number, y2:number, col:integer, thickness:number):nil
---@field render_rect_xy fun(self:window, min_x:number, min_y:number, max_x:number, max_y:number, col:integer, rounding:number, thickness:number, flag_1:integer|nil, flag_2:integer|nil, flag_3:integer|nil, flag_4:integer|nil):nil
---@field render_rect_filled_xy fun(self:window, min_x:number, min_y:number, max_x:number, max_y:number, col:integer, rounding:number, flag_1:integer|nil, flag_2:integer|nil, flag_3:integer|nil, flag_4:integer|nil):nil
---@field render_rect_filled_multicolor_xy fun(self:window, min_x:number, min_y:number, max_x:number, max_y:number, col_upr_left:integer, col_upr_right:integer, col_bot_right:integer, col_bot_left:integer, rounding:number, flag_1:integer|nil, flag_2:integer|nil, flag_3:integer|nil, flag_4:integer|nil):nil
---@field render_circle_filled_xy fun(self:window, center_x:number, center_y:number, radius:number, col:integer, num_segments:integer|nil):nil
---@field push_clip_rect_xy fun(self:window, min_x:number, min_y:number, max_x:number, max_y:number, intersect:boolean):nil
---@field force_next_begin_window_pos_xy fun(self:window, x:number, y:number):nil
---@field force_window_size_xy fun(self:window, width:number, height:number):nil
---@field set_next_window_padding_xy fun(self:window, x:number, y:number):nil
---@field set_next_window_items_spacing_xy fun(self:window, x:number, y:number):nil
--- sets the background of the window (call before begin) to a multi-colored rectangle with the given colors. If this function is called, the color passed to the begin function is ignored.
---@field set_background_multicolored fun(self:window, top_left_color:color, top_right_color:color, bot_right_color:color, bot_left_color:color):nil
---forces the next window position. Call before begin.
---@field force_next_begin_window_pos fun(self:window, position:vec2):nil
---stops forcing the next window position 
---@field stop_forcing_position fun(self:window):nil
---function to avoid console errors when calling set_next_window_padding or spacing
---@field set_end_called_state fun(self:window):nil
---@field copy_to_clipboard fun(self:window, text:string):nil
---@field get_clipboard_text fun(self:window):string

---@class window
---@field push_font fun(self:window, font_id:integer):nil
---@field pop_font fun(self:window):nil -- Pops the previously pushed font
---@field add_menu_element_pos_offset fun(self:window, pos_offset:vec2):nil
---@field begin_group fun(self:window, begin_func:function):nil
---@field begin_window_sub_context fun(self:window, offset:vec2, add_flags:boolean, begin_func:function):nil
---@field allocate_space fun(self:window, width:number, height:number, spacing:number|nil):vec2, vec2
---@field begin_navbar fun(self:window, dock:integer, size:number, offset_or_callback:vec2|function, spacing_or_callback:number|function|nil, callback:function|nil):boolean
---@field begin_navbar_at fun(self:window, position:vec2, size:vec2, callback:function):boolean
---@field begin_content_area fun(self:window, callback:function):boolean
---@field set_next_window_close_cross_pos_offset fun(self:window, offset:vec2):nil
---@field render_text_clipped fun(self:window, rect_start:vec2, rect_end:vec2, text:string):nil
---@field block_input_capture fun(self:window):nil
---@field begin_popup fun(self:window, bg_color:color, border_color:color, size:vec2, pos:vec2, is_close_on_release:boolean, is_triggering_from_button:boolean, begin_func:function):boolean
---@field push_clip_rect fun(self:window, min:vec2, max:vec2, intersect:boolean):nil -- Pushes a clipping rectangle onto the stack
---@field pop_clip_rect fun(self:window):nil -- Pops the previously pushed clipping rectangle
---@field set_id fun(self:window, id:string):nil -- Sets the window ID
---@field get_type fun(self:window):integer -- Returns the window type
---@field set_render_layer fun(self:window, layer:integer):nil -- Sets the render layer for the window
---@field get_close_cross_bounds fun(self:window):table -- Returns a table with min and max vec2 representing the close cross bounds relative to window position
--note: you can also pass special_window_flag_1:integer, special_window_flag_2:integer, special_window_flag_3:integer after the cross_style parameter. Check enums to see what these parameters represent

---@class window
local window = {}

--- Begins rendering the window with various options.
--- @param self window The window object.
--- @param resizing_flag integer The flag for resizing options.
--- @param is_adding_close_cross boolean Whether to add a close cross to the window.
--- @param bg_color color The background color of the window.
--- @param border_color color The border color of the window.
--- @param cross_style integer The style of the close cross.
--- @param begin_func function The function to execute when beginning the window.
--- @return boolean Indicates if the window is open.
--- @overload fun(self: window, resizing_flag: integer, is_adding_close_cross: boolean, bg_color: color, border_color: color, cross_style: integer, special_window_flag_1: integer, begin_func: function): boolean
--- @overload fun(self: window, resizing_flag: integer, is_adding_close_cross: boolean, bg_color: color, border_color: color, cross_style: integer, special_window_flag_1: integer, special_window_flag_2: integer, begin_func: function): boolean
--- @overload fun(self: window, resizing_flag: integer, is_adding_close_cross: boolean, bg_color: color, border_color: color, cross_style: integer, special_window_flag_1: integer, special_window_flag_2: integer, special_window_flag_3: integer, begin_func: function): boolean
function window:begin(resizing_flag, is_adding_close_cross, bg_color, border_color, cross_style, begin_func, ...)
    -- Function implementation
    return false
end

---@class window
---@field draw_next_dynamic_widget_on_new_line fun(self:window):nil
---@field draw_next_dynamic_widget_on_same_line fun(self:window, offset_from_start:number|nil, spacing:number|nil):nil
---@field add_text_on_dynamic_pos fun(self:window, col:color, text:string):nil
---@field add_separator fun(self:window, right_sep_offset:number, left_sep_offset:number, y_offset:number, width_offset:number, custom_color:color):nil
---@field animate_widget fun(self:window, animation_id:integer, start_pos:vec2, end_pos:vec2, starting_alpha:integer, max_alpha:integer, alpha_speed:number, movement_speed:number, only_once:boolean):table
---@field make_loading_circle_animation fun(self:window, id:integer, center:vec2, radius:number, color:color, thickness:number, animation_type:integer)

-- ============================================================================
-- SDF paint pack (shader-driven primitives, League-core port).
-- All positions are WINDOW-LOCAL offsets (added to the window's position).
-- `time` is an absolute clock in seconds (pass core.time()); `speed` scales it.
-- Animated effects are resolution-independent and draw as a single quad each.
-- ============================================================================

---@class window
---Soft radial fog puff centered on `center`. `density` (default 3.0) controls falloff steepness; lower = wider, softer halo.
---@field render_fog fun(self:window, center:vec2, radius:number, col:color, density:number|nil):nil
---Rounded rect, soft-edged (alias of render_smooth_rect under the League name). rounding default 4, softness default 1.
---@field render_sdf_rect fun(self:window, p_min:vec2, p_max:vec2, col:color, rounding:number|nil, softness:number|nil):nil
---Soft anti-aliased filled circle (League name). softness default 1.
---@field render_sdf_circle fun(self:window, center:vec2, radius:number, col:color, softness:number|nil):nil
---Filled circle with optional border ring. border defaults to none; border_width default 0; softness default 1.
---@field render_filled_circle fun(self:window, center:vec2, radius:number, fill:color, border:color|nil, border_width:number|nil, softness:number|nil):nil
---Outer glow halo around a (rounded) rect. glow_size default 10 px, glow_intensity default 1.
---@field render_rect_glow fun(self:window, p_min:vec2, p_max:vec2, glow_col:color, rounding:number|nil, glow_size:number|nil, glow_intensity:number|nil):nil
---Complete animated button face (base plate + elevation + accent sheen). hover/press are 0..1 blend factors; border_in insets the border.
---@field render_button_face fun(self:window, p_min:vec2, p_max:vec2, base:color, elevated:color, accent:color, rounding:number|nil, hover:number|nil, press:number|nil, time:number|nil, speed:number|nil, border_in:number|nil):nil
---Page-title plate with accent underline + halo. rounding default 8.
---@field render_page_title fun(self:window, p_min:vec2, p_max:vec2, plate:color, accent:color, halo:color, rounding:number|nil, hover:number|nil, time:number|nil, speed:number|nil):nil
---Toast/notification card: base plate, accent strip (strip_w, default 3) and lifetime progress bar (prog_h, default 2). alpha_env is the fade envelope 0..1; life_t is remaining-life 0..1.
---@field render_toast_card fun(self:window, p_min:vec2, p_max:vec2, base:color, elevated:color, accent:color, rounding:number|nil, alpha_env:number|nil, life_t:number|nil, strip_w:number|nil, prog_h:number|nil, time:number|nil, speed:number|nil):nil
---Animated aurora ribbon between two colors. intensity default 1.8.
---@field render_aurora fun(self:window, p_min:vec2, p_max:vec2, primary:color, secondary:color, intensity:number|nil, rounding:number|nil, softness:number|nil, time:number|nil, speed:number|nil):nil
---Animated layered dark fog (the menu's background weather). zoom/warp default 0.
---@field render_vanta_fog fun(self:window, p_min:vec2, p_max:vec2, base:color, highlight:color, secondary:color, density:number|nil, time:number|nil, speed:number|nil, zoom:number|nil, warp:number|nil):nil
---One-shot radial burst. Drive `progress` 0..1 yourself; `seed` varies the pattern.
---@field render_explosion fun(self:window, p_min:vec2, p_max:vec2, core_col:color, accent:color, progress:number|nil, seed:number|nil):nil
---Film-grain noise overlay. noise_scale default 2, intensity default 0.1.
---@field render_noise fun(self:window, p_min:vec2, p_max:vec2, base:color, noise_scale:number|nil, intensity:number|nil, rounding:number|nil, time:number|nil):nil
---Animated diagonal flame wash (three-color ramp). density default 1.5.
---@field render_diagonal_fire fun(self:window, p_min:vec2, p_max:vec2, core_col:color, mid:color, edge:color, density:number|nil, time:number|nil, speed:number|nil):nil
---Keybind pill in its ACTIVE state. hover/active are 0..1 blends; border_in insets the border.
---@field render_keybind_active fun(self:window, p_min:vec2, p_max:vec2, base:color, elevated:color, accent:color, rounding:number|nil, hover:number|nil, active:number|nil, time:number|nil, speed:number|nil, border_in:number|nil):nil
---Keybind pill in its LISTENING (press-a-key) state. listening is a 0..1 blend.
---@field render_keybind_listening fun(self:window, p_min:vec2, p_max:vec2, base:color, elevated:color, accent:color, rounding:number|nil, hover:number|nil, listening:number|nil, time:number|nil, speed:number|nil, border_in:number|nil):nil
---Search/tutorial highlight ring, reticle style (corner brackets + pulse). pulse 0..1, brightness default 1.
---@field render_widget_highlight_reticle fun(self:window, p_min:vec2, p_max:vec2, body:color, accent:color, halo:color, rounding:number|nil, pulse:number|nil, time:number|nil, speed:number|nil, brightness:number|nil):nil
---Search/tutorial highlight, scanline sweep style. Same parameters as the reticle variant.
---@field render_widget_highlight_scanline fun(self:window, p_min:vec2, p_max:vec2, body:color, accent:color, halo:color, rounding:number|nil, pulse:number|nil, time:number|nil, speed:number|nil, brightness:number|nil):nil
---Search/tutorial highlight, sigil style. Same parameters as the reticle variant.
---@field render_widget_highlight_sigil fun(self:window, p_min:vec2, p_max:vec2, body:color, accent:color, halo:color, rounding:number|nil, pulse:number|nil, time:number|nil, speed:number|nil, brightness:number|nil):nil
---Soft anti-aliased line. thickness default 2, softness default 1.5.
---@field render_smooth_line fun(self:window, p1:vec2, p2:vec2, col:color, thickness:number|nil, softness:number|nil):nil
---Soft arc stroke between two angles (radians). thickness default 2, softness default 1.
---@field render_arc fun(self:window, center:vec2, radius:number, start_angle_rad:number, end_angle_rad:number, col:color, thickness:number|nil, softness:number|nil):nil
---Frosted-glass blur of whatever is behind the quad, masked to a rounded rect whose corner radius is the WINDOW's set_corner_rounding (there is no per-call radius).
---EXPENSIVE: every render_blur call copies the full backbuffer (one CopyResource + barriers), so use at most one per window per frame and never try to
---compose a non-rectangular frosted shape out of strips. The kernel is clamped inside the quad, so blur_radius must suit the quad size (large radii on
---small quads collapse into a directional smear: ~14/4.5 works for a ~36 px plate, 40/4.0 for full panels). tint (optional) is blended over the blur.
---@field render_blur fun(self:window, p_min:vec2, p_max:vec2, blur_radius:number|nil, sigma:number|nil, opacity:number|nil, tint:color|nil):nil

-- ============================================================================
-- Text measurement + custom scrollbar override.
-- ============================================================================

---@class scrollbar_state
---@field x_min number Track left edge (screen space)
---@field x_max number Track right edge (screen space)
---@field y_min number Track top edge (screen space)
---@field y_max number Track bottom edge (screen space)
---@field thumb_y_min number Thumb top edge (screen space)
---@field thumb_y_max number Thumb bottom edge (screen space)
---@field thumb_t number Scroll progress 0..1
---@field thumb_h_norm number Thumb height as a fraction of the track
---@field hov number Eased hover animation 0..1
---@field drag number Eased drag animation 0..1

---@class window
---Measures `text` in the given font at an explicit pixel size (unlike get_text_size, which uses the font's baked size).
---@field get_text_size_custom fun(self:window, font_id:integer, font_size:number, text:string):vec2
---One-shot: suppress the built-in scrollbar on the NEXT begin_navbar/begin_navbar_at (content still scrolls via wheel).
---@field set_next_no_scrollbar fun(self:window, flag:boolean):nil
---One-shot: arm a C++-managed custom scrollbar on the next navbar (NoScrollbar flag + thumb geometry + click/drag interaction).
---Pass nil for any color / 0 for any dimension to use built-in defaults. skip_paint=true suppresses the C++ paint so Lua can draw its own
---visual from get_scrollbar_state() while keeping the interaction.
---@field enable_next_scrollbar fun(self:window, enable:boolean, track_col:color|nil, thumb_col:color|nil, accent_col:color|nil, width:integer|nil, inset:integer|nil, min_thumb_h:integer|nil, skip_paint:boolean|nil, bottom_inset:integer|nil):nil
---Geometry + eased animation state of the most recent end-of-navbar scrollbar pass, or nil when there is no overflow / no override armed.
---@field get_scrollbar_state fun(self:window):scrollbar_state|nil