AtomUI/docs/modules/native/linux.md

AtomUI.Native Linux 平台 API

范围

AtomUI 在 Linux 上有两条完全不同的窗口后端路径：

后端	Avalonia 包	原生对象	AtomUI 可使用的能力
X11 / XWayland	Avalonia.X11	IPlatformHandle，descriptor 为 XID	Xlib 初始几何、_GTK_FRAME_EXTENTS、XCB SHAPE input region
原生 Wayland	Avalonia.Wayland	IWindowImpl.Handle == null	xdg-shell move/resize、CSD/SSD、surface geometry；无公开 input-region API

不得只用 OperatingSystem.IsLinux() 决定调用 X11 API。所有 Xlib/XCB 路径还必须验证窗口后端为 X11；原生 Wayland、Linux framebuffer 和 headless 后端都不是 X11。

本文以 /workspace/projects/ReferenceProjects/Avalonia 的 12.1.0 tag （commit a21b9f573172f705a944dcc8aad7f036b9986f39）为 Avalonia 行为事实源。

X11 能力

初始窗口几何

WindowExtensions.ConfigureLinuxInitialWindowGeometry() 将 Avalonia DIP 尺寸转成 device pixel， 再调用 WindowUtilsLinux.ConfigureInitialWindowGeometry()：

1. XOpenDisplay() 打开独立 Xlib 连接。
2. XSetWMNormalHints() 写入 position、size、min/max size 和 resize increment。
3. XMoveResizeWindow() 在 map 前设置窗口位置和大小。
4. XFlush() 后关闭该次 Xlib 连接。

该逻辑依赖 XID 和全局屏幕坐标，只能由 X11WindowChromeManager 调用。Wayland surface 没有全局位置， Avalonia.Wayland.WindowImpl.Move(PixelPoint) 明确是 no-op。

CSD frame extents

WindowExtensions.SetLinuxX11CsdFrameExtents() 先验证 platform handle descriptor 为 XID，然后由 WindowUtilsLinux.SetX11CsdFrameExtents() 写入 _GTK_FRAME_EXTENTS。

属性格式为四个 32-bit CARDINAL，顺序是 left, right, top, bottom，单位为 device pixel。AtomUI 在 normal 状态写入阴影 extents；最大化和全屏写入全零，避免 Mutter/KWin 继续按旧阴影范围做放置和吸附。

SHAPE input region

ClickThroughShadowExtensions 用 XCB SHAPE 的 XCB_SHAPE_SK_INPUT 把输入区限制为一个矩形，目的 是让视觉阴影区域的点击穿透到下方窗口，同时保留窄 resize band。

当前实现的真实生命周期：

1. XcbConnectionHolder 懒创建一条进程级独立 XCB 连接。
2. 首次初始化时查询并缓存 SHAPE 扩展是否可用。
3. 所有请求在 XcbConnectionHolder.SyncRoot 下串行执行。
4. xcb_shape_rectangles_checked() 替换 input region，随后检查请求并 flush。
5. 该连接在进程生命周期内复用；不是每次调用都 connect/disconnect。

ClickThroughShadowExtensions 监听 Bounds、WindowDecorationMargin、WindowState、 TransparencyLevelHint 以及调用方给出的额外属性。坐标先按 RenderScaling 从 DIP 转成 device pixel。 最大化或全屏时 input region 恢复为整个 surface。

这不是“整窗忽略鼠标”的 API。Linux 版本的 SetWindowIgnoreMouseEventsLinux()、 IsWindowIgnoreMouseEventsLinux()、xcb_get_geometry() 和 shape-query 旧实现已经删除；文档和新代码都 不得继续引用这些成员。

Wayland 能力与线程模型

Avalonia 12.1 的 Wayland 后端使用专用 AvaloniaWayland worker 线程：

UI thread WindowImpl
  -> WXdgTopLevelProxy
  -> WaylandWorkerClient.Marshaller
  -> PostWithCommit / PostOob
  -> worker-thread WSurface / WlSurface

源码中的关键约束：

