Tui Realm

https://docs.rs/tuirealm
Admin
Tui Realm is a framework for Ratatui that simplifies terminal user interface development with...
Tokens:781,186
Snippets:5,547
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Flex Start Example: Mixed Constraints

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/layout/enum.Flex.html

Illustrates the 'Start' alignment for items within a container, showing how Percentage, Length, and Fixed constraints are positioned at the beginning.

```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)     │ 
└──────────────────┘
```

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

### Initialize TermionBackend with Terminal

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/backend/struct.TermionBackend.html

Example of setting up TermionBackend with stdout or stderr, enabling raw mode and alternate screen, and creating a Terminal instance. This is the typical setup for most applications.

```rust
use std::io::{stderr, stdout};

use ratatui::*
use ratatui::backend::TermionBackend;
use ratatui::termion::{raw::IntoRawMode, screen::IntoAlternateScreen};
use ratatui::Terminal;

let writer = stdout().into_raw_mode()?.into_alternate_screen()?;
let mut backend = TermionBackend::new(writer);
// or
let writer = stderr().into_raw_mode()?.into_alternate_screen()?;
let backend = TermionBackend::new(stderr());
let mut terminal = Terminal::new(backend)?;

terminal.clear()?;
terminal.draw(|frame| {
    // -- snip --
})?;
```

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

### Run tui-realm Demo Example

Source: https://docs.rs/tuirealm/latest/index.html

Execute the demo example to see tui-realm in action. This helps in understanding its workflow.

```bash
cargo run --example demo
```

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

### Create a Simple Chart with One Dataset

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/struct.Chart.html

This example shows the minimal setup for creating a Chart with a single Dataset. It uses default configurations for the Dataset and Chart.

```rust
use ratatui::widgets::{Chart, Dataset};

let data_points = vec![];
let chart = Chart::new(vec![Dataset::default().data(&data_points)]);
```

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

### Terminal Example: Resize and Scroll

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/crossterm/terminal/index.html

An example demonstrating how to resize the terminal and scroll its content using `execute`.

```APIDOC
### Examples
```rust
use std::io::{self, Write};
use crossterm::{execute, terminal::{ScrollUp, SetSize, size}};

fn main() -> io::Result<()> {
    let (cols, rows) = size()?;
    // Resize terminal and scroll up.
    execute!(
        io::stdout(),
        SetSize(10, 10),
        ScrollUp(5)
    )?;

    // Be a good citizen, cleanup
    execute!(io::stdout(), SetSize(cols, rows))?;
    Ok(())
}
```
For manual execution control check out `crossterm::queue`.
```

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

### StatefulWidget Example Usage

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/trait.StatefulWidget.html

An example demonstrating how to use `StatefulWidget` with a `List` widget to manage selected items and scrolling.

```APIDOC
### Examples
```rust
use std::io;

use ratatui::{
    backend::TestBackend,
    widgets::{List, ListItem, ListState, StatefulWidget, Widget},
    Terminal,
};

// Let's say we have some events to display.
struct Events {
    // `items` is the state managed by your application.
    items: Vec<String>,
    // `state` is the state that can be modified by the UI. It stores the index of the selected
    // item as well as the offset computed during the previous draw call (used to implement
    // natural scrolling).
    state: ListState,
}

impl Events {
    fn new(items: Vec<String>) -> Events {
        Events {
            items,
            state: ListState::default(),
        }
    }

    pub fn set_items(&mut self, items: Vec<String>) {
        self.items = items;
        // We reset the state as the associated items have changed. This effectively reset
        // the selection as well as the stored offset.
        self.state = ListState::default();
    }

    // Select the next item. This will not be reflected until the widget is drawn in the
    // `Terminal::draw` callback using `Frame::render_stateful_widget`.
    pub fn next(&mut self) {
        let i = match self.state.selected() {
            Some(i) => {
                if i >= self.items.len() - 1 {
                    0
                } else {
                    i + 1
                }
            }
            None => 0,
        };
        self.state.select(Some(i));
    }

    // Select the previous item. This will not be reflected until the widget is drawn in the
    // `Terminal::draw` callback using `Frame::render_stateful_widget`.
    pub fn previous(&mut self) {
        let i = match self.state.selected() {
            Some(i) => {
                if i == 0 {
                    self.items.len() - 1
                } else {
                    i - 1
                }
            }
            None => 0,
        };
        self.state.select(Some(i));
    }

    // Unselect the currently selected item if any. The implementation of `ListState` makes
    // sure that the stored offset is also reset.
    pub fn unselect(&mut self) {
        self.state.select(None);
    }
}


