responsive fluid/physical scaling, widget-API stabilization, and perf guardrails
Responsive scaling. ltk now offers two first-class ways to size a UI so it adapts across screens, chosen per process via `WidgetScaling { Fluid, Physical }` (`set_widget_scaling` / `widget_scaling`, default `Fluid`). Fluid sizing (`Length::fluid( px )`) makes a design pixel a proportion of the surface's smaller side, calibrated against a reference width (`set_fluid_reference` / `fluid_reference`, 412 px default) and bounded by `FLUID_MIN` / `FLUID_MAX`; physical sizing (`Length::dp( px )`) is a constant-physical-size pixel scaled by display density (`set_density` / `density`). `Length` gains `orient( portrait, landscape )` — resolve one value in portrait, another in landscape — plus `widget( px )`, which picks fluid or dp per the active mode. Canvas exposes `geom_px` (geometry, resolved in physical layout space) and `font_px` (font size, bridging logical / physical per mode) so widgets and apps share one resolution path. Note the rename: `set_design_reference` / `design_reference` became `set_fluid_reference` / `fluid_reference`, and `Length::dp` changed meaning — the old surface-proportional behaviour now lives on `Length::fluid`.
Widgets. Every stock widget resolves its default geometry and font through the widget-scaling mode instead of frozen pixels, so a whole UI scales coherently without per-call units. New size builders where they were missing: `button` gains `font_size` / `height`, `text_edit` gains `height` / `font_size_fluid`, `separator` gains `pad_v`, and assorted widgets accept a `Length` where they previously took only `f32`.
Overlays. `OverlaySpec::size` is now `( Length, Length )` instead of `( u32, u32 )`, resolved against the main surface when the overlay is materialized, so overlays can scale with the display; `Length::px( … )` reproduces the old fixed sizing.
API stabilization (toward 1.0). Widget struct fields are now `pub( crate )` — they are configured through builders, not field access — except the value / state types apps genuinely read or construct (`Time`, `Date`, `ComboState`), which stay public. The internal `test_support` helpers move behind a `test-support` Cargo feature (off by default, so third-party builds never see them; ltk's own `make test` enables it). `Separator` drops its `0.0`-means-mode sentinel for `Option<Length>`, so an explicit `pad_v( 0.0 )` is a real flush divider distinct from the mode-following default.
Performance guardrails. Opt-in diagnostics via `LTK_PERF_WARN=1` warn about stuck animations, sustained software-render animation, and low `poll_interval`; software-rendered animation is capped near 30 Hz to spare CPU on machines that fall back off EGL. Apps can override the cap with `App::cap_software_animation`.
Docs and build. The two scaling modes are documented in README, onboarding and architecture, with the earlier gradient / backdrop doc drift cleaned up. The Makefile now ships the `locales/` directory into the packaged crate (fixing i18n keys rendering raw for downstreams), builds the new `responsive` example, and runs tests with `--features test-support`.
This commit is contained in:
@@ -13,6 +13,7 @@ reference, see [`docs/widgets.md`](./widgets.md). For theme JSON, see
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Responsive sizing across mobile / tablet / desktop](#responsive-sizing-across-mobile--tablet--desktop)
|
||||
- [Slide-in panel](#slide-in-panel)
|
||||
- [Password field with PAM submit](#password-field-with-pam-submit)
|
||||
- [Swipe-to-dismiss overlay](#swipe-to-dismiss-overlay)
|
||||
@@ -28,6 +29,45 @@ reference, see [`docs/widgets.md`](./widgets.md). For theme JSON, see
|
||||
|
||||
---
|
||||
|
||||
## Responsive sizing across mobile / tablet / desktop
|
||||
|
||||
Size everything as a fraction of the surface so one view reads
|
||||
coherently from a portrait phone to a landscape desktop window,
|
||||
without per-target forks. The rule is *fluid but clamped*: a `vmin`
|
||||
percentage tracks the surface's smaller side, and a px `clamp` keeps
|
||||
it from collapsing on a tiny screen or ballooning on a 4K monitor.
|
||||
Use `Length::orient( portrait, landscape )` when the *proportion*
|
||||
itself should differ between orientations, and `Image::short_side` to
|
||||
size a logo along the screen's short side while preserving its aspect
|
||||
ratio.
|
||||
|
||||
```rust,no_run
|
||||
# use std::sync::Arc;
|
||||
# use ltk::{ column, img_widget, text, Length, Element };
|
||||
# #[ derive( Clone ) ] enum Msg {}
|
||||
# fn _ex( logo: Arc<Vec<u8>>, lw: u32, lh: u32 ) -> Element<Msg> {
|
||||
column::<Msg>()
|
||||
.padding( Length::vmin( 4.0 ).clamp( 16.0, 48.0 ) )
|
||||
.spacing( Length::vmin( 2.0 ).clamp( 8.0, 24.0 ) )
|
||||
// Logo: 40 % of the width in portrait, 5 % of the height in landscape.
|
||||
.push( img_widget( logo, lw, lh ).short_side( Length::orient( 40.0, 5.0 ) ) )
|
||||
// Heading: fluid, but never below 20 px nor above 44 px.
|
||||
.push( text( "Welcome" ).size( Length::vmin( 6.0 ).clamp( 20.0, 44.0 ) ) )
|
||||
.into()
|
||||
# }
|
||||
```
|
||||
|
||||
Fluid units scale with the screen's pixels, not real-world
|
||||
millimetres. For body text that must stay physically legible and
|
||||
honour the user's font-size preference across an open-ended device
|
||||
set, prefer `Length::dp` or `Length::em` over raw `vmin`; the
|
||||
[`typography`](../src/theme/typography.rs) scale (`h0`…`body_xs`)
|
||||
gives clamped-`vmin` sizes tuned for running text. Reserve
|
||||
`view()`-level branching on `surface_width` / `surface_height` for
|
||||
genuine layout restructuring (sidebar → bottom tabs), not for sizing.
|
||||
|
||||
---
|
||||
|
||||
## Slide-in panel
|
||||
|
||||
A quick-settings or notification panel that slides down from the top of
|
||||
@@ -36,7 +76,7 @@ edge does not knife-cut against the layer below.
|
||||
|
||||
```rust,no_run
|
||||
# use std::time::Instant;
|
||||
# use ltk::{ container, text, viewport, Anchor, Element, Layer, OverlayId, OverlaySpec };
|
||||
# use ltk::{ container, text, viewport, Anchor, Element, Layer, Length, OverlayId, OverlaySpec };
|
||||
# const OVERLAY_QS: OverlayId = OverlayId( 1 );
|
||||
# const SLIDE_DURATION: f32 = 0.25;
|
||||
# #[ derive( Clone ) ] enum Msg { CloseQs }
|
||||
@@ -71,7 +111,7 @@ fn build_quick_settings_overlay( &self ) -> OverlaySpec<Msg>
|
||||
id: OVERLAY_QS,
|
||||
layer: Layer::Overlay,
|
||||
anchor: Anchor::TOP,
|
||||
size: ( self.surface_width, visible_h as u32 ),
|
||||
size: ( Length::px( self.surface_width as f32 ), Length::px( visible_h ) ),
|
||||
exclusive_zone: 0,
|
||||
keyboard_exclusive: false,
|
||||
input_region: None,
|
||||
@@ -211,7 +251,7 @@ A modal panel that closes when the user swipes down past a threshold or
|
||||
taps outside the panel.
|
||||
|
||||
```rust,no_run
|
||||
# use ltk::{ column, container, spacer, text, Anchor, Element, Layer, OverlayId, OverlaySpec };
|
||||
# use ltk::{ column, container, spacer, text, Anchor, Element, Layer, Length, OverlayId, OverlaySpec };
|
||||
# const OVERLAY_MODAL: OverlayId = OverlayId( 2 );
|
||||
# #[ derive( Clone ) ] enum Msg { CloseModal }
|
||||
# struct App { modal_open: bool, modal_drag_progress: f32 }
|
||||
@@ -239,7 +279,7 @@ fn overlays( &self ) -> Vec<OverlaySpec<Msg>>
|
||||
id: OVERLAY_MODAL,
|
||||
layer: Layer::Overlay,
|
||||
anchor: Anchor::ALL,
|
||||
size: ( 0, 0 ),
|
||||
size: ( Length::px( 0.0 ), Length::px( 0.0 ) ),
|
||||
exclusive_zone: 0,
|
||||
keyboard_exclusive: false,
|
||||
input_region: None, // accept input
|
||||
@@ -488,7 +528,7 @@ blocking other UI.
|
||||
|
||||
```rust,no_run
|
||||
# use std::time::Instant;
|
||||
# use ltk::{ container, text, App, Anchor, Color, Element, Layer, OverlayId, OverlaySpec };
|
||||
# use ltk::{ container, text, App, Anchor, Color, Element, Layer, Length, OverlayId, OverlaySpec };
|
||||
# const OVERLAY_TOAST: OverlayId = OverlayId( 3 );
|
||||
# #[ derive( Clone ) ] enum Msg {}
|
||||
struct AppState
|
||||
@@ -539,7 +579,7 @@ impl App for AppState
|
||||
id: OVERLAY_TOAST,
|
||||
layer: Layer::Overlay,
|
||||
anchor: Anchor::BOTTOM,
|
||||
size: ( 0, 0 ),
|
||||
size: ( Length::px( 0.0 ), Length::px( 0.0 ) ),
|
||||
exclusive_zone: 0,
|
||||
keyboard_exclusive: false,
|
||||
input_region: Some( vec![] ), // pass-through
|
||||
|
||||
Reference in New Issue
Block a user