go-xcgui-dev — Go xcgui （炫彩界面库）开发助手

核心准则

🔴 铁律 — 违反以下任意一条都可能导致错误回答：

1. 零预训练回答：关于 xcgui 的 API 签名、参数说明、常量值、函数用法等信息，严禁依赖模型预训练知识回答。每一次回答都必须基于对本地 source/ 目录下源文件的实时检索。
2. 源码即真理：source/xcgui/ 下的 .go 文件是唯一的 API 真相来源，source/xcgui-example/ 是唯一的用法示例来源。
3. 必须优先使用 scripts/search.py 进行源码检索。如果 scripts/search.py 搜索不到内容，你可以尝试更换搜索关键词, 或者更换检索工具自行搜索。
4. 先查后答：收到任何 xcgui 相关问题时，第一步永远是检索源码，第二步才组织回答。
5. 双重 API 层：xcgui 有两层 API —— widget/window 包提供面向对象的 Go 风格封装，xc 包提供底层 C 函数绑定。两层都可以使用，示例中常同时展示两种写法。回答时应根据用户场景推荐合适层级。
6. xcgui 仅支持 Windows 平台, 是纯 Go 封装的, 不依赖 cgo, 无需 C 编译器。
7. 禁止修改 source/ 目录下的文件内容, 这些内容是受保护的只读资源, 你生成的文件禁止创建到 source/ 目录下。
8. 禁止将你生成的文件创建到本技能目录下。

🚫 反例与禁止事项

以下操作绝对禁止，违反将导致程序崩溃、内存泄漏或功能异常：

源码初始化与更新(这是给AI看的)

本技能不包含 source/ 目录，首次使用或需要更新源码时，请执行以下操作。

自动下载源码

在技能根目录执行以下命令，自动下载 xcgui 和 xcgui-example 源码到 source/ 目录：

python scripts/download.py

如果下载失败py脚本输出结果会给出下载链接的。

下载失败？手动下载

如果自动下载失败，提醒用户手动下载以下两个仓库的 ZIP 并解压到 source/ 目录(下载地址会在py脚本输出结果中提供的)：

1. xcgui 源码：

- 解压后重命名文件夹为 xcgui

1. xcgui-example 示例：

- 解压后重命名文件夹为 xcgui-example

最终 source/ 目录结构应如下：

source/
├── xcgui/           # 主库源码
└── xcgui-example/   # 示例代码

更新源码

当 xcgui 库有更新时，你可以发出"更新 xcgui 源码"或"重新下载源码"指令，我会重新执行 python scripts/download.py 下载最新源码。

信息检索工作流

收到任何 xcgui 问题时，必须使用 scripts/search.py 搜索工具按以下步骤主动检索源码：

Step 0：检查前置条件

🔴 CHECKPOINT: 收到 xcgui 问题时，必须先确认 source/ 目录存在（如不存在则执行 python scripts/download.py），然后至少执行一次 search.py 检索。不可跳过此步骤直接凭记忆回答。

Step 1：确定搜索类型

根据问题类型，选择对应的搜索命令：

关键词规则：用 / 分割多个关键词，不区分大小写；含中文时触发注释搜索。list funcs / list events 默认不含 Event 前缀函数（edge 包除外），末尾加 all 参数可全部列出。

Step 2：阅读确认

搜索到候选后，用 read 工具打开目标文件（路径与行号已在搜索结果中给出），确认：

• 完整函数签名（多行参数、返回值类型）
• 中文注释（// 函数_描述 和参数说明）
• 事件回调的完整签名

Step 3：回答

🔴 CHECKPOINT: 检索完毕。确认所有 API 引用均来自 source/ 下的源码文件，附带了文件路径和行号，未使用模型预训练知识。

基于源码内容组织回答，附上相对文件路径和行号。

附上是基于什么版本的 xcgui 源码来回答的, 本地的 xcgui 源码版本号可在 source/xcgui/README.md 中找到, 可使用 release-(\d+\.\d+\.\d+) 正则表达式提取出该版本号, 会得到 1.4.0 这样的版本号。

故障处理与降级策略

当遇到以下场景时，按指定路径处理，不可静默失败。每个场景提供三段式方案：触发条件 → 一线修复 → 兜底方案。

1. 源码下载失败

2. 源码搜索失败

3. 版本号提取失败

4. WebView2 运行时缺失

常见问题

