Ratatui Core

https://docs.rs/ratatui-core
Admin
Ratatui Core is the foundational library for building rich terminal user interfaces in Rust,...
Tokens:3,508,038
Snippets:19,573
Trust Score:9.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Flex Start Alignment Example in Rust

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/layout/enum.Flex

Illustrates the 'Start' Flex option, which aligns items to the beginning of the container. This example shows different constraint combinations and how they are positioned when using the 'Start' alignment.

```rust
/*
<------------------------------------80 px------------------------------------->
┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
│Percentage(20)││    Length(20)    ││     Fixed(20)    │
└──────────────┘└──────────────────┘└──────────────────┘

<------------------------------------80 px------------------------------------->
┌──────20 px───────┐┌──────20 px───────┐
│      Max(20)     ││      Max(20)     │
└──────────────────┘└──────────────────┘

<------------------------------------80 px------------------------------------->
┌──────20 px───────┐
│      Max(20)     │
└──────────────────┘
*/
```

--------------------------------

### Flex Start Alignment Example (Rust)

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/layout/enum.Flex_search=std%3A%3Avec

Demonstrates the 'Start' Flex alignment, where items are aligned to the beginning of the container. This example shows how elements with different constraint types are positioned at the start when excess space is available, showcasing the flexibility in layout arrangement.

```text
<------------------------------------80 px------------------------------------->
┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐
│Percentage(20)││    Length(20)    ││     Fixed(20)    │
└──────────────┘└──────────────────┘└──────────────────┘

<------------------------------------80 px------------------------------------->
┌──────20 px───────┐┌──────20 px───────┐
│      Max(20)     ││      Max(20)     │
└──────────────────┘└──────────────────┘

<------------------------------------80 px------------------------------------->
┌──────20 px───────┐
│      Max(20)     │
└──────────────────┘
```

--------------------------------

### Examples

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/widgets/trait.Widget_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Code examples demonstrating how to use the Widget trait and its implementations.

```APIDOC
## Examples

### Basic Widget Rendering
```rust
use ratatui::{
    backend::TestBackend,
    widgets::{Clear, Widget},
    Terminal,
};

// Assume 'terminal' is an initialized Terminal instance
// terminal.draw(|frame| {
//     frame.render_widget(Clear, frame.area());
// });
```

### Custom Widget Implementation
```rust
use ratatui_core::buffer::Buffer;
use ratatui_core::layout::Rect;
use ratatui_core::text::Line;
use ratatui_core::widgets::Widget;

struct MyWidget;

impl Widget for MyWidget {
    fn render(self, area: Rect, buf: &mut Buffer) {
        Line::raw("Hello").render(area, buf);
    }
}
```
```

--------------------------------

### Terminal Initialization Examples (Rust)

Source: https://docs.rs/ratatui-core/0.1.0/src/ratatui_core/terminal/terminal.rs_search=u32+-%3E+bool

Demonstrates two ways to initialize and use the `Terminal` in Rust applications. The recommended modern approach uses convenience functions like `ratatui::run()`, while the manual construction method provides more fine-grained control over the backend and terminal setup.

```rust
use std::io::stdout;

use ratatui::{backend::CrosstermBackend, widgets::Paragraph, Terminal};

// Manual construction example
let backend = CrosstermBackend::new(stdout());
let mut terminal = Terminal::new(backend)?;
terminal.draw(|frame| {
    let area = frame.area();
    frame.render_widget(Paragraph::new("Hello World!"), area);
})?;

// Convenience function example (modern approach)
ratatui::run(|terminal| {
    terminal.draw(|frame| {
        let area = frame.area();
        frame.render_widget(Paragraph::new("Hello World!"), area);
    })?;
    Ok(())
})?;
# std::io::Result::Ok(())

```

--------------------------------

### Line Creation Examples

Source: https://docs.rs/ratatui-core/latest/ratatui_core/text/struct.Line_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples demonstrating how to create Line objects using various methods and initial data.

```APIDOC
## Examples: Creating Lines

`Line`s can be created from `Span`s, `String`s, and `&str`s. They can be styled with a `Style`.

```rust
use ratatui_core::style::{Color, Modifier, Style, Stylize};
use ratatui_core::text::{Line, Span};

let style = Style::new().yellow();
let line = Line::raw("Hello, world!").style(style);
let line = Line::styled("Hello, world!", style);
let line = Line::styled("Hello, world!", (Color::Yellow, Modifier::BOLD));

let line = Line::from("Hello, world!");
let line = Line::from(String::from("Hello, world!"));
let line = Line::from(vec![
    Span::styled("Hello", Style::new().blue()),
    Span::raw(" world!"),
]);
```
```

--------------------------------

### Line Styling Examples

Source: https://docs.rs/ratatui-core/latest/ratatui_core/text/struct.Line_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples illustrating how to apply styles to Line objects.

