Module events

Events for communicating state change to views and models.

Views and Models communicate with each other via events. An Event contains a message, as well as metadata to describe how events should propagate through the tree. By default events will propagate up the tree from the target, visiting each ancestor as well as any models attached to the ancestors.

A message can be any static thread-safe type but is usually an enum. For example:

enum AppEvent {
    Increment,
    Decrement,    
}

Then, to send an event up the tree from the current entity, we can use cx.emit(...), for example:

pub struct AppData {
    count: i32,
}

impl Model for AppData {}

pub enum AppEvent {
    Increment,
    Decrement,    
}

Application::new(|cx|{
    AppData {
        count: 0,
    }.build(cx);

    Label::new(cx, "Increment")
        .on_press(|cx| cx.emit(AppEvent::Increment));
})
.run();

Views and Models receive events through the event() method of the View or Model traits. The event message must then be downcast to the right type using the map or take methods on the event:

pub struct AppData {
    count: i32,
}

pub enum AppEvent {
    Increment,
    Decrement,    
}

impl Model for AppData {
    fn event(&mut self, _cx: &mut EventContext, event: &mut Event) {
        // `event.map()` will attempt to cast the event message to the desired type and
        // pass a reference to the message type to the closure passed to the `map()` method.
        event.map(|app_event, _| match app_event {
            AppEvent::Increment => {
                self.count += 1;
            }

            AppEvent::Decrement => {
                self.count -= 1;
            }
        });
     
        // Alternatively, `event.take()` will attempt to cast the event message to the
        // desired type and return the value of the message (not a reference),
        // removing it from the event and thus preventing it from propagating further.
        event.take(|app_event, meta| match app_event {
            AppEvent::Increment => {
                self.count += 1;
            }

            AppEvent::Decrement => {
                self.count -= 1;
            }
        });
    }
}

Modules

• event_manager

Structs

• Event
  A wrapper around a message, providing metadata on how the event travels through the view tree.
• EventMeta
  The metadata of an Event.
• TimedEventHandle
  A handle used to cancel a scheduled event before it is sent with cx.cancel_scheduled.
• Timer
  A handle used to start, stop, and check the running status of a timer added with cx.add_timer().

Enums

• Propagation
  Determines how an event propagates through the tree.
• TimerAction
  Enum which can be used to determine the reason a timer callback was called.
• WindowEvent
  Events generated by the application in response to OS events as well as events that can be used to set properties of the window.