Struct ComponentBuilder 

pub struct ComponentBuilder<C: Component> {
    pub root: C::Root,
    /* private fields */
}

A component that is ready for docking and launch.

Fields

root: C::Root

The root widget of the component.

Implementations

impl<C: Component> ComponentBuilder<C>

pub fn update_root<F: FnOnce(&mut C::Root)>(self, func: F) -> Self

Configure the root widget before launching.

pub const fn widget(&self) -> &C::Root

Access the root widget before the component is initialized.

pub fn priority(self, priority: Priority) -> Self

Change the priority at which the messages of this component are handled.

• Use glib::Priority::HIGH for high priority event sources.
• Use glib::Priority::LOW for very low priority background tasks.
• Use glib::Priority::DEFAULT_IDLE for default priority idle functions.
• Use glib::Priority::HIGH_IDLE for high priority idle functions.

impl<C: Component> ComponentBuilder<C>

where C::Root: AsRef<Widget>,

pub fn attach_to<T: RelmContainerExt<Child = Widget>>( self, container: &T, ) -> Self

Attach the component’s root widget to a given container.

Examples found in repository

relm4/examples/settings_list.rs (line 25)

fn main() {
    gtk::Application::builder()
        .application_id("org.relm4.SettingsListExample")
        .launch(|_app, window| {
            // Initialize a component's root widget
            let mut component = AppModel::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());
        });
}

impl<C: Component> ComponentBuilder<C>

where C::Root: AsRef<Window> + Clone,

pub fn transient_for(self, widget: impl AsRef<Widget>) -> Self

Set the component’s root widget transient for a given window. This function doesn’t require a gtk::Window as parameter, but instead uses RelmWidgetExt::toplevel_window() to retrieve the toplevel window of any gtk::Widget. Therefore, you don’t have to pass a window to every component.

If the root widget is a native dialog, such as gtk::FileChooserNative, you should use transient_for_native instead.

Examples found in repository

relm4/examples/transient_dialog.rs (line 111)

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

relm4/examples/components.rs (line 186)

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

relm4/examples/message_stream.rs (line 147)

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

relm4-components/examples/alert.rs (line 107)

    fn init(
        _: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let model = App {
            counter: 0,
            alert_toggle: false,
            dialog: Alert::builder()
                .transient_for(&root)
                .launch(AlertSettings {
                    text: Some(String::from(
                        "Do you want to quit without saving? (First alert)",
                    )),
                    secondary_text: Some(String::from("Your counter hasn't reached 42 yet")),
                    confirm_label: Some(String::from("Close without saving")),
                    cancel_label: Some(String::from("Cancel")),
                    option_label: Some(String::from("Save")),
                    is_modal: true,
                    destructive_accept: true,
                    extra_child: Some(gtk::Button::with_label("Button in Alert").into()),
                })
                .forward(sender.input_sender(), convert_alert_response),
            second_dialog: Alert::builder()
                .transient_for(&root)
                .launch(AlertSettings {
                    text: Some(String::from(
                        "Do you want to quit without saving? (Second alert)",
                    )),
                    secondary_text: Some(String::from("Your counter hasn't reached 42 yet")),
                    confirm_label: Some(String::from("Close without saving")),
                    cancel_label: Some(String::from("Cancel")),
                    option_label: Some(String::from("Save")),
                    is_modal: true,
                    destructive_accept: true,
                    extra_child: None,
                })
                .forward(sender.input_sender(), convert_alert_response),
        };

        let widgets = view_output!();

        ComponentParts { model, widgets }
    }

impl<C: Component> ComponentBuilder<C>

where C::Root: AsRef<NativeDialog> + Clone,

pub fn transient_for_native(self, widget: impl AsRef<Widget>) -> Self

Set the component’s root widget transient for a given window. This function doesn’t require a gtk::Window as parameter, but instead uses RelmWidgetExt::toplevel_window() to retrieve the toplevel window of any gtk::Widget. Therefore, you don’t have to pass a window to every component.

Applicable to native dialogs only, such as gtk::FileChooserNative. If the root widget is a non-native dialog, you should use transient_for instead.

Examples found in repository

relm4-components/examples/file_dialogs.rs (line 99)

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

