Relm Blog

A big release for relm

Sun, 14 Feb 2021 00:00:00 +0000

It’s been a while since I’ve written in this blog, but the development continues!

I just released relm 0.21 which is probably the biggest release since the inception of this idiomatic GUI library for Rust.

So, what’s new in this release?

Nested `view!` macro

The biggest usability improvement of this release is the ability to use nested view! macros. Previously, we couldn’t create gtk::Menu with the declarative syntax because gtk::Menu behaves differently than the other widgets. You have to call set_submenu() to add items to a menu instead of just adding the items as children of the menu.

With nested view! macros, we can now create a gtk::Menu using the declarative syntax, like the following example shows:

gtk::MenuBar {
    gtk::MenuItem {
        label: "File",
        submenu: view! {
            gtk::Menu {
                gtk::MenuItem {
                    label: "Quit",
                },
            },
        }
    },
}

This also works with other widgets, like the title bar which makes it easier to write a responsive application using libhandy:

gtk::Window {
    titlebar: view! {
        handy::HeaderBar {
            show_close_button: true,
            title: Some("handy title"),
        },
    }
}

It’s time to start using relm on your PinePhone!

Ability to create multiple objects in a single `view!` macro

In GTK+, there are objects that you would want to create that are not widgets. It would still be useful to create them using the view! macro but where would they go in it? They cannot be add in another widget, since it’s not a widget. One example was gtk::Gesture. Well, now it is possible to add objects after the main widget. Here’s an example:

view! {
    gtk::Window {
        gtk::Box {
            orientation: Vertical,
            #[name="drawing_area"]
            gtk::DrawingArea {
                child: {
                    expand: true,
                }
            },
        },
        delete_event(_, _) => (Quit, Inhibit(false)),
    }

    gtk::GestureDrag(&self.drawing_area) {
        drag_begin(_, x, y) => Click(x, y),
        drag_update(_, x, y) => Move(x, y),
        drag_end(_, _, _) => End,
    }
}

Fix reference cycle

For a long time, there was an issue in relm that could cause reference cycles and thus, leak memory. This is now fixed by the introduction of a new type StreamHandle which is a weak reference to an EventStream. This new version of relm might cause your application to stop working in case you were relying on this bug. The solution is to keep a reference to your components in order for them to not be dropped instantly.

I used to be able to prevent breaking changes for the users of the #[widget] attribute, but for this fix, I was unable to prevent it.

Here are what changed:

The widgets now reside inside self.widgets instead of self directly.
The component streams are avaible inside self.streams.
The type StreamHandle must be used instead of EventStream or sometimes even instead of ContainerComponent.

To have an example of how to do this update, you can look at the commit that updates to relm 0.21 for two big projects using it:

titanium
mg

The road ahead

With these new features and this big fix, the biggest road blockers towards a 1.0 version are done.

The biggest remaining thing is probably to finish writing the tutorial.

As always, please report bugs you find and your feature requests on GitHub.

Relm drop support for futures!

Sun, 01 Apr 2018 00:00:00 +0000

Un concepteur sait qu’il a atteint la perfection non pas quand il n’y a plus rien à ajouter mais quand il ne reste rien à enlever.

— Antoine de Saint-Exupery

Relm is an attempt to do an idiomatic GUI library in Rust, based on gtk+. See the introduction article for details about why this library was created and how to use it.

New release

I’ve just released relm version 0.14!

This new release, like the previous one, does not provide a bunch of new features, but fix a very important issue: it removes the dependency on futures.

The reason for that is to simplify the library. Indeed, futures and tokio are generic, abstract libraries that can be quite complex to use. Many of the reasons why I decided to drop these crates are explained in this blog article. One point that is not mentioned there is that it is incredibly difficult to write a library for a new protocol implemented on top of tokio. Why is that? Simply because there’s no way to debug issues like why isn’t this fd polled except using strace.

So, what’s the alternative? If you don’t need async IO, well, you don’t need anything and you won’t have this extra complexity anymore. If you need it, you can use the gio async methods with one of the connect_async! macros. The now working http example shows how to do that. In the next months, I’ll work on implementing a few abstractions, as needed, while working on one of my project that needs it. The goal is to build a very simple abstraction, that will work nicely with relm, and keep it as simple as possible to avoid the issues we got with tokio.

Conclusion