let mut events = Events::new(vec![String::from("Item 1"), String::from("Item 2")]);

loop {
    terminal.draw(|f| {
        // The items managed by the application are transformed to something
        // that is understood by ratatui.
        let items: Vec<ListItem> = events
            .items
            .iter()
            .map(|i| ListItem::new(i.as_str()))
            .collect();
        // The `List` widget is then built with those items.
        let list = List::new(items);
        // Finally the widget is rendered using the associated state. `events.state` is
        // effectively the only thing that we will "remember" from this draw call.
        f.render_stateful_widget(list, f.size(), &mut events.state);
    });

    // In response to some input events or an external http request or whatever:
    events.next();
}
```
```

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

### Stylize Examples

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/crossterm/style/trait.Stylize.html

Illustrative examples demonstrating the usage of the Stylize trait methods for applying various text styles and colors.

```APIDOC
## Examples

```rust
use crossterm::style::Stylize;

println!("{}", "Bold text".bold());
println!("{}", "Underlined text".underlined());
println!("{}", "Negative text".negative());
println!("{}", "Red on blue".red().on_blue());
```
```

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

### Set Layout Flex Behavior to Start

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/struct.Layout.html

Use this to align items to the start of the layout. Requires importing `Flex` and `Layout` from `ratatui::layout`.

```rust
use ratatui::layout::{Constraint::*, Flex, Layout};

let layout = Layout::horizontal([Length(20), Length(20), Length(20)]).flex(Flex::Start);
```

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

### Initializing a Terminal Backend

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/backend/index.html

Example of how to initialize a CrosstermBackend and create a Terminal instance.

```APIDOC
## Initialization

### Description
Initializes a new terminal backend using the Crossterm library.

### Request Example
```rust
use std::io::stdout;
use ratatui::{backend::CrosstermBackend, Terminal};

let backend = CrosstermBackend::new(stdout());
let mut terminal = Terminal::new(backend)?;
terminal.clear()?;
```
```

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

### Execute Commands Example

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/crossterm/macro.execute.html

Demonstrates executing print commands directly to stdout.

```rust
use std::io::{Write, stdout};
use crossterm::{execute, style::Print};

// will be executed directly
execute!(stdout(), Print("sum:\n".to_string()));

// will be executed directly
execute!(stdout(), Print("1 + 1 = ".to_string()), Print((1+1).to_string()));

// ==== Output ====
// sum:
// 1 + 1 = 2
```

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

### Creating Titles

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/block/struct.Title.html

Examples of creating titles with different styles and configurations.

```rust
use ratatui::widgets::block::Title;

Title::from("Title");
```

```rust
use ratatui::{style::Stylize, widgets::block::Title};

Title::from("Title".blue().on_white());
```

```rust
use ratatui::{style::Stylize, text::Line, widgets::block::Title};

Title::from(Line::from(vec!["Q".white().underlined(), "uit".gray()]));
```

```rust
use ratatui::{
    layout::Alignment,
    widgets::{
        block::{Position, Title},
        Block,
    },
};

Title::from("Title")
    .position(Position::Top)
    .alignment(Alignment::Right);
```

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

### Start EventListener Configuration

Source: https://docs.rs/tuirealm/latest/src/tuirealm/listener/builder.rs.html

Starts the event listener with the configured parameters. Returns an error if async ports are defined without a handle. This method is crucial for initializing the listener after configuration.

```rust
pub(crate) fn start(mut self) -> Result<EventListener<UserEvent>, ListenerError> {
        #[cfg(feature = "async-ports")]
        let start_async =
            !self.async_ports.is_empty() || (self.async_tick && self.tick_interval.is_some());
        #[cfg(not(feature = "async-ports"))]
        let store_tx = false;
        #[cfg(feature = "async-ports")]
        let store_tx = start_async;
        #[cfg(not(feature = "async-ports"))]
        let sync_tick_interval = self.tick_interval;
        #[cfg(feature = "async-ports")]
        let sync_tick_interval = self.tick_interval.take_if(|_| !self.async_tick);
        let mut res = EventListener::new(self.poll_timeout);

        // dont start a sync worker if there are no sync tasks
        if !self.sync_ports.is_empty() || sync_tick_interval.is_some() {
            res = res.start(self.sync_ports, sync_tick_interval, store_tx);
        }

        // dont start a taskpool without any actual tasks
        #[cfg(feature = "async-ports")]
        if start_async {
            let Some(handle) = self.handle else {
                return Err(ListenerError::NoHandle);
            };
            res = res.start_async(
                self.async_ports,
                handle,
                self.tick_interval.take_if(|_| self.async_tick),
            );
        }

        Ok(res)
    }
```

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

