rat-event 2.0.0

ratatui event handler trait for widgets
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

![semver](https://img.shields.io/badge/semver-☑-FFD700)
![stable](https://img.shields.io/badge/stability-stable-8A2BE2)
[![crates.io](https://img.shields.io/crates/v/rat-event.svg)](https://crates.io/crates/rat-event)
[![Documentation](https://docs.rs/rat-event/badge.svg)](https://docs.rs/rat-event)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![License](https://img.shields.io/badge/license-APACHE-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
![](https://tokei.rs/b1/github/thscharler/rat-salsa)

This crate is a part of [rat-salsa][refRatSalsa].

* [Changes](https://github.com/thscharler/rat-salsa/blob/master/rat-event/changes.md)

# Rat-Event


## Why?


This crate defines the trait [HandleEvent](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.

```rust ignore
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](Regular) - Do what is considered 'normal' behaviour.
  Can vary depending on the actual state of the widget
  (e.g. focus)

* [MouseOnly](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](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) - 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](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](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](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.

[refRatSalsa]: https://docs.rs/rat-salsa