Crate saudade 

saudade — a minimal, retained-mode GUI library for small Win 3.1-styled utilities (about boxes, simple dialogs, system info viewers).

The library follows the architecture sketched in saudade.md but 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();

Modules

mock

Offscreen backend for snapshot / image-based tests.

Structs

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.

Dropdown

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

EventCtx

Capabilities granted to a widget while it handles an event.

Font

A loaded font, ready for glyph rasterization.

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.

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.

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.

DialogIcon

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

Event

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.

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.