
--------------------------------------------------------------------------------
-- text element module
--------------------------------------------------------------------------------

---@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 Abscissa, unit is physical pixel
---@field y integer Vertical coordinate, unit is physical pixel

---@class ui_element_selector*
---@field title? string The human-readable title of the element, has the same meaning as text
---@field text? string The human-readable title of the element, which has the same meaning as title
---@field text_contains? string The substring contained in the human-readable title
---@field value? ui_element_value element current value
---@field value_contains? string the substring contained in the element value
---@field identifier? string element identifier
---@field bundle_id? string The bundle identifier of the App to which the element belongs
---@field role? ui_element_role|string element type
---@field traits? string|string[] Element characteristic name, such as Button, StaticText, Toggle, Adjustable
---@field visible? boolean Is the element visible?
---@field hittable? boolean Whether the element is currently hitable
---@field checked? boolean Confirmation status of switches, check boxes, radio options and other controls
---@field selected? boolean Whether the element is selected
---@field index? integer Sequential number in multiple matches, starting from 1

---@class ui_element_element*
---@field text? string The human readable title of the element
---@field value? any element current value
---@field identifier? string element identifier
---@field hint? string System auxiliary prompts
---@field bundleId? string The bundle identifier of the App to which the element belongs
---@field x? integer The upper left abscissa of the element area, the unit is physical pixels
---@field y? integer The upper left ordinate of the element area, the unit is physical pixels
---@field width? integer Element area width in physical pixels
---@field height? integer Element area height, unit is physical pixels
---@field centerPoint? ui_element_point* Center point of element, unit is physical pixel
---@field children? ui_element_element*[] array of child elements
---@field traits? integer element eigenvalue
---@field traitsDescription? string[] Array of element characteristic names
---@field isVisible? boolean Is the element visible?
---@field isSelected? boolean Whether the element is selected
---@field isToggle? boolean Whether the element behaves like a switch control
---@field isAdjustable? boolean Whether the element supports increase or decrease adjustment
---@field checked? boolean Confirmation status of switches, check boxes, radio options and other controls
---@field hasTextEntry? boolean Whether the element behaves like a text input target
---@field isKeyboardKey? boolean Whether the element looks like a keyboard key
---@field absoluteValue? number Normalized values that adjustable controls such as sliders may return
---@field canHit? boolean Is it currently possible to hit from the top level?
---@field hitVerified? boolean Has the hit status been verified?
---@field hitTestPoint? ui_element_point* Hit point, in physical pixels

---@class ui_element_options*
---@field pid? integer The process identifier of the target App. If not passed, the foreground App is usually used.
---@field max_level? integer Child element recursion depth
---@field max_elements? integer Maximum number of top-level elements returned
---@field fallback_children? boolean Try to read child elements when normal list is empty
---@field include_hit_state? boolean Whether to add the hit status field
---@field hit_test? boolean Whether to enable screen sampling hits
---@field fallback_hit_test? boolean Whether to try screen sampling hits when the normal list is empty
---@field hit_test_spacing? number Screen sampling interval, unit is logical coordinate
---@field point? ui_element_point* The coordinate point used for scrolling or hitting, in physical pixels
---@field x? integer The abscissa used for scrolling or hitting, in physical pixels
---@field y? integer The vertical coordinate used for scrolling or hitting, in physical pixels
---@field steps? number Step parameters for scroll, increase or decrease operations

---@class ui_element_snapshot*
---@field elements ui_element_element*[] List of current UI elements
---@field count integer Number of elements
local ui_element_snapshot = {}

---@class ui_element*
---@field _VERSION string Module version
local ui_element = {}

--- Get the list of text elements of the current target App
--- This module can only be used in versions after 20260507
---@param pidOrOptions? ui_element_pid_or_options Target App process ID or options
---@return ui_element_element*[]? elements UI array of elements
---@return string? errMsg error message
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.list_text_elements)
---
function ui_element.list_text_elements(pidOrOptions) end

--- Get the UI element at the coordinates
--- The coordinate unit is physical pixels; for fixed coordinate clicks, please use touch.tap first.
--- This function can only be used in versions after 20260507
---@param coordX integer abscissa
---@param coordY integer vertical coordinate
---@param pidOrOptions? ui_element_pid_or_options Target App process ID or options
---@return ui_element_element*? element The UI element hit at the coordinate
---@return string? errMsg error message
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.text_element_at_position)
---
function ui_element.text_element_at_position(coordX, coordY, pidOrOptions) end

--- Find a UI element
--- If the selector contains index, returns the index-th element in the matching result.
--- This function can only be used in versions after 20260507
---@param selector ui_element_selector* selector
---@param options? ui_element_options* Options
---@return ui_element_element*? element The first matching UI element
---@return string? errMsg error message
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.find)
---
function ui_element.find(selector, options) end

--- Find multiple UI elements
--- Returns an empty array if there are no matches
--- This function can only be used in versions after 20260507
---@param selector ui_element_selector* selector
---@param options? ui_element_options* Options
---@return ui_element_element*[] elements array of all matching elements
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.find_all)
---
function ui_element.find_all(selector, options) end