```APIDOC
## Examples: Styling Lines

The line’s `Style` is used by the rendering widget to determine how to style the line. Each `Span` in the line will be styled with the `Style` of the line, and then with its own `Style`. If the line is longer than the available space, the style is applied to the entire line, and the line is truncated. `Line` also implements `Styled` which means you can use the methods of the `Stylize` trait.

```rust
use ratatui_core::style::{Color, Modifier, Style, Stylize};
use ratatui_core::text::Line;

let line = Line::from("Hello world!").style(Style::new().yellow().italic());
let line = Line::from("Hello world!").style(Color::Yellow);
let line = Line::from("Hello world!").style((Color::Yellow, Color::Black));
let line = Line::from("Hello world!").style((Color::Yellow, Modifier::ITALIC));
let line = Line::from("Hello world!").yellow().italic();
```
```

--------------------------------

### Ratatui Flex Start Alignment Example

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/layout/enum.Flex_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates the 'Start' alignment option for Ratatui's Flex enum, where items are aligned to the beginning of the container. This example shows different constraint types and their positions.

```Text
<------------------------------------80 px------------------------------------->\n┌────16 px─────┐┌──────20 px───────┐┌──────20 px───────┐\n│Percentage(20)││    Length(20)    ││     Fixed(20)    │\n└──────────────┘└──────────────────┘└──────────────────┘
```

--------------------------------

### Constraint Creation and Usage Examples

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/layout/enum.Constraint_search=

Illustrates how to use Percentage, Ratio, and Fill constraints to define layout proportions and provides visual examples of their application.

```APIDOC
## Percentage Constraint

### Description
Defines a constraint that occupies a specific percentage of the available space.

### Examples
`[Percentage(75), Fill(1)]`
```
┌────────────────────────────────────┐┌──────────┐
│                38 px               ││   12 px  │
└────────────────────────────────────┘└──────────┘
```

`[Percentage(50), Fill(1)]`
```
┌───────────────────────┐┌───────────────────────┐
│         25 px         ││         25 px         │
└───────────────────────┘└───────────────────────┘
```

## Ratio Constraint

### Description
Applies a ratio of the available space to an element. This ratio is converted to a floating-point value and multiplied by the area, then rounded for layout calculations.

### Examples
`[Ratio(1, 2) ; 2]`
```
┌───────────────────────┐┌───────────────────────┐
│         25 px         ││         25 px         │
└───────────────────────┘└───────────────────────┘
```

`[Ratio(1, 4) ; 4]`
```
┌───────────┐┌──────────┐┌───────────┐┌──────────┐
│   13 px   ││   12 px  ││   13 px   ││   12 px  │
└───────────┘└──────────┘└───────────┘└──────────┘
```

## Fill Constraint

### Description
Applies a scaling factor proportional to other `Constraint::Fill` elements to fill excess space. Elements with `Fill` constraints expand proportionally to occupy available space after other constraints are met.

### Examples
`[Fill(1), Fill(2), Fill(3)]`
```
┌──────┐┌───────────────┐┌───────┐
│ 8 px ││     17 px     ││  25 px│
└──────┘└───────────────┘└───────┘
```

`[Fill(1), Percentage(50), Fill(1)]`
```
┌───────────┐┌───────────────────────┐┌──────────┐
│   13 px   ││         25 px         ││   12 px  │
└───────────┘└───────────────────────┘└──────────┘
```
```

--------------------------------

### Text Examples

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/text/struct.Text_search=u32+-%3E+bool

Illustrative examples demonstrating how to create, style, and combine Text objects.

```APIDOC
## Examples

### Creating Text
A `Text`, like a `Line`, can be constructed using one of the many `From` implementations or via the `Text::raw` and `Text::styled` methods. `Text` also implements `core::iter::Extend` which enables the concatenation of several `Text` blocks.

```rust
use std::borrow::Cow;
use std::iter;

use ratatui_core::style::{Color, Modifier, Style, Stylize};
use ratatui_core::text::{Line, Span, Text};

let style = Style::new().yellow().italic();
let text = Text::raw("The first line\nThe second line").style(style);
let text = Text::styled("The first line\nThe second line", style);
let text = Text::styled(
    "The first line\nThe second line",
    (Color::Yellow, Modifier::ITALIC),
);

let text = Text::from("The first line\nThe second line");
let text = Text::from(String::from("The first line\nThe second line"));
let text = Text::from(Cow::Borrowed("The first line\nThe second line"));
let text = Text::from(Span::styled("The first line\nThe second line", style));
let text = Text::from(Line::from("The first line"));
let text = Text::from(vec![
    Line::from("The first line"),
    Line::from("The second line"),
]);
let text = Text::from_iter(iter::once("The first line").chain(iter::once("The second line")));

