十一行跑出一个窗口:C++ 桌面 GUI 的入口、坐标与消息循环

0 阅读11分钟

上一篇把库编出来、接进了 VS 工程。这一篇开始写代码:先把一个窗口弄到屏幕上,然后把它身上那一圈接口过一遍——入口、显示与关闭、几何、状态、外观,最后是渲染后端和驱动模式。

十一行就能跑起来。但真正会让界面偏几十像素、让后端静默回退的坑,都在后面几节。

视频版:【C++ 桌面 GUI Zekit:单静态库,内置 D3D12 / Vulkan / OpenGL 渲染后端】P3 第一个窗口

源码:GitHub | Gitee


一、最小骨架:十一行

#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() 就返回,程序继续往下走、然后结束。这一句之后程序不再往下走,它在等消息。

三条纪律:

  1. 一个进程只调一次 exec()。
  2. 不要跟 PollEvents 混着用——那是两个循环在抢同一件事。
  3. 后面所有的演示,全都包在这一个 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,一秒才画一帧。所以设置完要按读回来的值排帧,别按你传进去的值。另外,帧率只影响顺滑度,不影响这段动画跑多久。


十一、动手:四个小练习

看完不如写一遍。建议按这个顺序:

  1. 两个入口各跑一次,感受控制台的区别;
  2. 把尺寸改成 800 × 600,把客户区和客户区原点打印出来,看看差多少像素;
  3. 加三个按钮,分别做最小化 / 最大化 / 置顶;
  4. 把关闭按钮禁掉,用自己画的按钮去关。

这四个练完,这一集的接口就真在你手里了。

剩下的函数不一个个演示,文档里都有——Releases 下 ZekitGuide 就能离线翻,2,749 页都在那个 exe 里:

github.com/Z-ze489/Zek…

渲染、驱动模式、帧率这三块的细节,第 5 篇会再展开一次。


十二、复盘:一个窗口,四类接口

  • 入口:ZEKIT_APP_ENTRY,编出来没有控制台黑框
  • 动作:Show / Hide / Close / exec
  • 几何:客户区、外框、工作区三套坐标
  • 外观:状态、尺寸约束、标题栏、图标

再加两条本集埋下的纪律:

  • UseRenderer 只能紧跟构造,迟一步就静默回退;
  • SetTimeout 单位是毫秒,不是秒。

下一篇进入控件:控件基类三件套——Widget、BoxWidget、TextWidget,以及为什么 Panel 是最推荐的基类。