ltk/docs/widgets.md at 96f437544a2a9a0418cd95223cb02f6f8195e55e

Files

Pedro M. de Echanove Pasquin bbab5e238d First commit. Version 0.1.0

2026-05-10 09:58:23 +02:00

24 KiB

Raw Blame History

A flat reference of every widget and layout exported at the crate root. Each entry has the same four sections: what it is, when to use it, minimal example, see also. The full builder API and per-method docs live on cargo doc; this file is the at-a-glance index.

For mental model and architecture, read docs/onboarding.md and docs/architecture.md first. For copy-pasteable patterns built from these widgets, see docs/cookbook.md.

Buttons and activations
- button · icon_button · pressable · window_button · list_item
Stateful binary controls
- toggle · checkbox · radio
Continuous controls
- slider · vslider · progress_bar
Text input and display
- text · text_edit
Decoration and chrome
- container · separator · img_widget
Clipping wrappers
- scroll · viewport · flex
Overlays and feedback
- spinner · toast · tooltip · combo · tabs · notebook · dialog
Pickers
- date_picker · time_picker · color_picker
Layouts
- column · row · stack · grid · spacer

Buttons and activations

`button`

A standard text button. Activates on tap, Enter, or Space when focused.

When: any place a normal app would have a "Save" / "Cancel" / "Send" control.

# use ltk::{ button, Element };
# #[ derive( Clone ) ] enum Msg { Save }
# fn _ex() -> Element<Msg> {
button( "Save" ).on_press( Msg::Save )
.into()
# }

See also: pressable for activation on a richer custom-shaped surface, icon_button for image-only buttons.

`icon_button`

A button whose visual is an RGBA bitmap instead of text. Same dispatch shape as button.

When: toolbar icons, system tray glyphs, anywhere the visual is icon-first.

# use std::sync::Arc;
# use ltk::{ icon_button, Element };
# #[ derive( Clone ) ] enum Msg { OpenSearch }
# fn _ex( rgba_bytes: Arc<Vec<u8>>, w: u32, h: u32 ) -> Element<Msg> {
icon_button( rgba_bytes, w, h ).on_press( Msg::OpenSearch )
.into()
# }

See also: button, window_button (specialised icon button for window decorations).

`pressable`

Wraps any Element so it dispatches a press message. Invisible to drawing — the wrapped child paints itself.

When: a card, a custom-styled list row, or any non-trivial visual that should behave like a button. Inner widgets that are themselves interactive (a button nested inside) keep priority.

# use ltk::{ column, container, pressable, row, Element, Pressable };
# #[ derive( Clone ) ] enum Msg { OpenWifiPicker }
# fn _ex(
#     icon:     Element<Msg>,
#     title:    Element<Msg>,
#     subtitle: Element<Msg>,
# ) -> Pressable<Msg> {
pressable(
    container( row()
        .push( icon )
        .push( column().push( title ).push( subtitle ) ) )
    .surface( "surface-card" )
)
.on_press( Msg::OpenWifiPicker )
# }

See also: button when a plain text button is enough, list_item for the standard "label + subtitle + trailing" pattern.

`window_button`

A title-bar control button (minimize / maximize / restore / close). Comes with a special hover-tint for Close.

When: building custom server-side window decorations.

# use ltk::{ window_button, window_controls, Element, WindowButton, WindowButtonKind };
# #[ derive( Clone ) ] enum Msg { CloseWindow, Minimize, Maximize, Close }
# fn _ex() -> ( WindowButton<Msg>, Element<Msg> ) {
let close = window_button( WindowButtonKind::Close ).on_press( Msg::CloseWindow );

// Or the full standard set:
let bar = window_controls(
    Some( Msg::Minimize ),
    WindowButtonKind::Maximize,
    Some( Msg::Maximize ),
    Some( Msg::Close ),
);
# ( close, bar.into() )
# }

focusable( true ) opts the button into the Tab cycle (off by default to match desktop convention).