let mut text = Text::default();
text.extend(vec![
    Line::from("The first line"),
    Line::from("The second line"),
]);
text.extend(Text::from("The third line\nThe fourth line"));
```

### Styling Text
The text’s `Style` is used by the rendering widget to determine how to style the text. Each `Line` in the text will be styled with the `Style` of the text, and then with its own `Style`. `Text` also implements `Styled` which means you can use the methods of the `Stylize` trait.

```rust
use ratatui_core::style::{Color, Modifier, Style, Stylize};
use ratatui_core::text::{Line, Text};

let text = Text::from("The first line\nThe second line").style(Style::new().yellow().italic());
let text = Text::from("The first line\nThe second line")
    .yellow()
    .italic();
let text = Text::from(vec![
    Line::from("The first line").yellow(),
    Line::from("The second line").yellow(),
])
.italic();
```
```

--------------------------------

### Example Searches for Rust Functions and Types

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/style/trait.Styled_search=

Provides example search queries for Rust code, demonstrating how to find specific functions, types, and generic patterns. These examples are useful for navigating and understanding the Ratatui codebase or other Rust projects.

```rust
std::vec
```

```rust
u32 -> bool
```

```rust
Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Layout Example Usage

Source: https://docs.rs/ratatui-core/latest/ratatui_core/layout/struct.Layout_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

A practical example demonstrating how to use the Layout struct to divide a terminal area and render content.

```APIDOC
## §Example

```rust
use ratatui_core::buffer::Buffer;
use ratatui_core::layout::{Constraint, Direction, Layout, Rect};
use ratatui_core::text::Text;
use ratatui_core::widgets::Widget;

fn render(area: Rect, buf: &mut Buffer) {
    // Create a vertical layout with two constraints: a fixed height of 5 and the remaining space.
    let layout = Layout::vertical([Constraint::Length(5), Constraint::Fill(1)]);
    
    // Split the given area according to the layout constraints.
    let [top, bottom] = layout.areas(area);
    
    // Render content into the split areas.
    Text::from("foo").render(top, buf);
    Text::from("bar").render(bottom, buf);
}
```

See the `layout`, `flex`, and `constraints` examples in the Examples folder for more details about how to use layouts. For comprehensive layout documentation and examples, see the `layout` module.
```

--------------------------------

### Rust Search Examples for Ratatui Core

Source: https://docs.rs/ratatui-core/0.1.0/src/ratatui_core/layout/flex.rs_search=

This section provides example search queries for a Rust project, likely within the Ratatui ecosystem. These examples demonstrate how to search for specific types, function signatures, and generic type transformations, aiding in code navigation and understanding.

```rust
Example searches:
  * std::vec
  * u32 -> bool
  * Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Line Alignment Examples

Source: https://docs.rs/ratatui-core/latest/ratatui_core/text/struct.Line_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Examples demonstrating how to align Line objects within available space.

```APIDOC
## Examples: Aligning Lines

The line’s `Alignment` is used by the rendering widget to determine how to align the line within the available space. If the line is longer than the available space, the alignment is ignored and the line is truncated.

```rust
use ratatui_core::layout::Alignment;
use ratatui_core::text::Line;

let line = Line::from("Hello world!").alignment(Alignment::Right);
let line = Line::from("Hello world!").centered();
let line = Line::from("Hello world!").left_aligned();
let line = Line::from("Hello world!").right_aligned();
```
```

--------------------------------

### Widget Usage Example

Source: https://docs.rs/ratatui-core/latest/ratatui_core/widgets/trait.Widget_search=

A practical example demonstrating how to use the `Widget` trait, specifically rendering a `Clear` widget.

```APIDOC
## Example

```rust
use ratatui::{
    backend::TestBackend,
    widgets::{Clear, Widget},
    Terminal,
};

// Assuming 'terminal' is an initialized Terminal instance
// let backend = TestBackend::new(80, 24);
// let mut terminal = Terminal::new(backend).unwrap();

// terminal.draw(|frame| {
//     frame.render_widget(Clear, frame.area());
// });
```

It's common to render widgets inside other widgets, often composing complex UI elements from simpler ones. The `render` method is the key to this composition.

```rust
use ratatui_core::buffer::Buffer;
use ratatui_core::layout::Rect;
use ratatui_core::text::Line;
use ratatui_core::widgets::Widget;

struct MyWidget;

impl Widget for MyWidget {
    fn render(self, area: Rect, buf: &mut Buffer) {
        // Render a simple line of text within the given area
        Line::raw("Hello").render(area, buf);
    }
}
```
```

--------------------------------

### Layout Example Usage

Source: https://docs.rs/ratatui-core/latest/ratatui_core/layout/struct.Layout

Provides a practical code example demonstrating how to use the `Layout` struct to divide a terminal area and render content into the resulting sub-areas.

```APIDOC
## §Example
```rust
use ratatui_core::buffer::Buffer;
use ratatui_core::layout::{Constraint, Direction, Layout, Rect};
use ratatui_core::text::Text;
use ratatui_core::widgets::Widget;

