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

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

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

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

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

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

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.

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

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

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

examples/multi_window.rs (line 88)

    fn update(&mut self, msg: Self::Input, _sender: ComponentSender<Self>) {
        match msg {
            Msg::Increment => {
                self.counter = self.counter.wrapping_add(1);
            }
            Msg::Decrement => {
                self.counter = self.counter.wrapping_sub(1);
            }
            Msg::NewWindow => {
                let app = relm4::main_application();
                let builder = Self::builder();

                // Add window to the GTK application.
                // This ensures that the app will live as long
                // as at least one window exists.
                app.add_window(&builder.root);

                builder.launch(self.counter).detach_runtime();
            }
        }
    }

examples/components.rs (line 183)

    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 148)

    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/drop_sub_components.rs (line 74)

    fn update_with_view(
        &mut self,
        widgets: &mut Self::Widgets,
        message: Self::Input,
        sender: ComponentSender<Self>,
        root: &Self::Root,
    ) {
        widgets.container.remove_all();
        match message {
            Msg::ShowInitialScreen => {
                let controller =
                    InitialScreen::builder()
                        .launch(())
                        .forward(sender.input_sender(), |msg| match msg {
                            InitialScreenOutput::ShowSubScreen1 => Msg::ShowSubScreen1,
                            InitialScreenOutput::ShowSubScreen2 => Msg::ShowSubScreen2,
                        });
                widgets.container.append(controller.widget());
                self.mode = Some(AppMode::Initial(controller));
            }
            Msg::ShowSubScreen1 => {
                let controller = SubScreen1::builder()
                    .launch(())
                    .forward(sender.input_sender(), |_| Msg::ShowInitialScreen);
                widgets.container.append(controller.widget());
                self.mode = Some(AppMode::SubScreen1(controller));
            }
            Msg::ShowSubScreen2 => {
                let controller = SubScreen2::builder()
                    .launch(())
                    .forward(sender.input_sender(), |_| Msg::ShowInitialScreen);
                widgets.container.append(controller.widget());
                self.mode = Some(AppMode::SubScreen2(controller));
            }
        }
        root.set_default_size(400, 300);
    }

Additional examples can be found in:

• examples/settings_list.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

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

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

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.