Saudade

A minimal, retained-mode GUI library for small Windows 3.1–styled utilities written in Rust. Built on winit + softbuffer with fontdue + fontdb for text — no GPU, no browser engine, no mobile support, or complex developer tooling.

Saudade exists to make tiny dialogs and tools (about boxes, system viewers, simple text editors, mini control panels) that look like they fell out of 1992 while staying portable, density-independent, and crisp on modern displays.

Applications built with Saudade pair exceptionally well with my Wayland window manager Canoe, but will work on any UNIX (Wayland/X11) or Mac system.

Status

Pre-1.0, intentionally small. The current widget set is enough to assemble small single-window utilities. There is currently no documentation apart from this huge braindump README.

Reference apps live under examples/. Run any of them with cargo run --example <name>:

Example	What it shows
notepad	Editor window with menu bar (MenuBar, TextEditor).
filer	Filesystem browser using List with folder/file icons.
picker	Pick-an-item dialog: List + buttons + Dialog, with Tab/Shift+Tab focus cycling.
counter	7GUIs task 1 — a Label field and a Button.
temperature	7GUIs task 2 — two TextInputs converting Celsius ↔ Fahrenheit live.
flight_booker	7GUIs task 3 — a Dropdown picks the flight type and reactively enables / disables the return-date field and the Book Button.
timer	7GUIs task 4 — a ProgressBar gauge, a duration Slider, and a reset Button.
crud	7GUIs task 5 — a List as a live, prefix-filtered database view with Create / Update / Delete Buttons that enable themselves reactively.
circle_drawer	7GUIs task 6 — a custom canvas (no circle primitive: midpoint outlines, span-filled disks) with hover selection, a right-click menu, a real modal dialog (Modal) hosting the diameter Slider, and snapshot undo/redo.
cells	7GUIs task 7 — a scrollable A–Z / 0–99 spreadsheet Grid (built on ScrollBar + TextInput) with a formula engine: cell refs, + - * /, ranges, SUM/AVG/…, reactive recompute and cycle detection.
patterns	Previews the window background patterns (none, solid, dots, lines, diagonal, cross-stitch): press p to cycle the pattern and c to cycle the color. Every app draws one behind its widgets — default superlight diagonal, overridable with SAUDADE_WINDOW_PATTERN / SAUDADE_WINDOW_PATTERN_COLOR (e.g. SAUDADE_WINDOW_PATTERN=dots SAUDADE_WINDOW_PATTERN_COLOR=light).
scaling	Previews widgets at an arbitrary logical→physical scale via Painter::draw_scaled: a Slider and preset Buttons (1.0x / 1.25x / … / 3.0x) drive a "preview scale" — starting at the display's OS scale — that a small panel of real widgets (TextInput, Dropdown, Checkbox, Buttons, ProgressBar) redraws at, plus a "zoom in 2x" Checkbox that magnifies the result. The window resizes itself (via EventCtx::request_window_size) to fit the preview at the chosen scale. The window's own (OS-owned) scale is never touched.
svg	Compares include_svg! (SVG baked to polygons at compile time, filled at runtime — no SVG crate in the binary) against include_str! + resvg (parse + rasterize at runtime). Draws six icons both ways for a side-by-side fidelity check and prints a micro-benchmark to the console (run with --release). Needs resvg only as a dev-dependency, for the comparison.

$ cargo run --example notepad        # or: filer, picker, counter, temperature,
                                     #     flight_booker, timer, crud, circle_drawer,
                                     #     cells, patterns, scaling, svg

Saudade was extracted from retrofetch, whose about-box dialog (Container + Label + Button + Image + Bevel) was the original demo; that project now lives in its own repository.

At a glance

use saudade::*;

fn main() {
    let root = Container::new(220, 100)
        .with_background(Color::WHITE)
        .with_border(Color::BLACK)
        .add(Label::new(Rect::new(20, 20, 180, 16), "Hello, saudade!"))
        .add(
            Button::new(Rect::new(70, 60, 80, 24), "OK")
                .default(true)
                .on_click(|cx| cx.close()),
        );

    App::new(WindowConfig::new("Hello", 220, 100), root).run();
}

Adding Saudade to your project

Saudade is on crates.io; add it the usual way:

$ cargo add saudade

or list it directly in your Cargo.toml:

# Cargo.toml
[dependencies]
saudade = "0.2.0"

The reference apps under examples/ are plain Cargo examples built against this crate; see those for a working setup, and run them with cargo run --example <name>.

Design philosophy

Saudade follows a small set of architectural principles:

• widgets are ordinary Rust values implementing the Widget trait
• events are typed Rust enums — no integer message IDs
• widgets request repaint / window-close / focus via a small EventCtx
• the runtime drives winit and writes pixels through softbuffer
• widgets paint in logical pixels; the library handles DPI

The mental model is closer to "a typed, ownership-safe GUI runtime" than to an object-oriented UI framework.

Module map