fn render(area: Rect, buf: &mut Buffer) {
    let layout = Layout::vertical([Constraint::Length(5), Constraint::Fill(1)]);
    let [top, bottom] = layout.areas(area);
    Text::from("foo").render(top, buf);
    Text::from("bar").render(bottom, buf);
}
```

See the `layout`, `flex`, and `constraints` examples in the Examples folder for more details about how to use layouts. For comprehensive layout documentation and examples, see the `layout` module.
```

--------------------------------

### Terminal Drawing Example

Source: https://docs.rs/ratatui-core/latest/ratatui_core/terminal/index_search=u32+-%3E+bool

An example demonstrating how to initialize a `Terminal` with a `CrosstermBackend` and draw a simple `Paragraph` widget.

```APIDOC
## §Example

```rust
use std::io::stdout;

use ratatui::{backend::CrosstermBackend, widgets::Paragraph, Terminal};

let backend = CrosstermBackend::new(stdout());
let mut terminal = Terminal::new(backend)?;
terminal.draw(|frame| {
    let area = frame.area();
    frame.render_widget(Paragraph::new("Hello world!"), area);
})?;
```
```

--------------------------------

### Widget Usage Example

Source: https://docs.rs/ratatui-core/latest/ratatui_core/widgets/trait.Widget_search=u32+-%3E+bool

Illustrates a basic example of how to use the `Widget` trait to render a simple UI element.

```APIDOC
## Examples

### Basic Usage
```rust
use ratatui::backend::TestBackend;
use ratatui::widgets::{Clear, Widget};
use ratatui::Terminal;

// Assuming 'terminal' is an initialized Terminal instance
// terminal.draw(|frame| {
//     frame.render_widget(Clear, frame.area());
// });
```

### Custom Widget
```rust
use ratatui_core::buffer::Buffer;
use ratatui_core::layout::Rect;
use ratatui_core::text::Line;
use ratatui_core::widgets::Widget;

struct MyWidget;

impl Widget for MyWidget {
    fn render(self, area: Rect, buf: &mut Buffer) {
        Line::raw("Hello").render(area, buf);
    }
}
```
```

--------------------------------

### Stylize Trait - Examples

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/style/trait.Stylize_search=

Illustrative examples demonstrating how to use the `Stylize` trait for various styling scenarios.

```APIDOC
## Examples

### Styling a Span
```rust
use ratatui_core::style::Stylize;

let styled_span = "hello".red().on_blue().bold();
```

### Styling a Line
```rust
use ratatui_core::style::Stylize;
use ratatui_core::text::Line;

let styled_line = Line::from([
    "hello".red().on_blue().bold(),
    "world".green().on_yellow().not_bold(),
]);
```

### Styling a Paragraph Widget
```rust
use ratatui_core::style::Stylize;
use ratatui_core::text::Line;
use ratatui_core::widgets::Paragraph;

let line = Line::from(["styled text".blue()]);
let styled_paragraph = Paragraph::new(line).italic().underlined();
```

### Styling a Block Widget
```rust
use ratatui_core::style::Stylize;
use ratatui_core::widgets::Block;

let styled_block = Block::bordered().title("Title").on_white().bold();
```
```

--------------------------------

### Creating Text Example

Source: https://docs.rs/ratatui-core/latest/ratatui_core/text/struct.Text_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates various ways to create Text instances using constructor and conversion methods.

```APIDOC
### Creating Text

A `Text`, like a `Line`, can be constructed using one of the many `From` implementations or via the `Text::raw` and `Text::styled` methods. `Text` also implements `core::iter::Extend` which enables the concatenation of several `Text` blocks.

```rust
use std::borrow::Cow;
use std::iter;

use ratatui_core::style::{Color, Modifier, Style, Stylize};
use ratatui_core::text::{Line, Span, Text};

// Using styled constructor
let style = Style::new().yellow().italic();
let text_styled_raw = Text::raw("The first line\nThe second line").style(style);
let text_styled_direct = Text::styled("The first line\nThe second line", style);
let text_styled_tuple = Text::styled("The first line\nThe second line", (Color::Yellow, Modifier::ITALIC));

// Using From implementations
let text_from_str = Text::from("The first line\nThe second line");
let text_from_string = Text::from(String::from("The first line\nThe second line"));
let text_from_cow = Text::from(Cow::Borrowed("The first line\nThe second line"));
let text_from_span = Text::from(Span::styled("The first line\nThe second line", style));
let text_from_line = Text::from(Line::from("The first line"));
let text_from_vec_line = Text::from(vec![Line::from("The first line"), Line::from("The second line")]);
let text_from_iter = Text::from_iter(iter::once("The first line").chain(iter::once("The second line")));

// Using Extend
let mut text_extend = Text::default();
text_extend.extend(vec![Line::from("The first line"), Line::from("The second line")]);
text_extend.extend(Text::from("The third line\nThe fourth line"));
```
```

--------------------------------

### Example: Get Frame Count - Rust

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/terminal/struct.Frame_search=u32+-%3E+bool

