Trait relm4::component::Component

pub trait Component: Sized + 'static {
    type CommandOutput: Debug + Send + 'static;
    type Input: Debug + 'static;
    type Output: Debug + 'static;
    type Init;
    type Root: Debug + Clone;
    type Widgets: 'static;

    // Required methods
    fn init_root() -> Self::Root;
    fn init(
        init: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>
    ) -> ComponentParts<Self>;

    // Provided methods
    fn builder() -> ComponentBuilder<Self> { ... }
    fn update(
        &mut self,
        message: Self::Input,
        sender: ComponentSender<Self>,
        root: &Self::Root
    ) { ... }
    fn update_cmd(
        &mut self,
        message: Self::CommandOutput,
        sender: ComponentSender<Self>,
        root: &Self::Root
    ) { ... }
    fn update_cmd_with_view(
        &mut self,
        widgets: &mut Self::Widgets,
        message: Self::CommandOutput,
        sender: ComponentSender<Self>,
        root: &Self::Root
    ) { ... }
    fn update_view(
        &self,
        widgets: &mut Self::Widgets,
        sender: ComponentSender<Self>
    ) { ... }
    fn update_with_view(
        &mut self,
        widgets: &mut Self::Widgets,
        message: Self::Input,
        sender: ComponentSender<Self>,
        root: &Self::Root
    ) { ... }
    fn shutdown(
        &mut self,
        widgets: &mut Self::Widgets,
        output: Sender<Self::Output>
    ) { ... }
    fn id(&self) -> String { ... }
}

The fundamental building block of a Relm4 application.

A Component is an element of an application that defines initialization, state, behavior and communication as a modular unit.

Component is powerful and flexible, but for many use-cases the SimpleComponent convenience trait will suffice. SimpleComponent enforces separation between model and view updates, and provides no-op implementations for advanced features that are not relevant for most use-cases.

Required Associated Types

type CommandOutput: Debug + Send + 'static

Messages which are received from commands executing in the background.

type Input: Debug + 'static

The message type that the component accepts as inputs.

type Output: Debug + 'static

The message type that the component provides as outputs.

type Init

The parameter used to initialize the component.

type Root: Debug + Clone

The top-level widget of the component.

type Widgets: 'static

The type that’s used for storing widgets created for this component.

Required Methods

fn init_root() -> Self::Root

Initializes the root widget.

fn init( init: Self::Init, root: Self::Root, sender: ComponentSender<Self> ) -> ComponentParts<Self>

Creates the initial model and view, docking it into the component.

Provided Methods

fn builder() -> ComponentBuilder<Self>

Create a builder for this component.

Examples found in repository

examples/worker.rs (line 95)

    fn init(
        _: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let model = App {
            counter: 0,
            worker: AsyncHandler::builder()
                .detach_worker(())
                .forward(sender.input_sender(), identity),
        };

        let widgets = view_output!();

        ComponentParts { model, widgets }
    }

examples/message_broker.rs (line 191)

    fn init(
        _init: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let header = Header::builder()
            .launch_with_broker((), &HEADER_BROKER)
            .forward(sender.input_sender(), identity);

        let dialog = Dialog::builder()
            .launch(root.clone().upcast())
            .forward(sender.input_sender(), identity);

        let model = App {
            mode: AppMode::View,
            header,
            dialog,
        };

        let widgets = view_output!();

        ComponentParts { model, widgets }
    }

examples/transient_dialog.rs (line 110)

    fn init(
        _init: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        // We don't have access to the parent window from here
        // but we can just use the button to set the transient window for the dialog.
        // Relm4 will get the window later by calling [`WidgetExt::root()`]
        // on the button once all widgets are connected.
        let dialog = Dialog::builder()
            .transient_for(&root)
            .launch_with_broker((), &DIALOG_BROKER)
            .forward(sender.input_sender(), identity);

        let model = Button { dialog };
        let widgets = view_output!();
        ComponentParts { model, widgets }
    }

    fn update(&mut self, _msg: Self::Input, _sender: ComponentSender<Self>) {}
}

#[derive(Debug)]
enum AppMsg {}

struct App {
    button: Controller<Button>,
}

#[relm4::component]
impl SimpleComponent for App {
    type Init = ();
    type Input = AppMsg;
    type Output = ();

    view! {
        main_window = gtk::ApplicationWindow {
            set_default_size: (500, 250),
            set_child: Some(model.button.widget()),
        }
    }

    fn init(
        _init: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let button = Button::builder()
            .launch(())
            .forward(sender.input_sender(), identity);
        let model = App { button };
        let widgets = view_output!();
        ComponentParts { model, widgets }
    }

examples/components.rs (line 182)

