Crate rat_event 

This crate is a part of rat-salsa.

• Changes

Rat-Event

Why?

This crate defines the trait HandleEvent to help with composability of event-handling for ratatui widgets.

Objectives are

• work for all event-types.
• allow for multiple handlers per widget
  • to override the key-bindings
  • to have different key-bindings for certain scenarios.
• have a return type to indicate what state change occurred.

pub trait HandleEvent<Event, Qualifier, Return>
where
    Return: ConsumedEvent
{
    fn handle(
        &mut self,
        event: &Event,
        qualifier: Qualifier
    ) -> Return;
}

Event

Can be anything.

Qualifier

There are predefined qualifiers

• Regular - Do what is considered ‘normal’ behaviour. Can vary depending on the actual state of the widget (e.g. focus)

• MouseOnly - Splitting off mouse interaction helps when you only want to redefine the key bindings. And handling mouse events is usually more involved/complicated/specific.

• DoubleClick - Double clicks are a bit special for widgets, often it requires a distinct return type and it’s not as generally needed as other mouse behaviour.

• Popup - Popup event-handlers are regular event-handlers, but they need processing before regular event-handlers. This is used for widgets that render popups above other widgets, and must make sure that event-handling for the popup doesn’t interfere with widgets below the popup. By ensuring the order of event-handling most of the problems can be solved.

• Dialog - Specialized event-handler for dialog-like popups. They want to be called first to be able to consume all events, thus blocking everything else.

Return

The return type can be anything too.

To be useful it is required to implement ConsumedEvent to indicate if the event has been handled by the widget and further event-handling can stop.

To set a baseline for the return type this crate defines the enum Outcome which can indicate if a render is necessary or not.

All return types in rat-salsa/rat-widget are convertible to/from Outcome and implement ConsumedEvent.

ConsumedEvent

ConsumedEvent has a few method to combine two Outcomes. Plus there are a few macros that work with ConsumedEvent too.

Modules

crossterm

Support for the ct_event! macro.

util

Some utility functions that pop up all the time.

Macros

break_flow

This macro doesn’t return from the current function, but does a labeled break if the block returns a value for which [ConsumedEvent::is_consumed] == true.

ct_event

This macro produces pattern matches for crossterm events.

event_flow

experimental

flow

Returns from the current function if the block returns a value for which [ConsumedEvent::is_consumed] == true.

try_flow

Returns from the current function if the block returns a value for which [ConsumedEvent::is_consumed] == true.

Structs

Dialog

Event-handling for a dialog like widget.

DoubleClick

Event-handler for double-click on a widget.

MouseOnly

Handle mouse-events only. Useful whenever you want to write new key-bindings, but keep the mouse-events.

Popup

Popup/Overlays are a bit difficult to handle, as there is no z-order/area tree, which would direct mouse interactions. We can simulate a z-order in the event-handler by trying the things with a higher z-order first.

Regular

All the regular and expected event-handling a widget can do.

Enums

Outcome

The baseline outcome for an event-handler.

Traits

ConsumedEvent

When calling multiple event-handlers, the minimum information required from the result is ‘has consumed/didn’t consume’ the event.

HandleEvent

A very broad trait for an event handler.