rat-cursor 1.2.0

ratatui trait to communicate the cursor position across 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

![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-cursor.svg)](https://crates.io/crates/rat-cursor)
[![Documentation](https://docs.rs/rat-cursor/badge.svg)](https://docs.rs/rat-cursor)
[![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-cursor/changes.md)

# Rat-Cursor


## Why?


This crate defines just the trait [HasScreenCursor](HasScreenCursor) for use in
other crates. This aims to overcome the shortcomings of ratatui
to handle cursor positioning by widgets.

> In the long run I hope there will be a solution within ratatui
> which will make this obsolete, but for now ...

```rust
pub trait HasScreenCursor {
    fn screen_cursor(&self) -> Option<(u16, u16)>;
}
```

## Use


### Widget


This trait is implemented for the widget-state struct.

> It's implemented for the state struct because the widget
> might need to run the full layout process to know the cursor
> position. Which would approximately double the rendering
> process.

Instead of setting the cursor position during rendering somehow,
the rendering process stores the cursor position in the state
struct, where it can be retrieved later on.

The trait returns a screen-position, but only if it actually
needs the cursor to be displayed:

* The cursor is not scrolled off-screen.
* The widget has some kind of input-focus.

### Container widget


A container widget can cascade down to its components.

```rust ignore
    fn screen_cursor(&self) -> Option<(u16, u16)> {
    self.widget1.screen_cursor()
        .or(self.widget2.screen_cursor())
        .or(self.widget3.screen_cursor())
}
```

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