TerimalRtdm

• ⏱️ Quickstart
• 📚 Documentation
• 🧩 Templates
• 👁️ Built with TerimalRtdm
• ⭐️ Leave a star!
• ⌨️ Contributing
• 📄 License

Add our crate to your toml:

cargo add TerimalRtdm 

Then declare it's usage:

use TerimalRtdm::*;

use TerimalRtdm::*;

fn main() {
  let mut app = App::new(); // 👈 New
  // Rest of the code ...
}

use TerimalRtdm::*;

fn main() {
  let mut app = App::new();
  clear(&mut app); // 👈 New
  // Rest of the code ...
}

use TerimalRtdm::*;

fn main() {
  let mut app = App::new();
  clear(&mut app);
  show_cursor(false); // 👈 New
  // Rest of the code ...
}

use TerimalRtdm::*;

fn main() {
  let mut app = App::new();
  clear(&mut app);
  show_cursor(false);

  loop { // 👈 New
    // Rest of the code ...
  }
}

use TerimalRtdm::*;

fn main() {
  let mut app = App::new();
  clear(&mut app);
  show_cursor(false);

  loop {
    Text::new().show(&mut app, "Hello world", pos!(0, 0)); // 👈 New
    // Rest of the code ...
  }
}

Text can be moved around the screen with the Pos struct, which moves text around by letter units, where the text should start to be displayed. If you want to see the length of the text use your_text_var.len() with the variable being a &str type. This returns the length of chars that will be printed with the first one starting at x in Pos.

Optionally: You can change the text's style, position, foreground(color of the text) and background.

Text::new()
    .foreground(Color::Black) // Check Color and style enum's for varient options!
    .background(Color::Magenta)
    .style(Style::Bold)
    .show(&mut app, "Hi", pos!(13, 0)); // each x and y is one char and "Hello world".len() returns 11, so we start at 13.

Keep in mind: Text is layered with the bottommost being the highest drawn layer, as your code goes down linearly.

In case you are displaying a text under a key being pressed, you can toggle it's vanishing under other keys.

Text::new()
    .vanish(false)
    .show(&mut app, "Test", pos!(0, 1)); // displays on the second line of the screen, as `y` is set to `1`.

KeyType is an enum representing all possible key combinations.
If a key is missing on the crate's end, it will default to: KeyType::Unknown

Key is a struct used for optional parameters, following idiomatic Rust patterns.

use TerimalRtdm::*;

fn main() {
  let mut app = App::new();
  clear(&mut app);
  show_cursor(false);

  loop {
    Text::new().show(&mut app, "Hello world", pos!(0, 0));

    if Key::o().pressed(&mut app, KeyType::Esc) { // 👈 New
      break;
    }
    // Rest of the code ...
  }
}

You can also add the no_clear() impl on Key::o() if you spefied text to show only under the specific input, and does not effect that text, which is useful for cursor movement.

if Key::o().no_clear().pressed(&mut app, KeyType::Esc) { // Example of using no_clear().
  break;
}

use TerimalRtdm::*;

fn main() {
  let mut app = App::new();
  clear(&mut app);
  show_cursor(false);

  loop {
    Text::new().show(&mut app, "Hello world", pos!(0, 0));

    if Key::o().pressed(&mut app, KeyType::Esc) { 
      break;
    }

    render(&app); // 👈 New
    // Rest of the code ...
  }
}

This allows us to check for this input next loop.

use TerimalRtdm::*;

fn main() {
  let mut app = App::new();
  clear(&mut app);
  show_cursor(false);

  loop {
    Text::new().show(&mut app, "Hello world", pos!(0, 0));

    if Key::o().pressed(&mut app, KeyType::Esc) { 
      break;
    }

    render(&app); 
    collect_presses(&mut app); // 👈 New
  }
}

Optional: Enable Escape Sequence Handling

By default, the app does not check for escape sequences (such as function keys and arrow keys).
This is because enabling them requires tracking the Esc key being pressed up to three times,
which can interfere with simple Esc based interactions.

Unless you really need to support function or arrow keys, it's recommended to leave this option disabled, so users can freely press Esc without unintended side effects.

If your app needs arrow or function key support, you can enable this behavior by toggling the relevant bool flag, and untoggle once the user needs to press escape, like in vim.

app.enable_f_row_and_arrow = true; 

use TerimalRtdm::*;

fn main() {
  let mut app = App::new();
  clear(&mut app);
  show_cursor(false);

  loop {
    Text::new().show(&mut app, "Hello world", pos!(0, 0));

    if Key::o().pressed(&mut app, KeyType::Esc) { 
      break;
    }

    render(&app); 
    collect_presses(&mut app); // 👈 New 
  }

  restore_terminal();
}

You can easily move the cursor using the Mov::cur().dir() method along with key inputs. This snippet shows a typical setup using Key::o() with KeyType directions.

moving the cursor in any direction

if Key::o().no_clear().pressed(&mut app, KeyType::k) { // Note: you can replace these example vim keys with any keys you so disire.
    Mov::cur().dir(&mut app, Dir::Up, 1); // the last para 1, is the distance in letter units.
}

if Key::o().no_clear().pressed(&mut app, KeyType::j) {
    Mov::cur().dir(&mut app, Dir::Down, 1);
}

if Key::o().no_clear().pressed(&mut app, KeyType::h) {
    Mov::cur().dir(&mut app, Dir::Left, 1);
}

if Key::o().no_clear().pressed(&mut app, KeyType::l) {
    Mov::cur().dir(&mut app, Dir::Right, 1);
}

You can also change the behavior when moving the cursor as well. By default it is set to wrap like a normal text editor. but you can optinal apply the impl block() or freefloat() on Mov::cur().

if Key::o().no_clear().pressed(&mut app, KeyType::l) {
    Mov::cur().block().dir(&mut app, Dir::Right, 1);
}