---@meta

-- Generated from native/src/bindings/features/screen/tree.cpp. Do not edit.

---@alias NodeId integer
---@alias NodeType "box"|"text"|"button"|"custom"
---@alias NodeDirection "up"|"down"|"left"|"right"

---@class NodeSpec
---@field type NodeType
---@field w? number|"fill"|"auto"
---@field h? number|"fill"|"auto"
---@field pad? number
---@field gap? number
---@field align? "start"|"center"|"end"|"stretch"
---@field justify? "start"|"center"|"end"|"between"
---@field row? boolean
---@field at? table Absolute-position fields.
---@field interactive? boolean
---@field label? string
---@field font? ScreenFont

---@class NodeStyle
---@field color? ScreenColor
---@field background? ScreenColor Background offered to descendants.
---@field fill? ScreenColor Surface painted by a box.
---@field border? ScreenColor
---@field face? ScreenColor Default button surface.
---@field pressedFace? ScreenColor Pressed button surface.
---@field pressedColor? ScreenColor Pressed button text.
---@field focusColor? ScreenColor Distinct outline for directional focus.
---@field radius? integer
---@field font? ScreenFont
---@field textStyle? ScreenTextStyle

---@class TreeLib
tree = {}

---Drops the current tree; all existing IDs become invalid.
function tree.reset() end

---Creates a node, optionally as a child of an existing one.
---@param parent? NodeId Nil creates a root.
---@param spec NodeSpec
---@return NodeId
function tree.create(parent, spec) end

---Adopts an existing root as a child.
---@param parent NodeId
---@param child NodeId Existing root without a parent.
function tree.attach(parent, child) end

---Changes a node's requested size before layout.
---@param id NodeId
---@param w? number|"fill"|"auto"
---@param h? number|"fill"|"auto"
function tree.setSize(id, w, h) end

---Measures and places a subtree.
---@param root NodeId
---@param x integer
---@param y integer
---@param w integer
---@param h integer
---@return true? ok
---@return string? error
function tree.layout(root, x, y, w, h) end

---Releases temporary measurement and placement inputs after layout.
function tree.dropScratch() end

---Returns the deepest interactive node under a point.
---@param root NodeId
---@param x integer
---@param y integer
---@return NodeId?
function tree.hit(root, x, y) end

---Returns a node's placed rectangle.
---@param id NodeId
---@return integer x
---@return integer y
---@return integer w
---@return integer h
function tree.getRect(id) end

---Pans a scrollable node's children, clamped to the content. The node is marked dirty, so the next draw repaints it.
---@param id NodeId
---@param x integer
---@param y integer
function tree.setScroll(id, x, y) end

---Returns a scrollable node's current offset, or zeroes.
---@param id NodeId
---@return integer x, integer y
function tree.getScroll(id) end

---Returns how far each axis can pan before the content's far edge reaches the box. Zero on an axis whose content fits.
---@param id NodeId
---@return integer maxX, integer maxY
function tree.getScrollRange(id) end

---Replaces a node's text and marks it for repaint.
---@param id NodeId
---@param text string
function tree.setLabel(id, text) end

---Returns a node's text.
---@param id NodeId
---@return string?
function tree.getLabel(id) end

---Returns a node's parent.
---@param id NodeId
---@return NodeId?
function tree.getParent(id) end

---Sets the style roles a subtree inherits.
---@param id NodeId
---@param style NodeStyle
function tree.setStyle(id, style) end

---Marks a node for repaint.
---@param id NodeId
function tree.invalidate(id) end

---Sets a node's pressed state.
---@param id NodeId
---@param pressed boolean
function tree.setPressed(id, pressed) end

---Whether a node is pressed.
---@param id NodeId
---@return boolean
function tree.isPressed(id) end

---Focuses the first interactive node in layout order.
---@param root NodeId
---@return NodeId? focused
function tree.focusFirst(root) end

---Changes focus and invalidates the previously and newly focused nodes.
---@param id? NodeId Nil clears focus.
function tree.setFocus(id) end

---Returns the focused node.
---@return NodeId?
function tree.getFocus() end

---Moves to the nearest interactive node in the requested direction without wrapping.
---@param root NodeId
---@param direction NodeDirection
---@return NodeId? focused Current focus when no candidate exists.
function tree.moveFocus(root, direction) end

---Registers the painter every custom node calls. The clip arguments are the region of the node being painted now -- one band of a composited repaint -- so a painter can cull to it instead of redrawing itself once per band.
---@param painter fun(id: NodeId, x: integer, y: integer, w: integer, h: integer, clipX: integer, clipY: integer, clipW: integer, clipH: integer)
function tree.setPainter(painter) end

---Paints dirty nodes; the firmware owns publication to the physical display.
---@param root NodeId
function tree.draw(root) end

---Returns the number of nodes in the tree.
---@return integer
function tree.getCount() end

---Returns the tree's memory use.
---@return integer bytes
function tree.getFootprint() end