如何用 Python 检测 Linux GUI 元素并实现光标吸附?
推荐先用 AT-SPI 验证控件覆盖范围
建议先用 AT-SPI 获取应用控件的语义信息和矩形范围,再为无法覆盖的标题栏按钮、dock 等目标增加桌面环境专用适配。
X11/EWMH 可以辅助获取窗口信息,但没有标准接口返回关闭、最小化和最大化按钮各自的位置。Wayland 下也可以使用无障碍接口,不过仍需分别验证控件树、全局坐标和系统光标控制。
| 目标 | 优先考虑的方式 | 主要限制 |
|---|---|---|
| 应用内按钮、搜索栏、文本框 | AT-SPI | 应用必须暴露相应的无障碍对象 |
| 应用自己绘制的标题栏按钮 | 先检查 AT-SPI | 取决于 toolkit 和应用实现 |
| window manager 绘制的标题栏按钮 | 检查其无障碍支持,再考虑专用适配 | EWMH 不提供按钮矩形 |
| taskbar/dock 图标 | 检查对应组件的 AT-SPI 树 | 取决于桌面组件或 extension 的实现 |
为什么 X11/EWMH 无法直接定位标题栏按钮?
EWMH 描述窗口层面的属性和请求,例如窗口状态、桌面归属及窗口边框范围。
其中,_NET_FRAME_EXTENTS 的内容为:
_NET_FRAME_EXTENTS, left, right, top, bottom, CARDINAL[4]/32
这四个值表示 window manager 在窗口四周添加的边框宽度,没有描述按钮的数量、排列、尺寸或点击区域。即使知道顶部边框的高度,也无法据此计算关闭按钮的准确位置。EWMH 窗口属性规范
python-xlib 和 ewmh 可以用于枚举 X11 窗口、读取几何信息和状态,但更换封装库不会增加协议本身没有提供的信息。也不能假设每个按钮都是独立的 X11 子窗口:控件可能只是 toolkit 或 window manager 绘制的一部分。
按窗口右上角的固定偏移量计算按钮位置,只适用于已限定桌面环境、主题和缩放配置的适配方案,不能作为通用 Linux GUI 检测方法。
AT-SPI 能否识别关闭、最小化和最大化按钮?
可以尝试。能否识别取决于谁绘制按钮,以及绘制方是否把按钮暴露为无障碍对象。
应用绘制的标题栏
使用 client-side decorations(CSD)时,标题栏控件属于应用界面,可以出现在应用的 AT-SPI 树中。例如,GTK 的 Gtk.WindowControls 用于显示最小化、最大化和关闭按钮,并参与 GTK 的无障碍体系。具体应用是否暴露这些按钮、能否返回有效矩形,仍需实际检查。Gtk.WindowControls 文档
window manager 绘制的标题栏
使用 server-side decorations(SSD)时,按钮由 window manager 或 compositor 绘制,通常不属于应用自己的无障碍子树。
这时应检查装饰绘制方是否另外暴露了无障碍对象。如果没有,遍历应用的 AT-SPI 树也找不到这些按钮,需要针对装饰实现进行适配。GNOME Shell extension 可以作为集成方式之一,但不能假定它天然提供所有标题栏按钮的矩形。
控件矩形与可点击性
AT-SPI 的 Component.get_extents() 可以返回控件的 (x, y, width, height),并允许指定坐标系。文档要求对象同时具有 VISIBLE 和 SHOWING 状态,返回值才有意义。Component.get_extents 文档
识别候选目标时,可以结合 role、状态以及 Action、EditableText 接口判断。不要只看名称是否包含 Close,因为名称可能被本地化,也可能为空。矩形本身也不能证明目标当前未被其他窗口遮挡。
Python 可以怎样读取这些信息?
可以通过 PyGObject 使用 gi.repository.Atspi。已有项目也可能使用 pyatspi,两者都用于访问 AT-SPI,无法自动补齐应用没有暴露的控件。
下面的一次性诊断示例会遍历部分无障碍树,输出具有动作或文本编辑接口的可见控件及其矩形。运行环境需要安装 PyGObject 和 Atspi introspection 数据,并能访问当前桌面会话的无障碍服务。
import gi
gi.require_version("Atspi", "2.0")
from gi.repository import Atspi, GLib
def candidate_rect(node):
states = node.get_state_set()
required = (
Atspi.StateType.VISIBLE,
Atspi.StateType.SHOWING,
Atspi.StateType.ENABLED,
)
if not all(states.contains(state) for state in required):
return None
component = node.get_component_iface()
if component is None:
return None
action = node.get_action_iface()
editable = node.get_editable_text_iface()
has_action = action is not None and action.get_n_actions() > 0
if not has_action and editable is None:
return None
rect = component.get_extents(Atspi.CoordType.SCREEN)
if rect.width <= 0 or rect.height <= 0:
return None
return rect.x, rect.y, rect.width, rect.height
desktop = Atspi.get_desktop(0)
stack = [(desktop, 0)] if desktop is not None else []
remaining = 2000 # Diagnostic traversal limit, not an API requirement.
while stack and remaining > 0:
node, depth = stack.pop()
remaining -= 1
try:
rect = candidate_rect(node)
if rect is not None:
print(node.get_role_name(), repr(node.get_name()), rect)
except GLib.Error:
pass # A remote object may disappear during inspection.
if depth >= 20:
continue
try:
for index in range(node.get_child_count()):
child = node.get_child_at_index(index)
if child is not None:
stack.append((child, depth + 1))
except GLib.Error:
continue
这里使用的入口和接口分别是 Atspi.get_desktop()、get_component_iface() 和 Action.get_n_actions()。
这个示例用于检查目标是否暴露,不能完整检测可点击目标。部分可交互控件不符合筛选条件,遍历上限也可能导致目标被遗漏。生产实现应针对当前相关窗口维护候选缓存,通过界面变化事件更新,避免在 MediaPipe 的每一帧中遍历整个桌面。
Wayland 下有哪些额外限制?
AT-SPI 使用独立的无障碍通信机制,在 Wayland 下也可能可用。即使拿到控件对象,也需要确认能否取得可用于桌面光标的全局坐标。
Wayland 的普通客户端不知道自身 surface 的全局位置,也不能直接访问其他客户端的 surface。因此,在某些 toolkit、compositor 和版本组合下,AT-SPI 可以提供窗口内相对位置,却无法提供可靠的屏幕绝对位置。必须在目标环境中验证 CoordType.SCREEN 的返回值,不能仅因调用成功就直接用于吸附。Wayland 协议模型
控制系统光标还需要单独的输入后端。可以评估桌面支持的 org.freedesktop.portal.RemoteDesktop,在用户授权的会话中发送指针事件;具备相应支持时,也可以通过 ConnectToEIS() 使用 libei。具体可用接口取决于 portal 后端及其版本。RemoteDesktop portal 文档
portal 提供输入控制能力,不提供 GUI 按钮列表。NotifyPointerMotionAbsolute() 使用指定屏幕流的逻辑坐标,不能直接假定它与截图像素、MediaPipe 映射坐标或 AT-SPI 坐标相同。
如果 Wayland 环境缺少可靠的全局位置映射,就需要 compositor 或桌面环境协助。对 GNOME 的适配与对其他桌面的适配应分别实现;在 XWayland 中读取 X11 信息也不能覆盖所有原生 Wayland 应用。
如何接入现有的手势光标逻辑?
建议按以下顺序实现:
- 先选定一个桌面会话和几种目标应用,分别检查应用内按钮、标题栏按钮、dock 图标是否出现在 AT-SPI 树中。
- 验证矩形与实际显示位置一致,再统一 MediaPipe、目标矩形和输入后端的坐标系。
- 优先对已验证的控件启用吸附。缺少目标数据时保留普通光标移动,再逐项补充桌面专用适配。
- 选择候选目标时,先计算手势映射位置到目标矩形的距离;进入阈值后,将显示光标吸附到矩形中心。
- 使用迟滞避免反复吸附和释放,并在目标消失、禁用或窗口布局变化后重新验证。
迟滞可以用两个阈值表达:
enter_radius < exit_radius
未锁定目标时,距离小于 enter_radius 才进入吸附;锁定后,距离大于 exit_radius 才释放。释放判断应使用手势映射得到的未吸附位置。如果使用已经固定在目标中心的系统光标位置,距离会一直很小,导致无法正常解除吸附。
还要检查多显示器偏移、负坐标及 fractional scaling。SHOWING 状态不能替代跨窗口遮挡检查,点击前应确认目标仍然有效。关闭按钮可以采用更保守的候选选择规则,避免在相邻按钮之间跳转。
对于当前项目,先用 X11 验证 AT-SPI 目标检测与吸附逻辑,通常更容易排查坐标问题;如果最终需要支持 Wayland,应尽早独立验证全局坐标和输入后端。窗口控制按钮的完整覆盖仍需要按实际桌面环境补充实现。
备注:内容仅供参考。