### Initialize Tabs with Titles

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/struct.Tabs.html

Examples for creating Tabs with basic or styled titles.

```rust
use ratatui::widgets::Tabs;

let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]);
```

```rust
use ratatui::{style::Stylize, widgets::Tabs};

let tabs = Tabs::new(vec!["Tab 1".red(), "Tab 2".blue()]);
```

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

### Create New Rect

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/layout/struct.Rect.html

Example of initializing a new Rect instance.

```rust
use ratatui::layout::Rect;

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

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

### Running Examples

Source: https://docs.rs/tuirealm/latest/tuirealm/index.html

How to execute the provided demo application to understand the tui-realm architecture.

```APIDOC
## Running Demo

### Description
Execute the built-in demo application to observe component lifecycle and event handling.

### Command
`cargo run --example demo`
```

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

### Get Terminal Size

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/trait.Backend.html

Example of retrieving the terminal dimensions.

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

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

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

### Create and Configure a Dataset

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/struct.Dataset.html

This example demonstrates how to create a Dataset, set its name, data points, marker, graph type, and apply a red style. It requires importing necessary components from ratatui.

```rust
use ratatui::{
    style::Stylize,
    symbols::Marker,
    widgets::{Dataset, GraphType},
};

let dataset = Dataset::default()
    .name("dataset 1")
    .data(&[(1., 1.), (5., 5.)])
    .marker(Marker::Braille)
    .graph_type(GraphType::Line)
    .red();
```

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

### Buffer::cell Example

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/buffer/struct.Buffer.html

Shows how to safely get a reference to a Cell within the buffer using the cell method, which returns None for out-of-bounds positions.

```rust
use ratatui::{
    buffer::{Buffer, Cell},
    layout::{Position, Rect},
};

let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));

assert_eq!(buffer.cell(Position::new(0, 0)), Some(&Cell::default()));
assert_eq!(buffer.cell(Position::new(10, 10)), None);
assert_eq!(buffer.cell((0, 0)), Some(&Cell::default()));
assert_eq!(buffer.cell((10, 10)), None);

```

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

### Set and Get Cursor Position Example

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/backend/trait.Backend.html

Shows how to set the cursor to a specific position and then verify its position using `get_cursor_position`. The origin (0,0) is at the top-left corner.

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

backend.set_cursor_position(Position { x: 10, y: 20 })?;
assert_eq!(backend.get_cursor_position()?, Position { x: 10, y: 20 });

```

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

### Get Terminal Size Example

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/backend/trait.Backend.html

Retrieves the terminal's dimensions in columns and rows using the `size` method. The result is a `Size` struct containing width and height.

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

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

```

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

### Example: Creating Text

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/struct.Text.html

Demonstrates various ways to create Text instances using different `From` implementations and constructor 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. Helpfully, `Text` also implements `core::iter::Extend` which enables the concatenation of several `Text` blocks.

```rust
use std::{borrow::Cow, iter};

