QCursor 自定义鼠标样式，让走 TaoToken 的 Codex 对照 bitmap/mask 热点

1. 为什么 QCursor 自定义鼠标样式总对不上做 Qt 桌面端的时候鼠标样式这件事看起来很小但真动手改起来坑比想象中多。Qt 内置的Qt::CursorShape枚举确实方便一行setCursor(Qt::PointingHandCursor)就能把箭头换成小手可一旦产品经理拿着设计稿说“我要这个带描边的十字准星”“我要一个 20x20 的彩色小圆点”内置枚举就不够用了。这时候就得走自定义路线QBitmapQBitmap mask的位图方案或者QPixmap加载 XPM 数组的方案。问题也随之而来——bitmap 和 mask 的黑白像素值到底谁代表“显示”、谁代表“透明”hotX/hotY传 -1 是什么意思XPM 色表里None、#FF796D这些字段怎么和数组对齐我见过太多人把 bitmap 和 mask 传反结果鼠标变成一个纯黑方块或者热点偏到左上角点按钮要点半天。这篇就按“接入配置”这个槽位来写先把 Qt Creator 里那几段设置光标的代码原样保留然后引入 TaoToken 作为参数对照和代码逐段核对的辅助工具。需要说明的是TaoToken 在这里只负责提供 Key 和 Base URL让你把 Codex 配通它不参与 Qt 的光标绘制bitmap、mask、hotX/hotY、XPM 数组这些还是得你自己贴给 Codex 去逐段比对。适合正在用 Qt 写桌面端、被自定义光标折磨过的同学。2. 前置准备TaoToken 的 Key 与 Base URL在开始对照参数之前先把 Codex 的接入配好。打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册账号进控制台创建一个 API Key。这个 Key 就是你后面让 Codex 帮你逐段核对 bitmap/mask 像素值、热点坐标、XPM 色表的凭证。创建 Key 的入口在控制台的 API Keys 页面直接访问 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 就能到。Key 生成后复制保存后面配置 Codex 时要用。Base URL 这块要特别注意填https://taotoken.net/api不要加/v1也不要带任何 UTM 参数。很多人习惯性在后面补/v1结果请求 404排查半天以为是 Key 的问题。记住这个地址就是纯https://taotoken.net/api。如果你更想先在网页里对话验证模型通不通可以走模型对话入口 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 先发一句“你好”确认链路正常再回到 Codex 里配。长期做编码和 Agent 任务的可以看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。3. 可复制配置Qt 三种光标写法 Codex 接入3.1 内置光标setCursor(Qt::PointingHandCursor)这是最省事的一种。Qt 内置了一批CursorShape枚举跨平台会被替换成当前系统支持的样式。在构造函数里直接写CustomCursor::CustomCursor(QWidget *parent) : QMainWindow(parent) { ui.setupUi(this); setCursor(Qt::PointingHandCursor); // 设置鼠标样式为小手 }Qt::PointingHandCursor就是链接悬停时那只手Qt::CrossCursor是十字Qt::WaitCursor是沙漏。缺点是样式受系统限制设计稿要的定制效果做不出来。3.2 位图方案QBitmap QBitmap mask自定义位图的核心是两张图bitmap决定形状mask决定哪些像素显示、哪些透明。用代码生成的话QBitmap bitmap(32, 32); // 生成 32x32 的 bitmap bitmap.fill(Qt::color1); // 填充 1 像素值 QBitmap bitmap_mask(32, 32); // 生成 32x32 的 mask bitmap_mask.fill(Qt::color0); // 填充 0 像素值 QCursor cursor(bitmap, bitmap_mask, -1, -1); // -1 -1 表示热点在中心 setCursor(cursor);这里Qt::color1对应像素值 1Qt::color0对应 0。用画图工具生成 PNG 时约定黑色 RGB(0,0,0) 表示 1白色 RGB(255,255,255) 表示 0。加载方式QBitmap bitmap(bitmap.png); // 背景透明的 png QBitmap bitmap_mask(bitmap_mask.png); // 掩码图 QCursor cursor(bitmap, bitmap_mask, -1, -1); setCursor(cursor);hotX/hotY传 -1 表示热点自动落在图片中心如果你要精确控制点击位置就传具体坐标比如QCursor cursor(bitmap, bitmap_mask, 5, 5)表示热点在 (5,5)。3.3 XPM 方案QPixmap 加载数组XPM 是文本格式的位图能直接写在代码里适合做彩色透明光标。数组头部20 20 3 1表示宽 20、高 20、3 种颜色、每像素 1 个字符。后面 c None是透明色 c #FF796D和* c #FFE6B2是两种实色。static const char* const xpmCursor[] { 20 20 3 1, c None, c #FF796D, * c #FFE6B2, , , , ********* , ********* , ********* , ********* , ********* , ********* , , , ********* , ********* , ********* , ********* , ********* , ********* , , , , }; CustomCursor::CustomCursor(QWidget *parent) : QMainWindow(parent) { ui.setupUi(this); QPixmap pixmap(xpmCursor); // 加载 xpm 生成的图标 QCursor cursor(pixmap); setCursor(cursor); }注意 XPM 数组里每一行的字符数必须和头部声明的宽度一致少一个空格都会导致解析失败或者图像错位。3.4 Codex 接入配置把 Codex 的 Base URL 填成https://taotoken.net/apiAPI Key 填你刚才创建的那串。配置示意{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: gpt-5-codex }配好之后你就可以把上面三段代码连同 bitmap、mask、hotX/hotY、XPM 数组一起贴给 Codex让它逐段对照原文帮你核对像素值和坐标。4. 验证请求让 Codex 逐段核对参数配置完成后先发一个最小请求确认链路通。在 Codex 里输入请帮我检查这段 Qt 光标代码的 bitmap 和 mask 是否传反了 QBitmap bitmap(32, 32); bitmap.fill(Qt::color1); QBitmap bitmap_mask(32, 32); bitmap_mask.fill(Qt::color0); QCursor cursor(bitmap, bitmap_mask, -1, -1);如果返回正常说明 Base URL 和 Key 都没问题。接着把完整的 XPM 数组贴进去让它核对色表和每行字符数下面这个 XPM 数组头部声明 20 20 3 1请逐行数一下字符数是否都是 20 并检查 c None 这一行是不是透明色定义 static const char* const xpmCursor[] { ... };实测下来Codex 能很快指出哪一行少了空格、哪个色表字段写错。成功的结果是它逐行列出字符数标出不一致的行号并给出修正后的数组。这时候你再把修正结果贴回 Qt Creator重新编译运行鼠标样式就对了。5. 本篇常见错排查bitmap 和 mask 传反最常见。记住bitmap是形状mask是透明区域。如果鼠标变成纯黑方块八成是两张图对调了。把两张图贴给 Codex让它对比像素值分布就能确认。hotX/hotY 传 -1 但热点不对-1 表示自动居中但如果你用的是非正方形图片居中点可能不是你想要的点击位置。改成具体坐标比如 20x20 的图想热点在左上角就传(0, 0)。XPM 色表对不上 c None前面是一个空格表示空格字符对应透明 c #FF796D表示字符对应这个颜色。如果色表字符和图像里的字符不一致图像会花掉。让 Codex 逐字符比对色表定义和图像行。Base URL 带了 /v1请求直接 404。确认填的是https://taotoken.net/api后面什么都不加。Key 无效或过期去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 重新生成一个注意复制时不要带空格。PNG 加载后全黑QBitmap加载 PNG 时对格式敏感确保是背景透明的 PNG且黑白像素值符合约定黑1白0。不确定的话用代码生成的方式先跑通再换成图片。6. 接入文档与后续操作Qt 光标这块的参数对照核心就是 bitmap/mask 的像素值、hotX/hotY 的坐标、XPM 的色表和字符数这三组。把这三组贴给 Codex 逐段核对比你自己盯着数组数空格快得多。需要重新创建 Key 或查看接入细节的走 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 和接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先在网页里验证模型响应的用模型对话 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。长期跑编码和 Agent 任务的Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 更合适。最后提醒一句Codex 帮你核对的是参数和逻辑Qt 的光标绘制本身还是由 Qt 运行时完成TaoToken 只提供 Key 和 Base URL 这条链路。把 bitmap、mask、hotX/hotY、XPM 数组贴清楚让它逐段对照比反复编译试错省时间。