上一篇把库编出来、接进了 VS 工程。这一篇开始写代码:先把一个窗口弄到屏幕上,然后把它身上那一圈接口过一遍——入口、显示与关闭、几何、状态、外观,最后是渲染后端和驱动模式。
十一行就能跑起来。但真正会让界面偏几十像素、让后端静默回退的坑,都在后面几节。
视频版:【C++ 桌面 GUI Zekit:单静态库,内置 D3D12 / Vulkan / OpenGL 渲染后端】P3 第一个窗口
一、最小骨架:十一行
#include <Zekit.h>
#include <ZekitApp.h>
ZEKIT_APP_ENTRY(myApp) {
Kit::Window window;
window.SetTitle("Zekit");
window.SetSize(1000, 700);
window.Show();
return window.exec();
}
两个头文件分工很明确:Zekit.h 管窗口,ZekitApp.h 管入口。
SetTitle改标题栏文字,走 UTF-8,中文直接写;SetSize(1000, 700)设的是客户区尺寸,这个"客户区"是后面第五节的主角;Show()把窗口显示出来;exec()进消息循环。
这五行就是所有 Zekit 程序的最小骨架。没有注册窗口类,没有 CreateWindow,没有自己写消息循环。
二、入口:三种写法,行为不一样
| 写法 | 程序子系统 | 有没有控制台黑框 |
|---|---|---|
ZEKIT_APP_ENTRY(name) | 窗口子系统 | 没有 |
ZEKIT_APP_ENTRY_CONSOLE(name) | 控制台子系统 | 有,可以 printf 打日志 |
int main() | C++ 默认入口 | 有 |
ZEKIT_APP_ENTRY 在链接阶段就把程序定成窗口子系统,所以在系统里双击运行不会弹出一个黑框。要打印日志,就换带 CONSOLE 的那个版本;也可以干脆写 int main,走 C++ 默认入口。
一个很常见的困惑:在 VS 里调试时看到控制台,不代表宏没生效。 那是工程的子系统设置盖过了宏——VS 默认按控制台程序链接。跟程序本身的行为没有关系。
三、exec() 在干什么
window.Show();
return window.exec(); // 这一句之后,程序不再往下走
exec() 进入消息循环,一直阻塞到最后一个窗口关闭为止。
所以调用 Close(),exec() 就返回,程序继续往下走、然后结束。这一句之后程序不再往下走,它在等消息。
三条纪律:
- 一个进程只调一次
exec()。 - 不要跟
PollEvents混着用——那是两个循环在抢同一件事。 - 后面所有的演示,全都包在这一个
exec()里。
四、给窗口加一个能点的按钮
上一节只留了骨架。这一份是能直接编译的完整版本:
#include <Zekit.h>
#include <ZekitApp.h>
#include <ZeButton.h>
ZEKIT_APP_ENTRY(myApp) {
Kit::Window window;
window.SetTitle("Zekit");
window.SetSize(1000, 700);
auto& closeButton = window.AddWidget(Kit::Button("关闭窗口"));
closeButton.SetGeometry(50, 50, 120, 60);
closeButton.SetOnClick([&window]() {
window.Close();
});
window.Show();
return window.exec();
}
注意 AddWidget 的用法:控件是按值交出去的,回来的是引用。
auto& closeButton = window.AddWidget(Kit::Button("关闭窗口"));
这个引用就是你后面调几何、挂回调的把手。不用 new,也不用管什么时候释放——Button 本身没有名字变量,你也不需要保留它。
lambda 里按引用捕获窗口,点下去就调 Close。加起来不到二十行,中间没有一行平台代码。
五、几何:三套坐标,混了就偏几十像素
这是这一集最需要记牢的一节。
| 坐标 | 是什么 | 谁在用 |
|---|---|---|
| 客户区 | 去掉标题栏和边框之后的那块 | 控件坐标全相对它 |
| 外框 | 客户区 + 标题栏 + 边框 | SetPosition 收的是它 |
| 工作区 | 屏幕扣掉任务栏之后的可用范围 | 居中、最大化时的边界 |
搞混这三个,界面就会偏几十个像素——而且自己的机器上看不出来,换台机器才暴露,因为边框和标题栏的厚度会随系统缩放和主题变化。
为什么窗口看起来比 1000 × 700 大
外框宽 = 客户区宽 + 左右边框
外框高 = 客户区高 + 标题栏 + 下边框
你在代码里写 SetSize(1000, 700),窗口在屏幕上会比这个数大一圈,多出来的就是边框和标题栏。
还有一件容易踩的事:
SetSize之后,窗口默认会在当前显示器的工作区里重新居中。想只改尺寸、不动位置,就补一次SetPosition把位置覆盖掉。
读尺寸:三种写法
int clientW = 0, clientH = 0;
window.GetClientSize(clientW, clientH); // 两个都是引用传出
已经有窗口对象了,就不用再传两个参数:
const int w = window.width();
const int h = window.height(); // 和 GetClientSize 是同一对数
为什么老强调客户区?因为控件坐标、布局、纹理尺寸全都相对它。你算一个控件在屏幕上的位置,第一步就是先知道这块客户区。
width()/height()在窗口关掉之后返回 0。拿它做除法之前先判一下。
摆位置与取边界
window.SetPosition(300, 300); // 收的是外框左上角,尺寸不变
window.adjustSize(); // 客户区收紧,刚好装下控件
window.CenterOnScreen(); // 在任务栏以上的范围里居中
想要那个"任务栏以上的范围"本身,用 GetScreenWorkArea:
int workX = 0, workY = 0;
int workW = 0, workH = 0;
const bool hasArea = window.GetScreenWorkArea(workX, workY, workW, workH);
它返回布尔值,成功时四个引用参数带出位置和大小,失败时返回 false——没有屏幕概念的平台就是这样,所以这个返回值别丢。
还有一个很像、但含义完全不同的接口:
window.SetPosition(300, 300);
int originX = 0, originY = 0;
window.GetClientOrigin(originX, originY);
// 客户区左上角在屏幕上的坐标
SetPosition 是"外框摆在哪",GetClientOrigin 是"客户区左上角实际上在屏幕的哪里"。这台机器上外框摆在 (300, 300),客户区原点比它多出 11 × 45——这几十个像素,就是边框和标题栏。
它的真正用途是跨窗口换算:
屏幕坐标 = A 的原点 + A 里的坐标
= B 的原点 + B 里的坐标
两个窗口要对齐、面板要能撕下来再贴回去,就得先有这个点。
六、状态与动作
| 接口 | 作用 |
|---|---|
Minimize() / Maximize() / Restore() | 最小化 / 最大化 / 还原 |
SetTopmost(true) | 置顶,切换的时候不抢焦点 |
SetWindowIcon(path) | 换图标,后面单独说 |
RequestRedraw() | 主动请求重绘一帧 |
SetTopmost 这条"不抢焦点"很重要:做工具面板、悬浮窗几乎必用,否则你一置顶,当前正在编辑的输入框就丢焦点了。
RequestRedraw 是主动要一帧:你改了控件、但没触发重绘时,靠它把画面刷出来。
redrawButton.SetOnClick([&window, &infoLabel](Kit::Widget&) {
infoLabel.SetText("文字改了");
window.RequestRedraw(); // 显式请求一帧
});
最小化和还原来回演示,靠的是定时器:
minimizeButton.SetOnClick([&window]() {
window.Minimize();
window.SetTimeout(1500, [&window]() {
window.Restore();
});
});
SetTimeout 的单位是毫秒
这是本集第二常见的坑:
1500 → 1.5 秒
1.5 → 1 毫秒,看起来像没执行
写成 1.5 手滑一下,窗口会像"没反应"。它不是报错,它是真的执行了——只是快到看不见。
另外两条:
- 它返回一个定时器编号,方便记账;
- 在回调里再调一次
SetTimeout,就相当于自己做了个循环——隐藏再显示就是这么写的; - 定时器跟着窗口走,窗口关了就一起没了。
七、尺寸约束:三个接口互相牵连
window.SetMinimumSize(400, 400); // 往里拖,到 400 就停
window.SetMaximumSize(1100, 800); // 往外拖,到 1100 × 800 就停
window.SetResizable(false); // 边框拖不动,最大化也灰了
两个限制量的都是客户区,不是外框;传 (0, 0) 就解除限制。
但它们的边界不一样,这张表值得收藏:
| 接口 | 限制用户拖边框 | 限制程序 SetSize | 影响最大化按钮 |
|---|---|---|---|
SetMinimumSize | 有效 | 有效 | 不影响 |
SetMaximumSize | 有效 | 有效 | 管不住 |
SetResizable(false) | 禁止 | 不影响,照旧 | 按钮变灰 |
三条规则互相牵连,串起来读就是:
SetMinimumSize:管用户拖,也管SetSize;最小化/最大化时不管;SetMaximumSize:管用户拖和SetSize,管不住最大化按钮;SetResizable(false):去掉拖边框和最大化按钮,SetSize照旧生效。
所以做固定尺寸的对话框,正确的组合是:
window.SetResizable(false);
window.SetMinimumSize(760, 520);
window.SetMaximumSize(760, 520); // 上下限相等 = 钉死
只写一个最大尺寸是不够的——用户还是能点最大化。
四个名字,四个意思
这几个名字太像,我把它们摆在一起:
| 接口 | 回答的问题 |
|---|---|
SetSize | 现在多大(会被约束夹一下) |
SetMinimumSize / SetMaximumSize | 允许多大(不直接改尺寸) |
adjustSize | 按内容算多大 |
SetPosition | 摆在哪 |
一个改状态,一个划边界,一个量内容,一个定位置。分清这四个,几何这块就不会写错。
八、标题栏与图标
window.SetTitleBarVisible(false); // 整条标题栏消失,边框还在
window.SetMinimizeButtonEnabled(false); // 三颗系统按钮可单独禁
window.SetMaximizeButtonEnabled(false);
window.SetCloseButtonEnabled(false); // 叉点不了,只能程序自己关
window.SetWindowIcon("icon_demo_b.ico"); // ico / png / jpg / bmp 都行
SetTitleBarVisible(false) 的效果是:标题文字和三个按钮一起没了,但边框还在、仍然能拖边缩放。这和"无边框窗口"不是一回事。
SetCloseButtonEnabled(false) 是个挺实用的开关:禁用之后用户关不掉,只能由程序自己调 Close()。做"确认后才能退出"的场景就不用拦消息了。
SetWindowIcon 直接传文件路径,不用先自己解码成位图。路径按 UTF-8 传,所以放在中文目录里也没问题。
九、渲染后端:顺序错了就是静默回退
这一条是硬坑,值得单独一节。
Kit::Window window;
window.UseRenderer(Rhi::Api::OpenGL); // ★ 必须紧接构造,早于 SetSize / Show
window.SetTitle("Zekit");
window.SetSize(920, 600);
window.Show();
return window.exec();
UseRenderer 必须是窗口构造之后的第一个调用,要早于 SetSize、SetPosition、AddWidget 和 Show。
原因:那几个接口会让默认后端先把窗口占住——D3D12 会建交换链,GL 会设像素格式。占住是不可逆的,之后再换后端只会返回 false、然后静默回退。
"静默"这两个字是关键:它不报错,不崩,你在任务管理器里看着程序好好的,只是它跑的其实不是你指定的那个后端。
唯一合法的顺序:
构造 → UseRenderer → SetTitle / SetSize → AddWidget → Show
中途加完控件再调 UseRenderer,一样失效。UseExternalRenderer 同样要在第一次绘制之前。
怎么事后确认到底跑的是哪个
| 接口 | 含义 |
|---|---|
rendererApi | 本窗口实际在跑的后端(回退后是回退值) |
gpuPreference | 你请求的策略 |
deviceInfo | 真正拿到的那块卡 |
一句话记:gpuPreference 是意图,deviceInfo 是事实。
排查"为什么我的帧率不对"时,先读 rendererApi,八成能省半天。
十、驱动模式:谁来决定画下一帧
| 模式 | 行为 | 适合 |
|---|---|---|
EventDriven | 有事才画,静止零 CPU(默认) | 绝大多数桌面应用 |
OnDemand | 有动画时按帧率画,动画停下就停 | 有局部动画的界面 |
Immediate | 无条件按帧率画,画面没变也在画 | 游戏式循环、实时预览 |
window.SetDriveMode(Kit::Window::DriveMode::OnDemand);
const auto mode = window.driveMode(); // 读回来
const int fps = window.frameRate();
SetDriveMode 要在 exec() 之前调;运行中改只影响下一轮。
OnDemand 到底省在哪,看这两行就明白了——一个自绘控件决定"要不要续约下一帧":
void RhythmBar::paintContent(Kit::FrameCollector& fc) const {
Tick(); // 每帧推进一次
Kit::ProgressBar::paintContent(fc);
}
bool RhythmBar::wantsAnimationFrame() const {
return running_; // 到位即停,不再续约
}
画完就续约下一帧;OnDemand 到位即停、不再续约,所以帧数不涨了——这就是它省 CPU 的地方。
帧率也有个小陷阱:
window.SetFrameRate(0); // 会被钳到 1
const int realFps = window.frameRate(); // 读回来才是真的
传 0 会被钳到 1,一秒才画一帧。所以设置完要按读回来的值排帧,别按你传进去的值。另外,帧率只影响顺滑度,不影响这段动画跑多久。
十一、动手:四个小练习
看完不如写一遍。建议按这个顺序:
- 两个入口各跑一次,感受控制台的区别;
- 把尺寸改成
800 × 600,把客户区和客户区原点打印出来,看看差多少像素; - 加三个按钮,分别做最小化 / 最大化 / 置顶;
- 把关闭按钮禁掉,用自己画的按钮去关。
这四个练完,这一集的接口就真在你手里了。
剩下的函数不一个个演示,文档里都有——Releases 下 ZekitGuide 就能离线翻,2,749 页都在那个 exe 里:
渲染、驱动模式、帧率这三块的细节,第 5 篇会再展开一次。
十二、复盘:一个窗口,四类接口
- 入口:
ZEKIT_APP_ENTRY,编出来没有控制台黑框 - 动作:
Show/Hide/Close/exec - 几何:客户区、外框、工作区三套坐标
- 外观:状态、尺寸约束、标题栏、图标
再加两条本集埋下的纪律:
UseRenderer只能紧跟构造,迟一步就静默回退;SetTimeout单位是毫秒,不是秒。
下一篇进入控件:控件基类三件套——Widget、BoxWidget、TextWidget,以及为什么 Panel 是最推荐的基类。