API referencestd/window

std/window

Public declarations, types, methods, and source contracts for std/window.

On this page

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/window"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias Package Source file
backend std/window/native window.dodo
graphics std/graphics window.dodo
handle std/window/handle window.dodo
heap std/window/heap window.dodo
mem core/mem window.dodo
raw std/window/raw window.dodo
time std/time window.dodo

Error

Type alias · Source

Why a window could not be opened or used; see raw.Error for each variant.

pub type Error = raw.Error

NativeHandle

Type alias · Source

The window-system objects behind a window, for GPU APIs; see std/window/handle.

pub type NativeHandle = handle.NativeHandle

error_name

Function · Source

pub fn error_name(error: Error) -> &str from(static)

MAX_SIZE

Constant · Source

The largest accepted width or height, in pixels.

pub const MAX_SIZE: u32 = 16384

WindowId

Type alias · Source

Names one window of the App. Ids start at 1 and are never reused within a process, so an event can be told apart from those of a window closed earlier; 0 is no window.

pub type WindowId = u32

Options

Struct · Source

How to open a window. The size is the drawing area’s, excluding the title bar and borders, in the window system’s own units: points on macOS and pixels at the system scale on Windows, so a window looks the same size on every display. The canvas is in physical pixels, scale_percent() / 100 times larger. X11 has no system scale; there both are pixels.

pub struct Options {
    pub title: &str
    pub width: u32
    pub height: u32
    // Whether the user may resize the window.
    pub resizable: bool
    // Whether the window has a pixel buffer for canvas() and update(). A
    // window that only a GPU draws into needs none, which saves its memory
    // and the copy on every resize.
    pub pixel_buffer: bool
}

Options.new

Function · Source

A resizable window with the given title and size and a pixel buffer.

pub fn new(title: &str, width: u32, height: u32) -> Options from(title)

Options.gpu

Function · Source

A resizable window without a pixel buffer, for drawing with Vulkan, OpenGL or Metal through native_handle().

pub fn gpu(title: &str, width: u32, height: u32) -> Options from(title)

Event

Enum · Source

Something that happened to one of the App’s windows, named by the WindowId each variant starts with; event_window() reads it from any event.

pub enum Event {
    // The user asked to close the window, for example with its close button.
    // The window stays open until close() or the end of its lifetime, so a
    // program may still ask "save changes?".
    Close(window: WindowId),
    // The drawing area changed size. The window's canvas() has the new size
    // from now on and keeps the old picture in its top-left corner; redraw
    // and update().
    Resize(window: WindowId, width: u32, height: u32),
    // The window gained (true) or lost (false) keyboard focus.
    Focus(window: WindowId, focused: bool),
    // A key went down, repeated, or came up in the focused window.
    Key(window: WindowId, key: KeyEvent),
    // Text typed through the keyboard layout, one Unicode scalar value per
    // event, after any Key event for the same keystroke. Control characters
    // are not reported; use Key events for Enter, Tab and Backspace.
    Text(window: WindowId, code_point: u32),
    // The pointer moved to (x, y) inside the drawing area.
    MouseMove(window: WindowId, x: i32, y: i32),
    // A mouse button went down or came up.
    MouseButton(window: WindowId, button: ButtonEvent),
    // The pointer left the drawing area.
    MouseLeave(window: WindowId),
    // A wheel or trackpad scrolled. 120 units are one wheel notch; trackpads
    // report finer amounts. Positive dx scrolls right, positive dy down.
    Scroll(window: WindowId, dx: i32, dy: i32),
    // Time to draw the window's next frame, which request_frame() asked for.
    Frame(window: WindowId),
    // 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.
    Quit
}

event_window

Function · Source

The window an event belongs to; 0 for Quit, which belongs to none.

pub fn event_window(event: &Event) -> WindowId

KeyEvent

Struct · Source

