Skip to content

Window

Generated from engine/app/window.h at 0f4f503. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.

Browse the app module

Audience: game code.

#include "engine/app/window.h" · namespace labrador

What a window has to tell whoever owns it. Modelled on DeviceNotify (engine/render/renderer.h) and const-qualified the same way: a handler that only reads the world is const, and one that changes it is not.

THE ACTIVATION FOUR ARE ON THE CHANGING SIDE, because they carry the news into the state stack, where a game's own code runs and may push, pop or transition. Fanning that out from a const handler would compile - the states hang off unique_ptrs, whose constness is one level deep - which is the reason the signature says so rather than leaning on it.

virtual void tick() = 0;

The frame. It is not a window event - it is what the loop does when there is nothing else to do. On Windows that is an empty queue, and WM_PAINT needs it too: while the user drags an edge Windows owns the loop, and painting is the only way back in. In a browser it is the animation-frame callback, which is the only loop there is.

on_activated · on_deactivated · on_suspending · on_resuming

Section titled “on_activated · on_deactivated · on_suspending · on_resuming”
virtual void on_activated() = 0;
virtual void on_deactivated() = 0;
virtual void on_suspending() = 0;
virtual void on_resuming() = 0;
virtual void on_keyboard_gained();
virtual void on_keyboard_lost();

THE KEYBOARD, WHERE IT IS NOT THE FOREGROUND. A Win32 window has the keyboard exactly while it is active, so it never calls these. A canvas is one element of a page, and a click beside it takes the keyboard while the player is still looking at the game, perhaps with a pad in their hands: the keys held are released, as a lost foreground releases them, and nothing else is meant - the pads stay live and no state is told.

virtual void on_fullscreen_changed([[maybe_unused]] bool fullscreen);

Whether the window is full screen now, said when the platform decided it rather than the caller: a player leaving with Escape, or a request refused. A Win32 window changes it only when asked, and so never calls this.

virtual void on_closed();

AFTER A BROWSER WINDOW HAS CLOSED, by a quit or an exception it caught, on a later task of the page's, once the update or handler that closed it has unwound. An owner in a browser outlives main and nothing destroys it, so this is where it lets go of what its destructor would: until it does, every listener and context it holds keeps the whole module alive. The page has already been told. A Win32 window's owner is destroyed after its pump returns, and that window never calls this.

virtual void on_window_moved() const = 0;
virtual void on_window_size_changed(int width, int height) = 0;
virtual void on_key_down(Key key) const = 0;
virtual void on_key_up(Key key) const = 0;
virtual void on_text(char32_t codepoint) const = 0;

THE KEYBOARD, THE MOUSE AND TOUCH, and they are here rather than behind a reader in engine/input/ because there is nowhere else they could be. A pad is polled: input/xinput/ asks XInput for a snapshot and owes this file nothing. These three arrive as messages in this window's queue, or as events on its canvas, so the only way into the input module is out through here - which is the whole reason input is fed rather than read, and the reason nothing in it names a window (keyboard.h says it at length).

const, like on_window_moved and for the same reason: they change nothing about the window, and everything they do reach is borrowed and fed rather than asked anything.

Already translated, both directions. Key and MouseButton are the engine's own names, decided by the window's implementation from the platform's codes, and codepoint is UTF-32 with any surrogate pair already assembled. Nothing above this line meets a VK_ constant, a KeyboardEvent.code string or a UTF-16 unit - message translation lives in the window, and that is the whole of the job this class exists to hand over.

On Windows, F10 and Alt pressed alone are keys and nothing else; Alt+F4 and Alt+Space reach the game and still close the window and open its system menu. In a browser the function keys and the Alt chords reach the game and keep their browser defaults.

on_mouse_move · on_mouse_button_down · on_mouse_button_up

Section titled “on_mouse_move · on_mouse_button_down · on_mouse_button_up”
virtual void on_mouse_move(int x, int y) const = 0;
virtual void on_mouse_button_down(MouseButton button) const = 0;
virtual void on_mouse_button_up(MouseButton button) const = 0;
virtual void on_mouse_capture_lost() const;

Cancel any held gesture without treating capture transfer as release.

on_mouse_wheel · on_mouse_wheel_horizontal

Section titled “on_mouse_wheel · on_mouse_wheel_horizontal”
virtual void on_mouse_wheel(float notches) const = 0;
virtual void on_mouse_wheel_horizontal(float notches) const = 0;

Notches, signed, fractional on a high-resolution wheel. Two functions rather than one with an axis flag, because a caller reading on_mouse_wheel(delta, true) cannot tell which way true points without looking it up (T4).