See also: [crate::theme_window_controls] for the colour tokens each mode supplies.

`list_item`

A row with a primary label, optional subtitle, optional right-aligned trailing text, and a tappable surface.

When: settings menus, navigation lists, contact rows. Doubles its height when a subtitle is set.

# use ltk::{ list_item, ListItem };
# #[ derive( Clone ) ] enum Msg { OpenWifi }
# fn _ex() -> ListItem<Msg> {
list_item( "Wi-Fi" )
    .subtitle( "Eduroam" )
    .trailing( "›" )
    .on_press( Msg::OpenWifi )
# }

See also: pressable for free-form tappable rows, scroll to wrap a list of items in a scrollable container.

Stateful binary controls

`toggle`

A two-state on / off switch. Renders as a horizontal pill with a sliding thumb.

When: prominent settings toggles ("Wi-Fi", "Do not disturb").

# use ltk::{ toggle, Toggle };
# #[ derive( Clone ) ] enum Msg { ToggleWifi }
# struct App { wifi_enabled: bool }
# impl App { fn _ex( &self ) -> Toggle<Msg> {
toggle( self.wifi_enabled )
    .label( "Wi-Fi" )
    .on_toggle( Msg::ToggleWifi )
# }}

See also: checkbox for less prominent opt-ins, radio for mutually-exclusive groups.

`checkbox`

A two-state opt-in with a square box and a check glyph.

When: form fields, terms acceptance, multi-select lists.

# use ltk::{ checkbox, Checkbox };
# #[ derive( Clone ) ] enum Msg { ToggleTerms }
# struct App { accept_terms: bool }
# impl App { fn _ex( &self ) -> Checkbox<Msg> {
checkbox( self.accept_terms )
    .label( "I accept the terms" )
    .on_toggle( Msg::ToggleTerms )
# }}

See also: toggle, radio.

`radio`

A single option inside a mutually-exclusive group. Build one per variant; the application owns "which is selected".

When: priority pickers, layout choices, anywhere exactly one of N is selected.

# use ltk::{ column, radio, Element };
# #[ derive( Clone, PartialEq ) ] enum Priority { Low, Medium, High }
# #[ derive( Clone ) ] enum Msg { SetPriority( Priority ) }
# struct App { priority: Priority }
# impl App { fn _ex( &self ) -> Element<Msg> {
column()
    .push( radio( self.priority == Priority::Low    ).label( "Low"    ).on_select( Msg::SetPriority( Priority::Low    ) ) )
    .push( radio( self.priority == Priority::Medium ).label( "Medium" ).on_select( Msg::SetPriority( Priority::Medium ) ) )
    .push( radio( self.priority == Priority::High   ).label( "High"   ).on_select( Msg::SetPriority( Priority::High   ) ) )
.into()
# }}

See also: checkbox, toggle.

Continuous controls

`slider`

A horizontal slider for selecting a value in [0.0, 1.0].

When: brightness / volume / scrub bars. Drag the thumb or tap a position; the change message fires continuously during drag.

# use ltk::{ slider, Slider };
# #[ derive( Clone ) ] enum Msg { SetBrightness( f32 ) }
# struct App { brightness: f32 }
# impl App { fn _ex( &self ) -> Slider<Msg> {
slider( self.brightness )
    .on_change( |v| Msg::SetBrightness( v ) )
# }}

accent_thumb( true ) swaps the default thumb for the two-circle brand-coloured variant. track_surface( id ) and fill_surface( id ) override the default theme slots.

See also: vslider for the vertical axis, progress_bar for read-only progress display.

`vslider`

A vertical slider. Same value model as slider — 0.0 at the bottom, 1.0 at the top.

When: column-shaped equalisers, compact volume / brightness picks inside narrow side panels.