A physical key press or release. key names the key’s position on a US keyboard regardless of the active layout, so WASD stays under the left hand on AZERTY keyboards too; use Text events for the characters typed.

pub struct KeyEvent {
    pub key: Key
    pub pressed: bool
    // True for presses generated by holding the key down.
    pub repeat: bool
    pub modifiers: Modifiers
}

Button

Enum · Source

pub enum Button {
    Left,
    Middle,
    Right,
    // The side buttons many mice have.
    Back,
    Forward
}

ButtonEvent

Struct · Source

pub struct ButtonEvent {
    pub button: Button
    pub pressed: bool
    // The pointer position in the drawing area.
    pub x: i32
    pub y: i32
    pub modifiers: Modifiers
}

Modifiers

Struct · Source

The modifier keys held during an input event.

pub struct Modifiers {
    // Private implementation fields omitted.
}

Modifiers.none

Function · Source

pub fn none() -> Modifiers

Modifiers.shift

Function · Source

pub fn shift(&self) -> bool

Modifiers.control

Function · Source

pub fn control(&self) -> bool

Modifiers.alt

Function · Source

Alt, called Option on Mac keyboards.

pub fn alt(&self) -> bool

Modifiers.meta

Function · Source

The Windows or Super key, or Command on Mac keyboards.

pub fn meta(&self) -> bool

Modifiers.caps_lock

Function · Source

pub fn caps_lock(&self) -> bool

Modifiers.shortcut

Function · Source

The platform’s shortcut modifier: Command on macOS, Control elsewhere.

pub fn shortcut(&self) -> bool

Cursor

Enum · Source

A standard mouse pointer shape for set_cursor(). Each system draws its own version, so the pointer looks like the rest of the desktop; on X11 the shapes come from the server’s core cursor font, which is plainer than desktop cursor themes.

pub enum Cursor {
    // The ordinary arrow.
    Arrow,
    // The I-beam over editable or selectable text.
    Text,
    // The pointing hand over links and other clickable things.
    Hand,
    Crosshair,
    // Arrows in four directions, for moving something; an open hand on
    // macOS, which has no such arrow.
    Move,
    // Resizing left and right, as over a vertical divider.
    ResizeEW,
    // Resizing up and down, as over a horizontal divider.
    ResizeNS,
    // Resizing along the diagonal from top left to bottom right.
    ResizeNWSE,
    // Resizing along the diagonal from top right to bottom left.
    ResizeNESW,
    // The action under the pointer is not possible.
    NotAllowed,
    // The program is busy: an hourglass or spinning circle, and on macOS
    // the arrow with a spinning wheel.
    Wait
}

ClipboardText

Struct · Source

Text read from the clipboard with App.clipboard_text(). It owns its bytes, so it stays valid while the program keeps working with the App.

pub struct ClipboardText {
    // Private implementation fields omitted.
}

ClipboardText.as_str

Function · Source

The text, always valid UTF-8: malformed bytes another program put on the clipboard read as U+FFFD.

pub fn as_str(&self) -> &str from(self)

ClipboardText.len

Function · Source

Its length in bytes.

pub fn len(&self) -> usize

ClipboardText.is_empty

Function · Source

True when the clipboard held no text.

pub fn is_empty(&self) -> bool

App

Struct · Source

The connection to the window system and the event loop of every window opened on it. Dropping the App, or close(), closes all its windows.

pub struct App {
    // Private implementation fields omitted.
}

App.new

Function · Source

Connect to the window system. Fails with NoDisplay without one, AlreadyOpen while another App exists, and Unsupported off the main thread on macOS.

pub fn new() -> App!Error

App.open

Function · Source

Open a window and show it. Fails with InvalidInput for a zero size or one above MAX_SIZE.

pub fn open(&mut self, options: Options) -> Window!Error

App.wait_event

Function · Source

The next event of any window, waiting as long as it takes.

pub fn wait_event(&mut self) -> Event!Error

App.poll_event

