Expand description
Native desktop widgets and chrome for iced.
icedtea opens a themed window, paints controls from semantic tokens,
and routes one action::Action table through menus, toolbars,
shortcuts, and the command palette. A constructor is a function
that returns an iced Element and sends your message. Your
program owns the data (and any database file).
§First compose
One Action feeds the toolbar. The same message is Save:
use icedtea::action::{Action, ActionTable};
use icedtea::i18n::Direction;
use icedtea::pattern;
use icedtea::shortcut::Shortcut;
use icedtea::theme;
let tok = theme::named("dark").tokens;
let save = ();
let mut table = ActionTable::new();
table.insert(
Action::new("file.save", "Save", save)
.with_shortcut(Shortcut::parse("ctrl+s").unwrap()),
);
let chrome: icedtea::Element<'_, ()> =
pattern::toolbar(table.iter(), tok, Direction::Ltr);
let _ = chrome;
assert_eq!(table.invoke("file.save"), Some(save));§Boot
run! opens that window. daemon! is the same Prepared
settings on iced::daemon: no window until Prepared::open,
and the process stays up when the last window closes.
The same program is
examples/hello.rs.
icedtea::run!(
icedtea::Boot::new("Notes", "dev.example.hello"),
Hello::new,
Hello::update,
Hello::view,
Hello::theme,
)§Keys
run! subscribes key::listen. Implement
From<keyboard::Event> on the application message. Wrap view
with focus::cycle. A focused list, tree, slider, or pick owns
arrows, Enter, and Space. Escape closes an open menu, pick,
context menu, drawer, or cancel dialog. Application windows call
ActionTable::seed_quit.
key::handle matches the table after an open modal and after
focused text:
use icedtea::action::{Action, ActionTable};
use icedtea::key::{handle, KeyContext};
use icedtea::shortcut::Shortcut;
let save = ();
let mut table = ActionTable::new();
table.insert(
Action::new("file.save", "Save", save)
.with_shortcut(Shortcut::parse("ctrl+s").unwrap()),
);
let ev = iced::keyboard::Event::KeyPressed {
key: iced::keyboard::Key::Character("s".into()),
modified_key: iced::keyboard::Key::Character("s".into()),
physical_key: iced::keyboard::key::Physical::Unidentified(
iced::keyboard::key::NativeCode::Unidentified,
),
location: iced::keyboard::Location::Standard,
modifiers: icedtea::shortcut::primary(),
text: None,
repeat: false,
};
assert_eq!(handle(KeyContext::default(), &table, &ev), Some(save));§Tokens
theme::named picks a colorway. light and dark are a neutral
desktop pair; follow-OS layers host chrome on that pair. Other
catalog names are a choice. Control paint paths read roles through
Tokens::scheme. Short fields (primary,
text, …) are aliases of those roles. Type size, corners, and
shadows follow Tokens::font_scale,
Tokens::shape, and
Tokens::elevation. Default chrome is
M3 shape None (0 dp, rectangular). theme::mix builds washes:
use icedtea::theme;
let tok = theme::named("dark").tokens;
let s = tok.scheme();
assert_eq!(theme::selection_fill(tok), s.secondary_container);
assert_eq!(s.on_surface, tok.text);§A widget
The hello editor is widget::textarea. The application owns the
buffer:
use icedtea::a11y::{A11y, Role};
use icedtea::theme;
use icedtea::widget;
#[derive(Clone)]
enum Message {
Edit(icedtea::iced::widget::text_editor::Action),
}
let tok = theme::named("dark").tokens;
let content = icedtea::iced::widget::text_editor::Content::new();
let editor: icedtea::Element<'_, Message> = widget::textarea(
&content,
Message::Edit,
tok,
icedtea::layout::FILL,
A11y::new("notes", Role::TextBox),
);
let _ = editor;§A pattern
pattern::toolbar paints the same file.save row:
use icedtea::action::{Action, ActionTable};
use icedtea::i18n::Direction;
use icedtea::pattern;
use icedtea::theme;
let tok = theme::named("dark").tokens;
let save = ();
let mut table = ActionTable::new();
table.insert(Action::new("file.save", "Save", save));
let bar: icedtea::Element<'_, ()> =
pattern::toolbar(table.iter(), tok, Direction::Ltr);
let _ = bar;§Scope
icedtea is chrome, actions, layout, and theme for iced desktop
applications. Constructors return Elements and emit the
application’s messages. A later job — a personal task list that
writes a SQLite file — is in the
guide cookbook.
§Non-goals
- A new renderer or a fork of iced. icedtea tracks iced releases.
- A stylesheet or markup language. Authors write Rust.
- Mobile, web, or embedded targets.
- A visual form designer.
- An in-process web view, print pipeline, or multimedia stack.
- Multiple-document-interface window mosaics.
- Binding the look to one desktop shell. Themes may follow system light/dark; chrome stays icedtea’s.
- Domain widgets that own a product protocol or store (session timelines, language services, mail accounts, host services). Applications own those. A face, header slot, or window knob a second app would call is library chrome.
- Document undo/redo. Applications own history.
- Sample documents and bitmaps as library API.
- A second collection widget for variable-height cards. Extend list.
- Library-owned parse caches or live-update daemons.
- System-wide hotkeys, host focus steal, or baking another toolkit’s theme files.
§Modules
| Start here | Role |
|---|---|
app / run! | Boot the window |
action / key / shortcut | Commands and chords |
theme / variant / typo / motion | Color, variant, type, motion |
a11y | Name, role, value, hint, and state on every constructor |
widget / collection | Controls, lists, tables |
select | Select-and-copy contract for content text |
layout / pattern / window | Recipes and chrome |
The guide walks composition and lists every public constructor. crates.io · source.
Re-exports§
pub use app::bootstrap;pub use app::Boot;pub use app::Prepared;pub use host::copy_rich;pub use host::copy_text;pub use host::native_dialog;pub use host::paste_text;pub use self;
Modules§
- a11y
- Accessible name, role, value, hint, and state for every public widget.
- action
- One action type for menus, toolbars, shortcuts, and the command palette.
- app
- Bootstrap: theme, locale, window settings for iced’s application builder.
- catalog
- Public widget and pattern ids.
- chrome
- Radius and elevation presets (Material Design 3).
- clipboard
- Clipboard text payloads.
- collection
- List / table / tree models and virtualization.
- density
- Spacing densities on a 4 dp Material grid.
- dialog
- Dialog specifications (native host executes file dialogs).
- dnd
- Drag-and-drop payloads: text and file paths.
- field
- Named read-only text the user can select and copy.
- focus
- Focus target, roving tabindex, spatial arrows, landmarks, live regions.
- fuzzy
- Fuzzy ranking for the command palette.
- host
- Native file dialogs and clipboard tasks.
- i18n
- Locale, direction, and chrome string catalogs.
- icon
- Bundled chrome icons.
- key
- Key handling: subscribe with
listen, resolve withhandle. - layout
- Layout recipes, size policy, and breakpoints.
- m3
- Material Design 3 foundations for icedtea.
- motion
- Overlay, disclose, switch, and attention paint from a 0..=1 progress.
- nav
- Page stack: push, pop, replace, automatic back.
- palette
- Keyboard-first command palette over an action table.
- pattern
- Application chrome: menu, toolbar, list/detail, prefs, about, palette.
- persist
- Save and restore window geometry, splits, docks, theme, and look.
- select
- Unified select-and-copy for content text.
- shortcut
- Keyboard shortcuts on actions.
- style
- iced style closures painted from M3 roles and control states.
- theme
- Semantic color tokens, mixing rules, and the named community catalog.
- toast
- Transient toast queue.
- typo
- Type scale. UI is the platform sans; code is the platform mono.
- variant
- Named control variants.
- widget
- Themed iced widget constructors for
view. - window
- Window kinds, overlay placement, and hide policy.
- workspace
- Nested dock tree: splits, tab groups, persist, perspectives.
Macros§
- daemon
- Boot theme and iced settings, then start
iced::daemon. - run
- Boot theme and window settings, then start iced’s application builder.
Structs§
- Task
- A set of concurrent actions to be performed by the iced runtime.
Type Aliases§
- Element
- A generic widget.