An example demonstrating how to retrieve and print the current frame count using the `count()` method.

```rust
let current_count = frame.count();
println!("Current frame count: {}", current_count);
```

--------------------------------

### TestBackend Initialization and Configuration

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/backend/struct.TestBackend_search=

Illustrates different ways to create a TestBackend instance. This includes creating a new backend with dimensions and initializing it with predefined lines to set the initial screen state. The `with_lines` method is particularly useful for setting up specific test scenarios.

```Rust
pub fn new(width: u16, height: u16) -> Self

pub fn with_lines<'line, Lines>(lines: Lines) -> Self
where
    Lines: IntoIterator,
    Lines::Item: Into<Line<'line>>
```

--------------------------------

### Create TestBackend with Initial Lines (Rust)

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/backend/struct.TestBackend_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to initialize a TestBackend using a collection of lines as the starting state of the screen buffer. The backend's size is derived from the provided lines.

```rust
use ratatui::backend::TestBackend;
use ratatui::text::Line;

let initial_lines = vec!["Line 1", "Line 2"];
let backend = TestBackend::with_lines(initial_lines);
// The backend's dimensions will be determined by the length of "Line 1" and the number of lines.
```

--------------------------------

### Layout Example: Get Specific Spacers (Rust)

Source: https://docs.rs/ratatui-core/0.1.0/src/ratatui_core/layout/layout.rs_search=std%3A%3Avec

Demonstrates using the `spacers` method with a const generic to specify the exact number of spacer rectangles expected. This example shows getting spacers from a vertical layout and verifies the output matches the expected number.

```rust
use ratatui_core::layout::{Constraint, Layout, Rect};

let area = Rect::new(0, 0, 10, 10);
let layout = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]);
let [before, inbetween, after] = layout.spacers::<3>(area);

// Further assertions can be made on before, inbetween, and after.
```

--------------------------------

### Get Nth Element from Start in Rust

Source: https://docs.rs/ratatui-core/latest/ratatui_core/layout/struct.Columns_search=std%3A%3Avec

Implements `nth` for the Columns iterator, allowing retrieval of the nth element from the start of the iterator. This method consumes elements up to `n`.

```rust
fn nth(&mut self, n: usize) -> Option<Self::Item>
where Self: Sized
```

--------------------------------

### Ratatui Backend: Get Terminal Size Example

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/backend/trait.Backend_search=

Provides an example of how to retrieve the current dimensions (width and height) of the terminal screen using the `size` method of the `Backend` trait, returning a `Size` struct.

```rust
use ratatui::{backend::Backend, layout::Size};

assert_eq!(backend.size()?, Size::new(80, 25));
```

--------------------------------

### Text Examples: Creating Text

Source: https://docs.rs/ratatui-core/latest/ratatui_core/text/struct.Text_search=std%3A%3Avec

Demonstrates various ways to create Text objects using constructor and conversion methods.

```APIDOC
## Examples: Creating Text

A `Text`, like a `Line`, can be constructed using one of the many `From` implementations or via the `Text::raw` and `Text::styled` methods. `Text` also implements `core::iter::Extend` which enables the concatenation of several `Text` blocks.

```rust
use std::borrow::Cow;
use std::iter;

use ratatui_core::style::{Color, Modifier, Style, Stylize};
use ratatui_core::text::{Line, Span, Text};

// Using Text::raw and Text::styled with explicit style
let style = Style::new().yellow().italic();
let text_raw_styled = Text::raw("The first line\nThe second line").style(style);
let text_styled = Text::styled("The first line\nThe second line", style);
let text_styled_tuple = Text::styled(
    "The first line\nThe second line",
    (Color::Yellow, Modifier::ITALIC),
);

// Using From implementations
let text_from_str = Text::from("The first line\nThe second line");
let text_from_string = Text::from(String::from("The first line\nThe second line"));
let text_from_cow = Text::from(Cow::Borrowed("The first line\nThe second line"));
let text_from_span = Text::from(Span::styled("The first line\nSecond Span", style));
let text_from_line = Text::from(Line::from("The first line"));
let text_from_vec_lines = Text::from(vec![
    Line::from("The first line"),
    Line::from("The second line"),
]);
let text_from_iter = Text::from_iter(iter::once("The first line").chain(iter::once("The second line")));

// Using Extend
let mut text = Text::default();
text.extend(vec![
    Line::from("The first line"),
    Line::from("The second line"),
]);
text.extend(Text::from("The third line\nThe fourth line"));
```
```

--------------------------------

### Get Text Width in Ratatui

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/text/struct.Text

Example of calculating the maximum width of all lines within a Text widget.

```rust
use ratatui_core::text::Text;

let text = Text::from("The first line\nThe second line");
assert_eq!(15, text.width());
```

--------------------------------

### Get Terminal Size Example - Rust

Source: https://docs.rs/ratatui-core/latest/ratatui_core/backend/trait.Backend_search=u32+-%3E+bool