This new version is the first step in making relm simpler and (as you may have guessed by the quote at the top of this article) you should expect more breaking changes to come that will make this crate even easier to use. As always, your feedback is very much appreciated. Also, there are issues that could use some love and many of them are tagged as easy if you wish to start with something simple. Don’t wait to make a difference in the Rust ecosystem!

Please comment on Reddit.

Relm now has better error messages!

Sat, 03 Mar 2018 00:00:00 +0000

Relm is an attempt to do an idiomatic GUI library in Rust, based on gtk+. See the introduction article for details about why this library was created and how to use it.

New release

I’ve just released relm version 0.12!

This new release does not provide a bunch of new features, but fix a very important issue: the bad error messages.

Before this release, the error message were not really helpful:

error[E0308]: mismatched types
  --> examples/buttons-attribute.rs:57:1
   |
57 | #[widget]
   | ^^^^^^^^^
   | |
   | expected &str, found struct `std::string::String`
   | help: consider borrowing here: `&#[widget]`
   |
   = note: expected type `&str`
              found type `std::string::String`

What a funny help message from the compiler!

Now, the error is shown exactly where it should be:

error[E0308]: mismatched types
  --> examples/buttons-attribute.rs:89:27
   |
89 |                     text: self.model.counter.to_string(),
   |                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |                           |
   |                           expected &str, found struct `std::string::String`
   |                           help: consider borrowing here: `&self.model.counter.to_string()`
   |
   = note: expected type `&str`
              found type `std::string::String`

Which is now helpful, to say the least.

This only works when using nightly and when using these features:

[features]
default = ["relm/unstable", "relm-attributes/unstable", "relm-derive/unstable"]

Other fix

This release also fixes another issue where it was impossible to set child properties in some cases.

Conclusion

I hope that the people who didn’t want to use relm because of the bad error messages will now give it a try. As always, your feedback is very much appreciated. Also, there are issues that could use some love and many of them are tagged as easy if you wish to start with something simple. Don’t wait to make a difference in the Rust ecosystem!

Please comment on Reddit.

What’s new in relm 0.10.0?

Mon, 14 Aug 2017 00:00:00 +0000

Relm is an attempt to do an idiomatic GUI library in Rust, based on gtk+ and tokio. See the introduction article for details about why this library was created and how to use it.

This new release is huge: a lot of changes happened under the hood, the API was changed and features that were unsound were removed. The web browser titanium has been updated to use this latest version of relm. The journey has not been without pitfalls and some convenient features of relm were removed because they caused issues.

Removed features

Shared model

The model is no longer a shared. In the previous versions of relm, it was a Rc<RefCell<Model>> for convenience: it was possible to share a model with a gtk+ callback for instance. However, when developing titanium, I’ve again got bitten by the infamous borrow mut error at runtime, while this was precisely one issue relm tries to solve. Now, there’s a single owner to a widget’s model and the only way to mutate the model is through its widget: if we want to update the model from another widget, we need to send a message to the other widget.

Synchronous callbacks

Also, the feature allowing to use synchronous callbacks in an asynchronous way were removed because they do not fit well within the model of relm, where everything is asynchronous. While this feature was convenient because it allowed to return a value to a gtk+ callback from within a widget’s update method, it was removed because it could cause slowdown if abused and mainly because it was unsound. Remember that the update method takes self by mutable reference, and with this feature, it was possible to block an event handling, while it was waiting for the widget to resolve the value to be returned to the gtk+ callback. So, if the event was triggered twice, it could be possible to have two &mut over the model. That’s a pretty bad thing that Rust prevents us from doing.

Networking examples

This release took a long time to be release. The reason is that I was waiting for tokio issues to be fixed. Since I’ve been waiting for months and they are still not resolved, I decided to release a version without the examples relying on tokio (the http and websockets examples). And they’re not likely to be fixed soon since tokio-proto is likely to be de-emphasize and it’s used both by hyper and twist (the websockets crate). That doesn’t mean it’s not possible to use tokio: titanium uses tokio, but it needs a special version of the tokio-based crate so that the futures can be spawned on the glib event loop. In order to be able to use tokio-based crates with relm, they need to be updated to use the new Executor trait instead of relying on the tokio-core Handle.

Switch to futures-glib

During the Rust+GNOME HackFest in Mexico, Alex Crichton and I worked on a way to spawn futures directly on the glib event loop: the futures-glib crate. Using that, relm now executes only in one thread, which simplify a lot of things while being more efficient.

