Skip to content

Commit 357ae7e

Browse files
joshkaorhun
joshka
and
orhun
authored
chore: move terminal types to ratatui-core (#1530)
- Move Terminal, TerminalOptions, ViewPort, CompletedFrame, Frame to ratatui-core crate - Move render_widget_ref() and render_stateful_widget_ref() to extension trait (FrameExt) due as the Ref types are unstable and kept in the main lib instead of -core - Fix rustdoc errors / feature config issues BREAKING CHANGE: to call `Frame::render_widget_ref()` or `Frame::render_stateful_widget_ref()` you now need to import the FrameExt trait from `ratatui::widgets` and enable the `unstable-widget-ref` feature. Co-authored-by: Orhun Parmaksız <orhunparmaksiz@gmail.com>
1 parent 3b13240 commit 357ae7e

File tree

14 files changed

+144
-100
lines changed

14 files changed

+144
-100
lines changed

‎BREAKING-CHANGES.md

+23
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ This is a quick summary of the sections below:
1212

1313
- [Unreleased](#unreleased)
1414
- The `From` impls for backend types are now replaced with more specific traits
15+
- `FrameExt` trait for `unstable-widget-ref` feature
1516
- [v0.29.0](#v0290)
1617
- `Sparkline::data` takes `IntoIterator<Item = SparklineBar>` instead of `&[u64]` and is no longer const
1718
- Removed public fields from `Rect` iterators
@@ -76,6 +77,28 @@ This is a quick summary of the sections below:
7677

7778
## Unreleased (0.30.0)
7879

80+
### `FrameExt` trait for `unstable-widget-ref` feature ([#1530])
81+
82+
[#1530]: https://github.com/ratatui/ratatui/pull/1530
83+
84+
To call `Frame::render_widget_ref()` or `Frame::render_stateful_widget_ref()` you now need to:
85+
86+
1. Import the `FrameExt` trait from `ratatui::widgets`.
87+
2. Enable the `unstable-widget-ref` feature.
88+
89+
For example:
90+
91+
```rust
92+
use ratatui::{
93+
layout::Rect,
94+
widgets::{Block, FrameExt},
95+
};
96+
97+
let block = Block::new();
98+
let area = Rect::new(0, 0, 5, 5);
99+
frame.render_widget_ref(&block, area);
100+
```
101+
79102
### `WidgetRef` no longer has a blanket implementation of Widget
80103

81104
Previously there was a blanket implementation of Widget for WidgetRef. This has been reversed to

‎README.md

+1-2
Original file line numberDiff line numberDiff line change
@@ -304,8 +304,7 @@ fn draw(frame: &mut Frame) {
304304
[Contributing]: https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md
305305
[Breaking Changes]: https://github.com/ratatui/ratatui/blob/main/BREAKING-CHANGES.md
306306
[FOSDEM 2024 talk]: https://www.youtube.com/watch?v=NU0q6NOLJ20
307-
[`Frame`]: terminal::Frame
308-
[`render_widget`]: terminal::Frame::render_widget
307+
[`render_widget`]: Frame::render_widget
309308
[`Widget`]: widgets::Widget
310309
[`Layout`]: layout::Layout
311310
[`Text`]: text::Text

‎ratatui-core/src/lib.rs

+1
Original file line numberDiff line numberDiff line change
@@ -43,5 +43,6 @@ pub mod buffer;
4343
pub mod layout;
4444
pub mod style;
4545
pub mod symbols;
46+
pub mod terminal;
4647
pub mod text;
4748
pub mod widgets;

‎ratatui/src/terminal.rs renamed to ‎ratatui-core/src/terminal.rs

-6
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,9 @@
3232
//! [`Buffer`]: crate::buffer::Buffer
3333
3434
mod frame;
35-
#[cfg(feature = "crossterm")]
36-
mod init;
3735
mod terminal;
3836
mod viewport;
3937

4038
pub use frame::{CompletedFrame, Frame};
41-
#[cfg(feature = "crossterm")]
42-
pub use init::{
43-
init, init_with_options, restore, try_init, try_init_with_options, try_restore, DefaultTerminal,
44-
};
4539
pub use terminal::{Options as TerminalOptions, Terminal};
4640
pub use viewport::Viewport;

‎ratatui/src/terminal/frame.rs renamed to ‎ratatui-core/src/terminal/frame.rs

+9-72
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
use crate::{
22
buffer::Buffer,
33
layout::{Position, Rect},
4-
widgets::{StatefulWidget, StatefulWidgetRef, Widget, WidgetRef},
4+
widgets::{StatefulWidget, Widget},
55
};
66

77
/// A consistent view into the terminal state for rendering a single frame.
@@ -14,7 +14,7 @@ use crate::{
1414
/// to the terminal. This avoids drawing redundant cells.
1515
///
1616
/// [`Buffer`]: crate::buffer::Buffer
17-
/// [`Terminal::draw`]: crate::Terminal::draw
17+
/// [`Terminal::draw`]: crate::terminal::Terminal::draw
1818
#[derive(Debug, Hash)]
1919
pub struct Frame<'a> {
2020
/// Where should the cursor be after drawing this frame?
@@ -37,7 +37,7 @@ pub struct Frame<'a> {
3737
/// [`Terminal::draw`] call have been applied. Therefore, it is only valid until the next call to
3838
/// [`Terminal::draw`].
3939
///
40-
/// [`Terminal::draw`]: crate::Terminal::draw
40+
/// [`Terminal::draw`]: crate::terminal::Terminal::draw
4141
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
4242
pub struct CompletedFrame<'a> {
4343
/// The buffer that was used to draw the last frame.
@@ -96,32 +96,6 @@ impl Frame<'_> {
9696
widget.render(area, self.buffer);
9797
}
9898

99-
/// Render a [`WidgetRef`] to the current buffer using [`WidgetRef::render_ref`].
100-
///
101-
/// Usually the area argument is the size of the current frame or a sub-area of the current
102-
/// frame (which can be obtained using [`Layout`] to split the total area).
103-
///
104-
/// # Example
105-
///
106-
/// ```rust
107-
/// # #[cfg(feature = "unstable-widget-ref")] {
108-
/// # use ratatui::{backend::TestBackend, Terminal};
109-
/// # let backend = TestBackend::new(5, 5);
110-
/// # let mut terminal = Terminal::new(backend).unwrap();
111-
/// # let mut frame = terminal.get_frame();
112-
/// use ratatui::{layout::Rect, widgets::Block};
113-
///
114-
/// let block = Block::new();
115-
/// let area = Rect::new(0, 0, 5, 5);
116-
/// frame.render_widget_ref(&block, area);
117-
/// # }
118-
/// ```
119-
#[allow(clippy::needless_pass_by_value)]
120-
#[instability::unstable(feature = "widget-ref")]
121-
pub fn render_widget_ref<W: WidgetRef>(&mut self, widget: W, area: Rect) {
122-
widget.render_ref(area, self.buffer);
123-
}
124-
12599
/// Render a [`StatefulWidget`] to the current buffer using [`StatefulWidget::render`].
126100
///
127101
/// Usually the area argument is the size of the current frame or a sub-area of the current
@@ -156,53 +130,16 @@ impl Frame<'_> {
156130
widget.render(area, self.buffer, state);
157131
}
158132

159-
/// Render a [`StatefulWidgetRef`] to the current buffer using
160-
/// [`StatefulWidgetRef::render_ref`].
161-
///
162-
/// Usually the area argument is the size of the current frame or a sub-area of the current
163-
/// frame (which can be obtained using [`Layout`] to split the total area).
164-
///
165-
/// The last argument should be an instance of the [`StatefulWidgetRef::State`] associated to
166-
/// the given [`StatefulWidgetRef`].
167-
///
168-
/// # Example
169-
///
170-
/// ```rust
171-
/// # #[cfg(feature = "unstable-widget-ref")] {
172-
/// # use ratatui::{backend::TestBackend, Terminal};
173-
/// # let backend = TestBackend::new(5, 5);
174-
/// # let mut terminal = Terminal::new(backend).unwrap();
175-
/// # let mut frame = terminal.get_frame();
176-
/// use ratatui::{
177-
/// layout::Rect,
178-
/// widgets::{List, ListItem, ListState},
179-
/// };
180-
///
181-
/// let mut state = ListState::default().with_selected(Some(1));
182-
/// let list = List::new(vec![ListItem::new("Item 1"), ListItem::new("Item 2")]);
183-
/// let area = Rect::new(0, 0, 5, 5);
184-
/// frame.render_stateful_widget_ref(&list, area, &mut state);
185-
/// # }
186-
/// ```
187-
#[allow(clippy::needless_pass_by_value)]
188-
#[instability::unstable(feature = "widget-ref")]
189-
pub fn render_stateful_widget_ref<W>(&mut self, widget: W, area: Rect, state: &mut W::State)
190-
where
191-
W: StatefulWidgetRef,
192-
{
193-
widget.render_ref(area, self.buffer, state);
194-
}
195-
196133
/// After drawing this frame, make the cursor visible and put it at the specified (x, y)
197134
/// coordinates. If this method is not called, the cursor will be hidden.
198135
///
199136
/// Note that this will interfere with calls to [`Terminal::hide_cursor`],
200137
/// [`Terminal::show_cursor`], and [`Terminal::set_cursor_position`]. Pick one of the APIs and
201138
/// stick with it.
202139
///
203-
/// [`Terminal::hide_cursor`]: crate::Terminal::hide_cursor
204-
/// [`Terminal::show_cursor`]: crate::Terminal::show_cursor
205-
/// [`Terminal::set_cursor_position`]: crate::Terminal::set_cursor_position
140+
/// [`Terminal::hide_cursor`]: crate::terminal::Terminal::hide_cursor
141+
/// [`Terminal::show_cursor`]: crate::terminal::Terminal::show_cursor
142+
/// [`Terminal::set_cursor_position`]: crate::terminal::Terminal::set_cursor_position
206143
pub fn set_cursor_position<P: Into<Position>>(&mut self, position: P) {
207144
self.cursor_position = Some(position.into());
208145
}
@@ -214,9 +151,9 @@ impl Frame<'_> {
214151
/// [`Terminal::show_cursor`], and [`Terminal::set_cursor_position`]. Pick one of the APIs and
215152
/// stick with it.
216153
///
217-
/// [`Terminal::hide_cursor`]: crate::Terminal::hide_cursor
218-
/// [`Terminal::show_cursor`]: crate::Terminal::show_cursor
219-
/// [`Terminal::set_cursor_position`]: crate::Terminal::set_cursor_position
154+
/// [`Terminal::hide_cursor`]: crate::terminal::Terminal::hide_cursor
155+
/// [`Terminal::show_cursor`]: crate::terminal::Terminal::show_cursor
156+
/// [`Terminal::set_cursor_position`]: crate::terminal::Terminal::set_cursor_position
220157
#[deprecated = "the method set_cursor_position indicates more clearly what about the cursor to set"]
221158
pub fn set_cursor(&mut self, x: u16, y: u16) {
222159
self.set_cursor_position(Position { x, y });

‎ratatui/src/terminal/terminal.rs renamed to ‎ratatui-core/src/terminal/terminal.rs

+2-3
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
use std::io;
22

3-
use ratatui_core::backend::{Backend, ClearType};
4-
53
use crate::{
4+
backend::{Backend, ClearType},
65
buffer::{Buffer, Cell},
76
layout::{Position, Rect, Size},
8-
CompletedFrame, Frame, TerminalOptions, Viewport,
7+
terminal::{CompletedFrame, Frame, TerminalOptions, Viewport},
98
};
109

1110
/// An interface to interact and draw [`Frame`]s on the user's terminal.

‎ratatui/src/terminal/viewport.rs renamed to ‎ratatui-core/src/terminal/viewport.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ use crate::layout::Rect;
1515
///
1616
/// See [`Terminal::with_options`] for more information.
1717
///
18-
/// [`Terminal::with_options`]: crate::Terminal::with_options
18+
/// [`Terminal::with_options`]: crate::terminal::Terminal::with_options
1919
#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
2020
pub enum Viewport {
2121
/// The viewport is fullscreen

‎ratatui-crossterm/Cargo.toml

+1-2
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,7 @@ rust-version.workspace = true
1818
default = ["underline-color"]
1919

2020
## enables the backend code that sets the underline color.
21-
## Underline color is only supported by the [`CrosstermBackend`](backend::CrosstermBackend) backend,
22-
## and is not supported on Windows 7.
21+
## Underline color is not supported on Windows 7.
2322
underline-color = ["ratatui-core/underline-color"]
2423

2524
## Use terminal scrolling regions to make Terminal::insert_before less prone to flickering.

‎ratatui-termion/Cargo.toml

+4-1
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,12 @@ rustdoc-args = ["--cfg", "docsrs"]
2121

2222
[features]
2323
default = []
24-
2524
## Use terminal scrolling regions to make Terminal::insert_before less prone to flickering.
2625
scrolling-regions = ["ratatui-core/scrolling-regions"]
26+
## Enables all unstable features.
27+
unstable = ["unstable-backend-writer"]
28+
## Enables getting access to backends' writer.
29+
unstable-backend-writer = []
2730

2831
[dependencies]
2932
document-features = { workspace = true, optional = true }

‎ratatui-termion/src/lib.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ use termion::{color as tcolor, color::Color as _, style as tstyle};
7272
///
7373
/// [`IntoRawMode::into_raw_mode()`]: termion::raw::IntoRawMode
7474
/// [`IntoAlternateScreen::into_alternate_screen()`]: termion::screen::IntoAlternateScreen
75-
/// [`Terminal`]: ratatui::terminal::Terminal
75+
/// [`Terminal`]: ratatui_core::terminal::Terminal
7676
/// [Termion]: https://docs.rs/termion
7777
#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
7878
pub struct TermionBackend<W>

‎ratatui/Cargo.toml

+5-2
Original file line numberDiff line numberDiff line change
@@ -89,8 +89,11 @@ unstable-rendered-line-info = ["ratatui-widgets/unstable-rendered-line-info"]
8989
## [`StatefulWidgetRef`]: widgets::StatefulWidgetRef
9090
unstable-widget-ref = []
9191

92-
## Enables getting access to backends' writers. Only the Crossterm backend currently supports this.
93-
unstable-backend-writer = ["ratatui-crossterm?/unstable-backend-writer"]
92+
## Enables getting access to backends' writers.
93+
unstable-backend-writer = [
94+
"ratatui-crossterm?/unstable-backend-writer",
95+
"ratatui-termion?/unstable-backend-writer",
96+
]
9497

9598
[dependencies]
9699
document-features = { workspace = true, optional = true }

‎ratatui/src/terminal/init.rs renamed to ‎ratatui/src/init.rs

+1-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
use std::io::{self, stdout, Stdout};
22

3+
use ratatui_core::terminal::{Terminal, TerminalOptions};
34
use ratatui_crossterm::{
45
crossterm::{
56
execute,
@@ -8,8 +9,6 @@ use ratatui_crossterm::{
89
CrosstermBackend,
910
};
1011

11-
use crate::{terminal::TerminalOptions, Terminal};
12-
1312
/// A type alias for the default terminal type.
1413
///
1514
/// This is a [`Terminal`] using the [`CrosstermBackend`] which writes to [`Stdout`]. This is a

‎ratatui/src/lib.rs

+10-8
Original file line numberDiff line numberDiff line change
@@ -290,8 +290,7 @@
290290
//! [Contributing]: https://github.com/ratatui/ratatui/blob/main/CONTRIBUTING.md
291291
//! [Breaking Changes]: https://github.com/ratatui/ratatui/blob/main/BREAKING-CHANGES.md
292292
//! [FOSDEM 2024 talk]: https://www.youtube.com/watch?v=NU0q6NOLJ20
293-
//! [`Frame`]: terminal::Frame
294-
//! [`render_widget`]: terminal::Frame::render_widget
293+
//! [`render_widget`]: Frame::render_widget
295294
//! [`Widget`]: widgets::Widget
296295
//! [`Layout`]: layout::Layout
297296
//! [`Text`]: text::Text
@@ -329,6 +328,10 @@
329328
/// re-export the `palette` crate so that users don't have to add it as a dependency
330329
#[cfg(feature = "palette")]
331330
pub use palette;
331+
pub use ratatui_core::{
332+
buffer, layout,
333+
terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport},
334+
};
332335
/// re-export the `crossterm` crate so that users don't have to add it as a dependency
333336
#[cfg(feature = "crossterm")]
334337
pub use ratatui_crossterm::crossterm;
@@ -338,11 +341,11 @@ pub use ratatui_termion::termion;
338341
/// re-export the `termwiz` crate so that users don't have to add it as a dependency
339342
#[cfg(feature = "termwiz")]
340343
pub use ratatui_termwiz::termwiz;
344+
341345
#[cfg(feature = "crossterm")]
342-
pub use terminal::{
346+
pub use crate::init::{
343347
init, init_with_options, restore, try_init, try_init_with_options, try_restore, DefaultTerminal,
344348
};
345-
pub use terminal::{CompletedFrame, Frame, Terminal, TerminalOptions, Viewport};
346349

347350
/// Re-exports for the backend implementations.
348351
pub mod backend {
@@ -355,10 +358,9 @@ pub mod backend {
355358
pub use ratatui_termwiz::{FromTermwiz, IntoTermwiz, TermwizBackend};
356359
}
357360

358-
pub use ratatui_core::{buffer, layout};
359361
pub mod prelude;
360-
pub use ratatui_core::{style, symbols};
361-
mod terminal;
362-
pub use ratatui_core::text;
362+
pub use ratatui_core::{style, symbols, text};
363363
pub mod widgets;
364364
pub use ratatui_widgets::border;
365+
#[cfg(feature = "crossterm")]
366+
mod init;

0 commit comments

Comments
 (0)