This Rust example illustrates how to retrieve the current dimensions (width and height) of the terminal screen using the `size` method of the `Backend` trait. The dimensions are returned as a `Size` struct.

```rust
use ratatui::{backend::Backend, layout::Size};

// Assuming 'backend' is a reference to a type implementing the Backend trait
let terminal_size = backend.size()?;
assert_eq!(terminal_size, Size::new(80, 25)); // Example assertion
```

--------------------------------

### TestBackend Initialization and Basic Usage

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/backend/struct.TestBackend_search=std%3A%3Avec

Demonstrates how to create a TestBackend instance, clear its buffer, and assert its content. This is useful for setting up tests and verifying initial states.

```rust
use ratatui::backend::{Backend, TestBackend};

let mut backend = TestBackend::new(10, 2);
backend.clear()?;
backend.assert_buffer_lines(["          "; 2]);
```

--------------------------------

### TestBackend Initialization (Rust)

Source: https://docs.rs/ratatui-core/latest/ratatui_core/backend/struct.TestBackend_search=std%3A%3Avec

Demonstrates creating a new TestBackend instance with specified dimensions or initial screen lines. The size is inferred from the lines if provided.

```Rust
/// Creates a new `TestBackend` with the specified width and height.
pub fn new(width: u16, height: u16) -> Self
```

```Rust
/// Creates a new `TestBackend` with the specified lines as the initial screen state.
/// The backend’s screen size is determined from the initial lines.
pub fn with_lines<'line, Lines>(lines: Lines) -> Self
where
    Lines: IntoIterator,
    Lines::Item: Into<Line<'line>>,
```

--------------------------------

### Get Text Height in Ratatui

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/text/struct.Text

Example of determining the total height of a Text widget based on the number of lines.

```rust
use ratatui_core::text::Text;

let text = Text::from("The first line\nThe second line");
assert_eq!(2, text.height());
```

--------------------------------

### Example: Getting Terminal Size (Rust)

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/backend/trait.Backend_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides an example of retrieving the current dimensions of the terminal screen, typically represented as width and height in columns and rows, using the `size` method. The result is returned as a `Size` struct.

```rust
use ratatui::{backend::Backend, layout::Size};

assert_eq!(backend.size()?, Size::new(80, 25));

```

--------------------------------

### TestBackend Initialization with Lines

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/backend/struct.TestBackend_search=std%3A%3Avec

Shows how to create a TestBackend pre-populated with specific lines of text. This allows for testing scenarios where the initial screen content is already defined.

```rust
use ratatui::backend::TestBackend;
use ratatui::text::Line;

let lines = vec![Line::from("Hello"), Line::from("World")],
let mut backend = TestBackend::with_lines(lines);
// The backend's size will be inferred from the provided lines.
```

--------------------------------

### Layout Example: Getting Only Spacers in Rust

Source: https://docs.rs/ratatui-core/latest/src/ratatui_core/layout/layout.rs_search=u32+-%3E+bool

Shows how to use the `spacers` method to retrieve only the spacer rectangles resulting from a layout calculation. This is beneficial when the primary concern is the spacing between UI elements rather than the elements themselves. The example demonstrates destructuring the result into a fixed-size array.

```rust
let area = Rect::new(0, 0, 10, 10);
let layout = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]);
let [before, inbetween, after] = layout.spacers::<3>(area);

// or explicitly specify the number of constraints:
let spacers = layout.spacers::<3>(area);
```

--------------------------------

### Ratio Constraint Layout with Flex::Start

Source: https://docs.rs/ratatui-core/latest/src/ratatui_core/layout/layout.rs_search=

Tests the `Layout` functionality with `Flex::Start` alignment using `Ratio` constraints. This example verifies how elements are distributed when ratios are applied, and the available space is divided based on the specified proportions.

```rust
fn ratio_start(
            #[case] flex: Flex,
            #[case] width: u16,
            #[case] constraints: &[Constraint],
            #[case] expected: &str,
        ) {
            letters(flex, constraints, width, expected);
        }
```

--------------------------------

### Get Terminal Size (Rust)

Source: https://docs.rs/ratatui-core/0.1.0/src/ratatui_core/backend.rs

Retrieves the dimensions of the terminal screen in columns and rows, returning a `Size` struct. The example shows how to assert the expected size.

```rust
    /// Get the size of the terminal screen in columns/rows as a [`Size`].
    ///
    /// The returned [`Size`] contains the width and height of the terminal screen.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// # use ratatui::{backend::{TestBackend}};
    /// # let backend = TestBackend::new(80, 25);
    /// use ratatui::{backend::Backend, layout::Size};
    ///
    /// assert_eq!(backend.size()?, Size::new(80, 25));
    /// # Result::Ok(())
    /// ```
    fn size(&self) -> Result<Size, Self::Error>;
