控件是值,交出去就会搬家:C++ GUI 库的控件基类是怎么分层的

0 阅读15分钟

上一篇把窗口弄到了屏幕上。这一篇往回退一步,把它拆开看:Zekit 的控件底座到底怎么搭的。

三个基类 Widget、BoxWidget、TextWidget,加一个官方推荐的 Panel。整集八十多个接口,我用一条主线把它们串起来——控件是值,交出去会搬家。理解了这句话,剩下的接口都只是它的推论。

视频版:【C++ 桌面 GUI Zekit:单静态库,内置 D3D12 / Vulkan / OpenGL 渲染后端】P4 控件基类三件套

源码:GitHub | Gitee


一、三层能力,各管一件事

基类负责什么一句话
Widget几何 · 命中 · 焦点 · 值语义控件的地基:在哪、多大、收不收得到事件
BoxWidget盒子外观绘制模板给控件一张脸:底色、边框、圆角、阴影
TextWidget单行文字排版在这张脸上写字:对齐、字号、四态文字色
Panel复合容器基类三层打包 + 直接可用的排版能力

分工很干净:Widget 不知道控件长什么样,BoxWidget 不管文字,TextWidget 不管排版。

Panel 是重点。 写复合控件就继承它——它同时给你排版能力、背景、边框,往里塞子控件用 AddChild。后面所有"自定义控件"的例子,基类基本都是 Panel。

讲解里会用到 Label(标签)和 Button(按钮)两个现成控件。它们本身不重要,重要的是它们身上每一套接口,都能在这三个基类里找到出处。


二、先记住一句话:控件是值,交出去会搬家

这是整集的地基。

Kit::Label tip("Hello Zekit!");
win.AddWidget(tip);     // 挂上去

AddWidget 收的不是指针,是控件的值。它干两件事:

  1. 把 tip 这个值移动进窗口的子树;
  2. 把所有权接过去——窗口析构时整棵树一起销毁。

所以你不需要给这个 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 / cursorAtcursorAt 按坐标返回,一个控件内可以有多个可交互区
悬停提示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:写复合容器就选它,排版白送

八十多个接口不用背,记住每一层负责什么,用的时候查就行。真正要留在手上的只有五条:

  1. 控件是值,AddWidget 交出去就搬家,接住返回的引用;
  2. 摘 ≠ 删:RemoveWidget 是退出画面,DestroyWidget 才是释放;
  3. 策略写规则,布局算尺寸——pref / hint / width 三套数分开读;
  4. 片段缓存会命中,改了外观必须标脏,批量改就"逐个脏 + 一次排帧";
  5. 事件返回 true 就到此为止,false 才放行。

下一篇进入布局:五种布局容器——VBox / HBox / Grid / Flow,以及它们的主轴交叉轴对齐、间距、裁剪域和脏标记。