Is relm usable on stable Rust?

Yes, it is! And you can even benefit from the nice syntax by using the relm_widget! macro.

Projects using relm

There’s already a few projects using relm. If you use relm, consider posting the link to your project in this issue.

New features

Here’s other new features of this release, in bulk:

Need help?

If you need help to use relm, there’s a gitter and I’m also usually on #gtk-rs, #rust-fr and the GNOME’s #rust channel. You may also open an issue on GitHub to ask questions.

Future

Beside many issues to be fixed and corner cases of gtk+ to support in relm, the most important thing to improve is the error messages. Since relm heavily uses code generation, the error message are very bad. Relm needs to be updated to use the proc-macro2 crate in order to be able to keep the position of the tokens in the generated code. This will require a huge refactor because many things changed in the syn crate.

Comment on reddit.

Relm, a GUI library, based on GTK+ and futures, written in Rust

Sun, 09 Apr 2017 00:00:00 +0000

Relm is a new crate (Rust library) to develop asynchronous GUI applications in Rust.

Introduction

Relm provides a way to combine futures/tokio with GTK+ in an elegant way, to easily write asynchronous GUI applications. This library is inspired by the elm programming language in that it uses The Elm Architecture, but adapted to both Rust and desktop applications.

Pain points with using GTK+ in Rust

I created relm because I had some recurrent issues when writing a somewhat complex GTK+ application in Rust. These pain points are detailed below.

State mutation

It is common practice to associate some data (called a model) with a widget and mutate it when the user does an action like clicking on a button. With gtk-rs, it is not possible to directly mutate a state in reaction to an event. To do so, one needs to use Rc<RefCell<Model>>:

let model = Rc::new(RefCell::new(Model { count: 0 }));
button.connect_clicked(move |_| {
  (*model.borrow_mut()).count += 1;
  label.set_text(&format!("{}", (*model.borrow()).count));
});

Which is not ergonomic and error-prone because you can get an error at run-time instead of compile time.

Asynchronous UI

This issue is more related to GTK+ in general. Sometimes, one wants to be able to wait after an HTTP request to finish or a timeout to happen and then update the UI accordingly, without freezing the UI. GTK+ supports this feature. However, I believe that having an abstraction to simplify asynchronous programming can make it easier to write GUI that doesn’t block the UI.

Cannot easily create new widgets

In Vala (and other object-oriented languages), it is easy to create a new widget. All you need is to create a new class inheriting from a widget:

class MyWidget : DrawingArea {
}

and you can use this widget like any other:

var widget = new MyWidget();
window.add(widget);

It is not as easy to do in Rust because it does not support subclassing.

One workaround is to add a Deref implementation for your widget:

struct MyWidget {
    drawing_area: DrawingArea,
}

impl Deref for MyWidget {
    type Target = DrawingArea;

    fn deref(&self) -> &DrawingArea {
        &self.drawing_area
    }
}

but then, you need to manually dereference the variable to use the widget:

window.add(&*widget);

Once again, it is not ergonomic and, while other solutions are available, it is currently not the way to go in gtk-rs.

For all these reasons, I decided to write relm, employing futures and tokio. This allows the users of relm to do an HTTP request with tokio without freezing the UI.

Inspiration by Elm

Relm took its inspiration from the Elm programming language. Having used this language a bit, I found out it provides a good solution to do MVC. To create a program in Elm, you only need to provide a model, an update function to transform the model when some event happens and a view function to create the view in a declarative way. The view communicate with the update function through message passing. In relm, it is very similar, but I adapted the pattern to Rust. For instance, update and view are methods of the Widget trait. Also, mutation is used when it makes sense (Elm being purely functional, mutation is not used in this language).

Example using the `#[widget]` attribute

Let’s look at an example to see how to create a GUI application using relm:

// Import statements ommited.

// Define the structure of the model.
#[derive(Clone)]
struct Model {
    counter: i32,
}

// The messages that can be sent to the update function.
#[derive(Msg)]
enum Msg {
    Decrement,
    Increment,
    Quit,
}

#[widget]
impl Widget<Msg> for Win {
    // The initial model.
    fn model() -> Model {
        Model {
            counter: 0,
        }
    }