Function · Source

The next event if one is pending, without waiting.

pub fn poll_event(&mut self) -> Option<Event>!Error

App.wait_event_timeout

Function · Source

The next event, waiting at most milliseconds for one; none when the time passes first.

pub fn wait_event_timeout(&mut self, milliseconds: u32) -> Option<Event>!Error

App.set_clipboard_text

Function · Source

Put text on the system clipboard, replacing what it held, for this and other programs to paste. Line endings are kept as they are.

On X11 the clipboard is a conversation between programs: the App keeps the text and hands it to programs that paste while the App’s event loop runs, until another program copies something or the App closes. A clipboard manager, which most desktops run, keeps the text available after that.

pub fn set_clipboard_text(&mut self, text: &str) -> void!Error

App.clipboard_text

Function · Source

The text on the system clipboard; empty when it holds none, such as when an image was copied. Text this App copied comes back unchanged.

On X11 this asks the program that copied for the text and waits for it, at most a second for each part of a large transfer. Events that arrive meanwhile are kept and returned by the next wait_event or poll_event, in order. A program that never answers reads as empty.

pub fn clipboard_text(&mut self) -> ClipboardText!Error

App.close

Function · Source

Close every window and the connection. Later calls fail with Closed; closing twice does nothing. The windows’ handles stay valid but report Closed, and their canvases are empty.

pub fn close(&mut self)

Window

Struct · Source

An open window. Closing happens with close() or when the value is dropped. A window does not borrow its App; once the App is gone it reports Closed.

pub struct Window {
    // Private implementation fields omitted.
}

Window.id

Function · Source

The id its events carry.

pub fn id(&self) -> WindowId

Window.size

Function · Source

Size of the drawing area in pixels; also the size of canvas(). After a Resize event it is the new size. 0 by 0 once the window is closed.

pub fn size(&self) -> graphics.Size

Window.width

Function · Source

pub fn width(&self) -> u32

Window.height

Function · Source

pub fn height(&self) -> u32

Window.scale_percent

Function · Source

How much the window system enlarges content, in percent: 100 on a classic display, 200 on a Retina or other high-density one. Canvases are always in physical pixels; multiply sizes by this to keep them readable, for example with font.medium().scaled(window.scale()).

pub fn scale_percent(&self) -> u32

Window.scale

Function · Source

scale_percent() rounded to a whole factor, at least 1.

pub fn scale(&self) -> u32

Window.has_pixel_buffer

Function · Source

Whether the window has a pixel buffer: false when it was opened with Options.gpu().

pub fn has_pixel_buffer(&self) -> bool

Window.canvas

Function · Source

The window’s pixel buffer as a canvas, in graphics.PixelFormat.Bgra8888. It keeps what was drawn into it until the window is resized, when it takes the new size here, keeping the old picture in its top-left corner. Drawing shows nothing until update(). A window without a pixel buffer lends out an empty 0x0 canvas.

pub fn canvas(&mut self) -> graphics.Canvas from(self)

Window.update

Function · Source

Show the dirty part of the pixel buffer, typically the rectangle canvas.take_dirty() returned. An empty rectangle shows nothing. Fails with Unsupported for a window without a pixel buffer, whose frames the GPU presents.

pub fn update(&mut self, dirty: graphics.Rect) -> void!Error

Window.update_all

Function · Source

Show the whole pixel buffer. Fails with Unsupported for a window without one.

pub fn update_all(&mut self) -> void!Error

Window.request_frame

Function · Source

Ask for one Frame event of this window when it is time to draw the next frame. An animation draws on each Frame and asks again:

win.request_frame()? for { match app.wait_event()? { window.Event.Frame(_) => { …draw, then win.update(dirty)?… win.request_frame()? } …other events… } }

