Relm

Asynchronous, GTK+-based, GUI library, inspired by Elm, written in Rust.

This library is in alpha stage: it has not been thoroughly tested and its API may change at any time.

Requirements

Since relm is based on GTK+, you need this library on your system in order to use it.

See this page for information on how to install GTK+.

Usage

First, add this to your Cargo.toml:

gtk = "^0.3.0"relm = "^0.11.0"relm-derive = "^0.11.0"

Next, add this to your crate:

externcrate gtk;#[macro_use]externcrate relm;#[macro_use]externcrate relm_derive;use relm::{Relm,Update,Widget};use gtk::prelude::*;use gtk::{Window,Inhibit,WindowType};

Then, create your model:

structModel{// …}

The model contains the data related to a Widget. It may be updated by the Widget::update function.

Create your message enum:

#[derive(Msg)]enumMsg{// …Quit,}

Messages are sent to Widget::update to indicate that an event happened. The model can be updated when an event is received.

Create a struct which represents a Widget which contains the GTK+ widgets (in this case, the main window of the application) and the model:

structWin{// …model:Model,window:Window,}

To make this struct a relm Widget that can be shown by the library, implement the Update and Widget traits:

implUpdateforWin{// Specify the model used for this widget.typeModel = Model;// Specify the model parameter used to init the model.typeModelParam = ();// Specify the type of the messages sent to the update function.typeMsg = Msg;// Return the initial model.fnmodel(_:&Relm<Self>, _:()) -> Model{Model{}}// The model may be updated when a message is received.// Widgets may also be updated in this function.fnupdate(&mutself,event:Msg){match event {Msg::Quit => gtk::main_quit(),}}}implWidgetforWin{// Specify the type of the root widget.typeRoot = Window;// Return the root widget.fnroot(&self) -> Self::Root{self.window.clone()}// Create the widgets.fnview(relm:&Relm<Self>,model:Self::Model) -> Self{// GTK+ widgets are used normally within a `Widget`.let window = Window::new(WindowType::Toplevel);// Connect the signal `delete_event` to send the `Quit` message.connect!(relm, window, connect_delete_event(_, _),return(Some(Msg::Quit),Inhibit(false)));// There is also a `connect!()` macro for GTK+ events that do not need a// value to be returned in the callback.
window.show_all();Win{
model,window: window,}}}

Finally, show this Widget by calling Win::run():

fnmain(){Win::run(()).unwrap();}

#[widget] attribute

For the nightly users, a #[widget] attribute is provided to simplify the creation of a widget.

This attribute does the following:

• Provide a view! macro to create the widget with a declarative syntax.

• Automatically create the fn root(), type Msg, type Model, type ModelParam and type Root items.

• Automatically insert the call to Widget::set_property() in the update() function when assigning to an attribute of the model.

• Automatically create the Widgetstruct.

• Both traits can be implemented at once.

To be able to use this attribute, you need to add the relm-attributes crate in your Cargo.toml:

relm-attributes = "^0.11.0"

and to add the following code:

externcrate relm_attributes;use relm_attributes::widget;

Here is an example using this attribute:

#[derive(Msg)]pubenumMsg{Decrement,Increment,Quit,}pubstructModel{counter:u32,}#[widget]implWidgetforWin{fnmodel() -> Model{Model{counter:0,}}fnupdate(&mutself,event:Msg){match event {// A call to self.label1.set_text() is automatically inserted by the// attribute every time the model.counter attribute is updated.Msg::Decrement => self.model.counter -= 1,Msg::Increment => self.model.counter += 1,Msg::Quit => gtk::main_quit(),}}view!{
gtk::Window{
gtk::Box{
orientation:Vertical,
gtk::Button{// By default, an event with one paramater is assumed.
clicked => Msg::Increment,// Hence, the previous line is equivalent to:// clicked(_) => Increment,
label:"+",},
gtk::Label{// Bind the text property of this Label to the counter attribute// of the model.// Every time the counter attribute is updated, the text property// will be updated too.
text:&self.model.counter.to_string(),},
gtk::Button{
clicked => Msg::Decrement,
label:"-",},},// Use a tuple when you want to both send a message and return a value to// the GTK+ callback.
delete_event(_, _) => (Msg::Quit,Inhibit(false)),}}}

Note	The struct Win is now automatically created by the attribute, as are the function root() and the associated types Model, ModelParam, Msg and Container. You can still provide the method and the associated types if needed, but you cannot create the struct.

Note	To benefit from better error messages, enable the following features: relm/unstable relm-attributes/unstable relm-derive/unstable To do so, add the following lines to your Cargo.toml: [features] default = ["relm/unstable", "relm-attributes/unstable", "relm-derive/unstable"]

Note	It is possible to use this syntax from stable Rust. To do so, you need to replace the following: #[widget]implWidgetforWin{} by: #[widget]relm_widget!{implWidgetforWin{}}

Warning

The #[widget] makes the generated struct public: hence, the corresponding model and message types must be public too.

Warning

Your program might be slower when using this attribute because the code generation is simple. For instance, the following code fnupdate(&mutself,event:Msg,model:&mutModel){for _ in0..100{ model.counter += 1;}} will generate this function: fnupdate(&mutself,event:Msg,model:&mutModel){for _ in0..100{ model.counter += 1;self.label1.set_text(&model.counter.to_string());}}

Warning

Also, the set_property() calls are currently only inserted when assigning to an attribute of the model. For instance, the following code fnupdate(&mutself,event:Msg,model:&mutModel){ model.text.push_str("Text");} will not work as expected. Please use the following variation if needed. fnupdate(&mutself,event:Msg,model:&mutModel){ model.text += "Text";}

For more information about how you can use relm, you can take a look at the examples.

Projects using relm

• Yellow Pitaya

• Game of Life

• Rusty Sounds

• Country Parser

• Chessground

• Effitask

If you want to add your project to this list, please create a pull request.