--- Get a UI snapshot
--- Snapshot is a one-time result; snapshot should be called again after the interface changes.
--- This function can only be used in versions after 20260507
---@param options? ui_element_options* Options
---@return ui_element_snapshot*? snapshot Current UI snapshot
---@return string? errMsg error message
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.snapshot)
---
function ui_element.snapshot(options) end

--- Get a one-time diagnostic UI snapshot
--- Returns the raw element tree and status fields without creating a reusable snapshot context
--- This function can only be used in versions after 20260507
---@param options? ui_element_options* Options
---@return ui_element_snapshot*? snapshot Current UI snapshot data
---@return string? errMsg error message
function ui_element.get_ui_snapshot_once(options) end

--- Click on a UI element
--- This function can only be used in versions after 20260507
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.click)
---
function ui_element.click(target, options) end

--- Scroll current page
--- This function can only be used in versions after 20260507
---@param direction ui_element_scroll_direction scroll direction
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.scroll)
---
function ui_element.scroll(direction, options) end

--- Scroll a UI element or the scrollable area it's in
--- This function can only be used in versions after 20260507
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param direction ui_element_scroll_direction scroll direction
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.scroll)
---
function ui_element.scroll(target, direction, options) end

--- Append input text
--- This function will first locate the text input target and then append the input text
--- This function can only be used in versions after 20260507
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param text string Content to be added
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.input_text)
---
function ui_element.input_text(target, text, options) end

--- Set text content
--- This function can only be used in versions after 20260507
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param text string What to set
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.set_text)
---
function ui_element.set_text(target, text, options) end

--- Clear text content
--- This function can only be used in versions after 20260507
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.clear_text)
---
function ui_element.clear_text(target, options) end

--- Switch control state
--- This function can only be used in versions after 20260507
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.toggle)
---
function ui_element.toggle(target, options) end

--- Set check status
--- When the target is already in the specified state, success will be returned directly.
--- This function can only be used in versions after 20260507
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param checked boolean Whether to enable or select
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.set_checked)
---
function ui_element.set_checked(target, checked, options) end

--- Set control value
--- This function can only be used in versions after 20260507
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param value ui_element_value control value to set
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.set_value)
---
function ui_element.set_value(target, value, options) end

--- Increase control value
--- Used for controls such as sliders and scroll wheels that support increase or decrease adjustments
--- This function can only be used in versions after 20260507
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.increase)
---
function ui_element.increase(target, options) end

--- Decrease control value
--- Used for controls such as sliders and scroll wheels that support increase or decrease adjustments
--- This function can only be used in versions after 20260507
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.decrease)
---
function ui_element.decrease(target, options) end

--- Find a UI element in a snapshot
---@param selector ui_element_selector* selector
---@return ui_element_element*? element The first matching UI element
---@return string? errMsg error message
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.snapshot)
---
function ui_element_snapshot:find(selector) end

--- Find multiple UI elements in a snapshot
---@param selector ui_element_selector* selector
---@return ui_element_element*[] elements array of all matching elements
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.snapshot)
---
function ui_element_snapshot:find_all(selector) end

--- Click on a UI element in the snapshot context
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.click)
---
function ui_element_snapshot:click(target, options) end

--- Scroll the current page in snapshot context
---@param direction ui_element_scroll_direction scroll direction
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.scroll)
---
function ui_element_snapshot:scroll(direction, options) end

--- Scroll a UI element or the scrollable area it is in within the context of a snapshot
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param direction ui_element_scroll_direction scroll direction
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.scroll)
---
function ui_element_snapshot:scroll(target, direction, options) end

--- Append input text in snapshot context
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param text string Content to be added
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.input_text)
---
function ui_element_snapshot:input_text(target, text, options) end

--- Set text content in snapshot context
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param text string What to set
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.set_text)
---
function ui_element_snapshot:set_text(target, text, options) end

--- Clear text content in snapshot context
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.clear_text)
---
function ui_element_snapshot:clear_text(target, options) end

--- Switch control state in snapshot context
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.toggle)
---
function ui_element_snapshot:toggle(target, options) end

--- Set check status in snapshot context
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param checked boolean Whether to enable or select
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.set_checked)
---
function ui_element_snapshot:set_checked(target, checked, options) end

--- Set control value in snapshot context
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param value ui_element_value control value to set
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.set_value)
---
function ui_element_snapshot:set_value(target, value, options) end

--- Increase control value in snapshot context
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.increase)
---
function ui_element_snapshot:increase(target, options) end

--- Decrement control value in snapshot context
---@param target ui_element_target Selector, element returned by query, or coordinate table
---@param options? ui_element_options* Options
---@return boolean? ok true on success, nil on failure
---@return table|string infoOrErr Action information or error information
---
---[Documentation](https://xxtouch.app/en/docs/handbook/ui_element/ui_element.decrease)
---
function ui_element_snapshot:decrease(target, options) end

--- Release resources held by an element returned from a query or a reusable snapshot
---@param target ui_element_element*|ui_element_snapshot* Object to release
function ui_element.release(target) end

return ui_element
