Module image_widget 

ImageWidget — displays a raster image (PNG, WebP) with a configurable sizing policy, content-fit mode, and intra-box alignment.

Unlike IconWidget which is designed for small square tintable icons, ImageWidget handles arbitrary aspect ratios and defaults to full-color rendering.

Sizing model

Two independent concerns, mirroring Qt’s QLabel/QPixmap, SwiftUI’s Image, and CSS’s replaced-element model:

1. Box size — how big the widget’s layout rectangle is.
   • width / height / size pin a fixed logical extent. A pinned axis is rigid: it is reported as-is and is never scaled up to a parent’s proposal (this is the SwiftUI .frame(width:height:) / Qt fixed-size behaviour). Pinning only one axis derives the other from the image’s aspect ratio (CSS width: Npx; height: auto).
   • With no axis pinned the widget reports its natural pixel size. By default (resizable = true) a constraining proposal scales that natural size down/up while preserving aspect ratio; resizable(false) locks it to the raw pixel dimensions (SwiftUI’s default non-.resizable() image).
2. Content fit — how the image pixels map into that box, via ImageFit (Contain / Cover / Fill / ScaleDown / None, the CSS object-fit set) plus alignment (the CSS object-position equivalent) for where slack/overflow lands. Modes that overflow the box (Cover, and None on an oversized image) are clipped to the box so the image never bleeds past its layout rectangle.

For a fixed 32×32 logo: ImageWidget::new(icon).size(32.0, 32.0) — the box is exactly 32×32 and the artwork is letterboxed inside it (Contain, the default).

// A 64×64 image shown at natural size with no masking.
let icon = RasterIcon::from_raw(vec![255; 64 * 64 * 4], 64, 64);
let _logo = ImageWidget::new(&icon).size(32.0, 32.0);

// Cover a square avatar slot and crop to a circle.
let _avatar = ImageWidget::new(&icon)
    .mask(ImageMaskShape::Circle)
    .fit(ImageFit::Cover)
    .alt("User avatar")
    .size(48.0, 48.0);

Structs

ImageWidget

A widget that displays a raster image (PNG, WebP, or raw RGBA pixels) with configurable fit and alignment.

Enums

ImageFit

How the image is fitted within its layout bounds.