    // Update the model according to the message received.
    fn update(&mut self, event: Msg, model: &mut Model) {
        match event {
            Decrement => model.counter -= 1,
            Increment => model.counter += 1,
            Quit => gtk::main_quit(),
        }
    }

    view! {
        gtk::Window {
            gtk::Box {
                // Set the orientation property of the Box.
                orientation: Vertical,
                // Create a Button inside the Box.
                gtk::Button {
                    // Send the message Increment when the button is clicked.
                    clicked => Increment,
                    label: "+",
                },
                gtk::Label {
                    // Bind the text property of the label to the counter attribute of the model.
                    text: &model.counter.to_string(),
                },
                gtk::Button {
                    clicked => Decrement,
                    label: "-",
                },
            },
            delete_event(_, _) => (Quit, Inhibit(false)),
        }
    }
}

fn main() {
    Relm::run::<Win>().unwrap();
}

(This example is truncated, look at the complete file here.)

Those of you that used Elm can notice the similarity between it and relm. A lot of magic happens in the #[widget] attribute.^[1] For example, this attribute generates the struct Win that contains the GTK+ and relm widgets.

The view! macro allows to write the view in a declarative way. One can connect a GTK+ signal to send a message using the fat arrow syntax. For instance, the following:

gtk::Button {
    clicked => Increment,
}

means that the message Increment will be sent to the update function when the button is clicked.

The attribute also changes the update function to insert the calls to gtk::Label::set_text() when the counter field of the model is updated.

Example without the attribute

If it is not possible for you to depend on Rust nightly, it is possible to avoid using the #[widget] attribute. However, it requires a bit of boilerplate code. Here is the same example without the attribute:

#[derive(Clone)]
struct Model {
    counter: i32,
}

#[derive(Msg)]
enum Msg {
    Decrement,
    Increment,
    Quit,
}

// Create the structure that holds the widgets used in the view.
struct Win {
    counter_label: Label,
    window: Window,
}

impl Widget<Msg> for Win {
    // Specify the type of the outer widget.
    type Container = Window;
    // Specify the model used for this widget.
    type Model = Model;

    // Return the outer widget.
    fn container(&self) -> &Self::Container {
        &self.window
    }

    fn model() -> Model {
        Model {
            counter: 0,
        }
    }

    fn update(&mut self, event: Msg, model: &mut Model) {
        let label = &self.counter_label;

        match event {
            Decrement => {
                model.counter -= 1;
                // Manually update the view.
                label.set_text(&model.counter.to_string());
            },
            Increment => {
                model.counter += 1;
                label.set_text(&model.counter.to_string());
            },
            Quit => gtk::main_quit(),
        }
    }

    fn view(relm: RemoteRelm<Msg>, _model: &Self::Model) -> Self {
        // Create the view using the normal GTK+ method calls.
        let vbox = gtk::Box::new(Vertical, 0);

        let plus_button = Button::new_with_label("+");
        vbox.add(&plus_button);

        let counter_label = Label::new("0");
        vbox.add(&counter_label);

        let minus_button = Button::new_with_label("-");
        vbox.add(&minus_button);

        let window = Window::new(WindowType::Toplevel);

        window.add(&vbox);

        window.show_all();

        // Send the message Increment when the button is clicked.
        connect!(relm, plus_button, connect_clicked(_), Increment);
        connect!(relm, minus_button, connect_clicked(_), Decrement);
        connect!(relm, window, connect_delete_event(_, _) (Some(Quit), Inhibit(false)));

        Win {
            counter_label: counter_label,
            window: window,
        }
    }
}

fn main() {
    Relm::run::<Win>().unwrap();
}

(This example is truncated, look at the complete file here.)

You can see some similarity with the previous example, but you now need to create the widgets the same way you would do when using gtk-rs directly, i.e. by calling constructors like Button::new_with_label(). Moreover, you need to update the view manually in the update method:

label.set_text(&model.counter.to_string());

You also need to create the container function, the types Container and Model and the struct Win that are automatically created by the #[widget] attribute.

One difference with gtk-rs is how you connect signals:

connect!(relm, plus_button, connect_clicked(_), Increment);

This is the equivalent of:

clicked => Increment

that was used in the previous example.

Example using tokio

That was a basic example. Now let’s look at a more involved example actually using tokio to send messages to a websockets server:

type WSService = ClientService<TcpStream, WebSocketProtocol>;