Module	Contents
geometry	Point, Size, Rect, Color
event	Event, MouseButton, Key, NamedKey, Modifiers, EventCtx
theme	Theme, default Theme::windows_31() palette
painter	Painter — drawing primitives + Win 3.1 chrome helpers
svg	SvgImage, SvgPolygon, FillRule + the include_svg! macro — compile-time vector icons
font	Font — system font lookup + glyph rasterization
widget	Widget trait (paint / event / focus / overlay hooks)
widgets	Container, Column, Row, Label, Button, Checkbox, Bevel, Image, MenuBar, Menu, MenuItem, ScrollBar, Slider, ProgressBar, List, Modal, Dialog, TextInput, TextEditor
app	App, WindowConfig — runtime entry point

Everything user-facing is re-exported from the crate root; you generally just use saudade::*;.

Core types

Color

Packed 32-bit ARGB. Helpers cover the Win 3.1 default palette:

Color::rgb(0x40, 0x40, 0x40);
Color::argb(0x80, 0x00, 0x00, 0xFF); // half-transparent blue
Color::BLACK;      Color::WHITE;
Color::LIGHT_GRAY; Color::MID_GRAY; Color::DARK_GRAY;
Color::NAVY;       Color::RED;
Color::GREEN;      Color::YELLOW;
Color::TRANSPARENT;

Color::TRANSPARENT is used by Image to mark "skip this pixel".

Point, Size, Rect

let p = Point::new(10, 20);
let s = Size::new(60, 24);
let r = Rect::new(10, 20, 60, 24);

assert!(r.contains(Point::new(15, 25)));
assert_eq!(r.right(), 70);
assert_eq!(r.bottom(), 44);
let inset = r.inset(2); // shrinks by 2 px on every side

All coordinates are logical pixels (i32). The library multiplies by the OS-reported scale factor when drawing.

Events

pub enum Event {
    PointerMove  { pos: Point },
    PointerDown  { pos: Point, button: MouseButton },
    PointerUp    { pos: Point, button: MouseButton },
    PointerLeave,
    Scroll       { pos: Point, delta_x: f32, delta_y: f32 },
    KeyDown      { key: Key, modifiers: Modifiers },
    KeyUp        { key: Key, modifiers: Modifiers },
    Char         { ch: char, modifiers: Modifiers },
}

pub enum MouseButton { Left, Right, Middle }

pub enum Key {
    Named(NamedKey),  // editing / navigation keys
    Char(char),       // physical key as a logical character
}

pub enum NamedKey {
    Enter, Backspace, Delete, Tab, Escape, Space,
    Left, Right, Up, Down, Home, End, PageUp, PageDown,
}

pub struct Modifiers { pub shift: bool, pub control: bool, pub alt: bool, pub logo: bool }

Event::position() returns the cursor Point for positional events — including Scroll, so containers route a wheel turn to the widget under the pointer — or None for PointerLeave and keyboard events. Event::is_keyboard() distinguishes the three keyboard variants.

Scroll carries the wheel / trackpad movement in document lines, positive toward the content's end (delta_y down, delta_x right). One wheel notch is three lines; trackpad pixel deltas become a fractional line count, which the backends normalize so both kinds of scroll feed widgets the same units. ScrollBar, List, and TextEditor all honor it; the latter two scroll whenever the pointer is anywhere over the field, leaving the selection and caret untouched.

KeyDown / KeyUp are for keys — useful for Backspace, arrows, and modifier-bearing shortcuts. Char is for text input — what the keyboard layout decided the user typed. The runtime suppresses Char when a command modifier (Ctrl / Alt / Logo) is held so editors don't ingest "\x01" for Ctrl+A; the matching KeyDown still fires.

Modifiers::has_command() is true if any of Ctrl / Alt / Logo is held.

EventCtx

Inside an event handler, widgets receive a mutable &mut EventCtx and can ask the runtime to do things:

pub struct EventCtx { /* opaque */ }

impl EventCtx {
    pub fn request_paint(&mut self);             // mark window dirty
    pub fn close(&mut self);                     // close the window after dispatch
    pub fn request_focus(&mut self);             // become the keyboard target
    pub fn release_focus(&mut self);             // drop keyboard focus
    pub fn request_window_size(&mut self, w: i32, h: i32); // resize the window
}

Widgets never poke at the runtime directly. The runtime collects the requests after a dispatch completes and applies them all at once, which keeps event handling deterministic and re-entrancy-free.

Theme

pub struct Theme {
    pub background: Color,      // window / workspace fill
    pub face: Color,            // button / menu-bar face
    pub highlight: Color,       // light bevel edge
    pub shadow: Color,          // dark bevel edge
    pub border: Color,          // 1-px outer black border
    pub text: Color,
    pub disabled_text: Color,
    pub highlight_bg: Color,    // selected-item bg (Win 3.1: navy)
    pub highlight_text: Color,  // selected-item fg (Win 3.1: white)
    pub font_size: f32,
}

The default is Theme::windows_31(): white workspace, light-gray button face, white top/left highlight, mid-gray bottom/right shadow, black outer border, navy/white selection, 11pt text. Pass an alternative via App::with_theme(...) if you want to skin the same widgets differently.

Built-in widgets

All widgets implement Widget and own their own state. Coordinates are always in logical pixels.

Layout vs. absolute positioning

Saudade ships with two top-level container styles:

• Container — children are placed at absolute logical-pixel positions. This is what you want for dialogs (about boxes, simple alerts) that have a fixed design size and shouldn't reflow. If the OS gives the window a larger buffer than the design, the runtime centers the Container and fills the surroundings with theme.background.
• Column — children are stacked top-to-bottom and flex with the window. Each child is either add_fixed(widget, height) (takes a declared height) or add_fill(widget) (shares whatever space is left over). On every window resize, the runtime calls layout on the root widget; Column propagates that to its children, so a menu bar stays pinned to the top and a text editor below it grows with the window.

Widgets opt into layout by overriding Widget::layout(&mut self, bounds: Rect). Most box-shaped widgets do — MenuBar, TextEditor, List, ScrollBar, Row, Button, Checkbox and Label all store the new rect (and rebuild any cached geometry), so they reflow inside a Column/Row or any container that propagates layout. Widgets that don't override layout (e.g. Bevel, Image) keep the position they were given at construction — which is exactly what Container's children want.

// Notepad layout: menu bar pinned to the top, editor fills the rest.
// The runtime auto-focuses the first focusable widget (the editor) at
// startup, so the user can type immediately.
let root = Column::new()
    .with_background(Color::WHITE)
    .add_fixed(menu_bar, MENU_BAR_H)
    .add_fill(text_editor);

Column also handles capture, focus, accelerator routing, and the overlay pass — same contract as Container.

• Row — the horizontal sibling of Column. Same add_fixed(widget, width) / add_fill(widget) API, laying children left-to-right across the full height, with the same capture / focus / accelerator / Tab handling. Unlike Column it carries no overlay layer — keep modal dialogs on the top-level container so there's a single overlay owner.

Both Column and Row expose focus_child(index) to choose a non-default initial focus target (e.g. focus a content list instead of a leading toolbar field). Custom container widgets outside the crate can reuse Saudade's focus protocol via EventCtx::is_focus_requested / is_focus_released / clear_focus_flags.

Container

A flat collection of widgets at absolute positions. The container handles:

• hit testing — pointer events go to the top-most child whose bounds contain the cursor;
• pointer capture — a child whose captures_pointer() returns true keeps receiving pointer events until it un-captures (used by Button and MenuBar);
• keyboard focus — clicking a focusable child makes it the keyboard target; keyboard events route there only;
• focus cycling — Tab and Shift+Tab walk forward / backward through focusable children, wrapping at either end. The container looks at each child's focusable() and calls focus_first on the new target, so wrapper widgets that delegate focus to a nested leaf are handled transparently;
• accelerator routing — keyboard events also go to any child whose accepts_accelerators() returns true (used by MenuBar to catch Alt+letter combos while a sibling holds focus);
• overlay pass — every widget's paint_overlay runs after every widget's regular paint, so popups (menus, tooltips) draw on top of siblings.

let root = Container::new(395, 305)        // size in logical pixels
    .with_background(Color::WHITE)         // optional fill
    .with_border(Color::BLACK)             // optional 1-px outer border
    .add(Label::new(Rect::new(20, 20, 120, 16), "Hello"))
    .add(Button::new(Rect::new(150, 50, 80, 24), "OK"));

// imperatively:
let mut root = Container::new(395, 305);
root.push(Label::new(Rect::new(20, 20, 120, 16), "Hello"));

The runtime calls Widget::focus_first on the root once the window is ready, so a container that holds a TextEditor or List will hand it keyboard focus automatically. Override the trait method to choose a different initial target.

Add order matters: later widgets paint on top and are hit-tested first.

Label

A box of text. A Label always occupies a rectangle; text is laid out from the box's top-left corner. Inherits color and size from the active Theme unless overridden.

Label::new(Rect::new(10, 10, 120, 16), "Plain label");
Label::new(Rect::new(10, 30, 120, 14), "Smaller").with_size(8.0);
Label::new(Rect::new(10, 50, 120, 16), "Red").with_color(Color::RED);

Text is multi-line and word-wrapped to the box automatically — no wrap points to specify by hand. Explicit \n characters always start a new line, and any line too wide for the box breaks at whitespace (a single word wider than the box overflows rather than being split mid-word). Lines stack at the font's natural line height.

Label::new(Rect::new(10, 10, 200, 60),
    "A longer paragraph that wraps across several lines, plus an\nexplicit break.");

Anything that extends past the box — horizontally or vertically — is clipped to its bounds, so a label never paints outside the rectangle it was given. Placed in a Column or Row, a label adopts its slot and wraps/clips to that; placed at an absolute position in a Container, it keeps the rectangle it was constructed with.

Button

A classic Win 3.1 push button: raised face by default, sunken while pressed, optional 1-pixel outer black border for the dialog's default action.

Button::new(Rect::new(317, 16, 60, 22), "OK")
    .default(true)
    .on_click(|cx| cx.close());

Press behavior matches Windows: pressing inside arms the button, dragging out un-arms (sunken pops back up), dragging back in re-arms, releasing inside fires on_click, releasing outside cancels.

Buttons are focusable: Tab/Shift+Tab cycle through them and the focused button draws a dotted focus rectangle inside its bevel. Enter or Space fires the button while it holds focus.