核心反例（崩溃/泄漏/刷新等）请参见上方 [🚫 反例与禁止事项](#-反例与禁止事项)。

• Go 模块路径是 github.com/twgh/xcgui，最小 Go 版本 1.18
• 在动态添加布局元素后可调用 w.AdjustLayout().Redraw(false) 以刷新布局
• 当程序使用 app.New() 参数为 true 时, 此时为 Direct2D 渲染模式, 为 false 时为 GDI+ 渲染模式
• 生成颜色除了使用 xc.RGBA(r, g, b, a byte) uint32 外, 还可以使用 xc.HexRGB2RGBA(str string, a byte) uint32 将常见的 Web/CSS 十六进制颜色转换到炫彩界面库使用的颜色
• 默认窗口是有上下左右的边框的, 在你用绝对坐标创建元素/绘制等操作前得先用 GetBorderSize 获取到边框大小, 上边就是标题栏的高度, 得知边框大小后可以避免将元素创建到边框或标题上, 你也可以用 SetBorderSize 设置边框大小

需要创建数据适配器的元素

List, ListView, ListBox, Tree, CombBox, 不创建数据适配器就会报错, 无法存储数据, 怎么创建可读取 references/Elements that require creating a data adapter.md

源码目录地图

所有源码位于 source/ 下，分两大目录：

source/
├── xcgui/                    # 主库源码
│   ├── xc/                   # 底层 C API 绑定 — 所有 X* 函数
│   │   └── dll/              # DLL 加载逻辑
│   ├── xcc/                  # 常量定义
│   │   ├── xcconst.go        # 核心常量
│   │   ├── combinedstate.go  # 组合状态常量
│   │   ├── elementevent.go   # 元素事件常量
│   │   ├── windowevent.go    # 窗口事件常量
│   │   └── xml.go            # XML 相关常量
│   ├── widget/               # 控件封装 — Button, Edit, List, Table, Tree, ...
│   ├── window/               # 窗口封装
│   │   ├── window.go         # 基础窗口
│   │   ├── framewindow.go    # 框架窗口
│   │   ├── modalwindow.go    # 模态窗口
│   │   ├── floatwindow.go    # 浮动窗口
│   │   ├── windowbase.go     # 窗口基类
│   │   └── trayicon.go       # 托盘图标
│   ├── ani/                  # 动画高级封装
│   ├── ease/                 # 缓动函数
│   ├── svg/                  # SVG 处理
│   ├── drawx/                # 绘制扩展
│   ├── font/                 # 字体管理
│   ├── imagex/               # 图片处理
│   ├── res/                  # 资源管理
│   ├── tf/                   # 便捷创建窗口方便测试
│   ├── edge/                 # WebView2 封装 — ICoreWebView2* 接口
│   │   └── webviewloader/    # WebView2 运行时加载
│   ├── app/                  # 应用生命周期,炫彩全局API
│   ├── common/               # 公共工具
│   ├── adapter/              # 数据适配器
│   ├── bkmanager/            # 背景管理器
│   ├── bkobj/                # 背景对象
│   ├── objectbase/           # 对象基类
│   ├── wapi/                 # Windows API 封装
│   │   ├── wnd/              # 基于wapi封装窗口操作
│   │   └── wutil/            # 基于wapi封装工具函数
│   ├── tmpl/                 # 项模板
│   └── README.md             # xcgui 介绍
│
└── xcgui-example/            # 示例代码
    ├── Basic/                # 基础示例
    │   ├── SimpleWindow/     # 简单窗口 (入门必看)
    │   ├── ButtonImage/      # 图片按钮
    │   ├── ButtonSvg/        # SVG 按钮
    │   ├── FrameWindow/      # 框架窗口
    │   ├── ModalWindow/      # 模态窗口
    │   ├── List/List2/       # 列表控件
    │   ├── ListView/         # 列表视图
    │   ├── TabBar/           # 标签栏/Tab条
    │   ├── ToolBar/          # 工具栏
    │   ├── ComboBox/         # 下拉框
    │   ├── Edit/             # 编辑框
    │   ├── Tree/             # 树形控件
    │   ├── Menu/		      # 菜单
    │   ├── MenuBar/	      # 菜单条
    │   ├── ProgressBar/      # 进度条
    │   ├── SliderBar/        # 滑动条
    │   ├── DateTime/         # 日期时间
    │   ├── MonthCal/         # 月历
    │   ├── ScrollBar/        # 滚动条
    │   ├── Gif/              # GIF 动画
    │   ├── Timer/            # 定时器
    │   ├── ShapePicture/     # 形状图片
    │   ├── ShapeText/        # 形状文本
    │   ├── CheckButton/      # 复选框按钮
    │   ├── RadioButton/      # 单选按钮
    │   ├── ListBox/          # 列表框
    │   ├── ChooseColor/      # 颜色选择
    │   ├── OpenFile/         # 调用 wapi 打开/保存文件, 浏览文件夹
    │   ├── DropFiles/        # 拖放文件
    │   ├── ElementEvent/     # 元素事件
    │   ├── EventInterception/# 事件拦截
    │   ├── MultiWindow/      # 多窗口
    │   ├── SetDefaultFont/   # 设置默认字体
    │   ├── AutoDpi/          # 自适应 DPI
    │   ├── MemoryLoadImage/  # 内存加载图片
    │   ├── LoadLayoutFromString/ # 从字符串加载布局
    │   ├── MultithreadOperationUI/  # 多线程操作 UI
    │   ├── MultithreadOperationUI2/ # 多线程操作 UI(2)
    │   ├── ThreadOperationUI/    # 在非UI线程操作UI
    │   ├── WindowBkColor/    # 窗口背景色
    │   └── uidesigner/       # UI 设计器示例
    │
    ├── Advanced/             # 高级示例
    │   ├── Animation/        # 动画特效大全
    │   ├── TabControl/       # 选项卡切换控制
    │   ├── SideNavigation/   # 侧边导航
    │   ├── SvgDraw/          # SVG 绘制
    │   ├── AudioPlayer/      # 音频播放器
    │   ├── Editor/           # 编辑器
    │   ├── TrayIcon/         # 系统托盘
    │   ├── TrayIcon2/        # 系统托盘(2)
    │   ├── VirtualTable1/    # 虚表
    │   ├── VirtualTable2/    # 虚表排序
    │   ├── Attach/           # 附加窗口
    │   ├── DebugInfo/        # 调试信息
    │   ├── DrawMenu/         # 自绘菜单
    │   ├── DrawRoundButton/  # 自绘圆角按钮
    │   ├── Ease_All/         # 缓动函数大全
    │   ├── Ease_Easy/        # 简易缓动
    │   ├── GoImage/          # Go 图片到炫彩图片
    │   ├── HideTaskbarIcon/  # 隐藏任务栏图标
    │   ├── HideTaskbarIcon2/ # 隐藏任务栏图标(2)
    │   ├── HookKeyboard/     # 键盘钩子
    │   ├── HookMouse/        # 鼠标钩子
    │   ├── MouseCursor/      # 鼠标光标
    │   ├── RegisterHotKey/   # 注册热键
    │   ├── SendEvent/        # 发送事件
    │   ├── BeautifyEdit/     # 美化编辑框
    │   └── SetWindowIcon/    # 设置窗口图标
    │
    ├── webview/              # WebView2 示例
    │   ├── SimpleWebView/    # 简单 WebView
    │   ├── Chart/            # 图表
    │   ├── VueAndVite/       # Vue+Vite 集成
    │   ├── CalcMD5/          # JS-Go 互调
    │   ├── EmbedAssets/      # 嵌入资源
    │   ├── SharedBuffer/     # 共享缓冲区
    │   ├── CustomSchemeRegistration/ # 自定义协议
    │   ├── CreateByLayoutEle/ #  WebView2 综合示例(事件用法最全)
    │   ├── CreateByWindow/   # 创建WebView在窗口,仍然使用炫彩窗口标题栏
    │   ├── EnvironmentOptions/ # WebView环境选项
    │   ├── SaveMemory/       # 内存优化
    │   ├── RoundedShadowWindow/ # 圆角阴影窗口
    │   ├── AutomaticInstallWebView2Runtime/ # 自动安装 WebView2 运行时
    │   └── WebResourceRequestedEvent/ # 资源请求事件
    │
    └── HUMUI/                # 现代化 UI 示例 (2 个)
        ├── HouTai017/        # 后台管理
        └── YanZheng018/      # 登录/注册窗口

最简单标准代码

package main

import (
    "github.com/twgh/xcgui/app"
    "github.com/twgh/xcgui/window"
    "github.com/twgh/xcgui/widget"
    "github.com/twgh/xcgui/xcc"
)

func main() {
    app.InitOrExit()                          // 1. 初始化
    a := app.New(true)                         // 2. 创建 App 实例
    a.EnableAutoDPI(true).EnableDPI(true)      // 3. 启用 DPI

    w := window.New(0, 0, 600, 400, "标题", 0, xcc.Window_Style_Default) // 4. 创建窗口

    // 5. 创建控件并绑定事件
    btn := widget.NewButton(10, 10, 100, 30, "按钮", w.Handle)
    btn.AddEvent_BnClick(func(hEle int, pbHandled *bool) int {
        w.MessageBox("提示", "你点击了按钮", xcc.MessageBox_Flag_Ok, xcc.Window_Style_Modal)
        return 0
    })

    w.Show(true)                               // 6. 显示窗口
    a.Run()                                    // 7. 消息循环
    a.Exit()                                   // 8. 退出
}

常用包参考

如果找不到对应示例，可用 python scripts/search.py example <关键词> 搜索。

xcgui 源码的编码规范速查

这个指的是 xcgui 源码自身的编码规范, 不代表你写代码要遵循这个规范, 可读取 references/XCGUI Programming Standards.md 文件