#[derive(Clone)]
struct Model {
    // The message to be sent.
    message: String,
    service: Option<WSService>,
    // This contains all the messages received from the websockets server.
    text: String,
}

#[derive(Msg)]
enum Msg {
    // The user changed the message to be sent.
    Change(String),
    // Connection to the server successful.
    Connected(WSService),
    // A message received from the server.
    Message(String),
    // Send a message to the server.
    Send,
    Quit,
}

#[widget]
impl Widget<Msg> for Win {
    fn model() -> Model {
        Model {
            message: String::new(),
            service: None,
            text: String::new(),
        }
    }

    fn subscriptions(relm: &Relm<Msg>) {
        // Connect to the websocket server.
        let handshake_future = ws_handshake(relm.handle());
        let future = relm.connect_ignore_err(handshake_future, Connected);
        relm.exec(future);
    }

    fn update(&mut self, event: Msg, model: &mut Model) {
        match event {
            Change(message) => model.message = message,
            Connected(service) => model.service = Some(service),
            Message(message) => model.text += &format!("{}\n", message),
            Send => {
                model.message = String::new();
                self.entry.grab_focus();
            },
            Quit => gtk::main_quit(),
        }
    }

    fn update_command(relm: &Relm<Msg>, event: Msg, model: &mut Model) {
        if let Send = event {
            if let Some(ref service) = model.service {
                // Send the message to the server.
                let send_future = ws_send(service, &model.message);
                relm.connect_exec_ignore_err(send_future, Message);
            }
        }
    }

    view! {
        gtk::Window {
            gtk::Box {
                orientation: Vertical,
                gtk::Label {
                    text: &model.text,
                },
                // Give a name to this widget, so that we can use it in the update function.
                #[name="entry"]
                gtk::Entry {
                    activate => Send,
                    changed(entry) => Change(entry.get_text().unwrap_or_else(String::new)),
                    text: &model.message,
                },
                gtk::Button {
                    clicked => Send,
                    label: "Send",
                },
            },
            delete_event(_, _) => (Quit, Inhibit(false)),
        }
    }
}

(You can see the complete example here.)

There are two new methods in this example: subscriptions and update_command.

The former is to execute futures when the application starts. In this case, we initiate the websockets connection and connect the future to send the Connected message. This example ignores the possible errors, but it is also possible to handle the case where the future resolves to an error.

The update_command method is used in relm to execute futures when a message is received. This example sends the message Message(message) where message is the response from the websockets server. Relm executes the update_command method in another thread, where the tokio event loop runs: this is why we cannot execute the futures in the update method.

As you can see, events from GTK+ widgets and events from futures are managed in the same way.

Warning about API instability

It is to be noted that relm is under heavy development and has not been thoroughly tested. Moreover, the API is currently unstable and will be updated in the next releases. For instance, the update_command method will be removed (and merge with the update method) when this crate will switch to using futures-glib instead of using another thread to run the tokio event loop.

Conclusion

That was a short introduction to relm. Look at the examples if you want to learn more. The readme and the documentation also provide details about how to use this crate.

Comment on Reddit.

If you find any issue while using this library, please open an issue on GitHub.

Future of relm

Here are some improvements I’ll do in the next weeks and months:

Develop a GUI functional testing crate.
Improve the #[widget] attribute.
Add a more complex example.
Improve tests and documentation.
Switch to futures-glib.

And, of course, I’ll use relm for my own projects mg and titanium.

1. Attributes currently requires a nightly compiler.

Relm Blog

A big release for relm

Nested view! macro

Ability to create multiple objects in a single view! macro

Fix reference cycle

The road ahead

Relm drop support for futures!

New release

Conclusion

Relm now has better error messages!

New release

Other fix

Conclusion

What’s new in relm 0.10.0?

Removed features

Shared model

Synchronous callbacks

Networking examples

Switch to futures-glib

Is relm usable on stable Rust?

Projects using relm

New features

Need help?

Future

Relm, a GUI library, based on GTK+ and futures, written in Rust

Introduction

Pain points with using GTK+ in Rust

State mutation

Asynchronous UI

Cannot easily create new widgets

Inspiration by Elm

Example using the #[widget] attribute

Example without the attribute

Example using tokio

Warning about API instability

Conclusion

Future of relm

Nested `view!` macro

Ability to create multiple objects in a single `view!` macro

Example using the `#[widget]` attribute