```

--------------------------------

### Extend Text Widget with New Lines (Rust)

Source: https://docs.rs/ratatui-core/0.1.0/src/ratatui_core/text/text.rs

Shows how to start with an existing Text widget and append new lines to it. The example verifies that the text content is correctly updated after the extension.

```Rust
let mut text = Text::from("The first line\nThe second line");

assert_eq!(format!(lardı)), "The first line\nThe second line");

text.extend(vec![
    Line::from("The third line"),
    Line::from("The fourth line"),
]);

assert_eq!(
    format!(lardı),
    "The first line\nThe second line\nThe third line\nThe fourth line"
);
```

--------------------------------

### Initialize Terminal with Crossterm Backend

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/backend/index

Demonstrates how to initialize a `Terminal` instance using the `CrosstermBackend`. This involves creating a backend instance with a standard output stream and then constructing the `Terminal` with this backend. The example also shows clearing the terminal screen and initiating a drawing operation.

```Rust
use std::io::stdout;

use ratatui::{backend::CrosstermBackend, Terminal};

let backend = CrosstermBackend::new(stdout());
let mut terminal = Terminal::new(backend)?;
terminal.clear()?;
terminal.draw(|frame| {
    // -- snip --
})?;
```

--------------------------------

### Creating Lines Example

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/text/struct.Line

Demonstrates various ways to create Line objects using different constructors and data types.

```APIDOC
### Creating Lines

`Line`s can be created from `Span`s, `String`s, and `&str`s. They can be styled with a `Style`.

```rust
use ratatui_core::style::{Color, Modifier, Style, Stylize};
use ratatui_core::text::{Line, Span};

let style = Style::new().yellow();
let line = Line::raw("Hello, world!").style(style);
let line = Line::styled("Hello, world!", style);
let line = Line::styled("Hello, world!", (Color::Yellow, Modifier::BOLD));

let line = Line::from("Hello, world!");
let line = Line::from(String::from("Hello, world!"));
let line = Line::from(vec![
    Span::styled("Hello", Style::new().blue()),
    Span::raw(" world!"),
]);
```
```

--------------------------------

### Rust: Example of Getting Spacers Explicitly

Source: https://docs.rs/ratatui-core/0.1.0/src/ratatui_core/layout/layout.rs_search=u32+-%3E+bool

Demonstrates how to obtain spacer rectangles from a layout using the `spacers` method, explicitly specifying the number of spacers expected. This is useful when the exact number of areas is known at compile time.

```Rust
use ratatui_core::layout::{Constraint, Layout, Rect};

let area = Rect::new(0, 0, 10, 10);
let layout = Layout::vertical([Constraint::Length(1), Constraint::Fill(1)]);
let [before, inbetween, after] = layout.spacers::<3>(area);
```

--------------------------------

### Get Style of Ratatui Cell (Rust)

Source: https://docs.rs/ratatui-core/0.1.0/src/ratatui_core/buffer/cell.rs_search=

Demonstrates retrieving the current style of a Ratatui Cell. The `style` method returns a `Style` object representing the cell's foreground, background, and modifiers. The example shows the default style of an empty cell.

```Rust
let cell = Cell::EMPTY;
assert_eq(
    cell.style(),
    Style {
        fg: Some(Color::Reset),
        bg: Some(Color::Reset),
        #[cfg(feature = "underline-color")]
        underline_color: Some(Color::Reset),
        add_modifier: Modifier::empty(),
        sub_modifier: Modifier::empty(),
    }
);
```

--------------------------------

### Set and Get Cursor Position Example - Rust

Source: https://docs.rs/ratatui-core/latest/ratatui_core/backend/trait.Backend_search=u32+-%3E+bool

This Rust code snippet shows how to set the cursor's position on the terminal screen using `set_cursor_position` and then verify it using `get_cursor_position`. It utilizes the `Position` struct for coordinate representation.

```rust
use ratatui::{backend::Backend, layout::Position};

// Assuming 'backend' is a mutable reference to a type implementing the Backend trait
backend.set_cursor_position(Position { x: 10, y: 20 })?;
assert_eq!(backend.get_cursor_position()?, Position { x: 10, y: 20 });
```

--------------------------------

### Test Backend and Terminal Initialization in Rust

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/terminal/struct.Terminal

Demonstrates how to initialize a TestBackend and a Terminal in Rust for testing purposes. It shows how to get a frame, render a widget, and manually flush and swap buffers to inspect the output.

```rust
use ratatui::{backend::TestBackend, Terminal};
use ratatui::widgets::Paragraph;
let backend = TestBackend::new(30, 5);
let mut terminal = Terminal::new(backend).unwrap();
{
    let mut frame = terminal.get_frame();
    frame.render_widget(Paragraph::new("Hello"), frame.area());
}
// When not using `draw`, present the buffer manually:
terminal.flush().unwrap();
terminal.swap_buffers();
terminal.backend_mut().flush().unwrap();
```

--------------------------------

### Initialize and Draw with Ratatui Terminal

Source: https://docs.rs/ratatui-core/0.1.0/ratatui_core/terminal/index

This example demonstrates how to initialize a Crossterm backend and a Ratatui Terminal. It then uses the `draw` method to render a Paragraph widget displaying 'Hello world!' within the terminal's area. This is the fundamental pattern for rendering content in Ratatui applications.

```rust
use std::io::stdout;