# use ltk::{ vslider, VSlider };
# #[ derive( Clone ) ] enum Msg { SetVolume( f32 ) }
# struct App { volume: f32 }
# impl App { fn _ex( &self ) -> VSlider<Msg> {
vslider( self.volume ).on_change( |v| Msg::SetVolume( v ) )
# }}

See also: slider.

`progress_bar`

A read-only linear progress indicator.

When: determinate operations with a known fraction (downloads, file copies, install steps).

# use ltk::{ progress_bar, ProgressBar };
# struct App { download_fraction: f32 }
# impl App { fn _ex( &self ) -> ProgressBar {
progress_bar( self.download_fraction )
# }}

See also: spinner for indeterminate operations without a known fraction.

Text input and display

`text`

A single-line label. Truncates with an ellipsis when wider than its allocated rect.

When: titles, captions, anything non-interactive.

# use ltk::{ text, Color, Element };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex() -> ( Element<Msg>, Element<Msg> ) {
let title    = text( "Title" ).size( 24.0 ).color( Color::WHITE );
let centred  = text( "Centred" ).align_center();
# ( title.into(), centred.into() )
# }

See also: text_edit for editable text.

`text_edit`

A single-line text input with cursor, Backspace, Enter / Submit, clipboard support, a secure( true ) password mode that masks the visible characters and zeroizes the buffer on drop, and a password_toggle( visible, on_toggle ) builder that pins a show / hide-password eye icon to the right edge of the field.

When: login fields, chat inputs, search boxes.

# use ltk::{ text_edit, Element };
# #[ derive( Clone ) ] enum Msg {
#     UsernameChanged( String ), PasswordChanged( String ),
#     TogglePassword, Submit,
# }
# struct App { username: String, password: String, show_password: bool }
# impl App { fn _ex( &self ) -> ( Element<Msg>, Element<Msg> ) {
let user = text_edit( "Username", &self.username )
    .on_change( |s| Msg::UsernameChanged( s ) )
    .on_submit( Msg::Submit );

// Password field with the built-in show / hide eye. The widget
// owns the icon hit-testing — taps inside the eye zone fire
// `TogglePassword` instead of moving the caret. Flip the bool in
// your `update`; the widget reads it back on the next render.
let pw = text_edit( "Password", &self.password )
    .on_change( |s| Msg::PasswordChanged( s ) )
    .password_toggle( self.show_password, Msg::TogglePassword );
# ( user.into(), pw.into() )
# }}

password_toggle keeps the wipe-on-drop and IME-bypass guarantees of secure( true ) regardless of the current visibility, so flipping the eye does not weaken the field's threat model at runtime — only what the user sees on screen changes.

See also: the password recipe in docs/cookbook.md.

Decoration and chrome

`container`

A wrapper that adds padding, a background colour or themed surface, a border radius, and (via theme slots) shadows / inset shadows / backdrop blur.

When: cards, panels, callouts, anywhere a child needs a backdrop or elevation.

# use ltk::{ column, container, Element };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex( title: Element<Msg>, subtitle: Element<Msg> ) -> Element<Msg> {
container( column().push( title ).push( subtitle ) )
    .surface( "surface-card" )
    .padding( 16.0 )
    .radius( 24.0 )
.into()
# }

Per-edge padding is available with padding_top / padding_right / padding_bottom / padding_left. Per-corner radius takes a [Corners] struct or a tuple.

See also: pressable wrapping a container makes a card interactive.

`separator`

A horizontal divider line with theme-default colour and 1 px thickness.

When: visual breaks between settings groups, list categories, content blocks.

# use ltk::{ column, separator, text, Element };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex() -> Element<Msg> {
column()
    .push( text( "General" ) )
    .push( separator() )
    .push( text( "Network" ) )
.into()
# }

`img_widget`

A static image rendered from RGBA pixel data shared via Arc.

When: wallpapers, icons, illustrations. The shared Arc makes re-using the same buffer across frames a pointer copy.