A button created with .default(true) is also the container's Enter accelerator: pressing Enter anywhere inside the same Container or Column fires the default button, regardless of which sibling holds focus. The widget that consumed the event sets EventCtx::consume_event so the focused widget (e.g., a list whose Enter handler would otherwise activate the selected row) doesn't also react to the same keystroke.

Bevel

Decorative chrome — no events, no state.

Bevel::etched_line(20, 200, 350);                       // two-tone divider
Bevel::raised(Rect::new(10, 10, 100, 30));              // raised frame
Bevel::sunken(Rect::new(10, 50, 100, 30));              // sunken frame

Image

A static ARGB32 pixel buffer at an absolute position. Pixels with alpha == 0 are skipped (transparent). Useful for small procedural glyphs and logos:

let mut logo = Image::new(0, 0, 40, 28);
logo.fill_rect(Rect::new(2, 2, 16, 10), Color::RED);
logo.fill_rect(Rect::new(20, 4, 16, 10), Color::GREEN);
logo.set_pixel(1, 1, Color::BLACK);

Use Image::from_pixels(x, y, w, h, pixels) to attach an externally decoded raster (PNG/BMP/etc.) as ARGB32.

MenuBar, Menu, MenuItem

A classic Win 3.1 menu bar. Top labels live in a white bar (matching Win 3.1's program-manager chrome); clicking one drops a white popup with a sharp L-shape drop shadow. The currently-open top-level label and any hovered popup item are drawn with a navy background and white text. The popup is rendered in the overlay paint pass so it floats over every sibling widget.

let menu_bar = MenuBar::new(Rect::new(0, 0, 520, 20))
    .add_menu(Menu::new(
        "&File",
        vec![
            MenuItem::action("&New",   |cx| { /* … */ cx.request_paint(); }),
            MenuItem::action("&Open",  |_| { /* … */ }),
            MenuItem::action("&Save",  |_| { /* … */ }),
            MenuItem::separator(),
            MenuItem::action("E&xit",  |cx| cx.close()),
        ],
    ))
    .add_menu(Menu::new("&Help", vec![
        MenuItem::action("&About", |_| {}),
    ]));

Mnemonics. Labels may include & immediately before a character to declare the mnemonic. "&File" displays as File with F underlined; press Alt+F (closed bar) or just F (open menu) to fire it. Use && to render a literal &. Mnemonics route through the accepts_accelerators hook on the menu bar, so they keep working even while a TextEditor holds keyboard focus.

Mouse behavior. A single click on a top-level label opens the menu; moving the cursor over items highlights them, and a second click on an item fires it. A click that opens the menu without dragging pre-highlights the first action, so the user can immediately fire it with Enter or keep arrow-navigating. The press-drag-release gesture also works: press on a top-level label, drag down through the popup, release on an item to fire it without an intermediate click. Releasing anywhere else just disarms the gesture and leaves the menu open. Sliding the cursor along the bar with a menu open swaps between top-level menus. Click outside (or press Esc) to dismiss.

Keyboard navigation (active while a menu is open):

Key	Effect
↑ / ↓	move highlight to the previous / next action (skipping separators; wraps)
Home / End	jump to first / last action
← / →	switch to the previous / next top-level menu
Enter	fire the currently highlighted action
letter	fire the action whose mnemonic matches
Esc	dismiss the menu

Menus opened with Alt+letter (or arrow-switched left/right) always pre-highlight the first action of the newly opened menu — the previous highlight position never carries over. Click-to-open menus also pre-highlight the first item if the cursor never reached the popup before release; only drag-style opens leave nothing hovered.

While a menu is active no keyboard event is forwarded to the focused widget below — typing in an open menu doesn't leak into the editor.

Popups live in their own window. When a menu opens, the runtime spawns a borderless window for the popup, sized exactly to its contents and behaving like Chrome / Firefox menus on each backend:

• X11 (through winit): an override-redirect window with the _NET_WM_WINDOW_TYPE_DROPDOWN_MENU hint. The WM is bypassed entirely, so the popup appears instantly at the requested position and size and can extend beyond the main window's edges. The runtime also re-anchors it via Window::set_outer_position whenever the main window emits a Moved event, so the popup follows window drags.
• Wayland (through smithay-client-toolkit): a real xdg_popup surface created with an xdg_positioner anchored to the parent surface. The compositor handles placement, follow-on-drag, and auto-dismiss (sending popup_done, which we translate into a synthesized Escape).

The popup is dismissed by clicking outside it (the main window receives the click and the menu folds up), pressing Escape, or firing an item.

MenuBar::open(idx) programmatically opens a menu — handy for custom application-level keybindings.

ScrollBar

A Win 3.1 scrollbar: two arrow buttons bracketing a track with a proportionally-sized thumb. Built standalone — embed it next to any scrollable view, or let TextEditor carry one for you.

let mut bar = ScrollBar::vertical(Rect::new(380, 20, 16, 280));
bar.set_range(/* viewport */ 20, /* max */ 60);  // 80-row file, 20 visible
bar.set_value(0);
bar.set_line_step(1);

Interaction:

Input	Effect
click arrow	scroll by line_step toward the arrow
click track	scroll by viewport (one page) toward the click
drag thumb	scroll proportionally to the drag distance
mouse wheel	scroll three lines per notch along the bar's axis

The thumb is sized as track_extent × viewport / (viewport + max) with a sane minimum so it stays grabbable even on huge documents. Use SCROLLBAR_THICKNESS (16 logical pixels) to lay siblings out around it.

Slider

A Win 3.1 trackbar: a thin sunken groove with a raised, draggable thumb that picks an integer value in an inclusive [min, max] range. Unlike ScrollBar (which models a scroll position over a viewport), a Slider is a plain value control — use it to dial a number.

let slider = Slider::new(Rect::new(16, 16, 200, 24), 0, 100)
    .with_value(40)
    .with_step(5)                       // arrow-key increment (default 1)
    .on_change(|cx, value| {
        // fires on every change, including continuously during a drag
        cx.request_paint();
    });

let v: i32 = slider.value();

Interaction:

Input	Effect
click / drag	move the thumb to the cursor (fires on_change live)
← / ↓	decrease by step
→ / ↑	increase by step
PageUp / PageDown	jump by a tenth of the range
Home / End	snap to min / max

The slider is focusable and draws a dotted focus rectangle inside the thumb when focused. on_change fires during a drag, not just on release, so a gauge or label bound to it updates as the user moves the thumb. Use set_on_change to install the handler after construction (when the slider is held behind an Rc<RefCell<…>>).

ProgressBar

A sunken white field that fills from the left with a solid grey bar in proportion to its fraction (0.0–1.0). The fill is a neutral grey, not the selection navy used by lists and text fields — a progress bar isn't "focused," so it shouldn't borrow that color's meaning. Purely presentational — no events, no focus, no built-in animation: drive it by calling set_fraction from whatever owns the underlying progress.

let mut bar = ProgressBar::new(Rect::new(16, 16, 200, 16))
    .with_percentage(true);             // draw the rounded % over the bar
bar.set_fraction(0.6);                  // 60% full

With with_percentage(true) the bar draws the rounded percentage centered over the field in the normal text color, which stays legible over both the empty and filled halves.

TextEditor

A minimal multi-line text editor: sunken white field, monospace text, vertical cursor, selection, cut/copy/paste against the OS clipboard, and a built-in vertical scrollbar pinned to the right edge. Only the visible rows are measured and drawn each paint, so large files stay cheap. Designed for system-utility editors (Notepad-style); undo and word wrap come later.

let mut editor = TextEditor::new(Rect::new(4, 24, 512, 312))
    .with_font_size(11.0)
    .with_text("Hello\nWorld");

let text: String = editor.text();

The editor renders with the monospace font loaded by the runtime (Consolas / Courier / Liberation Mono / DejaVu Sans Mono, in that preference order). The rest of the UI (menu labels, dialog text) keeps the proportional default — pick whichever font you want per call via Painter::text vs Painter::mono_text.

Editing operations:

Input	Effect
typing	inserts the character (replaces selection)
Backspace	deletes the previous char or the selection
Delete	deletes the next char or the selection
Enter	splits the line (replacing the selection)
← / →	move cursor one character
↑ / ↓	move cursor one line, clamping column
Home / End	jump to line start / end
PageUp / PageDown	jump by one viewport
Shift + any move	extends the selection
Ctrl + A	select all
Ctrl + C	copy selection to the OS clipboard
Ctrl + X	cut selection to the OS clipboard
Ctrl + V	paste at the cursor (replaces selection)
left click	place the cursor
drag with left	extend the selection

Selected text renders with theme.highlight_bg (navy) behind it and theme.highlight_text (white) on top. Multi-line selections show a small visual continuation past end-of-line so the band looks unbroken.

Programmatic methods mirror the keyboard shortcuts so menu items can invoke the same operations:

editor.cut();
editor.copy();
editor.paste();
editor.select_all();

The clipboard handle is lazily initialized via arboard; in headless environments where the OS clipboard isn't reachable, copy/cut/ paste simply become no-ops — editing still works. On Wayland sessions arboard is built with the wayland-data-control feature so it speaks the native wlr-data-control protocol; clipboard exchange with other Wayland-native apps works without needing XWayland.

TextEditor keeps content as Vec<String> (one entry per line) and tracks (row, col) in characters, not bytes — multi-byte UTF-8 is handled correctly. Per-character widths are cached during paint so a click can be mapped to a column position without a Painter at event time — and the cache is keyed by row, so only rows currently on screen contribute work. The scrollbar's canonical position is its own value(); the editor reads it (no duplicate state). Clicking focuses the widget; the cursor only renders while focused; vertical scroll follows the cursor automatically.

Dropdown

A Win 3.1 drop-down list box (combobox): a sunken field showing the current selection with a raised drop-arrow on the right. Clicking it drops a popup list of the items — hosted in its own borderless top-level window, the same machinery MenuBar uses — so the list can extend past the main window's bottom edge.

let flight_type = Dropdown::new(Rect::new(16, 16, 200, 24))
    .with_items(["one-way flight", "return flight"])
    .with_selected(0)
    .on_change(|cx, index| {
        // fires whenever the selection changes
        cx.request_paint();
    });

let picked: Option<usize> = flight_type.selected_index();
let label: Option<&str> = flight_type.selected_text();

with_items accepts anything that iterates into strings (["a", "b"] or a Vec<String>); the first item becomes the initial selection. Use set_on_change to install the handler after construction when the dropdown is held behind an Rc<RefCell<…>> and needs to talk to widgets built later — the pattern the flight booker uses. set_selected updates the value without firing on_change, mirroring the other widgets' setters.

Interaction:

Input	Effect
click field	open / close the list
click a row	select it and close
click outside / Esc	dismiss without changing the selection
↑ / ↓ (closed)	step the selection in place
Space (closed)	open the list
↑ / ↓ (open)	move the highlight (clamped, no wrap)
Home / End (open)	highlight the first / last row
Enter / Space (open)	commit the highlight and close

The dropdown is focusable and draws a dotted focus rectangle inside the field. While the list is open it captures the pointer, so popup clicks and click-outside dismissals both route back to it — exactly like the menu bar. Dropdown::open() drops the list programmatically (handy for tests and custom keybindings).

An open dropdown also owns the keyboard: Container / Column suppress the accelerator pass while the focused child is capturing, so a sibling default Button doesn't steal Enter — the keystroke commits the highlighted row instead. Once the list closes, Enter fires the default button again. The flight booker relies on this: its Book button is the default action and lives next to the flight-type dropdown.

Disabled controls

Every interactive widget — Button, Checkbox, TextInput, TextEditor, Slider, List, and Dropdown — carries an enabled flag. Construct with .with_enabled(false) or flip it at runtime with set_enabled(bool) (read it back with is_enabled()). A disabled control paints greyed (an engraved label on a button, greyed text elsewhere), refuses keyboard focus, and ignores every input event — a disabled default Button even gives up its Enter accelerator. The flight booker uses this to grey out the return-date field for one-way flights and to block the Book button until the dates are valid; it surfaces an ill-formatted date not by recoloring the field but with a small red Label beside it.

The Widget trait

If a built-in doesn't fit, implement Widget yourself:

pub trait Widget {
    fn bounds(&self) -> Rect;
    fn paint(&mut self, painter: &mut Painter, theme: &Theme);
    fn paint_overlay(&mut self, _painter: &mut Painter, _theme: &Theme) {}
    fn event(&mut self, _event: &Event, _ctx: &mut EventCtx) {}
    fn captures_pointer(&self) -> bool { false }
    fn focusable(&self) -> bool { false }
    fn set_focused(&mut self, _focused: bool) {}
    fn accepts_accelerators(&self) -> bool { false }
    fn layout(&mut self, _bounds: Rect) {}
    fn focus_first(&mut self) -> bool { /* focus self if focusable */ }
    fn popup_request(&self) -> Option<PopupRequest> { None }
}

• bounds is the widget's logical-pixel hit rectangle.
• paint draws the widget using Painter and the active Theme.
• paint_overlay runs after every sibling's paint — for popups, tooltips, drag previews. Default: no-op.
• event reacts to typed input; default is no-op.
• captures_pointer keeps pointer events flowing to this widget while it's true, even if the cursor leaves its bounds (used by buttons during press, by menus while open).
• focusable flags the widget as a keyboard target. The container only routes keyboard events to focused children.
• set_focused is called when the widget gains or loses focus — use this to show/hide a cursor, commit pending input, etc.
• accepts_accelerators makes the widget receive keyboard events even without focus — used by menu bars for Alt+letter combos.
• layout is called by a layout-aware parent (e.g., Column) whenever the available rect changes. Widgets used in absolutely-positioned layouts ignore it; flexible widgets store the new rect and propagate it to their own children.
• focus_first is called by the runtime on the root widget once the window is configured. The default focuses self if focusable() is true; Container and Column override it to walk their children and delegate, so the first focusable widget in the tree becomes the initial keyboard target without any manual wiring.
• popup_request returns Some while the widget wants the runtime to host a popup (e.g., menubar dropdowns) in its own top-level window. Containers propagate it from their children; the runtime polls it after each event burst and opens / repositions / closes the popup window to match.

Minimal custom widget:

struct ColorBox { rect: Rect, color: Color }

impl Widget for ColorBox {
    fn bounds(&self) -> Rect { self.rect }

    fn paint(&mut self, p: &mut Painter, _theme: &Theme) {
        p.fill_rect(self.rect, self.color);
        p.stroke_rect(self.rect, Color::BLACK);
    }
}

Painter API

Painter is the only thing widgets use to draw. It exposes a logical-pixel API; internally it snaps to physical pixels at the current DPI.

Low-level primitives

p.fill(color);                              // clear the whole surface
p.fill_rect(rect, color);
p.stroke_rect(rect, color);                 // 1-logical-px outline
p.h_line(x, y, w, color);
p.v_line(x, y, h, color);
p.pixel(x, y, color);                       // 1×1 logical pixel

Win 3.1 chrome helpers

p.raised_bevel(rect, theme.highlight, theme.shadow);
p.sunken_bevel(rect, theme.highlight, theme.shadow);
p.etched_h_line(x, y, w, theme);            // dark + light two-tone line
p.button(rect, theme, pressed, default);    // full button face + bevels

Text

p.text(x, y, "Hello", 11.0, Color::BLACK);
p.text_centered(rect, "OK", 11.0, Color::BLACK);

let size = p.measure_text("Hello", 11.0);   // returns Size in logical px

Painter::font() returns the loaded font, if any. If no system font could be loaded, text calls become no-ops; layout code that depends on text measurement should be defensive.

Querying state

let s = p.size();    // physical buffer size in pixels
let z = p.scale();   // f32 logical-to-physical scale (e.g. 1.0, 1.25, 2.0)

Vector icons — include_svg!

For scalable marks (toolbar / list / dialog icons), saudade reads an SVG at compile time and bakes it into a set of flattened, filled polygons. The macro does all the SVG work — XML parsing, attribute inheritance, curve flattening, stroke-to-outline expansion — using usvg + kurbo, and emits a const SvgImage of 'static polygon data. At run time saudade only fills those polygons, so no SVG parser, usvg, resvg, or tiny-skia is linked into your binary — that whole tree lives only in the saudade-macros build-time crate.

use saudade::{include_svg, SvgImage};

// Path is resolved relative to the *invoking crate's* CARGO_MANIFEST_DIR
// (a stable-Rust proc macro can't see the call site's source file), so name
// it from the crate root — not, like `include_str!`, relative to the file.
const POWER: SvgImage = include_svg!("assets/icons/power.svg");

// In a Widget::paint, fill it into a rect (aspect-fit, centered, anti-aliased,
// re-snapped crisply at the live DPI — no per-size raster cache needed):
power.draw(painter, Rect::new(8, 8, 32, 32));
// or, equivalently:  painter.draw_svg(&POWER, Rect::new(8, 8, 32, 32));

The geometry is resolution-independent, so the same constant fills crisply at any size or scale factor. The supported SVG subset is the practical one — path / rect / circle / ellipse / line, groups with inherited fills/strokes, solid colors, the usual path commands, and transforms (usvg folds these into the baked coordinates). What it can't bake — gradients and pattern fills, clipPath/mask/filter, group opacity, embedded raster <image>s, and <text> — is dropped with a compile-time warning at the include_svg! call site naming exactly what was skipped, so a surprising SVG fails loudly rather than rendering blank. (Under #![deny(warnings)] that warning is an error — by design.)

The svg example renders icons both this way and via runtime resvg, and benchmarks the two (the baked path is several times faster at icon sizes and matches resvg's rasterization to within ~0.5% per channel).

Font handling

Font::load_system() walks fontdb for a reasonable proportional sans serif, preferring MS Sans Serif → Microsoft Sans Serif → Tahoma → Segoe UI → Arial → Helvetica → Geneva → DejaVu Sans → Liberation Sans, then falling back to any face it can load. Returns Option<Font> — None means no font was found, and the painter silently skips text.

The runtime calls Font::load_system() once at startup and hands the font reference to every Painter it constructs.

A monospace counterpart is loaded the same way via Font::load_monospace, preferring Lucida Console → Consolas → Courier New → Courier → Liberation Mono → DejaVu Sans Mono → Menlo → Monaco. If none of those match, fontdb's monospace flag is used as a fallback. Painter::mono_text / Painter::measure_mono_text use that font; Painter::text / Painter::measure_text keep using the proportional default.

Saudade does not ship a bundled bitmap font, so its text rendering inherits the local system font. The Win 3.1 chrome still looks right, but the typography will be Liberation Sans on most Linux boxes rather than MS Sans Serif — close enough for retro nostalgia, not faithful to the pixel.

Runtime

WindowConfig

pub struct WindowConfig {
    pub title: String,
    pub size: Size,        // logical pixels
    pub resizable: bool,
}

WindowConfig::new("About Retrofetch", 395, 305);
WindowConfig::new("Notepad", 520, 340).resizable(true);

App

App::new(window_cfg, root_widget)
   .with_theme(Theme::windows_31())   // optional
   .run();                            // blocks until window closes

App::run consumes the App, creates the winit event loop + softbuffer surface, loads a system font, and dispatches events to the widget tree until the user closes the window or a widget calls EventCtx::close.

You can have at most one App per process today; multi-window support is on the roadmap.

Backends

Saudade picks the windowing backend at startup based on the session:

• If WAYLAND_DISPLAY is set and non-empty, the runtime talks pure smithay-client-toolkit — no winit on the Wayland code path. This is what gets us real xdg_popup popups and lets us drop winit's wayland-csd-adwaita and wayland-dlopen features from the dependency tree.
• Otherwise (X11, including XWayland when WAYLAND_DISPLAY is unset) the runtime drives winit 0.30 with only the x11 feature enabled. Popups are X11 override-redirect windows.

The widget tree, painter, fonts, clipboard, theme, and every public API are identical across both paths — only app.rs + wayland.rs differ.

DPI and resizing

Widgets always work in logical pixels. The library handles the transformation to physical pixels itself.

• The window is requested at LogicalSize(size.w, size.h). winit + the compositor pick the physical buffer for the monitor's actual DPI.
• The Painter uses winit.scale_factor() (a possibly-fractional f32, e.g. 1.0, 1.25, 1.5, 2.0) directly.
• Rectangle edges are snapped independently to physical pixels — adjacent rects always share an exact pixel boundary, so chrome stays crisp regardless of DPI.
• Text is rasterized once at font_size × scale physical pixels via fontdue. No upscale, no resample, no blur.

When the window is resized larger than the design size, content does not stretch — it stays at its natural logical size. What happens around it depends on the root widget:

• a Container (absolute positioning) keeps its design size; the runtime centers it and fills the surroundings with theme.background, so dialogs always look the same regardless of window size;
• a Column (layout container) receives the new bounds via Widget::layout and reflows its children so the window's chrome and content fill the available space — pixels stay the same physical size but, e.g., the editor grows wider and taller.

Resize never scales pixels — it only changes how much space is available for layout decisions.

Trade-off to be aware of: at non-integer scale factors (1.25, 1.5,…) a 1-logical-pixel chrome line can land on a y-coordinate where the physical width rounds to 1 vs 2 pixels. The variation is invisible in practice on the dialogs we've built; if you hit a case where it matters, draw chrome at a fixed round(scale) thickness using Painter::scale().

The window's scale factor is owned by the OS — adopted at startup and refreshed only when the compositor reports a change. There is no API to override it: density independence comes from designing in logical pixels, not from forcing a particular scale.

What a widget can do is render content at a scale of its own choosing. Painter::draw_scaled(area, scale, zoom, bg, |p| …) draws the closure as a real window at scale DPI would — snapped chrome, re-rasterized text, no resampling — into area, then magnifies the result by the integer zoom (a nearest-neighbor pixel copy that never feeds back into scale). zoom == 1 draws in place; zoom > 1 renders once offscreen and blits it enlarged, which on a HiDPI display lets you actually see the per-pixel snapping a scale produced. It's how you'd build a "preview at 1.5x" pane, a zoomable canvas, or a thumbnail. See examples/scaling.rs, which drives such a preview — a small panel of real widgets — from a slider, presets, and a 2× zoom toggle.

End-to-end example: a Notepad-style editor

use std::cell::RefCell;
use std::rc::Rc;

use saudade::{
    App, Container, Event, EventCtx, Menu, MenuBar, MenuItem, Painter, Rect,
    TextEditor, Theme, Widget, WindowConfig,
};

const W: i32 = 520;
const H: i32 = 340;
const BAR_H: i32 = 20;

fn main() {
    let editor = Rc::new(RefCell::new(
        TextEditor::new(Rect::new(4, BAR_H + 4, W - 8, H - BAR_H - 8))
            .with_text("Hello, saudade!"),
    ));

    let menu_bar = MenuBar::new(Rect::new(0, 0, W, BAR_H))
        .add_menu(Menu::new(
            "&File",
            vec![
                MenuItem::action("&New", {
                    let editor = editor.clone();
                    move |cx| {
                        editor.borrow_mut().set_text("");
                        cx.request_paint();
                    }
                }),
                MenuItem::separator(),
                MenuItem::action("E&xit", |cx| cx.close()),
            ],
        ));

    let root = Container::new(W, H)
        .with_background(saudade::Color::WHITE)
        .add(menu_bar)
        .add(SharedEditor(editor.clone()));

    App::new(WindowConfig::new("Notepad", W, H).resizable(true), root).run();
}

// Tiny adapter so the menu callbacks can mutate the shared editor.
struct SharedEditor(Rc<RefCell<TextEditor>>);

impl Widget for SharedEditor {
    fn bounds(&self) -> Rect { self.0.borrow().bounds() }
    fn paint(&mut self, p: &mut Painter, t: &Theme) { self.0.borrow_mut().paint(p, t) }
    fn event(&mut self, e: &Event, c: &mut EventCtx) { self.0.borrow_mut().event(e, c) }
    fn focusable(&self) -> bool { self.0.borrow().focusable() }
    fn set_focused(&mut self, f: bool) { self.0.borrow_mut().set_focused(f) }
}

A more complete version, including Open/Save against a path passed as argv[1], lives in examples/notepad.rs in this repository (cargo run --example notepad).

Non-goals

The library does not:

• emulate HTML/CSS
• embed a browser engine
• provide immediate-mode-only APIs
• rely on heavy procedural-macro DSLs
• hide ownership semantics
• support GPU rendering, animation, or accessibility yet

It is meant to stay small enough that you can hold the whole codebase in your head.

Roadmap

Things that would fit Saudade's spirit but aren't there yet:

• Grid container (the horizontal Row sibling of Column now exists)
• RadioButton (single-line TextInput, Checkbox and List now exist)
• Horizontal scrolling in TextEditor (a horizontal ScrollBar is already implemented; the editor just doesn't ride it yet)
• Undo / redo in TextEditor
• Save-As / Open file dialogs
• Multi-window support
• Native menu bars where the platform offers them

License

MIT