Skip to main content

Crate icedtea

Crate icedtea 

Source
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 hereRole
app / run!Boot the window
action / key / shortcutCommands and chords
theme / variant / typo / motionColor, variant, type, motion
a11yName, role, value, hint, and state on every constructor
widget / collectionControls, lists, tables
selectSelect-and-copy contract for content text
layout / pattern / windowRecipes 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 with handle.
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.