DEV Community

泽
泽

Posted on

Creating your first window with Zekit: entry points, three coordinate systems, and one ordering trap

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();
}
Enter fullscreen mode Exit fullscreen mode

Two headers, two jobs: Zekit.h for the window, ZekitApp.h for the entry point.

  • SetTitle takes 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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Call exec() once per process.
  2. Don't mix it with PollEvents — those are two loops competing for the same job.
  3. 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();
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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();
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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();
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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();
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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

  1. Run both entry macros and compare the console behaviour.
  2. Set 800 × 600, print the client size and client origin, and count the pixels of chrome.
  3. Add three buttons for minimize / maximize / topmost.
  4. 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)