
--------------------------------------------------------------------------------
-- 文本元素模块
--------------------------------------------------------------------------------

---@alias ui_element_role
---| '"button"'
---| '"text_field"'
---| '"static_text"'
---| '"switch"'
---| '"checkbox"'
---| '"radio"'
---| '"slider"'
---| '"picker"'
---| '"scrollable"'
---| '"link"'
---| '"image"'
---| '"keyboard_key"'

---@alias ui_element_scroll_direction
---| '"down"'
---| '"up"'
---| '"left"'
---| '"right"'
---| '"top"'
---| '"bottom"'

---@alias ui_element_pid_or_options integer|ui_element_options*
---@alias ui_element_target ui_element_selector*|ui_element_element*|ui_element_point*
---@alias ui_element_value string|number|boolean

---@class ui_element_point*
---@field x integer 横坐标，单位为物理像素
---@field y integer 纵坐标，单位为物理像素

---@class ui_element_selector*
---@field title? string 元素的可读标题，和 text 含义相同
---@field text? string 元素的可读标题，和 title 含义相同
---@field text_contains? string 可读标题中包含的子串
---@field value? ui_element_value 元素当前值
---@field value_contains? string 元素值中包含的子串
---@field identifier? string 元素标识符
---@field bundle_id? string 元素所属 App 的 bundle identifier
---@field role? ui_element_role|string 元素类型
---@field traits? string|string[] 元素特征名称，例如 Button、StaticText、Toggle、Adjustable
---@field visible? boolean 元素是否可见
---@field hittable? boolean 元素当前是否可被命中
---@field checked? boolean 开关、勾选框、单选项等控件的确认状态
---@field selected? boolean 元素是否处于选中状态
---@field index? integer 多个匹配项中的序号，从 1 开始

---@class ui_element_element*
---@field text? string 元素的可读标题
---@field value? any 元素当前值
---@field identifier? string 元素标识符
---@field hint? string 系统辅助提示
---@field bundleId? string 元素所属 App 的 bundle identifier
---@field x? integer 元素区域左上横坐标，单位为物理像素
---@field y? integer 元素区域左上纵坐标，单位为物理像素
---@field width? integer 元素区域宽度，单位为物理像素
---@field height? integer 元素区域高度，单位为物理像素
---@field centerPoint? ui_element_point* 元素中心点，单位为物理像素
---@field children? ui_element_element*[] 子元素数组
---@field traits? integer 元素特征值
---@field traitsDescription? string[] 元素特征名称数组
---@field isVisible? boolean 元素是否可见
---@field isSelected? boolean 元素是否被选中
---@field isToggle? boolean 元素是否像开关控件
---@field isAdjustable? boolean 元素是否支持增减调节
---@field checked? boolean 开关、勾选框、单选项等控件的确认状态
---@field hasTextEntry? boolean 元素是否像文本输入目标
---@field isKeyboardKey? boolean 元素是否像键盘按键
---@field absoluteValue? number 滑块等可调节控件可能返回的归一化值
---@field canHit? boolean 当前是否能从顶层命中
---@field hitVerified? boolean 是否已经验证过命中状态
---@field hitTestPoint? ui_element_point* 命中点，单位为物理像素

---@class ui_element_options*
---@field pid? integer 目标 App 的进程标识符，不传时通常使用前台 App
---@field max_level? integer 子元素递归深度
---@field max_elements? integer 最多返回的顶层元素数量
---@field fallback_children? boolean 普通列表为空时尝试读取子元素
---@field include_hit_state? boolean 是否补充命中状态字段
---@field hit_test? boolean 是否启用屏幕采样命中
---@field fallback_hit_test? boolean 普通列表为空时是否尝试屏幕采样命中
---@field hit_test_spacing? number 屏幕采样间距，单位为逻辑坐标
---@field point? ui_element_point* 滚动或命中使用的坐标点，单位为物理像素
---@field x? integer 滚动或命中使用的横坐标，单位为物理像素
---@field y? integer 滚动或命中使用的纵坐标，单位为物理像素
---@field steps? number 滚动、增加或减少操作的步进参数

---@class ui_element_snapshot*
---@field elements ui_element_element*[] 当前 UI 元素列表
---@field count integer 元素数量
local ui_element_snapshot = {}

---@class ui_element*
---@field _VERSION string 模块版本
local ui_element = {}

--- 获取当前目标 App 的文本元素列表
--- 该模块在 20260507 以后版本方可使用
---@param pidOrOptions? ui_element_pid_or_options 目标 App 进程号或选项
---@return ui_element_element*[]? elements UI 元素数组
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.list_text_elements)
---
function ui_element.list_text_elements(pidOrOptions) end

--- 获取坐标处的 UI 元素
--- 坐标单位为物理像素；固定坐标点击请优先使用 touch.tap
--- 该函数在 20260507 以后版本方可使用
---@param coordX integer 横坐标
---@param coordY integer 纵坐标
---@param pidOrOptions? ui_element_pid_or_options 目标 App 进程号或选项
---@return ui_element_element*? element 坐标处命中的 UI 元素
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.text_element_at_position)
---
function ui_element.text_element_at_position(coordX, coordY, pidOrOptions) end

--- 查找一个 UI 元素
--- 如果选择器中包含 index，则返回匹配结果中的第 index 个元素
--- 该函数在 20260507 以后版本方可使用
---@param selector ui_element_selector* 选择器
---@param options? ui_element_options* 选项
---@return ui_element_element*? element 第一个匹配的 UI 元素
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.find)
---
function ui_element.find(selector, options) end

