Git Product home page Git Product logo

relm's Introduction

Relm

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

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

CI Relm Tutorial blueviolet relm rust documentation blue relm relm:matrix relm Donate Patreon orange

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.16.0"
relm = "^0.24.0"
relm-derive = "^0.24.0"

Next, add this to your crate:

use relm::{connect, Relm, Update, Widget};
use gtk::prelude::*;
use gtk::{Window, Inhibit, WindowType};
use relm_derive::Msg;

Then, create your model:

struct Model {
    // …
}

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

Create your message enum:

#[derive(Msg)]
enum Msg {
    // …
    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:

struct Win {
    // …
    model: Model,
    window: Window,
}

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

impl Update for Win {
    // Specify the model used for this widget.
    type Model = Model;
    // Specify the model parameter used to init the model.
    type ModelParam = ();
    // Specify the type of the messages sent to the update function.
    type Msg = Msg;

    // Return the initial model.
    fn model(_: &Relm<Self>, _: ()) -> Model {
        Model {
        }
    }

    // The model may be updated when a message is received.
    // Widgets may also be updated in this function.
    fn update(&mut self, event: Msg) {
        match event {
            Msg::Quit => gtk::main_quit(),
        }
    }
}

impl Widget for Win {
    // Specify the type of the root widget.
    type Root = Window;

    // Return the root widget.
    fn root(&self) -> Self::Root {
        self.window.clone()
    }

    // Create the widgets.
    fn view(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,
        }
    }
}

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

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

#[widget] attribute

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 Widget struct.

  • Update and Widget traits can be implemented at once.

To use this attribute, add the following code:

use relm_derive::widget;

Here is an example using this attribute:

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

pub struct Model {
    counter: u32,
}

#[widget]
impl Widget for Win {
    fn model() -> Model {
        Model {
            counter: 0,
        }
    }

    fn update(&mut self, 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.
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

fn update(&mut self, event: Msg) {
    for _ in 0..100 {
        self.model.counter += 1;
    }
}

will generate this function:

fn update(&mut self, event: Msg) {
    for _ in 0..100 {
        self.model.counter += 1;
        self.label1.set_text(&self.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

fn update(&mut self, event: Msg) {
    self.model.text.push_str("Text");
}

will not work as expected.

Please use the following variation if needed.

fn update(&mut self, event: Msg) {
    self.model.text += "Text";
}

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

Donations

If you appreciate this project and want new features to be implemented, please support me on Patreon.

become a patron button

Projects using relm

  • Yellow Pitaya: A desktop interface for the redpitaya hardware oscilloscope.

  • Game of Life: Conway’s Game of Life Simulator

  • Country Parser: Parses Google location history and displays timeline of countries visited

  • Chessground: An experimental chessboard widget

  • Effitask: Graphical task manager, based on the todo.txt format

  • KS Curve Tracer: A companion app for AD2 curve tracer

  • Cigale: Tool to prepare the timesheet of the tasks you did at work

  • Projectpad: Manage secret credentials and server information as a software developer or sysadmin.

  • TimezoneRS: A GUI application to visually see the time in different time zones

  • Tubefeeder / Pipeline: Watch YouTube, LBRY, and PeerTube videos in one place.

  • Hotwire: Study network traffic of a few popular protocols in a simple way

  • gue: GUI for controlling phillips hue lights

  • MyCitadel Wallet: MyCitadel Cryptocurrency Wallet app

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

relm's People

Contributors

antoyo avatar schmiddiii avatar sanpii avatar zzeroo avatar emmanueltouzery avatar juchiast avatar zmitchell avatar pentamassiv avatar eijebong avatar guillaumegomez avatar msrd0 avatar jonas-schievink avatar azanellato avatar ilya-epifanov avatar etrombly avatar deflateawning avatar chathaway-codes avatar euclio avatar gagath avatar repnop avatar crrodger avatar sunjay avatar atsjj avatar darkwater avatar rnestler avatar polymeilex avatar petar-dambovaliev avatar niklasf avatar lpil avatar lordmzte avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.