Frames come once per display refresh, frame_interval() apart, however many events arrive. Where the window system reports refreshes frames follow them: a display link on macOS 14 and later, the compositor’s timing on Windows and the Present extension on X11; elsewhere a timer keeps the pace. A program slower than the display skips refreshes rather than falling behind, and a hidden window, whose display reports no refreshes, still gets a frame every two intervals. Asking again before the Frame arrives changes nothing. While any window waits for a frame macOS does not put the program to sleep with App Nap.

pub fn request_frame(&mut self) -> void!Error

Window.frame_interval

Function · Source

How long one display refresh lasts, such as about 16.7 ms at 60 Hz: the time between Frame events, for advancing an animation by one frame. 60 Hz when the window system does not say; on X11 the real period is known after about half a second of frames.

pub fn frame_interval(&self) -> time.Duration

Window.set_title

Function · Source

pub fn set_title(&mut self, title: &str) -> void!Error

Window.set_cursor_visible

Function · Source

Show or hide the mouse pointer while it is over the window.

pub fn set_cursor_visible(&mut self, visible: bool) -> void!Error

Window.set_cursor

Function · Source

Show cursor while the pointer is over the drawing area, until the next call; new windows show Cursor.Arrow. A pointer hidden with set_cursor_visible(false) stays hidden and takes the shape when shown again.

pub fn set_cursor(&mut self, cursor: Cursor) -> void!Error

Window.set_size

Function · Source

Resize the drawing area to width by height in the units of Options: points on macOS, pixels at the system scale on Windows and pixels on X11. The size is kept within set_min_size and set_max_size. The window system may adjust it further, for example to fit the screen; the size it settles on arrives as a Resize event, after which size() and canvas() have it. Works on windows the user cannot resize too. While the window is fullscreen the size applies when it leaves fullscreen. Fails with InvalidInput for a zero size or one above MAX_SIZE.

pub fn set_size(&mut self, width: u32, height: u32) -> void!Error

Window.set_min_size

Function · Source

The smallest size the user can shrink the drawing area to, in the units of set_size; 0 leaves a dimension unlimited, and 0 by 0 removes the limit. A window smaller than the new minimum grows to it. Fails with InvalidInput above MAX_SIZE or above a maximum that is set.

pub fn set_min_size(&mut self, width: u32, height: u32) -> void!Error

Window.set_max_size

Function · Source

The largest size the user can enlarge the drawing area to, in the units of set_size; 0 leaves a dimension unlimited, and 0 by 0 removes the limit. A larger window shrinks to it. Fullscreen ignores the limit. Fails with InvalidInput above MAX_SIZE or below a minimum that is set.

pub fn set_max_size(&mut self, width: u32, height: u32) -> void!Error

Window.set_fullscreen

Function · Source

Make the window cover its whole screen without a title bar or borders (true), or return it to its earlier size and place (false). The new size arrives as a Resize event. macOS animates the change into a space of its own, as its green title-bar button does; X11 asks the window manager, and without one covers the screen itself.

pub fn set_fullscreen(&mut self, fullscreen: bool) -> void!Error

Window.is_fullscreen

Function · Source

Whether the window is fullscreen, or is changing to fullscreen after set_fullscreen(true). On macOS it also follows the user entering or leaving fullscreen with the title-bar button; X11 reports what the program asked for. False once the window is closed.

pub fn is_fullscreen(&self) -> bool

Window.native_handle

Function · Source

The window system’s objects behind this window, for creating a Vulkan, OpenGL or Metal surface that draws straight into it: the X11 window and a libxcb connection on Linux, the NSWindow and NSView on macOS, the HWND and HINSTANCE on Windows. The drawing area’s size in pixels is size(); after a Resize event, resize the GPU’s swapchain or drawable to the new size.

On Linux the first call loads libxcb (libxcb.so.1, part of every X11 installation) and opens a second connection to the X server, since Vulkan and EGL need a library connection rather than std/window’s own socket; programs that never ask need nothing beyond libc. That connection is shared by every window and closes with the App. Fails with NoDisplay when libxcb is missing or cannot connect, and Closed once the window or its App is closed.