use ratatui::{
    style::{Color, Modifier, Style, Stylize},
    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"));
```
```

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

### Terminal Initialization

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/struct.Terminal.html

Demonstrates how to create a new Terminal instance with a specified backend.

```APIDOC
## Terminal Initialization

### Description
Initializes a new `Terminal` instance with a given backend and a full screen viewport.

### Method
`Terminal::new()`

### Parameters
- **backend** (B) - Required - The backend implementation to use for terminal interaction.

### Request Example
```rust
use std::io::stdout;

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

let backend = CrosstermBackend::new(stdout());
let terminal = Terminal::new(backend)?;
```

### Response
- **Terminal<B>** - A new `Terminal` instance.
- **Error** - If initialization fails.
```

```APIDOC
## Terminal with Options Initialization

### Description
Initializes a new `Terminal` instance with a given backend and custom terminal options, including viewport configuration.

### Method
`Terminal::with_options()`

### Parameters
- **backend** (B) - Required - The backend implementation to use for terminal interaction.
- **options** (Options) - Required - Terminal options, such as viewport settings.

### Request Example
```rust
use std::io::stdout;

use ratatui::{backend::CrosstermBackend, layout::Rect, Terminal, TerminalOptions, Viewport};

let backend = CrosstermBackend::new(stdout());
let viewport = Viewport::Fixed(Rect::new(0, 0, 10, 10));
let terminal = Terminal::with_options(backend, TerminalOptions { viewport })?;
```

### Response
- **Terminal<B>** - A new `Terminal` instance with specified options.
- **Error** - If initialization fails.
```

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

### EventListenerCfg Struct

Source: https://docs.rs/tuirealm/latest/tuirealm/listener/struct.EventListenerCfg.html

The event listener configurator is used to setup an event listener. Once you’re done with configuration just call `EventListenerCfg::start` and the event listener will start and the listener will be returned.

```rust
pub struct EventListenerCfg<UserEvent>
where
    UserEvent: Eq + PartialEq + Clone + Send,
{
    /* private fields */
}
```

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

### Flex Layout Example

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/layout/enum.Flex.html

Demonstrates the visual representation of Flex layout with percentage and length-based sizing.

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

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

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

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

### Create Layout Instances

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/struct.Layout.html

Shows various ways to initialize a new Layout using different constraint inputs.

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

Layout::new(
    Direction::Horizontal,
    [Constraint::Length(5), Constraint::Min(0)],
);

Layout::new(
    Direction::Vertical,
    [1, 2, 3].iter().map(|&c| Constraint::Length(c)),
);

Layout::new(Direction::Horizontal, vec![1, 2]);
```

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

### Get TTY Device

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/termion/fn.get_tty.html

Use this function to obtain the TTY device. It ensures that stdio represents only the TTY, excluding other streams. No specific setup or imports are required beyond the function's availability.

```rust
pub fn get_tty() -> Result<File, Error>
```

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

### Conditional Subscription with Attribute Check

Source: https://docs.rs/tuirealm/latest/src/tuirealm/core/application.rs.html

Illustrates mounting a component with a subscription that requires a specific attribute condition (e.g., Focus) to be met. This example shows the setup for such a subscription, implying that events will only be processed if the condition is satisfied.

```rust
assert!(
            application
                .mount(
                    MockComponentId::InputFoo,
                    Box::new(MockFooInput::default()),
                    vec![]
                )
                .is_ok()
        );
        assert!(
            application
                .mount(
                    MockComponentId::InputBar,
                    Box::new(MockBarInput::default()),
                    vec![Sub::new(
                        // NOTE: won't be thrown, since requires focus
                        SubEventClause::Tick,
                        SubClause::HasAttrValue(
                            MockComponentId::InputBar,
                            Attribute::Focus,
                            AttrValue::Flag(true)
                        )
                    )]
                )
                .is_ok()
        );
```

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

### Initialize and Draw with Terminal

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/struct.Terminal.html

This example demonstrates how to initialize a Terminal with a Crossterm backend and draw a simple Paragraph widget. Ensure you have the necessary backend and widget imports.

```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);
})?;
```

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

### Create a Basic Table with Header, Footer, and Styling

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/struct.Table.html

Demonstrates creating a table with custom row data, column widths, spacing, header, footer, and various styling options. Use this for displaying structured data with clear visual separation.

```rust
use ratatui::{
    layout::Constraint,
    style::{Style, Stylize},
    widgets::{Block, Row, Table},
};

let rows = [Row::new(vec!["Cell1", "Cell2", "Cell3"])];
// Columns widths are constrained in the same way as Layout...
let widths = [
    Constraint::Length(5),
    Constraint::Length(5),
    Constraint::Length(10),
];
let table = Table::new(rows, widths)
    // ...and they can be separated by a fixed spacing.
    .column_spacing(1)
    // You can set the style of the entire Table.
    .style(Style::new().blue())
    // It has an optional header, which is simply a Row always visible at the top.
    .header(
        Row::new(vec!["Col1", "Col2", "Col3"])
            .style(Style::new().bold())
            // To add space between the header and the rest of the rows, specify the margin
            .bottom_margin(1),
    )
    // It has an optional footer, which is simply a Row always visible at the bottom.
    .footer(Row::new(vec!["Updated on Dec 28"]))
    // As any other widget, a Table can be wrapped in a Block.
    .block(Block::new().title("Table"))
    // The selected row, column, cell and its content can also be styled.
    .row_highlight_style(Style::new().reversed())
    .column_highlight_style(Style::new().red())
    .cell_highlight_style(Style::new().blue())
    // ...and potentially show a symbol in front of the selection.
    .highlight_symbol(">>");
```

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

### GET /get_cursor_position

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/type.DefaultTerminal.html

Gets the current cursor position after the last draw call.

```APIDOC
## GET /get_cursor_position

### Description
Gets the current cursor position after the last draw call.

### Method
GET

### Endpoint
/get_cursor_position

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let position = terminal.get_cursor_position()?;
```

### Response
#### Success Response (200)
- **Position** (Position) - The current cursor position as a `Position` struct.

#### Response Example
```json
{
  "x": 10,
  "y": 5
}
```
```

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

### Initialize terminal with options

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/fn.init_with_options.html

Demonstrates how to configure a terminal with a custom viewport using TerminalOptions.