use ratatui::{backend::CrosstermBackend, widgets::Paragraph, Terminal};

let backend = CrosstermBackend::new(stdout());
let mut terminal = Terminal::new(backend)?;
terminal.draw(|frame| {
    let area = frame.area();
    frame.render_widget(Paragraph::new("Hello world!"), area);
})?;
```

--------------------------------

### Get Rect Coordinates

Source: https://docs.rs/ratatui-core/latest/ratatui_core/layout/struct.Rect_search=std%3A%3Avec

These methods retrieve the coordinates of the Rect's boundaries. `left` and `top` give the starting coordinates, while `right` and `bottom` give the coordinate immediately outside the Rect. Note that `right` and `bottom` can be clamped to `u16::MAX`.

```rust
use ratatui_core::layout::Rect;

let rect = Rect::new(1, 2, 3, 4);

assert_eq!(rect.left(), 1);
assert_eq!(rect.top(), 2);
assert_eq!(rect.right(), 1 + 3); // right is exclusive
assert_eq!(rect.bottom(), 2 + 4); // bottom is exclusive
```

--------------------------------

### Layout Construction and Initialization Example (Rust)

Source: https://docs.rs/ratatui-core/latest/ratatui_core/layout/struct.Layout_search=std%3A%3Avec

Demonstrates how to create a new Layout instance with specified direction and constraints. It shows flexibility in accepting different iterable types for constraints, including integers, iterators, and vectors.

```rust
use ratatui_core::layout::{Constraint, Direction, Layout};

// Using an array of constraints
Layout::new(
    Direction::Horizontal,
    [Constraint::Length(5), Constraint::Fill(1)],
);

// Using an iterator of constraints
Layout::new(
    Direction::Vertical,
    [1, 2, 3].iter().map(|&c| Constraint::Length(c)),
);

// Using a Vec of constraints
Layout::new(Direction::Horizontal, vec![1, 2]);
```

--------------------------------

### Render Text Widget using Frame in Rust (Ignored)

Source: https://docs.rs/ratatui-core/latest/src/ratatui_core/text/text.rs_search=u32+-%3E+bool

Demonstrates rendering a `Text` widget using the `render_widget` method on a `Frame` in Rust. This is a common pattern within a `Terminal::draw` closure. This example is marked with `ignore` as it requires a full `Frame` setup.

```rust
# use ratatui::{Frame, layout::Rect, text::Text};
fn draw(frame: &mut Frame, area: Rect) {
    let text = Text::from("The first line\nThe second line");
    frame.render_widget(text, area);
}
```

--------------------------------

### Render Full Control Sequence in Rust

Source: https://docs.rs/ratatui-core/0.1.0/src/ratatui_core/buffer/buffer.rs

Tests the rendering of ANSI escape codes within a string in Rust. This example shows how a full control sequence, including start and end codes, is correctly interpreted and rendered within the buffer, affecting text styling.

```rust
    #[test]
    fn control_sequence_rendered_full() {
        let text = "I \x1b[0;36mwas\x1b[0m here!";

        let mut buffer = Buffer::filled(Rect::new(0, 0, 25, 3), Cell::new("x"));
        buffer.set_string(1, 1, text, Style::new());

        let expected = Buffer::with_lines([
            "xxxxxxxxxxxxxxxxxxxxxxxxx",
            "xI [0;36mwas[0m here!xxxx",
            "xxxxxxxxxxxxxxxxxxxxxxxxx",
        ]);
        assert_eq!(buffer, expected);
    }

```

--------------------------------

### Widget Examples

Source: https://docs.rs/ratatui-core/latest/ratatui_core/widgets/trait.Widget_search=std%3A%3Avec

Illustrates common patterns for using the Widget trait, including rendering basic widgets and implementing custom widgets.

```APIDOC
## Examples

### Basic Widget Rendering

```rust
use ratatui::{
    backend::TestBackend,
    widgets::{Clear, Widget},
    Terminal,
};

// Assuming 'terminal' is an initialized Terminal instance
// terminal.draw(|frame| {
//     frame.render_widget(Clear, frame.area());
// });
```

### Implementing a Custom Widget

It’s common to render widgets inside other widgets:

```rust
use ratatui_core::buffer::Buffer;
use ratatui_core::layout::Rect;
use ratatui_core::text::Line;
use ratatui_core::widgets::Widget;

struct MyWidget;

impl Widget for MyWidget {
    fn render(self, area: Rect, buf: &mut Buffer) {
        Line::raw("Hello").render(area, buf);
    }
}
```
```
Tokens:
Raw