# use std::sync::Arc;
# use ltk::{ img_widget, Element };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex( rgba_bytes: Arc<Vec<u8>>, width: u32, height: u32 ) -> Element<Msg> {
img_widget( rgba_bytes, width, height )
    .opacity( 0.8 )
.into()
# }

cover() scales to fill the rect preserving aspect; size( w, h ) sets explicit display dimensions.

See also: Image::from_path helper for disk-loaded files (PNG, JPEG via the image crate).

Clipping wrappers

`scroll`

A vertically-scrollable viewport. Drag the content to scroll; clipping is automatic.

When: lists or grids that may overflow the available height.

# use ltk::{ column, list_item, scroll, Element };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex() -> Element<Msg> {
scroll(
    column()
        .push( list_item::<Msg>( "Item 1" ) )
        .push( list_item( "Item 2" ) )
        .push( list_item( "Item 3" ) )
)
.into()
# }

The scroll widget owns its own gesture handling — drags inside it do not trigger the app-level on_swipe_* callbacks.

See also: viewport for passive clipping without gestures, grid inside a scroll for app drawers.

`viewport`

A passive clipping wrapper. Clips its child to the assigned rect; no scrolling, no gesture handling.

When: panels that animate in via a parent translation, fade-in content, anywhere you want a hard clip without scrolling. The fade_bottom( px ) builder feathers the bottom edge to transparent during slide-in animations (GLES backend; software backend renders a hard edge).

# use ltk::{ viewport, Element };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex( panel_view: Element<Msg>, panel_height: f32 ) -> Element<Msg> {
viewport( panel_view )
    .height( panel_height )
    .fade_bottom( 16.0 )
.into()
# }

See also: the slide-in panel recipe in docs/cookbook.md.

`flex`

A row-only filler wrapper. Treats its non-spacer child like a spacer for leftover-width distribution but draws the child inside the allocated rect.

When: a row where one non-trivial child should fill the remaining width (a card next to a fixed-size icon).

# use ltk::{ column, flex, row, Element };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex(
#     icon:     Element<Msg>,
#     title:    Element<Msg>,
#     subtitle: Element<Msg>,
# ) -> Element<Msg> {
row()
    .push( icon )
    .push( flex( column().push( title ).push( subtitle ) ) )
.into()
# }

weight( n ) sets the relative share when there are several flex / spacer siblings.

See also: spacer for invisible fillers, column and row.

Overlays and feedback

`spinner`

Indeterminate progress indicator. Animates while in the tree.

When: long-running operations with no known fraction (network calls, indexing, "waiting for compositor").

# use ltk::{ spinner, Spinner };
# fn _ex() -> Spinner {
spinner().size( 24.0 )
# }

See also: progress_bar for determinate progress.

`toast`

Transient notification that floats over the surface and dismisses itself after a timeout.

When: confirmation snackbars ("Saved"), non-blocking errors, status flashes.

# use ltk::{ toast, Toast };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex() -> Toast<Msg> {
toast( "Saved" ).duration( 3.0 )
# }

See also: tooltip for hover-anchored hints.

`tooltip`

Anchored hint that appears next to a target widget on hover or focus.

When: discoverable affordances on icon-only controls, keyboard shortcut reminders, helper text that should not occupy permanent layout space.

# use ltk::{ tooltip, Tooltip, WidgetId };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex() -> Tooltip<Msg> {
tooltip( "Ctrl+S", WidgetId( "btn/save" ) ).max_width( 240 )
# }

The widget paints next to the widget that registered the matching WidgetId. See docs/cookbook.md for the full overlay wiring.

See also: toast for transient self-dismissing notifications.

`combo`

Editable single-select with a popup list. Supports type-to-filter and free-text entry.

When: pick-one fields with too many options for a row of radio buttons but where a free typed answer is also valid (autocomplete, country list, theme picker).