    fn init(
        _: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let header = Header::builder()
            .launch(())
            .forward(sender.input_sender(), identity);
        let dialog = Dialog::builder()
            .transient_for(&root)
            .launch(DialogInit {
                text: "Do you want to close before saving?".to_string(),
                secondary_text: Some("All unsaved changes will be lost".to_string()),
                accept_text: "Close".to_string(),
                cancel_text: "Cancel".to_string(),
            })
            .forward(sender.input_sender(), identity);

        let model = App {
            mode: AppMode::View,
            header,
            dialog,
        };
        let widgets = view_output!();

        ComponentParts { model, widgets }
    }

examples/message_stream.rs (line 146)

    fn update(&mut self, msg: Self::Input, sender: ComponentSender<Self>, root: &Self::Root) {
        match msg {
            AppMsg::StartSearch => {
                self.searching = true;

                let stream = Dialog::builder()
                    .transient_for(root)
                    .launch(())
                    .into_stream();
                sender.oneshot_command(async move {
                    // Use the component as stream
                    let result = stream.recv_one().await;

                    if let Some(search) = result {
                        let response =
                            reqwest::get(format!("https://duckduckgo.com/lite/?q={search}"))
                                .await
                                .unwrap();
                        let response_text = response.text().await.unwrap();

                        // Extract the url of the first search result.
                        if let Some(url) = response_text.split("<a rel=\"nofollow\" href=\"").nth(1)
                        {
                            let url = url.split('\"').next().unwrap().replace("amp;", "");
                            Some(format!("https:{url}"))
                        } else {
                            None
                        }
                    } else {
                        None
                    }
                });
            }
        }
    }

examples/settings_list.rs (line 23)

fn main() {
    gtk::Application::builder()
        .application_id("org.relm4.SettingsListExample")
        .launch(|_app, window| {
            // Initialize a component's root widget
            let mut component = App::builder()
                // Attach the root widget to the given window.
                .attach_to(&window)
                // Start the component service with an initial parameter
                .launch("Settings List Demo".into())
                // Attach the returned receiver's messages to this closure.
                .connect_receiver(move |sender, message| match message {
                    Output::Clicked(id) => {
                        eprintln!("ID {id} Clicked");

                        match id {
                            0 => xdg_open("https://github.com/Relm4/Relm4".into()),
                            1 => xdg_open("https://docs.rs/relm4/".into()),
                            2 => {
                                sender.send(Input::Clear).unwrap();
                            }
                            _ => (),
                        }
                    }

                    Output::Reload => {
                        sender
                            .send(Input::AddSetting {
                                description: "Browse GitHub Repository".into(),
                                button: "GitHub".into(),
                                id: 0,
                            })
                            .unwrap();

                        sender
                            .send(Input::AddSetting {
                                description: "Browse Documentation".into(),
                                button: "Docs".into(),
                                id: 1,
                            })
                            .unwrap();

                        sender
                            .send(Input::AddSetting {
                                description: "Clear List".into(),
                                button: "Clear".into(),
                                id: 2,
                            })
                            .unwrap();
                    }
                });

            // Keep runtime alive after the component is dropped
            component.detach_runtime();

            println!("parent is {:?}", component.widget().toplevel_window());
        });
}

fn update( &mut self, message: Self::Input, sender: ComponentSender<Self>, root: &Self::Root )

Processes inputs received by the component.

fn update_cmd( &mut self, message: Self::CommandOutput, sender: ComponentSender<Self>, root: &Self::Root )

Defines how the component should respond to command updates.

fn update_cmd_with_view( &mut self, widgets: &mut Self::Widgets, message: Self::CommandOutput, sender: ComponentSender<Self>, root: &Self::Root )

Updates the model and view upon completion of a command.

Overriding this method is helpful if you need access to the widgets while processing a command output.

The default implementation of this method calls update_cmd followed by update_view. If you override this method while using the component macro, you must remember to call update_view in your implementation. Otherwise, the view will not reflect the updated model.

fn update_view( &self, widgets: &mut Self::Widgets, sender: ComponentSender<Self> )

Updates the view after the model has been updated.

fn update_with_view( &mut self, widgets: &mut Self::Widgets, message: Self::Input, sender: ComponentSender<Self>, root: &Self::Root )

Updates the model and view when a new input is received.

Overriding this method is helpful if you need access to the widgets while processing an input.

The default implementation of this method calls update followed by update_view. If you override this method while using the component macro, you must remember to call update_view in your implementation. Otherwise, the view will not reflect the updated model.

fn shutdown( &mut self, widgets: &mut Self::Widgets, output: Sender<Self::Output> )

Last method called before a component is shut down.

This method is guaranteed to be called even when the entire application is shut down.

fn id(&self) -> String

An identifier for the component used for debug logging.

The default implementation of this method uses the address of the component, but implementations are free to provide more meaningful identifiers.

Object Safety

This trait is not object safe.

Implementors

impl<C> Component for C

where C: SimpleComponent,

type Init = <C as SimpleComponent>::Init

type Input = <C as SimpleComponent>::Input

type Output = <C as SimpleComponent>::Output

type Root = <C as SimpleComponent>::Root

type Widgets = <C as SimpleComponent>::Widgets

type CommandOutput = ()