--- 查找多个 UI 元素
--- 没有匹配项时返回空数组
--- 该函数在 20260507 以后版本方可使用
---@param selector ui_element_selector* 选择器
---@param options? ui_element_options* 选项
---@return ui_element_element*[] elements 所有匹配元素组成的数组
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.find_all)
---
function ui_element.find_all(selector, options) end

--- 获取一次 UI 快照
--- 快照是一次性结果；界面变化后应重新调用 snapshot
--- 该函数在 20260507 以后版本方可使用
---@param options? ui_element_options* 选项
---@return ui_element_snapshot*? snapshot 当前 UI 快照
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.snapshot)
---
function ui_element.snapshot(options) end

--- 获取一次诊断 UI 快照
--- 返回原始元素树及数量等状态字段，不创建可复用的快照上下文
--- 该函数在 20260507 以后版本方可使用
---@param options? ui_element_options* 选项
---@return ui_element_snapshot*? snapshot 当前 UI 快照数据
---@return string? errMsg 错误信息
function ui_element.get_ui_snapshot_once(options) end

--- 点击 UI 元素
--- 该函数在 20260507 以后版本方可使用
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.click)
---
function ui_element.click(target, options) end

--- 滚动当前页面
--- 该函数在 20260507 以后版本方可使用
---@param direction ui_element_scroll_direction 滚动方向
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.scroll)
---
function ui_element.scroll(direction, options) end

--- 滚动 UI 元素或其所在的可滚动区域
--- 该函数在 20260507 以后版本方可使用
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param direction ui_element_scroll_direction 滚动方向
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.scroll)
---
function ui_element.scroll(target, direction, options) end

--- 追加输入文本
--- 该函数会先定位文本输入目标，再追加输入文本
--- 该函数在 20260507 以后版本方可使用
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param text string 要追加输入的内容
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.input_text)
---
function ui_element.input_text(target, text, options) end

--- 设置文本内容
--- 该函数在 20260507 以后版本方可使用
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param text string 要设置的内容
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.set_text)
---
function ui_element.set_text(target, text, options) end

--- 清空文本内容
--- 该函数在 20260507 以后版本方可使用
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.clear_text)
---
function ui_element.clear_text(target, options) end

--- 切换控件状态
--- 该函数在 20260507 以后版本方可使用
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.toggle)
---
function ui_element.toggle(target, options) end

--- 设置勾选状态
--- 目标已经是指定状态时会直接返回成功
--- 该函数在 20260507 以后版本方可使用
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param checked boolean 是否开启或选中
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.set_checked)
---
function ui_element.set_checked(target, checked, options) end

--- 设置控件值
--- 该函数在 20260507 以后版本方可使用
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param value ui_element_value 要设置的控件值
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.set_value)
---
function ui_element.set_value(target, value, options) end

--- 增加控件值
--- 用于滑块、滚轮等支持增减调节的控件
--- 该函数在 20260507 以后版本方可使用
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.increase)
---
function ui_element.increase(target, options) end

--- 减少控件值
--- 用于滑块、滚轮等支持增减调节的控件
--- 该函数在 20260507 以后版本方可使用
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.decrease)
---
function ui_element.decrease(target, options) end

--- 在快照中查找一个 UI 元素
---@param selector ui_element_selector* 选择器
---@return ui_element_element*? element 第一个匹配的 UI 元素
---@return string? errMsg 错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.snapshot)
---
function ui_element_snapshot:find(selector) end

--- 在快照中查找多个 UI 元素
---@param selector ui_element_selector* 选择器
---@return ui_element_element*[] elements 所有匹配元素组成的数组
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.snapshot)
---
function ui_element_snapshot:find_all(selector) end

--- 在快照上下文中点击 UI 元素
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.click)
---
function ui_element_snapshot:click(target, options) end

--- 在快照上下文中滚动当前页面
---@param direction ui_element_scroll_direction 滚动方向
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.scroll)
---
function ui_element_snapshot:scroll(direction, options) end

--- 在快照上下文中滚动 UI 元素或其所在的可滚动区域
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param direction ui_element_scroll_direction 滚动方向
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.scroll)
---
function ui_element_snapshot:scroll(target, direction, options) end

--- 在快照上下文中追加输入文本
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param text string 要追加输入的内容
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.input_text)
---
function ui_element_snapshot:input_text(target, text, options) end

--- 在快照上下文中设置文本内容
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param text string 要设置的内容
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.set_text)
---
function ui_element_snapshot:set_text(target, text, options) end

--- 在快照上下文中清空文本内容
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.clear_text)
---
function ui_element_snapshot:clear_text(target, options) end

--- 在快照上下文中切换控件状态
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.toggle)
---
function ui_element_snapshot:toggle(target, options) end

--- 在快照上下文中设置勾选状态
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param checked boolean 是否开启或选中
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.set_checked)
---
function ui_element_snapshot:set_checked(target, checked, options) end

--- 在快照上下文中设置控件值
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param value ui_element_value 要设置的控件值
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.set_value)
---
function ui_element_snapshot:set_value(target, value, options) end

--- 在快照上下文中增加控件值
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.increase)
---
function ui_element_snapshot:increase(target, options) end

--- 在快照上下文中减少控件值
---@param target ui_element_target 选择器、查询返回的元素或坐标表
---@param options? ui_element_options* 选项
---@return boolean? ok 成功时为 true，失败时为 nil
---@return table|string infoOrErr 动作信息或错误信息
---
---[查看文档](https://xxtouch.app/docs/handbook/ui_element/ui_element.decrease)
---
function ui_element_snapshot:decrease(target, options) end

--- 释放查询返回的元素或可复用快照所占用的资源
---@param target ui_element_element*|ui_element_snapshot* 要释放的对象
function ui_element.release(target) end

return ui_element
