Skip to content

windows-window.md

Latest commit

 

History

History
128 lines (103 loc) · 6.33 KB

windows-window.md

File metadata and controls

128 lines (103 loc) · 6.33 KB
Raw

windows-window

Minimal window creation and message-loop support for hosting graphics and other content against a raw HWND.

windows-window provides just enough Win32 windowing to open a top-level window and run a message loop, so crates and samples that need a host window — windows-canvas swap chains, WebView2 controllers, Direct2D/Direct3D rendering — don't have to depend on the full windows crate or hand-roll a windows-bindgen build script.

It is intentionally small: a Window with an optional message handler and resize callback, plus run, run_with, and quit. All Win32 details are private; you work with a safe Window and the raw HWND it exposes for interop.

Getting started

use windows_window::*;

let window = Window::new("Hello")
    .size(800, 600)
    .on_resize(|width, height| {
        // forward the new client size to your renderer
    })
    .create()?;

// Hand window.hwnd() to windows-canvas, WebView2, Direct2D, etc.
let hwnd = window.hwnd();

run(); // blocking, event-driven message loop

The API

  • Window::new(title) returns a WindowBuilder. Configure it with .size(width, height), .style(..), .ex_style(..), .on_message(..), and .on_resize(..), then .create() to open and show the window.
  • Window::hwnd() returns the raw *mut c_void handle for interop.
  • Window::client_size() returns the current client area as (width, height).
  • style(WS_*) / ex_style(WS_EX_*) override the window styles (raw u32). They default to WS_OVERLAPPEDWINDOW and none — pass Win32 style constants for custom chrome (e.g. WS_EX_NOREDIRECTIONBITMAP for a DirectComposition target).
  • on_message(|hwnd, message, wparam, lparam| -> Option<isize>) handles raw window messages; return Some(result) to handle a message or None to fall through to default processing.
  • on_resize(|width, height|) is a convenience for WM_SIZE, giving the new client size in pixels.

Handlers are detached while they run, so a handler that triggers reentrant dispatch (for example calling SetWindowPos, which synchronously sends WM_WINDOWPOSCHANGING / WM_SIZE) won't re-enter itself — the nested messages fall through to default processing. This keeps shared state behind an Rc<RefCell<..>> safe from reentrant borrows.

The message loop

  • run() — a blocking, event-driven loop (GetMessage) until the window closes. Best for interactive apps such as a WebView2 host.
  • run_with(render) — calls render whenever the queue is empty; render returns Ok(true) to keep rendering immediately (continuous animation) or Ok(false) to wait for the next message (event-driven/occluded). Returns Ok(()) when the window closes, or early if render returns an error.
  • quit() — posts a quit message. An unhandled WM_DESTROY posts one automatically, so closing the window ends the loop without extra code.
  • pump() — dispatches all currently-pending messages without blocking and returns false if a quit was received. Lets a caller drive the loop while waiting on an external condition, such as pumping until an asynchronous callback completes.

Samples

  • create_window the minimal case — open a window and pump messages with run_with, depending only on windows-window (no windows crate).
  • window_message handles raw messages (WM_PAINT, mouse, keyboard) via on_message, with direct access to wparam/lparam.
  • canvas/standalone hosts a windows-canvas swap chain in a windows-window window driven by run_with.
  • windows/direct2d drives a Direct2D swap chain with run_with, rendering only while visible.
  • windows/direct3d12 binds a Direct3D 12 swap chain to window.hwnd() and renders on WM_PAINT.
  • windows/dcomp hosts a DirectComposition target (custom ex_style) and pumps with run, relying on reentrancy-safe handlers for its DPI handling.

Internal documentation

The remainder of this page covers how the crate is built and maintained. It is for contributors and is not needed to use windows-window.

How it's built

src/bindings.rs is generated by tool_bindings from crates/tools/bindings/src/window.txt — minimal, flat bindings for the RegisterClassW / CreateWindowExW / message-pump surface plus the handful of structs and constants they need. Everything in window.rs (the Window, WindowBuilder, and the message loop) is hand-written over those bindings and depends only on windows-core, so the crate stays fast to build.

Design

  • One window class — a single process-wide window class is registered lazily; all windows share it and route messages through one wndproc.
  • State in GWLP_USERDATA — the boxed message/resize handlers are stored in the window's user data, set after CreateWindowExW returns, and reclaimed on WM_NCDESTROY. Window::drop calls DestroyWindow if the window still exists.
  • Reentrancy-safe — wndproc moves the handlers out of the state before invoking them and restores them afterward, so a handler that pumps nested messages can't alias (or, behind RefCell, panic on re-borrowing) itself.
  • Not a kitchen sink — the crate covers window creation, a resize hook, and a message loop only. Anything beyond that (menus, input, multiple monitors, etc.) belongs in the consuming app or a focused windows-bindgen binding.

Testing

cargo check -p windows-window and cargo clippy -p windows-window --all-targets. The canvas/standalone sample exercises it end to end.