```rust
use ratatui::{TerminalOptions, Viewport};

let options = TerminalOptions {
    viewport: Viewport::Inline(5),
};
let terminal = ratatui::init_with_options(options);
```

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

### GET /get_cursor

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/type.DefaultTerminal.html

Gets the current cursor position. Deprecated: use `get_cursor_position` instead.

```APIDOC
## GET /get_cursor

### Description
Gets the current cursor position. Deprecated: use `get_cursor_position` instead.

### Method
GET

### Endpoint
/get_cursor

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let (x, y) = terminal.get_cursor()?;
```

### Response
#### Success Response (200)
- **(u16, u16)** - A tuple representing the (x, y) coordinates of the cursor.

#### Response Example
```json
{
  "x": 10,
  "y": 5
}
```
```

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

### Start Async Worker

Source: https://docs.rs/tuirealm/latest/src/tuirealm/listener/mod.rs.html

Starts async ports on a taskpool. Panics if called more than once per EventListener.

```rust
#[cfg(feature = "async-ports")]
    pub(self) fn start_async(
        mut self,
        mut ports: Vec<AsyncPort<UserEvent>>,
        handle: tokio::runtime::Handle,
        tick_interval: Option<Duration>,
    ) -> Self {
        use async_ticker::AsyncTicker;

        let taskpool = TaskPool::new(handle);
        // unwrap is safe the first time as it is always assigned in "start"
        let tx = self.tx.take().unwrap();

        if let Some(tick_interval) = tick_interval {
            ports.push(AsyncPort::new(
                Box::new(AsyncTicker::new()),
                tick_interval,
                1,
            ));
        }

        for port in ports {
            let tx = tx.clone();
            let paused = self.paused.clone();
            taskpool.spawn(async move {
                let _ = poll_task(port, tx, paused).await;
            });
        }

        self.taskpool = Some(taskpool);

        self
    }
```

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

### Canvas Widget Example

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/canvas/struct.Canvas.html

An example demonstrating how to use the Canvas widget to draw a map, a line, and a rectangle.

```APIDOC
## Canvas Widget Example

### Description
This example shows how to initialize and use the `Canvas` widget to draw various elements like a map, a line, and a rectangle. It also demonstrates setting the canvas bounds and applying a block border.

### Code Example
```rust
use ratatui::{
    style::Color,
    widgets::{
        canvas::{Canvas, Line, Map, MapResolution, Rectangle},
        Block,
    },
};

Canvas::default()
    .block(Block::bordered().title("Canvas"))
    .x_bounds([-180.0, 180.0])
    .y_bounds([-90.0, 90.0])
    .paint(|ctx| {
        ctx.draw(&Map {
            resolution: MapResolution::High,
            color: Color::White,
        });
        ctx.layer();
        ctx.draw(&Line {
            x1: 0.0, y1: 10.0, x2: 10.0, y2: 10.0,
            color: Color::White,
        });
        ctx.draw(&Rectangle {
            x: 10.0, y: 20.0, width: 10.0, height: 10.0,
            color: Color::Red,
        });
    });
```
```

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

### Creating Lines Example

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/text/struct.Line.html

Demonstrates various ways to create Line instances from Spans, Strings, and &str, with styling.

```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::{
    style::{Color, Modifier, Style, Stylize},
    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!"),
]);
```
```

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

### Stylize Trait Examples

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/style/trait.Stylize.html

Illustrative examples demonstrating the usage of the Stylize trait for styling text and widgets.

```APIDOC
## Examples

```rust
use ratatui::{
    style::{Color, Modifier, Style, Stylize},
    text::Line,
    widgets::{Block, Paragraph},
};

let span = "hello".red().on_blue().bold();
let line = Line::from(vec![
    "hello".red().on_blue().bold(),
    "world".green().on_yellow().not_bold(),
]);
let paragraph = Paragraph::new(line).italic().underlined();
let block = Block::bordered().title("Title").on_white().bold();
```
```

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

### Implement StatefulWidget with List

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/trait.StatefulWidget.html

Example demonstrating how to manage application state and render a stateful List widget.

