Iced

A renderer-agnostic GUI library for Rust focused on simplicity and type-safety. Inspired by [Elm].

Features

• Simple, easy-to-use, renderer-agnostic API
• Responsive, flexbox-based layouting
• Type-safe, reactive programming model
• Built-in widgets
• Custom widget support

Iced is in a experimental stage. [Check out the issues] and [feel free to contribute!].

Installation

Add iced as a dependency in your Cargo.toml:

toml iced = "0.1"

Iced moves fast and the master branch can contain breaking changes! If you want to learn about a specific release, check out [the release list].

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:

```rust use iced::button;

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

// The local state of the two buttons
increment_button: button::State,
decrement_button: button::State,

} ```

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

```rust

[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:

```rust use iced::{Button, Column, Text}; use iced_wgpu::Renderer; // Iced does not include a renderer! We need to bring our own!

impl Counter { pub fn view(&mut self) -> Column { // We use a column: a simple vertical layout Column::new() .push( // The increment button. We tell it to produce an // IncrementPressed message when pressed Button::new(&mut self.incrementbutton, "+") .onpress(Message::IncrementPressed), ) .push( // We show the value of the counter here Text::new(&self.value.tostring()).size(50), ) .push( // The decrement button. We tell it to produce a // DecrementPressed message when pressed Button::new(&mut self.decrementbutton, "-") .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:

```rust 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 using our chosen renderer.

Browse the [documentation] and the [examples] to learn more!

Implementation details

Iced was originally born as an attempt at bringing the simplicity of [Elm] and [The Elm Architecture] into [Coffee], a 2D game engine I am working on.

The core of the library was implemented during May in [this pull request], using [stretch] for flexbox-based layouting. It was later released as the main feature of [Coffee 0.3.0].

After release, different folks suggested me to split the new [ui module] into its own standalone crate, as it could potentially benefit other engines and applications. I thought it was a great idea, and after a bit of work... Iced is here!

As an interesting note, Iced does not rely on reference counting and interior mutability. There is not a single Rc, RefCell, or similar used directly in the library. As a consequence, compiler guarantees stay intact and many kinds of pesky bugs and runtime errors are banished. No spooky action at a distance!

Contributing / Feedback

If you want to contribute, you are more than welcome to be a part of the project! Check out the current [issues] if you want to find something to work on. Try to share you thoughts first! Feel free to open a new issue if you want to discuss new ideas.

Any kind of feedback is welcome! You can open an issue or, if you want to talk, you can find me (and a bunch of awesome folks) over the #games-and-graphics and #gui-and-ui channels in the [Rust Community Discord]. I go by @lone_scientist there.