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.
keynames 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
millisecondsfor 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
texton 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
dirtypart 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
cursorwhile 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
widthbyheightin 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
dirtyfrom 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
codefrom 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)