```rust
use std::io;

use ratatui::{
    backend::TestBackend,
    widgets::{List, ListItem, ListState, StatefulWidget, Widget},
    Terminal,
};

// Let's say we have some events to display.
struct Events {
    // `items` is the state managed by your application.
    items: Vec<String>,
    // `state` is the state that can be modified by the UI. It stores the index of the selected
    // item as well as the offset computed during the previous draw call (used to implement
    // natural scrolling).
    state: ListState,
}

impl Events {
    fn new(items: Vec<String>) -> Events {
        Events {
            items,
            state: ListState::default(),
        }
    }

    pub fn set_items(&mut self, items: Vec<String>) {
        self.items = items;
        // We reset the state as the associated items have changed. This effectively reset
        // the selection as well as the stored offset.
        self.state = ListState::default();
    }

    // Select the next item. This will not be reflected until the widget is drawn in the
    // `Terminal::draw` callback using `Frame::render_stateful_widget`.
    pub fn next(&mut self) {
        let i = match self.state.selected() {
            Some(i) => {
                if i >= self.items.len() - 1 {
                    0
                } else {
                    i + 1
                }
            }
            None => 0,
        };
        self.state.select(Some(i));
    }

    // Select the previous item. This will not be reflected until the widget is drawn in the
    // `Terminal::draw` callback using `Frame::render_stateful_widget`.
    pub fn previous(&mut self) {
        let i = match self.state.selected() {
            Some(i) => {
                if i == 0 {
                    self.items.len() - 1
                } else {
                    i - 1
                }
            }
            None => 0,
        };
        self.state.select(Some(i));
    }

    // Unselect the currently selected item if any. The implementation of `ListState` makes
    // sure that the stored offset is also reset.
    pub fn unselect(&mut self) {
        self.state.select(None);
    }
}


let mut events = Events::new(vec![String::from("Item 1"), String::from("Item 2")]);

loop {
    terminal.draw(|f| {
        // The items managed by the application are transformed to something
        // that is understood by ratatui.
        let items: Vec<ListItem> = events
            .items
            .iter()
            .map(|i| ListItem::new(i.as_str()))
            .collect();
        // The `List` widget is then built with those items.
        let list = List::new(items);
        // Finally the widget is rendered using the associated state. `events.state` is
        // effectively the only thing that we will "remember" from this draw call.
        f.render_stateful_widget(list, f.size(), &mut events.state);
    });

    // In response to some input events or an external http request or whatever:
    events.next();
}
```

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

### Initialize and Configure a Gauge

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/struct.Gauge.html

Example showing how to create a default Gauge with a bordered block and custom styling.

```rust
use ratatui::{
    style::{Style, Stylize},
    widgets::{Block, Gauge},
};

Gauge::default()
    .block(Block::bordered().title("Progress"))
    .gauge_style(Style::new().white().on_black().italic())
    .percent(20);
```

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

### Start Sync Worker

Source: https://docs.rs/tuirealm/latest/src/tuirealm/listener/mod.rs.html

Starts a worker for Sync-Ports. If store_tx is true, the transmitter is stored for potential async usage.

```rust
pub(self) fn start(
        self,
        ports: Vec<SyncPort<UserEvent>>,
        tick_interval: Option<Duration>,
        store_tx: bool,
    ) -> Self {
        #[cfg(feature = "async-ports")]
        let tx = if store_tx { self.tx.clone() } else { None };

        // Prepare channel and running state
        #[allow(unused_mut)] // mutability is necessary when "async-ports" is active
        let mut res = self.setup_sync_worker(ports, tick_interval);

        #[cfg(feature = "async-ports")]
        {
            res.tx = tx;
        }

        res
    }
```

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

### Title Creation Examples

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/block/struct.Title.html

Demonstrates various ways to create and configure a Title instance.

```APIDOC
### Example

Title with no style.
```rust
use ratatui::widgets::block::Title;

Title::from("Title");
```

Blue title on a white background (via `Stylize` trait).
```rust
use ratatui::{style::Stylize, widgets::block::Title};

Title::from("Title".blue().on_white());
```

Title with multiple styles (see `Line` and `Stylize`).
```rust
use ratatui::{style::Stylize, text::Line, widgets::block::Title};

Title::from(Line::from(vec![ "Q".white().underlined(), "uit".gray() ]));
```

Complete example
```rust
use ratatui::{
    layout::Alignment,
    widgets::{
        block::{Position, Title},
        Block,
    },
};

Title::from("Title")
    .position(Position::Top)
    .alignment(Alignment::Right);
```
```

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

### Create a Chart Widget with Datasets and Axes

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/struct.Chart.html

This example demonstrates how to create a Chart widget by defining datasets, configuring X and Y axes, and then assembling them into a Chart. It includes styling and bounds for the axes.