• WaylandWorkerClient.CreateTopLevelHandle() 只向 UI 线程暴露 WXdgTopLevelProxy，注释明确说明真实 WXdgTopLevel 是 worker-thread state。
• 普通 surface 状态由 PostWithCommit 排队，与 compositor commit 保持顺序；move/resize 等需要输入 serial 的请求使用 OOB 路径。
• WSurface.OnBeforeNewBufferAttached() 在 attach/commit 前统一应用 frame callback、ack configure、 window geometry、viewport 和 buffer scale。
• WindowImpl.SetShadowExtents() 通过 proxy 更新 persistent surface；WSurface 再根据 shadow extents 调用 xdg_surface.set_window_geometry。

Wayland 核心协议虽然有 wl_surface.set_input_region，Avalonia 12.1 还没有公开对应 API。AtomUI 当前 WaylandWindowReflectionExtensions 从私有 proxy 中取出真实 target，并由 WaylandWindowUtils 直接调用 NWayland。这绕过了 worker marshalling 和重连模型，只能作为当前技术债记录，不能视为线程安全或受 Avalonia 支持的 Native 扩展点。后续正确实现应进入 Avalonia persistent surface/proxy，并通过 PostWithCommit 下发。

Wayland CSD/SSD

Wayland 的 NeedsManagedDecorations 来自 xdg-decoration 协商：

• Client-side mode：请求 TitleBar | Border | Shadow | ResizeGrips。
• Server-side mode：NeedsManagedDecorations=false，由 compositor 提供 SSD。
• 协商结果变化时触发 DrawnDecorationsRequestChanged。

WindowDecorations 在 Wayland 上不是可逆的 CSD/SSD toggle。Avalonia 12.1 的 SetWindowDecorations(None/TitleBar) 会设置 _csdSticky=true 并销毁 decoration object，之后设置 Full 也不会恢复 SSD。因此，AtomUI 不能在 IsCsdEnabled=False 时无条件设置 WindowDecorations=None；这会把刚协商出的 SSD 立即永久切回 CSD。

依赖和边界

AtomUI.Native 当前直接引用 NWayland 0.11.0，而 Avalonia.Wayland 12.1.0 也依赖同一版本。 NWayland 因而会进入所有引用 AtomUI.Native 的依赖图，包括 Browser 的共享项目闭包。Browser 项目 目前通过内部 WASM item 过滤桌面 assembly，这能消除已知 P/Invoke collector warning，但不能消除 restore 图中的桌面依赖，也不是理想的模块边界。

长期结构应把 X11、Wayland、Win32、macOS 后端能力放到可选平台 assembly，避免 AtomUI.Desktop.Controls/Browser 为单个平台实现携带所有桌面后端和协议依赖。平台 manager 负责 Avalonia 控件生命周期和状态机；AtomUI.Native 只负责已经确定后端之后的原生调用，不负责主题、 reflection discovery 或窗口策略。

关键源码

AtomUI

• src/AtomUI.Native/Linux/WindowUtils.Interop.cs
• src/AtomUI.Native/Linux/WindowUtils.Linux.cs
• src/AtomUI.Native/Linux/XcbConnectionHolder.cs
• src/AtomUI.Native/Linux/ClickThroughShadowExtensions.cs
• src/AtomUI.Native/Linux/WaylandWindowUtils.cs
• src/AtomUI.Native/WindowExtensions.cs
• src/AtomUI.Desktop.Controls/Window/X11WindowChromeManager.cs
• src/AtomUI.Desktop.Controls/Window/WaylandWindowChromeManager.cs
• src/AtomUI.Desktop.Controls/Window/WaylandWindowReflectionExtensions.cs

Avalonia 12.1.0

• src/Avalonia.Wayland/WindowImpl.cs
• src/Avalonia.Wayland/WindowImpl.Sink.cs
• src/Avalonia.Wayland/Server/WaylandWorkerClient.cs
• src/Avalonia.Wayland/Server/Persistent/IWXdgTopLevel.cs
• src/Avalonia.Wayland/Server/Persistent/WSurface.cs
• src/Avalonia.Controls/TopLevelHost.Decorations.cs
• src/Avalonia.X11/X11Window.cs