上一篇把窗口弄到了屏幕上。这一篇往回退一步,把它拆开看:Zekit 的控件底座到底怎么搭的。
三个基类
Widget、BoxWidget、TextWidget,加一个官方推荐的Panel。整集八十多个接口,我用一条主线把它们串起来——控件是值,交出去会搬家。理解了这句话,剩下的接口都只是它的推论。
视频版:【C++ 桌面 GUI Zekit:单静态库,内置 D3D12 / Vulkan / OpenGL 渲染后端】P4 控件基类三件套
一、三层能力,各管一件事
| 基类 | 负责什么 | 一句话 |
|---|---|---|
Widget | 几何 · 命中 · 焦点 · 值语义 | 控件的地基:在哪、多大、收不收得到事件 |
BoxWidget | 盒子外观绘制模板 | 给控件一张脸:底色、边框、圆角、阴影 |
TextWidget | 单行文字排版 | 在这张脸上写字:对齐、字号、四态文字色 |
Panel | 复合容器基类 | 三层打包 + 直接可用的排版能力 |
分工很干净:Widget 不知道控件长什么样,BoxWidget 不管文字,TextWidget 不管排版。
Panel 是重点。 写复合控件就继承它——它同时给你排版能力、背景、边框,往里塞子控件用 AddChild。后面所有"自定义控件"的例子,基类基本都是 Panel。
讲解里会用到
Label(标签)和Button(按钮)两个现成控件。它们本身不重要,重要的是它们身上每一套接口,都能在这三个基类里找到出处。
二、先记住一句话:控件是值,交出去会搬家
这是整集的地基。
Kit::Label tip("Hello Zekit!");
win.AddWidget(tip); // 挂上去
AddWidget 收的不是指针,是控件的值。它干两件事:
- 把
tip这个值移动进窗口的子树; - 把所有权接过去——窗口析构时整棵树一起销毁。
所以你不需要给这个 Label 写 delete,写了反而是二次释放。
但这里有个必须接住的东西
Kit::Label& tip = win.AddWidget(Kit::Label("Hello Zekit!"));
tip.SetGeometry(24, 16, 120, 60); // 必须用返回的引用
AddWidget 返回的是树里那一份的引用,不是原来那个 tip。值是移动进去的,tip 已经被搬空,只剩一个壳。后面要改文字、要设几何,都得用返回的这个引用。
这就是上一篇里 auto& closeButton = window.AddWidget(...) 那种写法的由来——不是为了少打几个字,是原变量真的不能用了。
如果一定要确认"这个变量是不是已经被搬空了":
Kit::Label source("我会被搬走");
Kit::Widget* oldPtr = &source; // 拿住挂载前的地址
Kit::Label& placed = win.AddWidget(source); // 内部 move → source 变成空壳
bool shell = oldPtr->isMovedFrom(); // true —— 壳
bool real = placed.isMovedFrom(); // false —— 树里的实体
顺带一个反直觉的建议:别长期持有控件指针。 控件交给窗口就会搬家,地址变了,你之前存的指针就靠不住。真需要跨回调访问,用下面第九节的"名字"。
三、树上的四个动作:挂、摘、删、搬
| 动作 | 接口 | 语义 |
|---|---|---|
| 挂 | AddWidget / AddChild | 收值,移动进子树 |
| 挂(特殊) | AddWidgetUnchecked | 绕过排版检查,自定义类内部用 |
| 摘 | RemoveWidget | 退出树,不析构 |
| 删 | DestroyWidget | 析构整棵子树,存储还回去 |
| 清 | ClearChildren | 一次清空所有直接子项 |
| 搬出 | releaseChild | 连存储一起摘走,交给你 unique_ptr |
| 搬入 | adoptChild | 你手上的 unique_ptr 连所有权交给容器 |
RemoveWidget 和 DestroyWidget 的区别值得单独记住:
摘下来是为了以后还能用,删掉是因为再也用不上了。
RemoveWidget 只做一件事——把这个节点从父节点的子项列表里摘掉。它不析构、不释放存储,那块内存还在窗口手里,一直留到窗口析构。摘下来之后对象仍然活着,成员、子树、几何全都还在,只是不在画面上了。
DestroyWidget 是真销毁:从树里摘掉、析构整棵子树、把存储还给容器。返回值告诉你到底删成功了没有。
// 一次删掉一个子项
list.DestroyWidget(*list.children().front());
list.Invalidate(); // 销毁后必须通知重排
销毁之后一定要通知重排(
Invalidate()),否则布局还按老节点表算,画面上会留一个洞。
搬家的两个接口是配对的:
Kit::Panel& a = win.AddWidget(Kit::Panel());
a.AddChild(Kit::Label("第 1 行"));
// 连存储一起摘走
std::unique_ptr<Kit::Widget> held = a.releaseChild(*a.children().back());
// 反方向:把手上这个连所有权交给另一个容器
Kit::Panel& panel = win.AddWidget(Kit::Panel());
auto p = std::make_unique<Kit::Label>("我原本不在这棵树上");
panel.adoptChild(std::move(p));
panel.Invalidate();
控件在容器之间搬家(比如把一个 Tab 拖成独立窗口),走的就是这一对。
两个编译期坑
**AddWidgetUnchecked 只在一种场合用:**你自己写了类继承 Widget,在它的构造函数里往自己身上塞子控件。
因为 Widget 本身不排版,子项永远拿不到几何,所以基类把 Widget 上的 AddWidget 标成了弃用——你写了就报 C4996。AddWidgetUnchecked 就是绕过这道检查,意思是:我知道它不排版,我自己管。
顺带第二个坑: Widget 把 Paint 声明成纯虚函数,派生类必须实现,哪怕函数体是空的:
class ManualStack : public Kit::Widget {
public:
ManualStack() {
Kit::Label tip("Hello Zekit!");
AddWidgetUnchecked(tip);
}
void Paint(Kit::FrameCollector&) const override {} // 不写就报 C2259
};
不写就报 C2259,说这个类无法实例化。
真正的建议:写容器就继承
Panel,它自带排版,子项会自动排队。AddWidgetUnchecked只留给确知自己要手工排版的人。
四、几何:写、读、量
写
| 接口 | 写什么 |
|---|---|
SetSize(w, h) | 只写尺寸意图 |
SetGeometry(x, y, w, h) | 位置 + 尺寸一次给全 |
SetPosition / SetX / SetY | 只挪位置 |
SetSize 只声明"我想要多大",不负责落在哪。位置永远交给父容器:挂在窗口上就按你说的尺寸放,挂在容器里就由容器决定。
读
int px = (int)btn.x(); int py = (int)btn.y();
int pw = (int)btn.width(); int ph = (int)btn.height();
这四个读的是实际几何——布局算完之后,控件真正落在哪、真正多大。它不一定等于你设的值。
三套尺寸,别混
同一个控件身上同时存在三套尺寸:
| 读法 | 含义 |
|---|---|
prefWidth() | 你想要的(没表态就是 0) |
hintWidth() | 内容需要的(按文字量出来的自然尺寸) |
width() | 布局最终给的实际尺寸 |
pref是意图,hint是内容,width是事实。- 只有
width()是"现在真的是这么大",另外两个都是给布局看的输入。
量
btn.SetText("内容改变了,这段内容很长");
btn.AutoSize(); // 让控件按新内容重新量一次
改完文字,尺寸不会自己变,文字就会被挤掉。AutoSize 解决的就是这件事。
还有 SetDefaultSize——设的是兜底尺寸:前两个都不管用的时候,才轮到它出声。它不写 pref,所以你设的意图它一概不动。
五、尺寸策略:只写规则,不写尺寸
这一节的接口有个共同点:它们几乎都不写尺寸,只写规则。真正算尺寸的还是布局。
| 接口 | 规则 |
|---|---|
SetSizePolicy / 单轴 Policy | 这个方向上,我想不想吃掉剩余空间 |
SetMinSize / SetMaxSize | 一把钳子:能压到多小、能撑到多大 |
SetMargin | 和邻居的距离(加在外侧,自己不缩) |
SetFlexGrow | 剩余空间按权重分 |
SetAlignSelf | 我在交叉轴上单独对齐 |
SetFillWindow | 跟着窗口缩放,铺满客户区 |
Kit::VBoxLayout& box = win.AddWidget(Kit::VBoxLayout());
box.AddChild(Kit::Label("标题:只占自己那一行"));
Kit::Panel& body = box.AddChild(Kit::Panel());
body.SetSizePolicy(Kit::SizePolicy::Preferred,
Kit::SizePolicy::Expanding); // 纵轴吃掉剩余高度
上面这段值得细看:标题只占自己那一行,下面的 body 把剩余高度全吃掉——这就是"自述式布局"的典型写法,你从头到尾没写过一个像素值。
权重按比例分,不是按像素分:
b.SetFlexGrow(1.0f); // B 拿一份
c.SetFlexGrow(2.0f); // C 拿两份 —— 剩余宽度按 1 : 2 分
钳子的效果很直观:
box.SetMinSize(200.0f, 80.0f); // 下限
box.SetMaxSize(360.0f, 160.0f); // 上限
box.SetSize(100.0f, 50.0f); // 请求越界 → 实际被钳成 200 × 80
六、绘制:先理解"片段缓存"
这一部分解决三个问题:控件怎么画自己、画完怎么让窗口知道该重画、不该出现时怎么退出画面。
理解它的前提是一个概念:片段缓存。
窗口不是每帧重画所有控件的。一个控件画过之后,那段顶点会被缓存;下一帧如果它没变,缓存命中,直接复用。
所以你改了外观却不打招呼,画面就不会变——你的改动根本没机会被画出来。
这不是 bug,是性能的来源。代价是:谁改状态,谁负责标脏。
| 接口 | 作用 |
|---|---|
Paint(FrameCollector&) | 自己画的唯一入口,往收集器里追加图元 |
clipChildrenRect() | 子项裁在哪 |
paintsOnTop() | 返回 true 则推到"所有控件画完之后"再画 |
wantsAnimationFrame() | 别让窗口睡,我要做动画 |
RequestWindowRedraw() | 标脏 + 调度一帧 |
InvalidatePaint() | 只标脏,不排帧 |
SetVisible(false) | 不画,但还在树里 |
SetEnabled(false) | 照样画、照样占位,只是不能操作 |
void SetState(int v) {
state_ = v; // 只改状态 —— 画面不会自己变
RequestWindowRedraw(); // 标脏 + 调度一帧,这才会重画
}
批量改的时候,一个个请求重画太浪费:
for (Kit::Label* l : labels) {
l->SetText(std::to_string(n));
l->InvalidatePaint(); // 每个只标脏,不调度
}
batch.RequestWindowRedraw(); // 最后统一调度一帧
一个脏 + 一次排帧,这就是批量更新的标准写法。
另外三个"要不要出现在画面上"的开关,容易混:
SetVisible(false):不参与绘制、命中和布局,但还在树里;SetEnabled(false):翻的是交互资格,不是显隐,禁用之后照样画、照样占位;RemoveWidget:从树上摘掉,连布局都不参与。
做动画的控件记得申报:
bool wantsAnimationFrame() const override { return animating_; }
// true → 窗口一直给你排帧;false → 它立刻休眠
七、命中与事件:返回值的语义是统一的
先判落点,再走事件。 判落点用 HitTest,默认实现是矩形:
bool HitTest(float x, float y) const override {
const float cx = this->x() + width() * 0.5f;
const float cy = this->y() + height() * 0.5f;
return std::hypot(x - cx, y - cy) <= width() * 0.5f; // 只认圆内
}
控件画成一个圆,命中判定却默认是矩形——四个角明明没东西,点上去照样有反应。HitTest 就是这条判定线。
事件入口都是 On 开头的虚函数,返回 true 表示我处理了,事件到此为止;返回 false 就是放行,让父控件接着处理。这条规则全库统一,记住了就不用一个个查。
bool OnMousePress(Kit::MouseEvent& e) override {
e.accept(); // 显式声明"这个事件归我了"
return true;
}
| 组 | 入口 |
|---|---|
| 鼠标 | OnMousePress / OnMouseRelease / OnMouseMove / OnMouseWheel |
| 进出 | OnMouseEnter / OnMouseLeave(虚钩子,没有 Set 版本) |
| 触摸 | OnTouchBegin / OnTouchUpdate / OnTouchEnd / OnTouchCancel |
| 键盘 | OnKeyPress(语义键)/ OnCharInput(真字符,char32_t) |
键盘那两个别用错:按键本身走 OnKeyPress,真正打进文字的字符走 OnCharInput。 单指的点击和拖动,平台层已经合成为鼠标事件了,触摸四件套是给多指手势用的。
想在自己这一层提前拦事件,装一个过滤器:
class ABlocker : public Kit::EventFilter {
public:
bool onKey(Kit::Window&, Kit::KeyEvent& e) override {
if (e.key != Kit::Key::A) return false; // 放行
return true; // 拦下,子树收不到这颗 A
}
};
ABlocker blocker; // 过滤器要活得比安装期长
const auto id = pad.InstallEventFilter(blocker); // 装到 pad 的整棵子树上
注意
blocker的生命周期——它必须活得比安装期长,卸载用RemoveEventFilter(id)。
八、焦点:三个问题,三个接口
焦点在库里是一个全局互斥的状态:同一刻只有一个控件握着它,仲裁权在窗口,控件只收通知。
最容易写错的地方,是把下面三个问题混成一个:
| 问题 | 接口 |
|---|---|
| 我有没有资格聚焦? | isFocusable() |
| 现在轮不轮得到我?(可能被禁用、被挡住) | isFocusTarget() |
| 此刻是不是真的握着? | hasFocus() |
edit.SetEnabled(false);
bool can = edit.isFocusTarget(); // false —— Tab 和点击都会跳过它
想收键盘输入,第一步是申报:
edit.SetFocusable(true); // 默认是 false,不申报就不参与焦点轮转
得失通知只能派生覆写,没有回调注册入口:
void OnFocusIn() override {
Kit::InputBox::OnFocusIn(); // 先交基类:重置光标、激活输入法
out_->SetText("获得焦点:可以打字了");
}
void OnFocusOut() override {
Kit::InputBox::OnFocusOut(); // 基类要取消未完成的输入法合成
out_->SetText("失去焦点:已提交「" + Text() + "」");
}
基类调用不能省。 输入框的焦点进出背后挂着光标和输入法合成状态,跳过基类就会出现"光标不闪""候选窗不消失"这类怪事。
WantsSoftKeyboard() 是给移动端用的:只读展示框、自定义数字键盘这类控件,聚焦时不该弹软键盘,覆写它返回 false 就行。
九、身份与查找:名字比地址可靠
控件会搬家,指针靠不住。所以给它一个逻辑名字,名字跟着值一起走:
Kit::Label& title = panel.AddChild(Kit::Label("我是 title"));
title.SetObjectName("title");
if (auto* p = panel.FindWidget<Kit::Label>("title"))
info.SetText("找到:" + p->ObjectName());
| 接口 | 范围 |
|---|---|
FindWidget<T>(name) | 只查直接子项,不往下钻 |
FindWidgetDeep<T>(name) | 从自己开始递归整棵子树,返回第一个匹配 |
FindAll<T>(name) | 返回 vector,同名同类型的全拿出来 |
VisitTree(fn) | 前序遍历,回调给 (控件, 深度) |
SetWidget(name, w) | 按名字原位替换,没有就新增 |
FindWidget 有个容易踩的点:名字和类型都得对上,缺一个就是空指针。
Kit::Label* a = win.FindWidget<Kit::Label>("target"); // 命中
Kit::Label* c = win.FindWidget<Kit::Label>("row"); // 不递归 → nullptr
Kit::Button* d = win.FindWidget<Kit::Button>("target"); // 名字对、类型错 → nullptr
SetWidget 是"原位更新"的正确姿势——别删了重加:
col.SetWidget("mid", Kit::Label("第二行:第 0 次")); // 第一次 = 新增
col.SetWidget("mid", Kit::Label("第二行:第 1 次")); // 再给 = 原位替换,不堆叠
用"删掉再添加"来刷新内容,只要有一次漏删,就会越点越多;SetWidget 用名字当位置,天然没有这个问题。
遍历整棵树,打印结构最直观:
root.VisitTree([&](Kit::Widget& w, int depth) {
out += std::string(depth * 2, ' ') + w.ObjectName() + "\n";
});
十、控件身上的窗口转发与小能力
Widget 上除了树、几何、事件,还挂了两类东西。
第一类:窗口便利 API。 三十多个函数——关窗口、改标题、设窗口尺寸、置顶,全都能在控件上直接喊,不用手里攥着窗口引用。
第二类:每个控件都可能用得上的小能力。
| 能力 | 接口 | 注意 |
|---|---|---|
| 悬停光标 | SetCursor / cursorAt | cursorAt 按坐标返回,一个控件内可以有多个可交互区 |
| 悬停提示 | SetTooltip / ClearTooltip | 支持纯文字,也支持带标题和图标的富内容 |
| 文件拖放 | SetAcceptFileDrop + 四阶段 / SetOnFileDrop | 不声明就一个事件都收不到 |
| 换肤 | ApplyTheme / markStyled / hasCustomStyle | 手动设过的样式靠标记才不被主题覆盖 |
| 原生表面 | 声明持有 + 每帧同步 | 画布、视频这类控件用 |
| 类型转换 | As<T>() | 回调只给 Widget&,要具体类型就转 |
拖放这里有个"省事版":
zone.SetAcceptFileDrop(); // 前提:不开通道,回调不会来
zone.SetOnFileDrop([&log](const std::vector<std::string>& files) {
log.SetText("收到 " + std::to_string(files.size()) + " 个文件");
});
只关心"放下"那一刻,就不用派生类覆写四个虚函数。
十一、BoxWidget:一个盒子拆成几个槽
Widget 只管控件在哪、多大、收不收得到事件,它不知道控件长什么样。外观全在 BoxWidget 这一层。
理解方式:一个矩形盒子被拆成几个槽位,每个槽位独立。
| 槽位 | 代表接口 |
|---|---|
| 底色 | SetBodyColor / SetHoverBodyColor |
| 边框 | SetBorderColor / SetBorderWidth / SetBorderStyle |
| 圆角 | SetRadiusMode(语义档位)/ SetRadius(死数值) |
| 内容 | SetPadding |
| 整体 | SetOpacity |
| 背景图 | SetBackgroundImage / DrawMode / Align |
| 阴影轮廓 | SetShadow / SetOutline |
槽位的独立性很实用——同底色、五种描边的对比图,就是只改边框槽做出来的:
Kit::Button b;
b.SetBodyColor(Kit::Color4f::FromHex(0xE5484D)); // 常态底色
b.SetHoverBodyColor(Kit::Color4f::FromHex(0xE5484D)); // 顺手钉住悬停色
b.SetBorderWidth(0.0f); // 清掉主题默认边框
三行连着写是有原因的:只改底色不动悬停色,鼠标一移上去就跳成主题色;不清边框,底色看起来会脏。
圆角优先用档位,别写死像素:
b.SetRadiusMode(Kit::RadiusMode::Capsule); // 短边一半,两端半圆
SetRadiusMode 给的是语义(小 / 中 / 大 / 胶囊),具体多少像素由主题决定;SetRadius 直接给数值,内部会把档位切成"自定义",从此只认你给的数。
先说颜色:Color4f 的五种写法
| 写法 | 用途 |
|---|---|
Color4f::FromHex(0x0091FF) | 十六进制,最常用 |
Color4f::White() | 几个具名色 |
Color4f{0, 0, 0, 0.5f} | 红绿蓝 + 透明度 |
c.withAlpha(0.6f) | 只改透明度 |
c.lighten(0.25f) | 往白里推 25%,算悬停色就靠它 |
五种写法指向同一个类型,挑顺手的用。lighten 那条建议记住:悬停色的标准做法就是常态色 lighten 一档,比手调一个十六进制值稳。
十二、TextWidget 与 Panel
TextWidget 是带文字的控件基类——Label 和 Button 都是它。它除了拥有盒子那一整套属性,还多了一整套文字接口:
t1.SetTextAlign(Kit::TextHAlign::Center); // 对齐
t4.SetFontSize(28); t4.SetBold(true); // 字号 + 粗体
t5.SetTextDecoration(Kit::TextDecoration::LineThrough); // 装饰线
t6.SetHoverTextColor(Kit::Color4f::FromHex(0x30A46C)); // 文字四态
文字自己也有四种状态色(常态 / 悬停 / 按下 / 禁用),和盒子的四种状态是两套,各管各的。
Panel 是把三层打包好的那个基类:
class Card : public Kit::Panel { // 继承 = 排版 + 背景 + 边框
public:
Card() {
SetBackground(Kit::Color4f::FromHex(0xFFFFFF));
AddChild(Kit::Label("我是标题")); // 用 AddChild,会自动排队
}
};
前面那个"子项全挤在左上角"的坑,在 Panel 这里不存在——它自带排版,AddChild 进去的子项会自动排队。
十三、复盘:三层各管什么
Widget:几何 · 命中 · 焦点 · 值语义——控件的地基BoxWidget:盒子怎么画,拆成若干个槽位TextWidget:单行文字排版,文字另有四态Panel:写复合容器就选它,排版白送
八十多个接口不用背,记住每一层负责什么,用的时候查就行。真正要留在手上的只有五条:
- 控件是值,
AddWidget交出去就搬家,接住返回的引用; - 摘 ≠ 删:
RemoveWidget是退出画面,DestroyWidget才是释放; - 策略写规则,布局算尺寸——
pref/hint/width三套数分开读; - 片段缓存会命中,改了外观必须标脏,批量改就"逐个脏 + 一次排帧";
- 事件返回 true 就到此为止,false 才放行。
下一篇进入布局:五种布局容器——VBox / HBox / Grid / Flow,以及它们的主轴交叉轴对齐、间距、裁剪域和脏标记。