basic qt widgets support

PLAN.md

@@ -550,11 +550,62 @@ cmake --build build
 ```
 `run.sh` sets `LD_LIBRARY_PATH` (GammaRay + qtmcp libs) and `QT_PLUGIN_PATH` (qtmcp `mcpserverbackend/libqmcpserverstdio.so`) and `QT_QPA_PLATFORM=offscreen`.
 
+## Qt Widget support (planned)
+
+GammaRay 的 widget inspector 与 quick inspector 共享同一套底层架构（`PropertyController`、`SelectionModelClient`、`RemoteModel`），大部分 QML 工具的模式可直接复用。
+
+### 可提供的 widget 工具
+
+**导航（与 QML 类似，模型名不同）**
+- `listWidgets()` — 遍历 `com.kdab.GammaRay.WidgetTree` 模型，返回 widget 层次树
+- `selectWidget(address)` — 通过 `SelectionModelClient` 选取 widget，触发 `PropertyController` 填充子模型（属性、attribute 等）
+- `listTopLevelWindows()`（已有 `listQuickWindows`，可在 widget 应用中继续使用）
+
+**属性/attribute（与 QML 共享读取实现）**
+- `getWidgetProperties(address)` — 读取同一套 `AggregatedPropertyModel`（通过 `PropertyController`），模型对象名 `com.kdab.GammaRay.Widget.<address>.properties`，与 `getItemProperties` 共享实现代码
+- `getWidgetAttributes(address)` — 读取 `widgetAttributeModel`（`AttributeModel<QWidget, Qt::WidgetAttribute>`），列出 Qt::WidgetAttribute 值
+
+**视觉/分析（新功能，需 RemoteViewInterface）**
+- `grabWidget(address)` — 通过 `WidgetRemoteView`（`com.kdab.GammaRay.WidgetRemoteView`）抓取 widget 截图，异步图像传输
+- `analyzePainting(address)` — 触发 `PaintAnalyzer` 捕获绘制操作
+- `exportWidgetAsSvg(address)` — 通过 `WidgetInspectorInterface` 导出 SVG
+- `exportWidgetAsUiFile(address)` — 导出 Qt Designer .ui 文件
+
+**控制**
+- `setInputRedirection(enabled)` — 允许将鼠标/键盘事件转发到目标 widget
+
+### 实现策略
+
+| 难度 | 工作项 | 说明 |
+|---|---|---|
+| 低 | `listWidgets()` / `selectWidget()` | 直接复用 `listQuickItems()` / `selectQuickItem()` 的代码模式，模型名改为 `com.kdab.GammaRay.WidgetTree` |
+| 低 | `getWidgetProperties()` | 与 `getItemProperties()` 完全一样，都读 `AggregatedPropertyModel`，可提取共享函数 |
+| 中 | `getWidgetAttributes()` | 需要读取 `widgetAttributeModel`（`PropertyController` 子模型），模式与 `getMaterialProperties()` 类似 |
+| 中 | `WidgetInspectorInterface` 代理 | IID `com.kdab.GammaRay.WidgetInspector`，用于 `export*`/`setInputRedirection` 等方法，类似 `QuickInspectorProxy` |
+| 高 | `grabWidget()` / `analyzePainting()` | 需要 `RemoteViewInterface` 的 `TransferImage` 异步路径，模式与 `MaterialExtensionInterface` 的 `gotShader` 信号类似 |
+
+### 与 QML 工具的关键区别
+
+- **选取机制不同**：QML 用 `QuickItemModel.selection`，Widget 用 `WidgetTree.selection` → 不同的 `PropertyController` 实例
+- **模型对象名不同**：property model 对象名为 `com.kdab.GammaRay.QuickItem.<address>.properties` vs `com.kdab.GammaRay.Widget.<address>.properties`
+- **Attribute 模型是 widget 独有的**：QML 项没有 `Qt::WidgetAttribute` 的概念
+- **Widget 没有 SceneGraph**：不需要 `getNodeVertices`/`getMaterialShaders` 等 SG 工具
+- **Widget 有截图和绘制分析**：QML 的 texture grab 类似但不同
+
 ## Next steps
 
-1. **Optimize test suite runtime** — share bridge across tests or reduce settle delays to bring ~8min down to ~2-3min.
-2. **Test `getShaderSource` async path end-to-end** — needs a QML app with real shaders (current test app uses software renderer where GeometryNodes have `nullptr` geometry).
-3. **Test geometry/material tools against a QML app with real QSGGeometry data** — current test app `relayout.qml` uses software renderer so `hasGeometry: false` and empty sub-models are correct behavior.
-4. **Implement `grabTexture(objectId)`** — `TextureExtension` async image grab via `RemoteViewInterface` `TransferImage`. Follows the `MaterialExtensionInterface` proxy pattern.
-5. **Fix `listScenegraphNodes` first-call fill stability** — single-call instead of caller needing a second call.
-6. **Build `--connect` startup flag integration** with systemd service for auto-attach during development.
+### QML SceneGraph 工具（当前阶段）
+
+1. **Test `getShaderSource` async path end-to-end** — needs a QML app with real shaders (current test app uses software renderer where GeometryNodes have `nullptr` geometry).
+2. **Test geometry/material tools against a QML app with real QSGGeometry data** — current test app `relayout.qml` uses software renderer so `hasGeometry: false` and empty sub-models are correct behavior.
+3. **Implement `grabTexture(objectId)`** — `TextureExtension` async image grab via `RemoteViewInterface` `TransferImage`. Follows the `MaterialExtensionInterface` proxy pattern.
+4. **Fix `listScenegraphNodes` first-call fill stability** — single-call instead of caller needing a second call.
+5. **Build `--connect` startup flag integration** with systemd service for auto-attach during development.
+
+### Qt Widget 支持（未来阶段）
+
+1. 创建 widget_tools.{h,cpp}，注册 `listWidgets` / `selectWidget` / `getWidgetProperties` / `getWidgetAttributes` MCP 工具
+2. 从 `scenegraph_tools.cpp` 提取共享的 `AggregatedPropertyModel` 读取函数，供 QML 和 widget 工具共用
+3. 创建 `WidgetInspectorInterface` 代理（类似 `QuickInspectorProxy`），处理 `export*`/`setInputRedirection`
+4. 实现 `RemoteViewInterface` 异步图像传输路径（grabWidget/analyzePainting）
+5. 添加 widget 测试应用（简单 QWidget 窗口 + 按钮/布局），编写 widget 工具的集成测试