uia

Windows UI Automation 的 xlang 与 C 接口：查找窗口和控件、读取属性、调用控件协议、订阅事件。

版本 0.1.0 · Windows 专用 · C / xlang

快速开始

import uia

auto window = uia.test_window()
auto edit = uia.from_hwnd(window.edit_hwnd())
assert edit.set_value("hello")
println(edit.text())
edit.release()
window.release()
uia.shutdown()

test_window() 只供自建窗口测试。真实桌面可从 desktop()、focused()、from_hwnd() 或 from_point() 进入。

接口

入口	用途
`by_name / by_automation_id / by_class_name`	构造元素查询条件。
`Element.find_first / find_all / children`	查找目标与枚举元素。
`Element.find_class_path`	按生成定位器的 Control View 类名、控件类型和兄弟序号精确查找；C 入口为 `x_uia_element_find_class_path`。
`Element.value / text / set_value / invoke / toggle`	使用目标控件支持的 UIA 协议；不支持的协议会报告失败。
`Element.close_window / wait_window_closed`	关闭窗口并等待；等待超时返回 `false`，不设置错误。无效元素及 UIA 查询失败仍报错。
`Element.snapshot_json / locator_json`	获取元素快照与可复用定位信息。
`events().poll_json(timeout_ms)`	轮询焦点或属性事件；无事件返回 `{}`。等待期间处理当前线程窗口消息；收到 `WM_QUIT` 时保留退出码并交还给宿主。消息回调重入释放队列时，轮询安全返回 `{}`。
`Events.poll_callback(handler, timeout_ms)`	从事件队列取出 JSON，调用 XLang 函数并返回其结果。

对象自动析构，也可调用 release() 提前释放。C 使用 extlibs/uia/include/uia.h；C 调用方须释放拥有型句柄及元素数组内的每个原生句柄，返回文本仅短暂借用。BSTR 文本转换按需扩容；内嵌 NUL、无效 UTF-16 与分配失败明确报错，缓冲在 shutdown() 时释放。快照与事件 JSON 完整输出上限为 16 MiB，超限返回错误，不返回截断结果。

验证与边界

xl run examples/extlibs/uia_quick.xl
xl run examples/extlibs/uia_quick_c.c extlibs/uia/x_uia_artifact.c --link user32 --link ole32 --link oleaut32
powershell -NoProfile -ExecutionPolicy Bypass -File extlibs/uia/test/check.ps1 -StrictC

2026-10-28：十条原生拥有型文本出口在十二条公开路径中直接移交结果，完整受控代码生成夹具的两处正文复制归零；空事件回调不再为比较 {} 创建临时字符串。借用诊断、BSTR 转码、JSON 构造、长度扫描与错误作用域仍有成本，不代表整个桥接零开销。文本协议回退不再吞掉内存失败，两个内存 HRESULT、BSTR 与七处句柄分配保留内存错误；普通协议缺失仍可回退。Windows 完整 -StrictC 门禁通过 C 13 组与 XLang 15 组固定预算、故障恢复、释放平衡、新用例 JIT/AOT，依赖包 ui.auto 的受控窗口边界也通过。预算只计 XRT 逻辑分配：所测 Edit 的 text 为两次，其余属性和空轮询为一次，不外推任意控件。默认范例不读取真实桌面子树、任意坐标窗口内容或全局焦点定位器；全局焦点入口仅代码生成检查和手动选项，不计自动端到端验收。

2026-10-27 Windows -StrictC 门禁通过：受控窗口的 C/XLang 关闭与等待对照覆盖无效元素、正常超时、关闭后成功和旧错误清除，JIT/AOT 输出一致。既有门禁还覆盖自建窗口的 C/JIT、五类有效句柄隐式释放 JIT/AOT、显式释放、原生组合条件、文本入口内嵌 NUL 拒绝、跨线程拒绝、事件短轮次压力与双语同输出。具名 XLang 函数通过 poll_callback 接收真实焦点事件，事件 JSON 与返回值在 JIT/AOT 两条路径均已核对；空队列不调用回调，回调抛错后事件句柄仍可释放。这是主动轮询后的函数调用，不是事件线程直接调用 XLang。构造 9,001 字符 BSTR 的转换层、9,000 字符快照属性和超过旧 64 KiB 的 JSON 均通过 C 回归；自建 Windows 控件的 UIA 属性只返回 4,096 字节，不能作为第三方控件超长属性端到端验收。定位器仍采用定长字段和最多 16 层的类路径；超长字段、超限路径、文本或数值属性读取失败及关键遍历失败均返回错误。默认门禁中核心、完整公开范例和配对范例 AOT 全部构建运行并核对输出；旧构建的共享符号阻断不再复现。UIA 上下文限定在创建线程使用；真实应用的权限、DPI、远程会话及 Windows 版本矩阵仍需验证。