Library

The GUI floor

The native windowing layer that the Dagon GUI framework is built on; a capability floor, not a public API.

since 0.1.0-alpha.1linux

Description

Desktop windows are provided to programs by a GUI floor: a small set of native functions in namespace std whose names start with sysGui. It is the language-side half of Dagon, the desktop GUI framework. Like the rest of the native floor (see lang.system-floor), it is an implementation detail and not an API for programs: its functions are hidden from the library documentation, and Dagon is the interface to use. Write windows, layout and widgets with Dagon; see the dagon package.

The floor is a curated set of capabilities, not a binding to a graphics library. A third-party library (SDL3 and its font library) is an implementation detail behind capability names, in the same way TLS hides OpenSSL (see lang.tls). The shape that follows from that is what a GUI program author may notice:

• Frames are submitted in batches. A frame of drawing is a block of integer words plus a parallel list of strings, replayed by a single native call, so the number of native calls per frame does not grow with the number of drawing operations. No C structure ever crosses the boundary.
• Input is drained in batches. Pending input events are read into a caller-owned block as fixed-size records by one call that never blocks.
• Handles are integers and are never reused. A window, font or texture handle is a positive integer. Once a handle has been closed it stays invalid forever, so a stale handle throws instead of silently pointing at a newer object.
• Main task only. Every GUI call must happen on the program's main task and throws anywhere else. GUI handles must not be passed to workers or through channels.
• Logical pixels. Geometry is in whole logical pixels; the floor applies the window's display scale when it draws.
• A malformed batch is rejected whole. The first invalid word aborts the submit with its position, and nothing is drawn.
• Two capability probes never throw: one reports whether a GUI is available at all (0 means yes, 1 the runtime was built without GUI support, 2 initialization failed, 3 there is no video driver), and one reports the system's light or dark theme preference. They are how a program decides whether to open a window.

The GUI shares the event loop. While a window exists the loop wakes every few milliseconds to service the windowing system, and there is no second loop. Events stay in the windowing system's queue until the program drains them.

Rules

• Use Dagon, not the sysGui* functions, in application code.
• A runtime built without GUI support is a supported configuration; every GUI call then fails with GUI floor not available: ..., and only the probes keep working.
• Every sysGui* function is denied in comptime code.
• The GUI floor is rejected when building for the browser target.
• Windows, fonts, textures, dialogs, the clipboard and text input are all reached through the same floor; their details belong to Dagon's documentation.

Examples

A program checks the capability probe before it creates a window; Dagon does this for you:

int status = std::sysGuiAvailable();
if (status == 0) {
    console.writeln("a GUI is available");
} else {
    console.writeln("no GUI, reason code ${status}");
}

Notes

Dagon is documented with the rest of the package libraries.

See also

• App