# use ltk::{ combo, Combo, ComboState };
# #[ derive( Clone ) ] enum Msg { Pick( usize ) }
# fn _ex( state: ComboState ) -> Combo<Msg> {
let items = vec![
    "One".to_string(),
    "Two".to_string(),
    "Three".to_string(),
];
combo( state, items ).on_select_idx( Msg::Pick )
# }

See also: radio for small mutually-exclusive sets, notebook for tabbed mode switches.

`tabs`

A bare tab bar — visual selection without owning the page content. Use this when you want full control over what each tab shows.

When: paged settings screens where the panes are large and you want to keep them as siblings in the tree, not as notebook children.

# use ltk::{ tabs, TabBar };
# #[ derive( Clone ) ] enum Msg { TabChanged( usize ) }
# fn _ex( active: usize ) -> TabBar<Msg> {
tabs::<Msg, _, _>( [ "Profile", "Network", "Privacy" ] )
    .selected( active )
    .on_select( Msg::TabChanged )
# }

See also: notebook for tabs that own their pages.

`notebook`

Tabbed container. Owns the pages and shows only the active one.

When: settings dialogs, multi-step forms, anywhere a flat tabs bar over hand-managed pages would be more code than benefit.

# use ltk::{ notebook, text, Notebook };
# #[ derive( Clone ) ] enum Msg { TabChanged( usize ) }
# fn _ex( active: usize ) -> Notebook<Msg> {
notebook::<Msg>()
    .page( "General",  text( "general body"  ) )
    .page( "Advanced", text( "advanced body" ) )
    .selected( active )
    .on_select( Msg::TabChanged )
# }

See also: tabs for a bare tab bar without page ownership.

`dialog`

Modal or non-modal centered confirmation card with a built-in scrim, optional title, subtitle, custom body, and a right-aligned action row. Pressing Esc fires the configured cancel message.

When: destructive confirmations ("Delete file?"), guided pickers that block other interaction until resolved, "are you sure" gates before a long-running operation.

# use ltk::{ button, dialog, ButtonVariant, Element };
# #[ derive( Clone ) ] enum Msg { Cancel, Confirm }
# fn _ex() -> Element<Msg> {
dialog()
    .title( "Delete partition?" )
    .subtitle( "This will erase every file on /dev/sda2." )
    .cancel( Msg::Cancel )
    .action( button::<Msg>( "Cancel" ).variant( ButtonVariant::Tertiary ).on_press( Msg::Cancel ) )
    .action( button::<Msg>( "Delete" ).variant( ButtonVariant::Primary  ).on_press( Msg::Confirm ) )
    .into()
# }

modal( false ) + dismiss_on_scrim( msg ) makes a tap on the dim background fire msg; combining dismiss_on_scrim with modal( true ) panics at lower time (the contracts contradict). body( elem ) swaps a custom element in between the subtitle and the action row — the example app at examples/dialog.rs uses this for an in-dialog slider.

See also: toast for non-blocking transient notifications, combo for a single-pick popup that does not require modal blocking.

Pickers

`date_picker`

Calendar-grid date selector with month / year navigation.

When: birthdays, deadlines, any single-date input.

# use ltk::{ date_picker, Date, DatePicker };
# #[ derive( Clone ) ] enum Msg { Picked( Date ) }
# fn _ex() -> DatePicker<Msg> {
date_picker( Date::new( 2026, 5, 7 ) ).on_change( Msg::Picked )
# }

`time_picker`

Hour / minute selector. Wheel-style scrubbing on touch.

When: alarms, scheduling, time-of-day input.

# use ltk::{ time_picker, Time, TimePicker };
# #[ derive( Clone ) ] enum Msg { Picked( Time ) }
# fn _ex( now: Time ) -> TimePicker<Msg> {
time_picker( now ).on_change( Msg::Picked )
# }

`color_picker`

Hue + saturation/value picker with a hex/RGB readout.

When: theming UIs, paint tools, accent customisation.

