Crate saudade 

Saudade — a minimal, retained-mode GUI library for small Win 3.1-styled programs and utilities. Targets Wayland, X11, Windows, macOS.

The library stays intentionally small:

• the runtime drives winit + softbuffer
• widgets are ordinary Rust values implementing Widget
• events are typed (no integer message IDs)
• widgets request repaint / window close via EventCtx
• the default Theme paints chrome that matches Windows 3.1

Minimal example

use saudade::*;

let root = Container::new(200, 80)
    .with_background(Color::WHITE)
    .add(Label::new(Rect::new(10, 10, 180, 16), "Hello, world!"))
    .add(
        Button::new(Rect::new(60, 40, 80, 24), "OK")
            .default(true)
            .on_click(|cx| cx.close()),
    );

App::new(WindowConfig::new("Hello", 200, 80), root).run();

Re-exports

pub use chrome::WindowChrome;

pub use chrome::WindowFrame;

Modules

chrome

Window chrome for framed screenshots.

mock

Offscreen backend for snapshot / image-based tests.

Macros

include_svg

Embed an SVG file as a saudade::SvgImage constant.

Structs

Accel

A keyboard accelerator: a chord of modifier roles plus a key.

AccelMods

The platform-independent modifier roles of an accelerator chord. Resolved to physical modifiers through a ModifierScheme.

App

Top-level entry point. Owns the window configuration, the theme, and the root widget tree, and drives the winit event loop until the user closes the window or a widget calls EventCtx::close.

Bevel

Decorative chrome: a thin etched line or a 3D frame.

Button

Classic Win 3.1 push button: raised face by default, sunken while pressed, optional 1px outer black border for the dialog’s default action.

Checkbox

Win 3.1 checkbox: a 13×13 sunken white box with a check glyph when set, followed by a text label. Click or Space toggles the state; the optional on_toggle handler fires with the new value.

Color

Column

Vertical layout container. Each child is given a horizontal slice of the column’s bounds: either a fixed height it asked for, or it shares the space left after every fixed child has been laid out (a fill child). Optional overlay children sit on top of everything else — useful for modal dialogs that should float over the menu bar / editor.

Container

A flat collection of widgets at absolute positions inside a fixed-size area.

Dialog

A modal message / alert box.

DragData

The payload of a drag-and-drop operation — what the user is dragging into the window.

Dropdown

A classic Win 3.1 drop-down list box (combobox).

EventCtx

Capabilities granted to a widget while it handles an event.

FileDialog

A modern, single-pane Open / Save file dialog.

FileFilter

A file-type choice shown in the dialog’s “File types” dropdown.

FocusLabel

A single-line caption that carries a keyboard mnemonic and hands focus to the field beside it when that mnemonic is pressed.

Font

A loaded font family, ready for glyph rasterization in any of its FontStyles.

FontSet

The set of font families a Painter draws with — a sans-serif, a serif, and a monospace face, each selectable per draw via FontFamily. Any family may be absent (None): drawing or measuring in a missing one is a no-op / zero. The painter borrows these for a paint pass; the backend owns the Fonts. Build it field-by-field (FontSet { sans: ..., ..Default::default() }) or start from FontSet::default (all empty).

Image

Static ARGB32 pixel buffer drawn at an absolute position. Alpha == 0 means “transparent — skip the pixel”. This is the workhorse for small retro glyphs/logos that you draw procedurally.

Label

A box of text.

List

A vertically-scrolling list of labeled rows with optional icons.

ListIcon

A small ARGB32 pixel buffer drawn next to a list item’s label. Pixels with alpha == 0 are skipped (transparent), so icons keep their outline crisp against the row’s selection color.

ListItem

A single entry inside a List: a text label and an optional icon shown to its left. The icon may be a raster ListIcon (via with_icon) or a compile-time-baked SvgImage (via with_svg_icon).

Menu

MenuBar

A classic Win 3.1 menu bar.

Modal

A modal dialog hosted in its own top-level window.

Modifiers

Painter

Point

PopupRequest

A widget asks the runtime to host its popup in a separate top-level window. The runtime polls Widget::popup_request after each event and matches the request against any existing popup window — opening, repositioning, or closing as needed.

ProgressBar

A horizontal progress indicator: 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 rather than the selection navy on purpose — navy means “focused / selected” on text fields and lists, which a progress bar isn’t. With with_percentage it also draws the rounded percentage centered over the bar in the normal text color.

Rect

Row

Horizontal layout container — the sibling of Column.

ScrollBar

A classic Win 3.1 scrollbar: two arrow buttons bracketing a track with a proportionally-sized thumb in the middle.

Size

Slider

A classic Win 3.1 trackbar: a thin sunken groove with a raised, draggable thumb that selects an integer value in an inclusive [min, max] range.

SvgImage

A compile-time-baked vector image: the viewBox box its geometry lives in, plus the polygons to paint, in back-to-front document order.

SvgPolygon

One solid-color paint operation: a set of contours (rings) filled together with one color under one FillRule. A <path>’s fill and its stroke each become one of these. Built by include_svg!; not meant to be hand-written.

TextEditor

A minimal multi-line text editor — sunken white field, monospace text, cursor, selection with cut/copy/paste, and a built-in vertical scrollbar.

TextInput

Single-line text input — sunken white field with proportional text, caret, range selection, clipboard, double-click word select / triple-click select-all and horizontal scrolling when the text doesn’t fit. Companion to TextEditor for the common case where a single line is enough.

Theme

Visual style palette. Widgets read from this rather than hard-coding colors, so the same widget code can render in different retro themes later.

WindowConfig

Enums

BackgroundPattern

A fill pattern for the background of a regular top-level window.

Cursor

The shape the mouse pointer takes while it rests over a widget.

DialogIcon

What icon — if any — to show on the left of the message.

Event

Note: Event is Clone but not Copy — the drag variants carry a DragData (which owns a Vec). Dispatch always passes &Event, so this costs nothing on the hot path; only a widget that wants to keep a dropped payload pays for the clone.

FillRule

Which rule decides whether a point is inside an overlapping set of contours. Mirrors SVG’s fill-rule. Stroke outlines are always filled NonZero.

FontFamily

Which family of font to draw with: a proportional sans-serif, a proportional serif, or a fixed-width monospace. The styled draw / measure entry points take one of these alongside a FontStyle; the plain text / measure_text default to Sans.

FontStyle

Which face of a font to draw with.

Key

Identifies a key press independent of any text it produces. Char events carry the text the user typed; KeyDown / KeyUp carry the key. Most editing widgets want both — Char for insertion, KeyDown(Named) for navigation and editing actions like Backspace.

MenuItem

One entry inside a drop-down Menu.

ModifierScheme

How the abstract modifier roles of an Accel map onto the physical modifier keys of Modifiers. See the module docs for the table.

MouseButton

NamedKey

Orientation

PopupKind

What kind of subordinate top-level a widget is asking the runtime to host. The runtime maps this onto different windowing-system objects: menus get override-redirect / xdg_popup chrome that’s anchored to the parent surface, dialogs get a real top-level window with transient / modal hints and no fixed position.

Constants

PATTERN_COLORS

The named foreground colors, lightest → darkest. These are the tokens SAUDADE_WINDOW_PATTERN_COLOR accepts, and what the patterns demo cycles.

SCROLLBAR_THICKNESS

Logical-pixel size of the arrow buttons at each end of the bar and the long-axis breadth of the bar itself. Matches Win 3.1’s chrome.

Traits

Widget

The fundamental UI abstraction.