Trait Component

pub trait Component: Default + Unpin {
    type Message: Clone + Send + Debug + Unpin;
    type Properties: Clone + Default;

    // Required method
    fn view(&self) -> VNode<Self>;

    // Provided methods
    fn update(&mut self, _msg: Self::Message) -> UpdateAction<Self> { ... }
    fn create(_props: Self::Properties) -> Self { ... }
    fn change(&mut self, _props: Self::Properties) -> UpdateAction<Self> { ... }
    fn mounted(&mut self) { ... }
    fn unmounted(&mut self) { ... }
}

This is the trait your UI components should implement.

You must always provide Message and Properties types, and the view() method. Properties only makes sense when used as a subcomponent, and should be set to the unit type () for your top level component.

A default implementation for update is provided which does nothing and always returns UpdateAction::None. You will probably want to reimplement this.

You don’t have to implement create and change for a top level component, but you’ll have to implement them for a subcomponent. The default implementation for create just constructs the default value for your component, ignoring its properties entirely (which is what you want for a top level component) and the default change will panic to remind you that you need to implement it.

A sensible pattern for a subcomponent without local state is to make Self::Properties = Self. create can then just return its input argument, and change could be as simple as *self = props; UpdateAction::Render, though you might want to compare the input with the current state if possible and return UpdateAction::Render only when they’re different.

Required Associated Types

type Message: Clone + Send + Debug + Unpin

The type of messages you can send to the Component::update() function.

type Properties: Clone + Default

A struct type which holds the properties for your Component.

The gtk! macro will construct this from the attributes on the corresponding component element.

This is not relevant and should be set to () if you’re writing a top level component.

Note: if you need to emit signals from a subcomponent, please see the documentation for Callback. Subcomponents do not support the on signal syntax, as they aren’t GTK objects and therefore can’t emit signals, and the convention is to use a Callback property named on_signal instead.

Required Methods

fn view(&self) -> VNode<Self>

Build a VNode tree to represent your UI.

This is called whenever the Component needs to re-render, and its UI state will be updated to reflect the VNode tree.

You’ll generally want to use the gtk! macro to build your VNode tree.

Provided Methods

fn update(&mut self, _msg: Self::Message) -> UpdateAction<Self>

Process a Component::Message and update the state accordingly.

If you’ve made changes which should be reflected in the UI state, return UpdateAction::Render. This will call Component::view() and update the widget tree accordingly.

If you need to perform I/O, you can return UpdateAction::Defer, which will run an async action and call Component::update() again with its result.

Otherwise, return UpdateAction::None.

fn create(_props: Self::Properties) -> Self

Construct a new Component given a Component::Properties object.

The default implementation ignores the Properties argument and constructs the component using Default::default(). This is what you want for a top level component, and almost certainly not what you want for a subcomponent.

fn change(&mut self, _props: Self::Properties) -> UpdateAction<Self>

Update a Component’s properties.

This method will never be called on a top level component. Its default implementation panics with a message telling you to implement it for your subcomponent.

fn mounted(&mut self)

This method is called when the Component becomes visible to the user.

The default implementation does nothing. You can reimplement it if you need to be aware of when this happens.

fn unmounted(&mut self)

This method is called just before the Component becomes hidden or is removed entirely.

The default implementation does nothing. You can reimplement it if you need to be aware of when this happens.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl Component for ()

type Message = ()

type Properties = ()

fn view(&self) -> VNode<Self>

Implementors