on_touch_down · on_touch_move · on_touch_up · on_touch_cancel

Section titled “on_touch_down · on_touch_move · on_touch_up · on_touch_cancel”
virtual void on_touch_down(uint32_t point, int x, int y) const = 0;
virtual void on_touch_move(uint32_t point, int x, int y) const = 0;
virtual void on_touch_up(uint32_t point, int x, int y) const = 0;
virtual void on_touch_cancel(uint32_t point) const = 0;

A FINGER ON THE GLASS, one call per thing it did. point is the platform's id for the contact - a Win32 pointer id or a DOM pointerId - and is stable from down to up or cancel, and engine/input/touch.h maps it onto ids of the engine's own. The position is client pixels, as on_mouse_move's is.

A pen and a mouse are not touch and do not arrive here: both stay the mouse. And a touch does not arrive at the mouse as well, which both platforms would otherwise arrange by synthesising mouse input from it - the window drops that, so one tap is one input.

Cancel is a point the platform took away rather than one the player lifted: a gesture the system claimed, or a capture lost. It carries no position because nothing about where it ended means anything.

~WindowNotify() = default;

What the window needs to exist. The names are ApplicationOptions' names on purpose: this is the subset of them a window can act on, and nothing about their meaning changes on the way across.

std::wstring window_class_name = L"LabradorWindowClass";
std::wstring window_title = L"Labrador";

Unique per process, so a game that ever opens two windows needs two. A browser has neither a window class nor a title of the game's - the page owns both - so neither is read there.

Vector2I client_size;

CLIENT pixels - the area the game draws into, not the outer rect. Turning one into the other is this class's job and nobody else's, at the DPI its frame is drawn at, which under per-monitor awareness v2 is the window's own, and a DPI change keeps it.

bool fullscreen = false;
bool visible = true;

Whether the window is shown at all. A hidden window still has a client area, a device still draws into it and its messages still arrive, which is what a smoke test or a capture tool wants: a whole shell that puts nothing on screen and takes no focus. The engine never shows a window created hidden; a window shown by other means is outside this contract. A browser shows whatever the page shows, so it is not read there.

bool cursor_visible = true;
bool cursor_confined = false;

The pointer over the client area: whether it is drawn, and whether it is kept inside (Window::set_cursor_visible, set_cursor_confined).

int min_window_width = 320;
int min_window_height = 200;
class Window

The platform's window: a Win32 window on Windows (engine/app/win32/) and the page's canvas in a browser (engine/app/web/). Exactly one is compiled, chosen by the platform being built for rather than by a cache variable, because neither half can be built for the other's platform.

THIS HEADER IS NEUTRAL AND THE PLATFORM IS BEHIND Impl, which is the shape GamepadReader and ThreadPool have and for a reason that is not taste: application.h includes this file, and check_engine_includes.cmake fails the build for any file outside a platform folder that includes a header inside one. A window.h in app/win32/ would make application.h a platform header. What the pointer costs is one hop on a path that runs once per message.

WHAT IS DELIBERATELY NOT HERE: the handlers themselves. They stay on Application and arrive through WindowNotify, because message translation lives here and what a message means does not.

Nothing forces it. No handler here ends below the seam, so a Window taking these messages would not have to include a backend - which makes this a judgement about layering and nothing else: the better reason to keep them where they are, and a worse one to move them.

Window(const WindowOptions& options, WindowNotify* notify);

Creates the window, or takes the page's canvas, and shows it. Throws std::runtime_error naming the step that failed (T6).

notify is taken here rather than set afterwards, and that is a contract rather than a preference: the first size report arrives before this constructor returns, and it is load-bearing - it is what corrects the caller to the client size the window really got. On Windows that is the WM_SIZE ShowWindow fires, and it matters most going full screen at launch, where the monitor decides the size and nothing here knows it. In a browser it is the canvas, measured here, because the page laid it out and nothing here chose its size. A notify set after construction would miss it, and the owner would never learn the size it got. A canvas that does not have the keyboard when it is taken says so here too, with on_keyboard_lost, and a full-screen request refused on the spot with on_fullscreen_changed.

A WINDOW CREATED HIDDEN IS THE EXCEPTION ON WINDOWS, because it is never shown. A full-screen one reports the size it asked for, not the monitor's, and a windowed one makes no report at all. Either has the client size it asked for, unless that is below the smallest window the system allows.

~Window();

Takes down what the constructor made, on every path out - not only the one where the loop ended.

