Crate rat_event

Current status: BETA

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 occured.

    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, Dialog - Specialized event-handlers, but they tend to popup again and again.

Return

The return type can be anything at all.

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.

For interop all return types in rat-salsa are convertible to/from Outcome.

Modules

• crossterm
  Support for the ct_event! macro.
• util
  Some utility functions that pop up all the time.

Macros

• ct_event
  This macro produces pattern matches for crossterm events.
• flow
  Breaks the control-flow if the block returns a value for which ConsumedEvent::is_consumed is true.
• try_flow
  Breaks the control-flow if the block returns a value for which ConsumedEvent::is_consumed is 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 consumed the event/didn’t consume the event.
• HandleEvent
  A very broad trait for an event handler.