Events

Tuix includes an event system to communicate user interaction to widgets.

Event Description

An event is described by the Event struct:

...
pub struct Event {
    // The entity that produced the event. Entity::null() for OS events or unspecified.
    pub origin: Entity,
    // The entity the event should be sent to. Entity::null() to send to all entities.
    pub target: Entity,
    // How the event propagates through the tree.
    pub propagation: Propagation,
    // Whether the event can be cancelled
    pub cancellable: bool,
    // Whether the event is unique (only the latest copy can exist in a queue at a time)
    pub unique: bool,
    // TODO
    pub order: i32,
    // The event type
    pub message: Box<Message>,
}

Message

A message is any rust struct or enum that implements Debug, Clone and PartialEq. Below is an example of a message enum used by the Textbox widget:

#[derive(Debug, Clone, PartialEq)]
pub enum TextboxEvent {
    SetValue(String),
    ValueChanged(String),
}

The `SetValue` variant is used to tell the textbox to change its value and originates from another widget. The `ValueChanged` variant is emitted by the textbox when the user changes the text inside the textbox.

# Receiveing Events

Events are received by a widget through the `on_event()` function within the `EventHandler` trait which is implemented by all widgets. To access the message within an event, the message must be downcast to the correct type. For example, inside the `on_event` function:

```Rust
if let Some(window_event) = event.message.downcast::<WindowEvent>() {
    // Do something with the window_event, like matching on the different variants
}

Event Propagation

It's worth taking a moment to understand how events propagate through tuix. Each application loop, sent events get put into a queue. On the next loop iteration, the events are flushed from the queue and sent to the corresponding targets one by one in the order of the hierarchy.

The hierarchy is a tree which contains all of the widgets in the application. The window is at the root of the tree and widgets and their children make up the branches and leaves. For example, an application with a window, a container, and a widget within the container would look like this in the hierarchy:

// Image here

There are four types of event propagation:

• DownUp: The event is sent from the root to the target and then back up to the root. This means that, unless the event is captured, many widgets along the path, except for the target, will receive the event twice.
• Down: The event propagates down from the root to the target.
• Up: The event propagates up from the target to the root.
• Fall: The event propagates from the target down the branch to the last leaf widget.
• Direct: The event is sent directly to the target and no other widgets.

Sending Events

Events are sent using the state like so:

state.insert_event(Event::new(CalculatorEvent::Digit('0')).target(entity));

This is from the calculator.rs example and shows how to send a custom event.

Window Events