iced-rs
Iced 0.14 GUI expert: custom widgets via iced::advanced, overlays, Canvas, Shader, pane_grid, theming, subscriptions, Elm architecture, with a bundled full-API reference. Load whenever building or debugging an Iced UI.
vanillagreencom · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add vanillagreencom/kendex --skill iced-rs技能说明
name: iced-rs description: "Load whenever building or debugging an Iced UI." summary: "Iced 0.14 GUI reference: custom widgets via iced::advanced, overlays, Canvas, Shader, pane_grid, theming, subscriptions, Elm architecture, with a bundled full-API reference." license: MIT user-invocable: true metadata: author: vanillagreen source: kendex repository: "https://github.com/vanillagreencom/kendex" bugs: "https://github.com/vanillagreencom/kendex/issues" version: "3.0.0" tags: [ui]
Project Instructions
Problems with a kendex-owned skill go through kendex report; check ownership in the file first.
Iced 0.14
Workflow
- Classify the surface against
references/guide-surface-selection.md. Do not skip. - Read the canonical example in
examples/, never generate 0.14 code from memory. - Read the guide for that surface; for animated layered UI,
references/guide-animated-layout.mdcomes first. - Stuck: the guide's "Common failure modes" / "Gotchas", then
references/guide-animation-debugging.mdfor animation and render bugs. The three most common: missingcapture_event, missinginvalidate_layout, 0.13 event signatures.
Surface choice: built-in widgets + .style(closure) for standard UI; Canvas for 2D custom drawing; Shader for GPU-dense rendering; iced::advanced::Widget for custom events, state, or layout; for a floating layer try tooltip, float, or stack+opaque before a custom Overlay.
Bundled resources
references/: API refs and guides
Full list in references/INDEX.md; load on demand.
| Guide | Use |
|---|---|
guide-surface-selection.md | Pick the right primitive |
guide-custom-widgets.md | iced::advanced::Widget |
guide-custom-overlays.md | iced::advanced::overlay::Overlay |
guide-animated-layout.md | Animated transitions, measured positions, keyed identity, clipping |
guide-animation-debugging.md | Symptom→cause checklist for animation/render bugs |
widgets.md | Widget catalog: every 0.14 widget, notes, canonical example |
examples/: every upstream Iced 0.14 example
| Need | Read first |
|---|---|
| Custom Widget impl | examples/custom_widget/src/main.rs |
| GPU shader pipeline | examples/custom_shader/ (full dir) |
| Mesh / vector geometry widget | examples/geometry/src/main.rs |
| Canvas 2D drawing | examples/bezier_tool, examples/clock, examples/color_palette |
| Canvas animation | examples/solar_system, examples/the_matrix, examples/game_of_life |
| Arc/ring animation | examples/loading_spinners, examples/arc |
| Modal dialog | examples/modal/src/main.rs (stack + opaque) |
| Toast/notification overlay | examples/toast/src/main.rs |
| Tooltip / zoom-on-hover | examples/loupe/src/main.rs |
| Styled components | examples/styling/ |
| pane_grid layout | examples/pane_grid/ |
| Multi-window | examples/multi_window/ |
| WebSocket subscription | examples/websocket/ |
| Text editing | examples/editor/ |
iced_wgpu/ and external fallbacks
Renderer source for shader work: iced_wgpu/src/ (engine.rs, layer.rs, quad.rs, quad/solid.rs, quad/gradient.rs, triangle.rs, triangle/msaa.rs, primitive.rs, buffer.rs, shader/quad.wgsl). Local references are pinned to 0.14.0; prefer them. For newer API surface: ctx7 docs /websites/rs_iced_iced "<query>", https://docs.rs/iced/0.14.0/iced/, or upstream master at https://github.com/iced-rs/iced (may have unreleased APIs).
Breaking changes from Iced 0.13
Widget::updatetakesevent: &Event(by ref, not by value)Widget::layouttakes&mut Tree- Keyboard subscriptions unified into
keyboard::listen
Rules (non-negotiable framework invariants)
Widget tree consistency
Conditional wrapping changes tree shape and breaks event tracking. Always wrap; conditionally attach the handler.
// WRONG: conditional wrapping changes tree shape
if dragging { mouse_area(label).into() } else { label.into() }
// RIGHT
let mut area = mouse_area(label);
if enable {
area = area.on_press(msg);
}
area
MouseArea has no on_press_maybe (button-only); gate the on_press call, not the wrapper.
view() is pure
No side effects, no memoization dependent on call frequency. All mutable state lives in State and is mutated only in update(). Never trigger redraws from view().
Redraw vs rebuild
request_redraw() repaints but does not call view(). Animation state must live in widget::Tree state. Widget struct fields are frozen between view() calls. See references/animation.md § "Redraw vs rebuild."
Animation invalidation
Paint-only changes (color, opacity, rotation within fixed bounds) need shell.request_redraw(). Layout-affecting changes (size, position, expand/collapse, clipping bounds) need shell.request_redraw() and shell.invalidate_layout(). A widget that "only updates on the second click" has stale layout. Add invalidate_layout().
Draw order is z-order
In custom widget draw(), child iteration order determines z-order; last drawn is on top. stack semantics do not apply inside manual draw loops.
Overlay visibility requires layout invalidation
A widget that conditionally returns an overlay must call shell.invalidate_layout() when visibility changes.
Custom overlays are the #1 panic source
Prefer built-ins (tooltip, float, stack+opaque). A violated contract panics as container.rs unwrap() on None. The contract: children() returns a fixed count; diff() reconciles all children regardless of visibility; layout() returns nodes matching children; draw() walks the same tree layout produced. Full spec: references/guide-custom-overlays.md.
Overlay viewport contract
When calling descendant Widget methods from inside an `Ove