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 widget that was constructed by 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

relm4-components/examples/web_image.rs (line 71)

    fn init(
        _: Self::Init,
        root: &Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let image = WebImage::builder().launch(IMAGES[0].to_owned()).detach();
        let model = App { image, idx: 0 };

        let image = model.image.widget();
        let widgets = view_output!();

        ComponentParts { model, widgets }
    }

relm4/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 }
    }

relm4/examples/message_broker.rs (line 187)

    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 }
    }

relm4-components/examples/open_button.rs (line 50)

    fn init(
        _: Self::Init,
        root: &Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let open_button = OpenButton::builder()
            .launch(OpenButtonSettings {
                dialog_settings: OpenDialogSettings::default(),
                text: "Open file",
                recently_opened_files: Some(".recent_files"),
                max_recent_files: 10,
            })
            .forward(sender.input_sender(), AppMsg::Open);
        let model = App { open_button };

        let widgets = view_output!();

        ComponentParts { model, widgets }
    }

relm4/examples/transient_dialog.rs (line 105)

    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 }
    }

relm4/examples/components.rs (line 178)

    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 }
    }

Additional examples can be found in:

• relm4-components/examples/file_dialogs.rs
• relm4/examples/message_stream.rs
• relm4-components/examples/alert.rs
• relm4/examples/settings_list.rs

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.

Implementors

impl<C> Component for Cwhere 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 = ()