Crate iced

Iced is a cross-platform GUI library focused on simplicity and type-safety. Inspired by Elm.

Features

• Simple, easy-to-use, batteries-included API
• Type-safe, reactive programming model
• Cross-platform support (Windows, macOS, Linux, and the Web)
• Responsive layout
• Built-in widgets (including text inputs, scrollables, and more!)
• Custom widget support (create your own!)
• Debug overlay with performance metrics
• First-class support for async actions (use futures!)
• Modular ecosystem split into reusable parts:
  • A renderer-agnostic native runtime enabling integration with existing systems
  • A built-in renderer supporting Vulkan, Metal, DX11, and DX12
  • A windowing shell
  • A web runtime leveraging the DOM

Check out the repository and the examples for more details!

Overview

Inspired by The Elm Architecture, Iced expects you to split user interfaces into four different concepts:

• State — the state of your application
• Messages — user interactions or meaningful events that you care about
• View logic — a way to display your state as widgets that may produce messages on user interaction
• Update logic — a way to react to messages and update your state

We can build something to see how this works! Let’s say we want a simple counter that can be incremented and decremented using two buttons.

We start by modelling the state of our application:

struct Counter {
    // The counter value
    value: i32,
}

Next, we need to define the possible user interactions of our counter: the button presses. These interactions are our messages:

#[derive(Debug, Clone, Copy)]
pub enum Message {
    IncrementPressed,
    DecrementPressed,
}

Now, let’s show the actual counter by putting it all together in our view logic:

use iced::widget::{button, column, text, Column};

impl Counter {
    pub fn view(&mut self) -> Column<Message> {
        // We use a column: a simple vertical layout
        column![
            // The increment button. We tell it to produce an
            // `IncrementPressed` message when pressed
            button("+").on_press(Message::IncrementPressed),

            // We show the value of the counter here
            text(self.value).size(50),

            // The decrement button. We tell it to produce a
            // `DecrementPressed` message when pressed
            button("-").on_press(Message::DecrementPressed),
        ]
    }
}

Finally, we need to be able to react to any produced messages and change our state accordingly in our update logic:

impl Counter {
    // ...

    pub fn update(&mut self, message: Message) {
        match message {
            Message::IncrementPressed => {
                self.value += 1;
            }
            Message::DecrementPressed => {
                self.value -= 1;
            }
        }
    }
}

And that’s everything! We just wrote a whole user interface. Iced is now able to:

1. Take the result of our view logic and layout its widgets.
2. Process events from our system and produce messages for our update logic.
3. Draw the resulting user interface.

Usage

The Application and Sandbox traits should get you started quickly, streamlining all the process described above!

Re-exports

• pub use application::Application;
• pub use settings::Settings;
• pub use runtime::futures;

Modules

• alignment
  Align and position widgets.
• application
  Build interactive cross-platform applications.
• clipboard
  Access the clipboard.
• event
  Handle events of a user interface.
• executor
  Choose your preferred executor to power your application.
• keyboard
  Listen and react to keyboard events.
• mouse
  Listen and react to mouse events.
• overlay
  Display interactive elements on top of other widgets.
• settings
  Configure your application.
• subscription
  Listen to external events in your application.
• theme
  Use the built-in theme and styles.
• time
  Listen and react to time.
• touch
  Listen and react to touch events.
• widget
  Display information and interactive controls in your application.
• window
  Configure the window of your application in native platforms.

Macros

• color
  Creates a Color with shorter and cleaner syntax.

Structs

• Color
  A color in the sRGB color space.
• Command
  A set of asynchronous actions to be performed by some runtime.
• Padding
  An amount of space to pad for each side of a box
• Point
  A 2D point.
• Rectangle
  A rectangle.
• Size
  An amount of space in 2 dimensions.
• Vector
  A 2D vector.

Enums

• Alignment
  Alignment on the axis of a container.
• Background
  The background of some element.
• ContentFit
  The strategy used to fit the contents of a widget to its bounding box.
• Error
  An error that occurred while running an application.
• Event
  A user interface event.
• Font
  A font.
• Length
  The strategy used to fill space in a specific dimension.
• Theme
  A built-in theme.

Traits

• Executor
  A type that can run futures.
• Sandbox
  A sandboxed Application.

Type Definitions

• Element
  A generic widget.
• Renderer
  A wgpu graphics renderer for iced.
• Result
  The result of running an Application.
• Subscription
  A request to listen to external events.