THE LOOP IS NOT THE ONLY WAY OUT of the scope that owns a Window. create_device throwing, a manifest that does not open, a state's update() throwing out of tick(): each unwinds the owner while the window still exists, and a window left behind would go on calling into an object that is gone.

notify is never called from in here. Whatever the platform says while the window is taken down arrives after the owner has started destroying itself - in Application's case with the renderer and the input devices already gone - so none of it is forwarded, and nothing is left queued that would end a message loop run afterwards.

Window(const Window&) = delete;
Window& operator=(const Window&) = delete;
void* handle() const;

The native window, as Renderer::create_device takes it: an HWND on Windows, and in a browser the canvas's event target as Emscripten's html5 functions name it, which is a C string.

Null once the window is gone, whether close() took it or the user did. Nothing that reaches a stale handle is a valid call, and a caller holding one after run() has returned would be making one.

int exit_code() const;

The process exit code, valid once pump_until_quit has returned.

void pump_until_quit();

Runs the frame loop until the window closes, calling notify->tick() once per frame.

Browser hosts supply Module.canvas before starting the game and keep it attached until the game quits. Removing it does not stop frames, release the WebGL2 context or unregister window listeners. Optional page callbacks are Module.onQuit(), Module.onError(message), Module.onContextLost() and Module.onContextRestored(). See the [page contract](https://labradorengine.com/docs/guides/browser/#the-page-and-what-it-owes-the-module) for their arguments, timing and the canvas's lifetime.

On Windows: one message if one is waiting, and otherwise tick(). Ticking only on an empty queue is the loop, not an implementation detail of it - draining the queue first is a defensible design and a different one, and it changes frame pacing. An exception out of tick() or out of a handler comes out of this call.

IN A BROWSER THIS CALL DOES NOT RETURN, and the stack below it does not survive it. The loop is the browser's: tick() runs once per animation frame, after control has gone back to the page, and Emscripten gets there by throwing through every frame between here and main - which runs their destructors before the first tick. So nothing tick() reaches may live on that stack; Application::run says what that means for a game. And with no caller left to throw to, an exception out of tick() or out of a handler ends the loop the way close() does and is reported instead: to stderr, and to the page's Module.onError if it supplied one.

void close() const;

Ends the loop. A game asking to exit does not need to know which platform it is on, so this is the whole of the quit path.

On Windows it destroys the window, which ends the pump. In a browser it cancels the frame loop, stops listening to the canvas and calls the page's Module.onQuit if it supplied one, because the page is what decides what a finished game looks like. A second call, or a call after the window has already gone, does nothing.

void resize_client(const Vector2I& client_size) const;

Resizes so client_size pixels are left to draw into, under whatever frame the window is currently wearing, and reports what it actually got - a size past the monitor's comes back clamped. On Windows this does not show or activate the window.

In a browser the page lays the canvas out and the drawing buffer follows that box, so there is nothing to ask for. The report is still made, of the size the canvas already has, because it is the report that corrects the caller (Application::set_resolution).

void enter_fullscreen() const;
void leave_fullscreen(const Vector2I& client_size) const;

Borderless and monitor-sized, and back again at client_size.

On Windows a hidden window stays hidden and inactive through both, and is given the size a shown one would be, or std::runtime_error is thrown if the size of its monitor cannot be read.

In a browser, the Fullscreen API on the canvas. A browser grants it only inside an input event, so a request made from a frame waits for the next key or button event and is made there. The browser has the last word either way - it may refuse, and the player may leave with Escape - and on_fullscreen_changed reports what it decided.

void set_cursor_visible(bool visible) const;

Whether the pointer is drawn while it is over the client area. A game played with a pad hides it. The mouse is read either way: a hidden pointer still moves, clicks and reports where it is.

Over anything else - the frame, the caption, the rest of a page - the pointer is the platform's. On Windows a change shows at once if the pointer is over the client area; in a browser it is the canvas's CSS cursor.

void set_cursor_confined(bool confined) const;

Whether the pointer is kept inside the client area.

On Windows the pointer is clipped to the client area while the window is active, shown and not minimised, and released while it is not and while the player moves or sizes it, so the frame and Alt+Tab are never trapped. The clip follows the client area through a move, a resize and full screen.

A BROWSER CANNOT CONFINE A POINTER, only lock it, which hides it and reports motion rather than a position. That is another mode with another contract, so this does nothing there.

Named in the public declarations above: Key, MouseButton, Vector2I.

The files that include this header directly. A file can also reach it through another header.

Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.

All documentation versions