Trait relm4::Component

source ·
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;

    fn init_root() -> Self::Root;
    fn init(
        init: Self::Init,
        root: &Self::Root,
        sender: ComponentSender<Self>
    ) -> ComponentParts<Self>; 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 { ... } }
Expand description

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§

Messages which are received from commands executing in the background.

The message type that the component accepts as inputs.

The message type that the component provides as outputs.

The parameter used to initialize the component.

The widget that was constructed by the component.

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

Required Methods§

Initializes the root widget.

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

Provided Methods§

Create a builder for this component.

Examples found in repository?
examples/worker.rs (line 95)
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
    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 }
    }
More examples
Hide additional examples
examples/message_broker.rs (line 187)
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
    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/relm4-components/open_button.rs (line 50)
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
    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 }
    }
examples/transient_dialog.rs (line 105)
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
    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 178)
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
    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/relm4-components/file_dialogs.rs (line 96)
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
    fn init(
        _: Self::Init,
        root: &Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let open_dialog = OpenDialog::builder()
            .transient_for_native(root)
            .launch(OpenDialogSettings::default())
            .forward(sender.input_sender(), |response| match response {
                OpenDialogResponse::Accept(path) => Input::OpenResponse(path),
                OpenDialogResponse::Cancel => Input::Ignore,
            });

        let save_dialog = SaveDialog::builder()
            .transient_for_native(root)
            .launch(SaveDialogSettings::default())
            .forward(sender.input_sender(), |response| match response {
                SaveDialogResponse::Accept(path) => Input::SaveResponse(path),
                SaveDialogResponse::Cancel => Input::Ignore,
            });

        let model = App {
            open_dialog,
            save_dialog,
            buffer: gtk::TextBuffer::new(None),
            file_name: None,
            message: None,
        };

        let widgets = view_output!();

        sender.input(Input::ShowMessage(String::from(
            "A simple text editor showing the usage of\n<b>OpenFileDialog</b> and <b>SaveFileDialog</b> components.\n\nStart by clicking <b>Open</b> on the header bar.",
        )));

        ComponentParts { model, widgets }
    }

Processes inputs received by the component.

Defines how the component should respond to command updates.

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.

Updates the view after the model has been updated.

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.

Last method called before a component is shut down.

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§