# use ltk::{ color_picker, Color, ColorPicker };
# #[ derive( Clone ) ] enum Msg { Picked( Color ) }
# fn _ex( current: Color ) -> ColorPicker<Msg> {
color_picker( current ).on_change( Msg::Picked )
# }

Layouts

`column`

Vertical flow. Children stack top-to-bottom with optional padding, spacing, alignment.

# use ltk::{ button, column, spacer, text, Element };
# #[ derive( Clone ) ] enum Msg { Ok }
# fn _ex() -> Element<Msg> {
column()
    .padding( 24.0 )
    .spacing( 12.0 )
    .push( text( "Title" ) )
    .push( spacer() )
    .push( button( "OK" ).on_press( Msg::Ok ) )
.into()
# }

max_width(px) caps the inner content width; fit_content() reports the natural content width to the parent (otherwise the column claims the full available width). center_y( true ) centres the content block vertically when there are no spacers.

`row`

Horizontal flow. Mirror of column on the X axis.

# use ltk::{ flex, row, Element };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex(
#     label:         Element<Msg>,
#     field:         Element<Msg>,
#     submit_button: Element<Msg>,
# ) -> Element<Msg> {
row()
    .spacing( 8.0 )
    .push( label )
    .push( flex( field ) )
    .push( submit_button )
.into()
# }

`stack`

Z-order overlay. Each child gets explicit horizontal and vertical alignment (HAlign / VAlign) plus an optional margin and pixel translation. Children are drawn in declaration order — the last child sits on top.

# use std::sync::Arc;
# use ltk::{ button, column, img_widget, stack, text, Element, HAlign, VAlign };
# #[ derive( Clone ) ] enum Msg { Add }
# fn _ex( background: Arc<Vec<u8>>, w: u32, h: u32 ) -> Element<Msg> {
stack()
    .push( img_widget( background, w, h ) )
    .push_aligned(
        column().push( text( "Heading" ) ),
        HAlign::Center, VAlign::Center,
    )
    .push_aligned_margin(
        button( "+" ).on_press( Msg::Add ),
        HAlign::End, VAlign::Bottom,
        16.0,
    )
.into()
# }

See also: column and row for flow layout.

`grid`

Fixed-column-count grid that wraps its children into rows.

When: icon launchers, photo galleries, app drawers.

# use std::sync::Arc;
# use ltk::{ grid, icon_button, Element };
# #[ derive( Clone ) ] enum Msg { OpenApp1, OpenApp2 }
# fn _ex( app1_rgba: Arc<Vec<u8>>, app2_rgba: Arc<Vec<u8>>, w: u32, h: u32 ) -> Element<Msg> {
grid( 4 )
    .padding( 16.0 )
    .spacing( 12.0 )
    .push( icon_button( app1_rgba, w, h ).on_press( Msg::OpenApp1 ) )
    .push( icon_button( app2_rgba, w, h ).on_press( Msg::OpenApp2 ) )
    // ...
.into()
# }

Wrap inside scroll when the grid may overflow.

`spacer`

An invisible flexible filler. Inside a column / row, absorbs leftover space along the parent's main axis.

# use ltk::{ column, spacer, Element };
# #[ derive( Clone ) ] enum Msg {}
# fn _ex( header: Element<Msg>, footer: Element<Msg> ) -> Element<Msg> {
column()
    .push( header )
    .push( spacer() )       // pushes footer to the bottom
    .push( footer )
.into()
# }

weight( n ) sets the relative share; height( px ) / width( px ) pin the spacer to a fixed size on its respective axis.

See also: flex for a non-empty filler.

24 KiB Raw Blame History Unescape Escape

ltk widget catalogue

Table of contents

Buttons and activations

button

icon_button

pressable

window_button

list_item

Stateful binary controls

toggle

checkbox

radio

Continuous controls

slider

vslider

progress_bar

Text input and display

text

text_edit

Decoration and chrome

container

separator

img_widget

Clipping wrappers

scroll

viewport

flex