relm4/examples/state_management.rs (line 577)

    fn init(
        _: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let view =
            FactoryVecDeque::builder()
                .launch_default()
                .forward(sender.input_sender(), |msg| match msg {
                    TaskOutput::Delete(index) => AppInput::DeleteTask(index),
                    TaskOutput::Name(index, name) => AppInput::ChangeTaskName(index, name),
                    TaskOutput::AddTag(index, name) => AppInput::AddTag(index, name),
                    TaskOutput::DeleteTag(task_index, tag_index) => {
                        AppInput::DeleteTag(task_index, tag_index)
                    }
                });

        let document =
            Document::builder()
                .launch(())
                .forward(sender.input_sender(), |msg| match msg {
                    DocumentOutput::Cleared => AppInput::Cleared,
                    DocumentOutput::DeletedTask(index) => AppInput::DeletedTask(index),
                    DocumentOutput::DeletedTag(task_index, tag_index) => {
                        AppInput::DeletedTag(task_index, tag_index)
                    }
                    DocumentOutput::AddedTask => AppInput::AddedTask,
                    DocumentOutput::AddedTag(index, name) => AppInput::AddedTag(index, name),
                    DocumentOutput::ChangedTaskName(index, name) => {
                        AppInput::ChangedTaskName(index, name)
                    }
                });

        let save_dialog = SaveDialog::builder()
            .transient_for_native(&root)
            .launch(SaveDialogSettings {
                create_folders: true,
                accept_label: "Save".into(),
                cancel_label: "Cancel".into(),
                is_modal: true,
                filters: tasks_filename_filters(),
            })
            .forward(sender.input_sender(), |response| match response {
                SaveDialogResponse::Accept(path) => AppInput::SaveResponse(path),
                SaveDialogResponse::Cancel => AppInput::None,
            });

        let open_dialog = OpenDialog::builder()
            .transient_for_native(&root)
            .launch(OpenDialogSettings {
                create_folders: false,
                folder_mode: false,
                cancel_label: "Cancel".into(),
                accept_label: "Open".into(),
                is_modal: true,
                filters: tasks_filename_filters(),
            })
            .forward(sender.input_sender(), |response| match response {
                OpenDialogResponse::Accept(path) => AppInput::OpenResponse(path),
                OpenDialogResponse::Cancel => AppInput::None,
            });

        let app = App {
            view,
            document,
            open_dialog,
            save_dialog,
        };

        let task_list_box = app.view.widget();
        let widgets = view_output!();

        ComponentParts {
            model: app,
            widgets,
        }
    }

impl<C: Component> ComponentBuilder<C>

pub fn launch(self, payload: C::Init) -> Connector<C>

Starts the component, passing ownership to a future attached to a gtk::glib::MainContext.

Examples found in repository

relm4/examples/transient_dialog.rs (line 149)

    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-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-components/examples/adw_combo_row.rs (lines 69-72)

    fn init(
        _: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let model = App {
            combo_row: SimpleComboRow::builder()
                .launch(SimpleComboRow {
                    variants: vec!["Variant 1", "Variant 2"],
                    active_index: None,
                })
                .forward(sender.input_sender(), AppMsg::Selected),
            selected_variant: 0,
        };

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

        ComponentParts { model, widgets }
    }

relm4/examples/message_broker.rs (line 196)

    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 (lines 51-57)

    fn init(
        _: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let open_button = OpenButton::builder()
            .launch(OpenButtonSettings {
                dialog_settings: OpenDialogSettings::default(),
                icon: None,
                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-components/examples/combo_box.rs (lines 84-87)

    fn init(
        _: Self::Init,
        root: Self::Root,
        sender: ComponentSender<Self>,
    ) -> ComponentParts<Self> {
        let default_idx = 0;

        let langs = vec![
            "English", "German", "French", "Polish", "Russian", "Chinese",
        ];

        let combo = SimpleComboBox::builder()
            .launch(SimpleComboBox {
                variants: langs,
                active_index: Some(default_idx),
            })
            .forward(sender.input_sender(), AppMsg::ComboChanged);

        let model = App {
            combo,
            idx: default_idx,
        };

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

        ComponentParts { model, widgets }
    }

Additional examples can be found in:

• relm4/examples/multi_window.rs
• relm4/examples/components.rs
• relm4/examples/navigation_splitview_with_stack.rs
• relm4-components/examples/file_dialogs.rs
• relm4/examples/message_stream.rs
• relm4/examples/drop_sub_components.rs
• relm4-components/examples/alert.rs
• relm4/examples/settings_list.rs
• relm4/examples/state_management.rs

pub fn launch_with_broker( self, payload: C::Init, broker: &MessageBroker<C::Input>, ) -> Connector<C>

Similar to launch() but also initializes a MessageBroker.

Panics

This method panics if the message broker was already initialized in another launch.

Examples found in repository

relm4/examples/message_broker.rs (line 192)

    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/examples/transient_dialog.rs (line 112)

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

impl<C> ComponentBuilder<C>

where C: Component<Root = (), Widgets = ()> + Send, C::Input: Send, C::Output: Send, C::CommandOutput: Send,

pub fn detach_worker(self, payload: C::Init) -> WorkerHandle<C>

Starts a worker on a separate thread, passing ownership to a future attached to a gtk::glib::MainContext.

Examples found in repository

relm4/examples/worker.rs (line 96)

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

Trait Implementations

impl<C: Debug + Component> Debug for ComponentBuilder<C>

where C::Root: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<C: Component> Default for ComponentBuilder<C>

fn default() -> Self

Prepares a component for initialization.