```rust
use ratatui::{
    style::{Style, Stylize},
    symbols,
    widgets::{Axis, Block, Chart, Dataset, GraphType},
};

// Create the datasets to fill the chart with
let datasets = vec![
    // Scatter chart
    Dataset::default()
        .name("data1")
        .marker(symbols::Marker::Dot)
        .graph_type(GraphType::Scatter)
        .style(Style::default().cyan())
        .data(&[(0.0, 5.0), (1.0, 6.0), (1.5, 6.434)]),
    // Line chart
    Dataset::default()
        .name("data2")
        .marker(symbols::Marker::Braille)
        .graph_type(GraphType::Line)
        .style(Style::default().magenta())
        .data(&[(4.0, 5.0), (5.0, 8.0), (7.66, 13.5)]),
];

// Create the X axis and define its properties
let x_axis = Axis::default()
    .title("X Axis".red())
    .style(Style::default().white())
    .bounds([0.0, 10.0])
    .labels(["0.0", "5.0", "10.0"]);

// Create the Y axis and define its properties
let y_axis = Axis::default()
    .title("Y Axis".red())
    .style(Style::default().white())
    .bounds([0.0, 10.0])
    .labels(["0.0", "5.0", "10.0"]);

// Create the chart and link all the parts together
let chart = Chart::new(datasets)
    .block(Block::new().title("Chart"))
    .x_axis(x_axis)
    .y_axis(y_axis);
```

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

### Get TextModifiers Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner TextModifiers value from an AttrValue. Returns None if the AttrValue is not of the TextModifiers variant.

```rust
pub fn as_text_modifiers(&self) -> Option<TextModifiers>
```

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

### Initialize CrosstermBackend and Terminal

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/backend/struct.CrosstermBackend.html

Demonstrates setting up the backend with stdout or stderr, enabling raw mode, and entering the alternate screen before drawing.

```rust
use std::io::{stderr, stdout};

use crossterm::{
    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
    ExecutableCommand,
};
use ratatui::{backend::CrosstermBackend, Terminal};

let mut backend = CrosstermBackend::new(stdout());
// or
let backend = CrosstermBackend::new(stderr());
let mut terminal = Terminal::new(backend)?;

enable_raw_mode()?;
stdout().execute(EnterAlternateScreen)?;

terminal.clear()?;
terminal.draw(|frame| {
    // -- snip --
})?;

stdout().execute(LeaveAlternateScreen)?;
disable_raw_mode()?;
```

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

### Get Text Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner TextSpan value from an AttrValue. Returns None if the AttrValue is not of the Text variant.

```rust
pub fn as_text(&self) -> Option<&TextSpan>
```

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

### Create List from various sources

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/struct.List.html

Examples of initializing a List from different data types.

```rust
use ratatui::widgets::List;

let list = List::new(["Item 1", "Item 2"]);
```

```rust
use ratatui::{
    style::{Style, Stylize},
    text::Text,
    widgets::List,
};

let list = List::new([
    Text::styled("Item 1", Style::new().red()),
    Text::styled("Item 2", Style::new().red()),
]);
```

```rust
use ratatui::widgets::List;

let empty_list = List::default();
let filled_list = empty_list.items(["Item 1"]);
```

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

### Get Table Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner Table value from an AttrValue. Returns None if the AttrValue is not of the Table variant.

```rust
pub fn as_table(&self) -> Option<&Table>
```

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

### Padding Usage Examples

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/widgets/block/struct.Padding.html

Demonstrates various ways to create Padding instances using static methods like uniform, horizontal, and proportional.

```rust
use ratatui::widgets::Padding;

Padding::uniform(1);
Padding::horizontal(2);
Padding::left(3);
Padding::proportional(4);
Padding::symmetric(5, 6);
```

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

### Get Style Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner Style value from an AttrValue. Returns None if the AttrValue is not of the Style variant.

```rust
pub fn as_style(&self) -> Option<Style>
```

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

### Example Usage

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/style/palette/tailwind/index.html

Demonstrates how to use the Tailwind color constants to create `ratatui::style::Color` objects.

```APIDOC
## §Example
```rust
use ratatui::style::{
    palette::tailwind::{BLUE, RED},
    Color,
};

assert_eq!(RED.c500, Color::Rgb(239, 68, 68));
assert_eq!(BLUE.c500, Color::Rgb(59, 130, 246));
```
```

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

### Get String Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner String value from an AttrValue. Returns None if the AttrValue is not of the String variant.

```rust
pub fn as_string(&self) -> Option<&String>
```

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

### Get Shape Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner Shape value from an AttrValue. Returns None if the AttrValue is not of the Shape variant.

```rust
pub fn as_shape(&self) -> Option<&Shape>
```

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

### Layout Example Usage

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/struct.Layout.html

Demonstrates how to use the Layout struct to split an area and render widgets.

```APIDOC
## Example
```
use ratatui::{
    layout::{Constraint, Direction, Layout, Rect},
    widgets::Paragraph,
    Frame,
};

