🔴 铁律 — 违反以下任意一条都可能导致错误回答：
source/ 目录下源文件的实时检索。
source/xcgui/ 下的 .go 文件是唯一的 API 真相来源，source/xcgui-example/ 是唯一的用法示例来源。
scripts/search.py 进行源码检索。如果 scripts/search.py 搜索不到内容，你可以尝试更换搜索关键词, 或者更换检索工具自行搜索。
widget/window 包提供面向对象的 Go 风格封装，xc 包提供底层 C 函数绑定。两层都可以使用，示例中常同时展示两种写法。回答时应根据用户场景推荐合适层级。
source/ 目录下的文件内容, 这些内容是受保护的只读资源, 你生成的文件禁止创建到 source/ 目录下。
以下操作绝对禁止，违反将导致程序崩溃、内存泄漏或功能异常：
| # | 禁止行为 | 后果 | 正确做法 |
|---|---------|------|---------|
| 1 | 在非 UI 线程操作 UI 元素 | 程序崩溃 | 用 xc.UI() 或 xc.Auto() 包裹 UI 操作 |
| 2 | 忘记调用 Redraw 就认为界面已更新 | 界面不刷新 | 修改元素后必须手动调用 Redraw(false)；列表修改数据后需先 RefreshRow 或 RefreshData 再 Redraw |
| 3 | 不创建数据适配器就直接使用 List/Tree/ListBox/ComboBox | 运行时错误 | 先调用 CreateAdapter()（参考 references/Elements that require creating a data adapter.md） |
| 4 | IStream 对象用完后不释放 | 内存泄漏 | 不再使用时调用 Release()，无论传参还是返回值 |
| 5 | WebView COM 对象用完后不释放 | 内存泄漏（COM 对象不被 Go GC 回收） | 手动调用 Release()；例外：WebView2_2~WebView2_28 等内部变量由 Close() 自动释放 |
| 6 | 将炫彩句柄当作 Windows 真实句柄 | 功能异常 | 用 GetHWND() 获取真实窗口句柄（uintptr 类型） |
| 7 | 凭模型记忆回答 API 细节，跳过源码检索 | 回答错误 | 必须用 search.py 检索 + read 确认后再回答 |
| 8 | 将生成的文件放到 source/ 或本技能目录下 | 污染源码 | 创建到用户的工作目录中 |
本技能不包含 source/ 目录，首次使用或需要更新源码时，请执行以下操作。
在技能根目录执行以下命令，自动下载 xcgui 和 xcgui-example 源码到 source/ 目录：
python scripts/download.py
如果下载失败py脚本输出结果会给出下载链接的。
如果自动下载失败，提醒用户手动下载以下两个仓库的 ZIP 并解压到 source/ 目录(下载地址会在py脚本输出结果中提供的)：
xcgui
xcgui-example
最终 source/ 目录结构应如下：
source/
├── xcgui/ # 主库源码
└── xcgui-example/ # 示例代码
当 xcgui 库有更新时，你可以发出"更新 xcgui 源码"或"重新下载源码"指令，我会重新执行 python scripts/download.py 下载最新源码。
收到任何 xcgui 问题时，必须使用 scripts/search.py 搜索工具按以下步骤主动检索源码：
🔴 CHECKPOINT: 收到 xcgui 问题时，必须先确认 source/ 目录存在（如不存在则执行 python scripts/download.py），然后至少执行一次 search.py 检索。不可跳过此步骤直接凭记忆回答。
根据问题类型，选择对应的搜索命令：
| 问题类型 | 使用命令 | 说明 |
|---------|---------|------|
| 查函数定义和注释 | python scripts/search.py func <关键词> | 会显示完整函数定义和注释 |
| 查常量定义和注释 | python scripts/search.py const <关键词> | 会显示完整常量定义和注释 |
| 查事件定义和注释 | python scripts/search.py event <关键词> | 会显示完整函数定义和注释 |
| 找示例参考 | python scripts/search.py example <关键词> | 搜 xcgui-example/ 全部示例 |
| 根据示例名或包注释精准找示例 | python scripts/search.py example_name | 会更精准 |
| 不知道有什么元素对象 | python scripts/search.py list widgets | 列出所有可用元素对象和描述 |
| 不知道有什么窗口对象 | python scripts/search.py list windows | 列出所有窗口对象和描述 |
| 查看对象的所有事件 | python scripts/search.py list events <对象名> | 含继承链上的所有事件函数名 (含描述) |
| 查看对象的所有方法 | python scripts/search.py list funcs <对象名> | 含继承链上的所有方法名(含事件) |
| 了解项目结构 | python scripts/search.py list packages | 列出所有包和文件数 (含描述) |
| 查看所有示例 | python scripts/search.py list examples | 列出所有示例 (含描述) |
| 不知道包里有什么对象 | python scripts/search.py list objects <包名> | 列出包内所有公开对象 (含描述) |
> 关键词规则：用 / 分割多个关键词，不区分大小写；含中文时触发注释搜索。list funcs / list events 默认不含 Event 前缀函数（edge 包除外），末尾加 all 参数可全部列出。
搜索到候选后，用 read 工具打开目标文件（路径与行号已在搜索结果中给出），确认：
// 函数_描述 和参数说明）
🔴 CHECKPOINT: 检索完毕。确认所有 API 引用均来自 source/ 下的源码文件，附带了文件路径和行号，未使用模型预训练知识。
基于源码内容组织回答，附上相对文件路径和行号。
附上是基于什么版本的 xcgui 源码来回答的, 本地的 xcgui 源码版本号可在 source/xcgui/README.md 中找到, 可使用 release-(\d+\.\d+\.\d+) 正则表达式提取出该版本号, 会得到 1.4.0 这样的版本号。
当遇到以下场景时，按指定路径处理，不可静默失败。每个场景提供三段式方案：触发条件 → 一线修复 → 兜底方案。
| 触发条件 | 一线修复 | 仍失败兜底 |
|----------|----------|-----------|
| python scripts/download.py 报错 | 检查 Python 是否安装（需 ≥3.7），重试 | 从 py 脚本输出中获取下载链接，告知用户手动下载 |
| 下载后 source/ 目录为空 | 检查网络连接，重试一次 | 告知用户手动下载 ZIP 并解压到 source/ 目录 |
| source/ 存在但缺子目录（如只有 xcgui 无 xcgui-example） | 重新执行 download.py | 告知用户缺失的具体目录名，请求手动补充 |
| 触发条件 | 一线修复 | 仍失败兜底 |
|----------|----------|-----------|
| search.py func/const/event 无结果 | 更换关键词：中英切换、大小写变体、缩写与全称互换 | 使用 grep -rn "关键词" source/ 直接搜索源文件 |
| search.py 本身报错（Python 异常） | 检查 Python 版本、确认脚本文件未损坏 | 回退到 grep 手动搜索，告知用户 search.py 异常 |
| 搜索结果过多（>50 条） | 缩小关键词范围，添加更多限定词 | 先使用 list 命令定位对象，再查具体方法 |
| 搜索到结果但不确定含义 | 用 read 工具打开目标文件确认完整签名和注释 | 搜索同名示例（search.py example ）交叉验证 |
| 触发条件 | 一线修复 | 仍失败兜底 |
|----------|----------|-----------|
| source/xcgui/README.md 不存在 | 执行 python scripts/download.py 下载源码 | 告知用户无法确定版本，建议重新下载 |
| README.md 中未匹配到版本号 | 手动打开文件确认格式是否变化 | 回复时标注"版本号未知"，不影响代码正确性 |
| 触发条件 | 一线修复 | 仍失败兜底 |
|----------|----------|-----------|
| 程序提示"请安装 WebView2 运行时" | 代码中调用 edge.DownloadWebView2() 下载小型安装引导程序 | 告知用户手动前往 Microsoft 官网下载安装 |
| 本机版本低于库要求版本 | 打印警告但仍尝试运行（低版本通常向后兼容） | 告知用户升级 WebView2 运行时以获取最佳兼容性 |
> 核心反例（崩溃/泄漏/刷新等）请参见上方 🚫 反例与禁止事项。
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 设置边框大小
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() // 2. 创建 App 实例
a.EnableAutoDPI().EnableDPI() // 3. 启用 DPI
w := window.New(0, 0, 600, 400, "标题", 0, xcc.Window_Style_Default) // 4. 创建窗口
// 5. 创建控件并绑定事件
btn := widget.NewButton(10, 40, 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() // 6. 显示窗口
a.Run() // 7. 消息循环
a.Exit() // 8. 退出
}
List, ListView, ListBox, Tree, CombBox, 不创建数据适配器就会报错, 无法存储数据, 怎么创建可读取 references/Elements that require creating a data adapter.md
> xcgui 库中所有包的导入路径均以 github.com/twgh/xcgui/ 为前缀，例如 github.com/twgh/xcgui/xc、github.com/twgh/xcgui/app。下文目录树中的目录名直接拼接此前缀即可得到完整导入路径。
所有源码位于 source/ 下，分两大目录：
source/
├── xcgui/ # 主库源码
│ ├── xc/ # 底层 C API 绑定 — 所有 X* 函数, 所有炫彩struct
│ ├── 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/ # 美化编辑框(自绘)
│ ├── BeautifyEdit2/ # 美化编辑框(使用背景管理器)
│ ├── BeautifySliderBar/ # 美化滑块条
│ ├── BeautifyCheckBox/ # 美化复选框
│ ├── BeautifyRadioButton/ # 美化单选按钮
│ ├── BeautifyButton/ # 美化按钮
│ ├── BeautifyProgressBar/ # 美化进度条
│ ├── BeautifyToggleButton/ # 美化开关按钮
│ ├── SetWindowIcon/ # 设置窗口图标
│ └── Draw/ # 绘制示例
│ ├── draw_basic_shapes/ # Draw 基本图形 — 矩形/圆角/椭圆/线/弧/多边形/虚线
│ ├── draw_custom_control/ # Draw 实战 — 自绘圆角按钮/窗口底栏
│ ├── draw_gradient/ # Draw 渐变填充 + 高级设置 — 渐变/裁剪/偏移/焦点框
│ ├── draw_image_svg/ # Draw 图片与SVG绘制
│ └── draw_text/ # Draw 文本绘制 — TextOut / DrawText / 对齐 / 字体 / 下划线
│
├── webview/ # WebView2 示例
│ ├── SimpleWebView/ # 简单 WebView
│ ├── Chart/ # 图表
│ ├── BindTypes/ # 演示 WebView 的 Bind 函数支持的参数和返回值类型
│ ├── modern-desktop-app/ # 现代风格桌面应用
│ ├── 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/ # 登录/注册窗口
这个指的是 xcgui 源码自身的编码规范, 不代表你写代码要遵循这个规范, 可读取 references/XCGUI Programming Standards.md 文件
共 7 个版本