Zekit is a C++20 desktop GUI toolkit that compiles to a single static library. Getting a window on screen takes eleven lines, and none of them are platform code.
This post walks the whole surface of a Kit::Window: the entry point, the event loop, geometry, size constraints, and the one ordering rule that will silently break your renderer choice if you get it wrong.
The eleven-line program
#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();
}
Two headers, two jobs: Zekit.h for the window, ZekitApp.h for the entry point.
-
SetTitletakes UTF-8, so non-ASCII text goes in directly. -
SetSize(1000, 700)sets the client area, not the outer frame. That distinction matters below. -
Show()makes it visible. -
exec()enters the message loop.
No window class registration, no CreateWindow, no hand-written message pump.
Three ways to enter the program
| Form | Subsystem | Console window |
|---|---|---|
ZEKIT_APP_ENTRY(name) |
Windows subsystem | none |
ZEKIT_APP_ENTRY_CONSOLE(name) |
console subsystem | yes — use this when you want printf
|
int main() |
C++ default | yes |
ZEKIT_APP_ENTRY sets the subsystem at link time, which is why double-clicking the executable doesn't flash a console.
One thing that confuses people: seeing a console while debugging in Visual Studio does not mean the macro failed. The project's subsystem setting overrides the macro, and VS defaults to console. The program's own behaviour is unaffected.
What exec() actually does
window.Show();
return window.exec(); // the program stops here
exec() runs the message loop and blocks until the last window closes. Call Close() and it returns, the program continues, and then exits.
Three rules:
- Call
exec()once per process. - Don't mix it with
PollEvents— those are two loops competing for the same job. - Everything below happens inside that single
exec().
Adding a button
#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("Close"));
closeButton.SetGeometry(50, 50, 120, 60);
closeButton.SetOnClick([&window]() {
window.Close();
});
window.Show();
return window.exec();
}
Read the AddWidget line carefully: the widget is passed by value, and what comes back is a reference to the copy that now lives in the window's tree. Every later call — geometry, callbacks — goes through that reference. You never call new, and you never free anything.
Three coordinate systems
This is where layouts drift by a few dozen pixels, usually on someone else's monitor.
| Space | What it is | Who uses it |
|---|---|---|
| client area | the region inside the title bar and border | all widget coordinates are relative to it |
| outer frame | client area + title bar + borders |
SetPosition takes this one |
| work area | the screen minus the taskbar | bounds for centering and maximizing |
frame width = client width + left border + right border
frame height = client height + title bar + bottom border
So SetSize(1000, 700) produces a window that looks bigger than 1000×700 — the difference is chrome.
And one behaviour to know: after SetSize the window re-centres itself in the current monitor's work area. To change size without moving, follow it with SetPosition.
Reading the client area:
int clientW = 0, clientH = 0;
window.GetClientSize(clientW, clientH); // both are out-parameters
const int w = window.width(); // same pair, shorter
const int h = window.height();
width() and height() return 0 once the window is closed, so check before dividing by them.
Position and bounds:
window.SetPosition(300, 300); // outer frame, top-left
window.adjustSize(); // shrink the client area to fit its content
window.CenterOnScreen(); // centre within the work area
int workX = 0, workY = 0, workW = 0, workH = 0;
const bool hasArea = window.GetScreenWorkArea(workX, workY, workW, workH);
GetScreenWorkArea returns a bool: false on platforms with no screen concept, in which case the out-parameters are meaningless. Don't drop the return value.
The one that surprises people is GetClientOrigin — it returns where the client area's top-left corner sits on screen:
window.SetPosition(300, 300);
int originX = 0, originY = 0;
window.GetClientOrigin(originX, originY);
On my machine the frame is at (300, 300) and the client origin is offset by 11 × 45 — that's the border and title bar, and the numbers change with display scaling and the visual theme. The reason to care is cross-window math:
screen = origin_A + coord_in_A
= origin_B + coord_in_B
Anything that aligns two windows, or tears a panel off into its own window and docks it back, needs this point.
Window state and actions
| Call | Effect |
|---|---|
Minimize() / Maximize() / Restore()
|
standard window states |
SetTopmost(true) |
always on top, without stealing focus |
RequestRedraw() |
ask for one frame |
SetTimeout(ms, fn) |
run a function later |
SetTopmost not stealing focus is the detail that makes it usable for tool palettes — otherwise every time you pin a panel, the input field you were typing in loses keystrokes.
RequestRedraw exists because of segment caching: if you change something and nothing schedules a frame, the cached vertices get reused and your change never appears.
SetTimeout takes milliseconds
1500 → 1.5 seconds
1.5 → 1 millisecond (looks like nothing happened)
It returns a timer id, calling it again from inside the callback gives you a loop, and timers die with the window.
Size constraints: three calls, three different scopes
window.SetMinimumSize(400, 400); // dragging stops at 400
window.SetMaximumSize(1100, 800); // growing stops at 1100 × 800
window.SetResizable(false); // borders locked, maximize button greyed out
Both limits apply to the client area, and (0, 0) removes them. But they don't cover the same ground:
| Call | Blocks user resize | Clamps SetSize
|
Affects maximize |
|---|---|---|---|
SetMinimumSize |
yes | yes | no |
SetMaximumSize |
yes | yes | no |
SetResizable(false) |
yes | no — SetSize still works |
button disabled |
Which means a fixed-size dialog is not "set a maximum":
window.SetResizable(false);
window.SetMinimumSize(760, 520);
window.SetMaximumSize(760, 520); // equal bounds = pinned
Four similar-sounding calls, four different questions:
| Call | Answers |
|---|---|
SetSize |
how big is it now (clamped by the limits) |
SetMinimum/MaximumSize |
how big is it allowed to be |
adjustSize |
how big does the content need |
SetPosition |
where does it sit |
Title bar and icon
window.SetTitleBarVisible(false); // bar gone, border stays
window.SetMinimizeButtonEnabled(false);
window.SetMaximizeButtonEnabled(false);
window.SetCloseButtonEnabled(false); // only code can close it now
window.SetWindowIcon("app.ico"); // ico / png / jpg / bmp
SetTitleBarVisible(false) removes the title and the three buttons but keeps the resize border — that is not the same thing as a borderless window.
SetCloseButtonEnabled(false) is useful for "confirm before exit" flows without intercepting window messages.
SetWindowIcon takes a file path; no manual decoding needed, and the path is UTF-8.
The ordering trap: UseRenderer must come first
Kit::Window window;
window.UseRenderer(Rhi::Api::OpenGL); // must be the first call after construction
window.SetTitle("Zekit");
window.SetSize(920, 600);
window.Show();
return window.exec();
UseRenderer has to run before SetSize, SetPosition, AddWidget and Show. Those calls let the default backend claim the window — D3D12 creates a swapchain, OpenGL sets a pixel format — and that claim is irreversible. A later call returns false and silently falls back.
Silently is the problem: nothing crashes, nothing warns, and the program runs on a backend you didn't ask for.
The only legal order:
construct → UseRenderer → SetTitle / SetSize → AddWidget → Show
Adding widgets and then switching backends fails the same way. UseExternalRenderer follows the same rule — before the first paint.
To check what you actually got:
| Call | Meaning |
|---|---|
rendererApi |
the backend that is really running (post-fallback) |
gpuPreference |
what you asked for |
deviceInfo |
the adapter you actually got |
Intent versus fact. When frame timings look wrong, read rendererApi first.
Drive modes: who decides to draw the next frame
| Mode | Behaviour |
|---|---|
EventDriven |
draw on demand, zero CPU when idle (default) |
OnDemand |
run at frame rate while something is animating, then stop |
Immediate |
run at frame rate unconditionally |
window.SetDriveMode(Kit::Window::DriveMode::OnDemand);
const auto mode = window.driveMode();
const int fps = window.frameRate();
Set the mode before exec(); changing it later only affects the next round.
OnDemand saves power because a custom widget decides whether to renew the animation contract:
bool wantsAnimationFrame() const override {
return running_; // true → keep scheduling; false → sleep
}
And a small trap: SetFrameRate(0) is clamped to 1, so you get one frame per second. Read the value back instead of trusting what you passed in.
Four exercises
- Run both entry macros and compare the console behaviour.
- Set
800 × 600, print the client size and client origin, and count the pixels of chrome. - Add three buttons for minimize / maximize / topmost.
- Disable the close button and close the window from your own button instead.
Those four cover the whole surface. Source and docs: https://github.com/Z-ze489/Zekit.
Top comments (0)