The addresses stay valid until the window closes: destroy every surface made from them first. A window without a pixel buffer (Options.gpu()) avoids keeping an unused one, but any window works.

pub fn native_handle(&mut self) -> NativeHandle!Error

Window.metal_layer

Function · Source

macOS: make a CAMetalLayer the backing layer of the window’s view and return its address, a CAMetalLayer * that the view keeps alive until the window closes. Metal renders into it through metal.MetalLayer.from_object, Vulkan through VK_EXT_metal_surface. Calling it again returns the same layer. std/window keeps the layer’s contentsScale and drawableSize at the window’s scale and pixel size, also across resizes. Fails with Unsupported on other systems and for a window with a pixel buffer, whose own layer shows the buffer.

pub fn metal_layer(&mut self) -> usize!Error

Window.close

Function · Source

Close the window. Later calls fail with Closed; closing twice does nothing. Dropping the window closes it too.

pub fn close(&mut self)

Window.format

Function · Source

The format the pixel buffer uses; presenting a canvas in another format converts it.

pub fn format(&self) -> graphics.PixelFormat

Window.present

Function · Source

Copy dirty from a canvas of your own into the window’s pixel buffer and show it, so a window works with graphics.present like any other display. Like every display it shows only what lies inside both the canvas’s bounds() and the window and ignores the rest, so a smaller canvas, one with an origin, or one left over from before a resize updates just the part it covers. Fails with Device when the window system fails or the window has no pixel buffer.

pub fn present(&mut self, canvas: &graphics.Canvas, dirty: graphics.Rect) -> void!graphics.Error

Key

Enum · Source

Physical keys, named after their position on a US keyboard.

pub enum Key {
    Unknown,
    A,
    B,
    C,
    D,
    E,
    F,
    G,
    H,
    I,
    J,
    K,
    L,
    M,
    N,
    O,
    P,
    Q,
    R,
    S,
    T,
    U,
    V,
    W,
    X,
    Y,
    Z,
    Digit0,
    Digit1,
    Digit2,
    Digit3,
    Digit4,
    Digit5,
    Digit6,
    Digit7,
    Digit8,
    Digit9,
    Escape,
    Enter,
    Tab,
    Backspace,
    Space,
    Minus,
    Equal,
    LeftBracket,
    RightBracket,
    Backslash,
    Semicolon,
    Apostrophe,
    Grave,
    Comma,
    Period,
    Slash,
    CapsLock,
    F1,
    F2,
    F3,
    F4,
    F5,
    F6,
    F7,
    F8,
    F9,
    F10,
    F11,
    F12,
    PrintScreen,
    ScrollLock,
    Pause,
    Insert,
    Home,
    PageUp,
    Delete,
    End,
    PageDown,
    Right,
    Left,
    Down,
    Up,
    NumLock,
    KeypadDivide,
    KeypadMultiply,
    KeypadSubtract,
    KeypadAdd,
    KeypadEnter,
    Keypad0,
    Keypad1,
    Keypad2,
    Keypad3,
    Keypad4,
    Keypad5,
    Keypad6,
    Keypad7,
    Keypad8,
    Keypad9,
    KeypadDecimal,
    KeypadEqual,
    IntlBackslash,
    Menu,
    LeftControl,
    LeftShift,
    LeftAlt,
    LeftMeta,
    RightControl,
    RightShift,
    RightAlt,
    RightMeta
}

key_from_code

Function · Source

The key with code code from key_code, or Unknown.

pub fn key_from_code(code: u32) -> Key

key_code

Function · Source

A stable number for each key, for storing key bindings.

pub fn key_code(key: &Key) -> u32

key_name

Function · Source

The variant name, such as “Escape” or “Keypad7”.

pub fn key_name(key: &Key) -> &str from(static)

Search every guide, reference page, and API declaration.