fn render(frame: &mut Frame, area: Rect) {
    let layout = Layout::new(
        Direction::Vertical,
        [Constraint::Length(5), Constraint::Min(0)],
    )
    .split(Rect::new(0, 0, 10, 10));
    frame.render_widget(Paragraph::new("foo"), layout[0]);
    frame.render_widget(Paragraph::new("bar"), layout[1]);
}
```

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

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

### Get Layout Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner Layout value from an AttrValue. Returns None if the AttrValue is not of the Layout variant.

```rust
pub fn as_layout(&self) -> Option<&Layout>
```

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

### Enable keyboard enhancement flags

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/crossterm/event/struct.PushKeyboardEnhancementFlags.html

Example usage showing how to execute the command to enable keyboard enhancement flags and restore them later.

```rust
use std::io::{Write, stdout};
use crossterm::execute;
use crossterm::event::{
    KeyboardEnhancementFlags,
    PushKeyboardEnhancementFlags,
    PopKeyboardEnhancementFlags
};

let mut stdout = stdout();

execute!(
    stdout,
    PushKeyboardEnhancementFlags(
        KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES
    )
);

// ...

execute!(stdout, PopKeyboardEnhancementFlags);
```

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

### Create Layouts with Constraints

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/layout/enum.Constraint.html

Demonstrates how to initialize layouts using different directional constraints.

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

let layout = Layout::new(Direction::Vertical, [1, 2, 3]).split(area);
let layout = Layout::horizontal([1, 2, 3]).split(area);
let layout = Layout::vertical([1, 2, 3]).split(area);
```

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

### Get InputType Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner InputType value from an AttrValue. Returns None if the AttrValue is not of the InputType variant.

```rust
pub fn as_input_type(&self) -> Option<&InputType>
```

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

### Styling Lines Example

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/prelude/text/struct.Line.html

Illustrates how to apply styles to a Line using the style method and Stylize trait.

```APIDOC
### 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::{
    style::{Color, Modifier, Style, Stylize},
    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();
```
```

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

### Get Direction Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner Direction value from an AttrValue. Returns None if the AttrValue is not of the Direction variant.

```rust
pub fn as_direction(&self) -> Option<Direction>
```

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

### Get Dataset Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner Dataset value from an AttrValue. Returns None if the AttrValue is not of the Dataset variant.

```rust
pub fn as_dataset(&self) -> Option<&Dataset>
```

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

### Initialize TerminalBridge with Default Settings

Source: https://docs.rs/tuirealm/latest/tuirealm/terminal/struct.TerminalBridge.html

Use these examples to quickly set up a terminal with default settings for crossterm or termion backends. Ensure the appropriate feature flag is enabled.

```rust
use tuirealm::terminal::TerminalBridge;

#[cfg(feature = "crossterm")]
let mut terminal = TerminalBridge::init_crossterm().unwrap();
#[cfg(feature = "termion")]
let mut terminal = TerminalBridge::init_termion().unwrap();
```

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

### Get Color Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner Color value from an AttrValue. Returns None if the AttrValue is not of the Color variant.

```rust
pub fn as_color(&self) -> Option<Color>
```

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

### Example Usage of Goto

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/termion/cursor/struct.Goto.html

Demonstrates how to use the Goto struct to position text on the terminal. Requires the termion crate.

```rust
extern crate termion;

fn main() {
    print!("{}{}Stuff", termion::clear::All, termion::cursor::Goto(5, 3));
}
```

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

### Get Borders Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner Borders value from an AttrValue. Returns None if the AttrValue is not of the Borders variant.

```rust
pub fn as_borders(&self) -> Option<&Borders>
```

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

### Example of Executing Commands

Source: https://docs.rs/tuirealm/latest/tuirealm/ratatui/termion/raw/struct.RawTerminal.html

Demonstrates how to use the `execute` method to print strings to the standard output. Requires `crossterm` and `std::io`.

```rust
use std::io;
use crossterm::{ExecutableCommand, style::Print};

fn main() -> io::Result<()> {
     // will be executed directly
      io::stdout()
        .execute(Print("sum:\n".to_string()))?
        .execute(Print(format!("1 + 1= {} ", 1 + 1)))?;

      Ok(())

     // ==== Output ====
     // sum:
     // 1 + 1 = 2
}

```

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

### Get Alignment Value from AttrValue

Source: https://docs.rs/tuirealm/latest/tuirealm/props/enum.AttrValue.html

Attempts to get a reference to the inner Alignment value from an AttrValue. Returns None if the AttrValue is not of the Alignment variant.

```rust
pub fn as_alignment(&self) -> Option<Alignment>
```
Tokens:
Raw