std/window opens desktop windows whose drawing areas are
std/graphics canvases. A program opens as many windows as it
needs, such as a main window, dialogs and tool windows, and reads the events
of all of them in one ordinary loop, so there are no callbacks to register.
It uses only what each operating system ships, so there is nothing to
install and no build flag to set:
| System | Window system | Linked |
|---|---|---|
| Linux (x86-64, AArch64) | The X11 protocol, spoken directly over the display socket | libc only |
| macOS (Apple silicon, Intel) | AppKit through the Objective-C runtime | AppKit, QuartzCore, CoreGraphics |
| Windows (x64) | Win32 | user32, gdi32 |
Drawing happens on the CPU, as everywhere in std/graphics, and the window
system only shows the result. A GPU can draw into a window too: Vulkan,
OpenGL and Metal present straight into it through its
native handle. Wayland desktops run these programs
through XWayland, which they provide by default.
Quickstart
Save this as hello_window.dodo:
package main
import "std/graphics"
import "std/graphics/font"
import "std/window"
fn run() -> void!window.Error {
app := window.App.new()?
win := app.open(window.Options.new("Hello", 480, 240))?
// 2 on a Retina display, whose canvas has twice the pixels per side.
scale := win.scale()
label := font.medium().scaled(scale)
for {
canvas := win.canvas()
canvas.clear(graphics.hex(0x1d2330))
canvas.fill_circle(60 * scale as i32, 60 * scale as i32, 30 * scale, graphics.hex(0xe5c07b))
canvas.text(&label, 20 * scale as i32, 120 * scale as i32, "Press Escape to quit", graphics.WHITE)
dirty := canvas.take_dirty()
win.update(dirty)?
match app.wait_event()? {
window.Event.Close(_) | window.Event.Quit => {
return ok()
}
window.Event.Key(_, key) => {
if key.key == window.Key.Escape {
return ok()
}
}
_ => {}
}
}
}
fn main() -> i32 {
match run() {
ok() => {
return 0
}
err(_) => {
return 1
}
}
}
dodo run hello_window.dodo
A 480x240 window titled “Hello” opens with a yellow disk and a line of text. It closes, and the program exits 0, when you press Escape, click the window’s close button or press Command-Q on macOS. Exit 1 means no window could be opened, for example because the program runs over SSH without X forwarding.
The program redraws after every event. Programs that animate ask for Frame
events instead, which say when the next frame is due;
examples/window.dodo in the repository is a bouncing ball that does.
Apps and windows
A window.App is the program’s connection to the window system and the
event loop of every window opened on it. A process has one App at a time:
App.new() fails with AlreadyOpen while another exists. app.open(options)
opens a window and returns a Window, which draws on its own and does not
borrow the App, so windows can be kept in variables and structs freely.
| Call | Does |
|---|---|
window.App.new() |
Connects to the window system. |
app.open(options) |
Opens and shows a window. |
app.wait_event() |
Waits for the next event of any window. |
app.poll_event() |
The next event if one is pending, else none; never waits. |
app.wait_event_timeout(ms) |
Waits at most ms milliseconds; none when the time passes first. |
app.set_clipboard_text(text), app.clipboard_text() |
Copy text to the system clipboard, or read what it holds; see Clipboard. |
app.close() |
Closes every window and the connection; dropping the App does the same. |
Each Window owns a pixel buffer exactly the size of its drawing area.
| Call | Does |
|---|---|
win.id() |
The WindowId its events carry. |
win.canvas() |
Lends the buffer out as a graphics.Canvas in Bgra8888. It keeps its contents between frames. |
win.update(dirty) |
Shows the dirty part of the buffer, usually what canvas.take_dirty() returned. |
win.update_all() |
Shows the whole buffer. |
win.request_frame() |
Asks for one Frame event when it is time to draw the next frame. |
win.frame_interval() |
The display’s refresh period as a time.Duration, such as 16.7 ms at 60 Hz. |
win.set_title(title) |
Changes the title. |
win.set_cursor(cursor), win.set_cursor_visible(visible) |
Choose the pointer shape over the window, or hide the pointer; see Cursor shapes. |
win.set_size(width, height), win.set_min_size(..), win.set_max_size(..) |
Resize the window from code and limit the sizes the user can give it; see Size, limits and fullscreen. |
win.set_fullscreen(on), win.is_fullscreen() |
Cover the whole screen, or return to the window. |
win.close() |
Closes the window; dropping it does the same. |
Drawing changes nothing on screen until update. After a Resize event,
the next canvas() has the new size and keeps the old picture in its
top-left corner; the buffer is only ever replaced inside the window’s own
calls, never while a canvas borrows it.
A window closed by close(), or left over after its App closed, fails with
Closed, reports a size of 0 by 0 and lends out an empty canvas.
Several windows
Every event names its window: each variant of Event starts with a
WindowId, and window.event_window(&event) reads it from any event. Compare
it with win.id() to route the event, or match it in a pattern. Ids are
never reused within a process, so a late event of a window you closed cannot
be mistaken for one of a newer window.
app := window.App.new()?
main := app.open(window.Options.new("Main", 640, 480))?
tools := app.open(window.Options { title: "Tools", width: 160, height: 320, resizable: false, pixel_buffer: true })?
for {
event := app.wait_event()?
from_tools := window.event_window(&event) == tools.id()
match event {
window.Event.Close(id) => {
if id == main.id() {
return ok()
}
tools.close()
}
window.Event.MouseButton(_, button) => {
if from_tools {
// ... pick a tool ...
} else {
// ... use it on the main window ...
}
}
_ => {}
}
}
Open a dialog by calling app.open when it is needed and close it, or let
it drop, when it is done; the other windows keep running meanwhile. The
first window appears where the system places new windows, centered on
macOS; later ones cascade from it. examples/window_palette.dodo paints on
one window with colors picked in a second.
Animation
An animation draws once per display refresh. win.request_frame() asks for
one Frame event; the loop draws when it arrives and asks again:
win.request_frame()?
for {
match app.wait_event()? {
window.Event.Close(_) | window.Event.Quit => {
return ok()
}
window.Event.Frame(_) => {
canvas := win.canvas()
// ... draw the next frame ...
dirty := canvas.take_dirty()
win.update(dirty)?
win.request_frame()?
}
_ => {
// ... handle the event ...
}
}
}
Frames come frame_interval() apart, at a fixed pace however many events
arrive: moving the mouse over the window does not hold frames back, because
a frame that is due comes before any other event. Where the window system
reports the display’s refreshes, frames follow them (see the platform
notes); elsewhere a timer at the refresh rate keeps the pace. A frame that
takes longer than one refresh skips the refreshes it missed instead of
making the next frames late. A hidden or minimized window, whose display
stops reporting refreshes, still gets a frame every two intervals. Each
window asks for its own frames, so an animated window and a still one, or two
windows on displays with different refresh rates, can share one loop.
Advance animations by frame_interval() per frame, or by the time measured
with std/time, rather than by a fixed step: displays refresh at 60, 120,
144 Hz or more, and the same step per frame would run twice as fast on a
120 Hz display.
Stop asking for frames when there is nothing left to animate, so the program sleeps until the next event.
Drawing into your own canvas
A window also implements the graphics.Display
protocol, so drawing code written against Display for a fake display or an
SPI panel works with a window unchanged:
// The same function draws on a window, a fake display or a panel.
fn show<D: graphics.Display>(display: &mut D, canvas: &mut graphics.Canvas) -> void!graphics.Error {
canvas.clear(graphics.BLACK)
canvas.fill_rect(10, 10, 100, 50, graphics.GREEN)
return graphics.present(display, canvas)
}
show(&mut win, &mut canvas) copies the dirty part of your canvas into the
window’s buffer, converting its pixel format if needed, and shows it. As with
every display, only what lies inside both the canvas’s bounds() and the
window is shown: a canvas the size of win.size() fills the window, while a
smaller one, one placed with set_origin, or
one left over from before a resize updates just the part it covers. On a
high-density display win.size() is larger than the size you opened the
window with. Drawing into win.canvas() avoids the copy and always has the
right size.
Events
Every variant but Quit starts with the WindowId of its window, left out
below.
| Event | Meaning |
|---|---|
Close(id) |
The user asked to close the window: its close button or Alt-F4. The window stays open until you call close() or drop it, so you can still ask whether to save. |
Resize(id, width, height) |
The drawing area has a new size in pixels. The next canvas() has it and keeps the old picture in its top-left corner; redraw and update_all(). |
Focus(id, focused) |
The window gained or lost keyboard focus. |
Key(id, KeyEvent) |
A key went down (pressed), auto-repeated (repeat), or came up, in the focused window. |
Text(id, code_point) |
A character typed through the keyboard layout. |
MouseMove(id, x, y) |
The pointer moved inside the drawing area. |
MouseButton(id, ButtonEvent) |
Left, Middle, Right, Back or Forward went down or up at x, y. |
MouseLeave(id) |
The pointer left the drawing area. |
Scroll(id, dx, dy) |
A wheel or trackpad scrolled; 120 units per wheel notch, positive dy scrolls down. |
Frame(id) |
Time to draw the frame request_frame() asked for. |
Quit |
The user asked the whole application to quit: Command-Q or the Quit menu item on macOS. Other systems close windows one at a time and never send it. |
Coordinates are pixels from the drawing area’s top-left corner. While a button is held, moves keep arriving outside the window, with coordinates that can be negative or beyond the size.
Keys and text
A key and the text it types are separate events. KeyEvent.key names the
physical key by its place on a US keyboard, whatever the layout: Key.W is
the key right of Tab, which types “z” on a French keyboard. That keeps game
controls in place on every layout. Text carries what the layout produced,
for text fields: Shift-2 gives Text(64) (“@”) on a US layout and Text(34)
(") on a German one, after the Key event for Digit2.
Text is reported for printable characters only, not for Enter, Tab,
Backspace or Escape. Shortcut combinations with Control, Alt or the
Command/Windows key type nothing, while AltGr, and Option on macOS, still type
their characters. KeyEvent.modifiers tells which modifier
keys were down; shortcut() is Command on macOS and Control elsewhere.
window.key_name(&key) gives the variant name and window.key_code(&key) a
stable number for saving key bindings.
Size and high-density displays
Options sizes are in the window system’s own units: points on macOS and
pixels at the system scale on Windows. A 480x240 window therefore looks the
same size on every screen. The canvas and all event coordinates are in
physical pixels, which on a Retina display is twice as many in each direction:
win.size() reports 960x480 there.
win.scale_percent() is the ratio in percent (100, 150, 200, …) and
win.scale() the nearest whole factor. Multiply your own sizes by it, and
scale bitmap fonts with font.medium().scaled(win.scale()), to keep them
readable. Nothing is scaled behind your back. X11 has no system-wide scale, so
there both units are pixels and the scale is always 100.
Pass resizable: false in the options to keep the size fixed; otherwise
handle Resize.
Size, limits and fullscreen
A program can change a window’s size itself. set_size and the limits take
the same units as Options. The size the window ends up with always arrives
as a Resize event, in pixels, after which size() and canvas() have it:
win.set_min_size(400, 300)? // the user cannot make it smaller
win.set_max_size(1600, 0)? // at most 1600 wide, any height
win.set_size(800, 600)? // a Resize event follows
win.set_fullscreen(true)? // another Resize, to the screen's size
| Call | Does |
|---|---|
win.set_size(width, height) |
Resizes the drawing area, keeping the window’s top-left corner in place. Also works on windows opened with resizable: false. |
win.set_min_size(width, height) |
The smallest size the user can drag the window to. A smaller window grows to it. |
win.set_max_size(width, height) |
The largest size, also when the window is maximized. A larger window shrinks to it. |
win.set_fullscreen(true) |
Covers the window’s screen, without a title bar or borders. |
win.set_fullscreen(false) |
Returns to the size and place the window had before. |
win.is_fullscreen() |
Whether the window is fullscreen, or on its way there. |
A 0 in a limit leaves that dimension unlimited, so set_max_size(0, 0)
removes the maximum. set_size keeps within the limits. A zero size, a size
above window.MAX_SIZE, or a minimum above the maximum fails with
InvalidInput.
Fullscreen ignores the limits. A set_size while the window is fullscreen
takes effect when it returns to the window. Each system does fullscreen its
own way:
- macOS animates the window into a space of its own, as the green
title-bar button does.
is_fullscreen()follows the user entering or leaving fullscreen with that button too. Calls made during the animation are carried out once it ends. - Windows makes the window a borderless window covering its monitor and restores the old frame and placement afterwards.
- X11 asks the window manager through the
_NET_WM_STATEprotocol that every current desktop supports. Without a window manager, the window moves to the screen’s top-left corner and takes the screen’s size itself.is_fullscreen()reports what the program asked for, even when the user leaves fullscreen with a window-manager shortcut.
Clipboard
The clipboard belongs to the App, since it is shared by the whole program:
app.set_clipboard_text("copied from Dodo")?
pasted := app.clipboard_text()?
editor.insert(pasted.as_str())
clipboard_text() returns a window.ClipboardText that owns its bytes:
as_str() borrows the text, len() is its length in bytes and is_empty()
says whether the clipboard held any text. When the clipboard holds no text,
for example after an image was copied, the result is empty rather than an
error. The text is always valid UTF-8: malformed bytes another program put
on the clipboard read as U+FFFD. Line endings pass through unchanged, so text
copied by Windows programs usually has \r\n line ends.
A typical editor copies on modifiers.shortcut() with Key.C and pastes on
Key.V, which is Command on macOS and Control elsewhere.
X11 has no clipboard service. Copying makes the App the owner of the
CLIPBOARD selection. Programs that paste then ask the App for the text, and
the App answers them from inside wait_event and poll_event, so the event
loop has to keep running. The text stays available until another program
copies something or the App closes. Most desktops run a clipboard manager
that takes a copy, so the text outlives the App there. Pasting asks the
current owner and waits for its answer, at most a second for each part of a
large transfer. Events that arrive meanwhile are kept, in order, for the next
wait_event. A program that never answers reads as an empty clipboard. Text
of any size works both ways, including the incremental transfers (INCR)
that programs use for large texts, and Latin-1 text from programs that offer
only STRING.
Cursor shapes
win.set_cursor(cursor) sets the pointer shown while the pointer is over the
window’s drawing area. Each system draws its own version of each shape:
window.Cursor |
Shows | For |
|---|---|---|
Arrow |
The ordinary arrow; every window starts with it | Everything else |
Text |
An I-beam | Editable or selectable text |
Hand |
A pointing hand | Links and buttons |
Crosshair |
A crosshair | Precise picking, drawing |
Move |
Four arrows; an open hand on macOS | Dragging something around |
ResizeEW, ResizeNS |
Left-right or up-down arrows | Splitters and column edges |
ResizeNWSE, ResizeNESW |
Diagonal arrows | Corner handles |
NotAllowed |
A crossed-out circle; a plain circle on X11 | Drop targets that refuse |
Wait |
A busy indicator | Long operations |
The shape stays until the next call, so a text editor sets Text when the
pointer enters the text area and Arrow when it moves over a toolbar.
set_cursor_visible(false) hides the pointer whatever its shape, and showing
it again brings the shape back.
On X11 the shapes come from the X server’s built-in cursor font, which looks plainer than the themed cursors of current desktops. The arrow is the one the desktop set for its own windows, so it matches the theme.
Drawing with the GPU
A window can be the target of a GPU API instead of, or as well as, a canvas.
win.native_handle() returns the window system’s own objects, which is what
Vulkan, EGL, WGL, NSOpenGL and Metal take to create a surface:
| System | window.NativeHandle |
Use it with |
|---|---|---|
| Linux | Xcb(connection, window, screen, visual): a libxcb connection and the X11 window id |
vkCreateXcbSurfaceKHR, EGL’s XCB platform |
| macOS | AppKit(window, view): the NSWindow and its content NSView |
NSOpenGLContext; win.metal_layer() for Metal and VK_EXT_metal_surface |
| Windows | Win32(hwnd, instance): the HWND and the program’s HINSTANCE |
vkCreateWin32SurfaceKHR, WGL |
Open the window with window.Options.gpu(title, width, height) when only the
GPU draws into it. That window has no pixel buffer: canvas() lends out an
empty 0x0 canvas, update() fails with Unsupported, and nothing is copied
on resize. win.has_pixel_buffer() tells the two kinds apart. Events, frame
pacing with request_frame(), size() and scale() work the same in both,
and one App can have windows of both kinds.
The simplest way to draw is std/gpu: a gpu.Surface
made from the handle presents frames on Metal, Vulkan or OpenGL, whichever
the machine has, as
examples/gpu_window.dodo
shows. The raw APIs take the handle as well;
std/gpu/opengl takes it directly:
app := window.App.new()?
win := app.open(window.Options.gpu("Triangle", 480, 320))?
native := win.native_handle()?
context := opengl.Context.create_for_window(&native, opengl.Options.default())?
win.request_frame()?
for {
match app.wait_event()? {
window.Event.Resize(_, _, _) => {
context.update_surface()
}
window.Event.Frame(_) => {
// ... draw into framebuffer 0, win.width() by win.height() ...
context.swap_buffers()?
win.request_frame()?
}
_ => {}
}
}
Three examples in the repository draw a spinning triangle this way:
opengl_window.dodo,
vulkan_window.dodo,
which makes a surface for each system and rebuilds its swapchain on resize
(see Vulkan),
and metal_window.dodo
for macOS.
The GPU’s drawing area is the window’s size in pixels, win.size(), which on
a Retina display is twice the size the window was opened with. After a
Resize event, resize the swapchain or drawable to match.
Each system’s catch
Linux. std/window speaks X11 over its own socket, but Vulkan and EGL
need a libxcb connection. The first native_handle() call therefore loads
libxcb.so.1, which every X11 installation has, and opens a second
connection to the same X server. X11 window ids are valid on every
connection, so the GPU presents into the window through it. Programs that
never ask for a handle still need nothing beyond libc. Every window of the App
shares that connection, which closes with the App; without libxcb the call
fails with NoDisplay.
macOS. win.metal_layer() makes a CAMetalLayer the backing layer of
the window’s view and returns its address. Wrap it with
metal.MetalLayer.from_object for Metal,
or pass it to vkCreateMetalSurfaceEXT for Vulkan through MoltenVK.
std/window keeps the layer’s contentsScale and drawableSize at the
window’s scale and size in pixels, also across resizes. Only windows opened
with Options.gpu() have one, since a pixel-buffer window’s layer shows the
buffer. Everything here, like the window itself, belongs to the main thread.
Windows. The window class has its own device context (CS_OWNDC), as
WGL wants, and a window keeps the first pixel format it is given.
The handle is plain addresses and ids that stay valid until the window closes. Destroy every surface, context or swapchain made from it first; local variables are dropped in reverse order, so declaring the window before the GPU objects does that.
Platform notes
| Linux (X11) | macOS | Windows | |
|---|---|---|---|
| Finding the display | DISPLAY, then the cookie for it in XAUTHORITY or ~/.Xauthority. Local displays use the Unix socket, host:N uses TCP, so SSH X forwarding works. |
The logged-in GUI session. | The interactive desktop. |
| Threads | Any one thread, the one that created the App. | The main thread only; elsewhere App.new fails with Unsupported. |
The thread that created the App must open the windows and read their events. |
| Text input | Latin-1 and Unicode keysyms, Shift, Caps Lock, NumLock and AltGr. Dead keys and compose sequences type nothing. | Characters from the layout, Option combinations included. No input method or dead keys. | Characters from the layout, including dead keys and surrogate pairs. |
| While resizing | Events keep flowing. | AppKit holds the event loop until the mouse is released, then reports the final size. | Windows holds the event loop until the mouse is released, then reports the size. |
| Clipboard | The App serves what it copied while its event loop runs; see Clipboard. | NSPasteboard, plain text. |
The system clipboard, Unicode text. |
| Cursor shapes | The X server’s core cursor font. | The system cursors; private AppKit ones where macOS has no public shape. | The system cursors. |
| Fullscreen | _NET_WM_STATE through the window manager; without one, the window covers the screen itself. |
A fullscreen space, animated. | A borderless window covering the monitor. |
| Frame timing | The Present extension reports each refresh of each window; servers without it fall back to a 60 Hz timer. frame_interval() is measured from Present after about half a second. |
A display link per window reports each refresh on macOS 14 and later; older systems use a timer at the screen’s refresh rate. Programs are exempt from App Nap while a window waits for a frame. | The compositor’s (DWM’s) refresh times; a high-resolution timer keeps the waits precise. |
Errors
window.Error and window.error_name(error):
| Error | When |
|---|---|
NoDisplay |
No window system to connect to: no DISPLAY on Linux, no desktop session. Also native_handle() on Linux without libxcb. |
AlreadyOpen |
Another App exists; a process has one at a time. |
Closed |
The window or its App was closed, or the connection to the window system ended. |
InvalidInput |
A zero size, a size above window.MAX_SIZE (16384), a minimum size above the maximum, or an oversized title. |
OutOfMemory |
The pixel buffer could not be allocated. |
Protocol |
The X server refused the connection (usually a missing or wrong cookie) or sent something malformed. |
Unsupported |
The X server’s default visual is not 24-bit true color, or macOS was used off the main thread. Also update() on a window without a pixel buffer, and metal_layer() on other systems or on a window with one. |
System |
Another operating-system call failed, such as when another program keeps the clipboard locked on Windows, or the X server refuses the clipboard to the App. |
Limits
Windows have no owner relationships yet: a dialog is an ordinary window,
not kept above the window it belongs to or modal to it, and there are no
borderless popups or ways to place a window. The clipboard carries plain
text only, without images or other formats, and there is no drag and drop.
Custom cursor images and input methods for Chinese, Japanese or Korean text
are not implemented. A canvas is copied to
the window system on every update; for drawing without that copy, use the
GPU. Native Wayland and drawing straight to the screen without a desktop
(DRM/KMS) are not implemented yet.