Crate Rusty_tui

source
Expand description

Rusty-TUI Library

This library provides simple components for creating Text User Interfaces (TUIs) in Rust. It includes basic elements such as labels and input boxes to enhance CLI applications.

§Rusty-TUI Documentation

Welcome to the Rusty-TUI documentation! This book will guide you through the features and usage of the Rusty-TUI library for creating terminal applications.

§Table of Contents

§Rusty-TUI

Rusty-TUI is a simple yet powerful TUI (Text User Interface) library designed for creating CLI (Command-Line Interface) applications. Its purpose is to make the development of CLI apps as straightforward as possible while still offering a rich set of features to enhance user interaction and experience.

With Rusty-TUI, developers can effortlessly incorporate elements like text labels and input boxes, enabling them to build engaging terminal applications. Whether you’re crafting a quick utility or a more complex interactive tool, Rusty-TUI provides the essential components to streamline your development process without sacrificing functionality.

§Key Features

  • Ease of Use: Designed for simplicity, Rusty-TUI allows you to create user-friendly interfaces with minimal effort.
  • Rich Functionality: Despite its simplicity, the library comes packed with features that cater to various use cases.
  • Customizable Components: Build applications that suit your specific needs with versatile components like Label and InputBox.

§Label Documentation

Welcome to the Label section of our TUI library! This document provides an overview of the Label struct, which is essential for displaying text at specific positions in your terminal application.

§Overview

The Label struct allows you to create text labels that can be drawn on the console at designated coordinates. Whether you want to greet your users, display instructions, or simply add some flair to your TUI, the Label struct is your trusty companion!

§Struct Definition

pub struct Label {
    text: String, // The text to be displayed by the label
    x: u16,       // The x-coordinate (horizontal position) where the label will be drawn
    y: u16,       // The y-coordinate (vertical position) where the label will be drawn
}

§Creating a Label

To create a new label, you can use the new method, which takes the text and coordinates as arguments.

pub fn new(text: &str, x: u16, y: u16) -> Self {
§Arguments
  • text: A string slice that holds the text of the label.
  • x: The horizontal position (x-coordinate) where the label will be drawn.
  • y: The vertical position (y-coordinate) where the label will be drawn.
§Returns
  • A new instance of Label.

§Drawing a Label

Once you have created a label, you can draw it on the console using the draw method.

pub fn draw(&self, stdout: &mut impl Write) -> io::Result<()> {
§Arguments
  • stdout: A mutable reference to any type that implements the Write trait, allowing the method to write the label’s text to the specified output.
§Errors
  • Returns an io::Result<()>, which will contain an error if the write operation fails.
§Example
use std::io::{self, Write};

let mut stdout = io::stdout();
let label = Label::new("Hello, world!", 10, 5);
label.draw(&mut stdout).unwrap(); // Draws the label

§InputBox Documentation

Welcome to the InputBox section of our TUI library! This document will guide you through the features and functionalities of the InputBox struct, which allows users to input text in a console application.

§Overview

The InputBox struct provides a simple interface for users to enter text, complete with a placeholder for guidance. It’s perfect for scenarios where user input is required, like forms or search boxes in terminal applications.

§Struct Definition

pub struct InputBox {
    pub input: String,   // The text entered by the user
    placeholder: String, // A placeholder text to display when input is empty
    x: u16,              // The x-coordinate (horizontal position) where the input box will be drawn
    y: u16,              // The y-coordinate (vertical position) where the input box will be drawn
}

§Creating an InputBox

To create a new input box, use the new method. This method initializes the input box with optional placeholder text.

pub fn new(input: &str, placeholder: &str, x: u16, y: u16) -> Self {
§Arguments
  • input: A string slice that holds the initial text of the input box.
  • placeholder: A string slice that holds the placeholder text to display when the input box is empty.
  • x: The horizontal position (x-coordinate) where the input box will be drawn.
  • y: The vertical position (y-coordinate) where the input box will be drawn.
§Returns
  • A new instance of InputBox.

§Retrieving Input

To get input from the user, call the get_input method. This method displays the input box at the specified position and handles user input, including character input and backspace.

pub fn get_input(&mut self) -> io::Result<String> {
§Returns
  • An io::Result<String> containing the input entered by the user or an error if the read operation fails.
§Example
let mut input_box = InputBox::new("", "Enter text here", 5, 10);
let user_input = input_box.get_input().unwrap(); // Gets user input

§Handling User Input

The get_input method handles several scenarios:

  • Displaying Placeholder: When the input is empty, the placeholder text is displayed.
  • Character Input: Characters are appended to the input string and displayed immediately.
  • Backspace Handling: The backspace key allows users to delete the last character in the input.
  • Finalizing Input: Pressing the Enter key finalizes the input and exits the loop.

§Example Usage of Label and InputBox

In this example, we will demonstrate how to create a simple terminal user interface (TUI) application using the Label and InputBox structs from our library. This application will prompt the user to enter their name and then greet them with a label.

§Prerequisites

Ensure you have Rust installed on your machine. If you haven’t set up a project yet, you can create one using:

cargo new tui_example
cd tui_example

Then, add your library as a dependency in Cargo.toml.

§Example Code

Here’s a complete example that utilizes both the Label and InputBox structs:

use std::io::{self, Write}; // Importing necessary modules for input/output operations
mod labels; // Assuming Label is in labels.rs
mod input_box; // Assuming InputBox is in input_box.rs

fn main() -> io::Result<()> {
    // Create a label to prompt the user
    let prompt_label = labels::Label::new("Please enter your name:", 5, 5);
    let mut input_box = input_box::InputBox::new("", "Enter your name...", 5, 7);

    // Draw the prompt label
    let mut stdout = io::stdout();
    prompt_label.draw(&mut stdout)?;

    // Get user input
    let user_name = input_box.get_input()?;

    // Create a greeting label
    let greeting_label = labels::Label::new(&format!("Hello, {}!", user_name), 5, 9);

    // Draw the greeting label
    greeting_label.draw(&mut stdout)?;

    Ok(())
}

§Explanation of the Code

  1. Importing Modules: We start by importing necessary modules for input and output operations. We also include our Label and InputBox modules.

  2. Creating a Label: We create a Label instance to prompt the user to enter their name.

  3. Creating an Input Box: An InputBox instance is created, initialized with an empty string and a placeholder.

  4. Drawing the Prompt: We use the draw method to display the prompt label on the console.

  5. Getting User Input: The get_input method of InputBox is called to retrieve the user’s name.

  6. Creating a Greeting: After the user inputs their name, we create another Label instance to greet the user.

  7. Displaying the Greeting: Finally, we draw the greeting label on the console.

§Running the Example

To run the example, navigate to your project directory and execute the following command:

cargo run

This will compile your project and run the TUI application. You should see the prompt asking for your name, and after entering it, a greeting will be displayed.

§Border Struct Documentation

§Overview

The Border struct represents a bordered area with specific dimensions and position in the console. It allows you to easily create and display borders made of customizable characters.

§Fields

  • border: String

    • The character(s) used for the border.

  • h: u16

    • The height of the area defined by the border.

  • w: u16

    • The width of the area defined by the border.

  • x: u16

    • The x-coordinate position of the border’s top-left corner.

  • y: u16

    • The y-coordinate position of the border’s top-left corner.

§Methods

§new

pub fn new(h: u16, w: u16, x: u16, y: u16, border: String) -> Border

Creates a new instance of Border.

§Parameters
  • h: The height of the border area.
  • w: The width of the border area.
  • x: The x-coordinate of the border’s position.
  • y: The y-coordinate of the border’s position.
  • border: A string representing the border character(s).
§Returns

Returns a new Border instance.

§draw

pub fn draw(&self)

Draws the border on the console.

This method prints the border starting at the specified (x, y) position. The border consists of repeated characters specified in the border field and is drawn for the height and width defined in the struct.

§Example
let border = Border::new(5, 10, 2, 1, "*".to_string());
border.draw();

This will create a border 10 characters wide and 5 characters high, starting from the x-coordinate 2 and y-coordinate 1.

§Example Usage

fn main() {
    let border = Border::new(5, 10, 2, 1, "*".to_string());
    border.draw();
}

This code snippet demonstrates how to create a Border instance and draw it on the console.

§Conclusion

The Border struct provides a simple way to create visually appealing borders in console applications. Customize the appearance by changing the border character, width, height, and position.

§Explanation of the Structure:

  • Overview: A brief introduction to the purpose of the struct.
  • Fields: A breakdown of each field within the struct, explaining its type and purpose.
  • Methods: Documentation for each method, including parameters, return values, and usage examples.
  • Example Usage: A complete example of how to instantiate and use the Border struct in a Rust program.
  • Conclusion: A summary of the utility of the Border struct.

Structs§

  • Border
    A structure representing a border with specific dimensions and position.
  • InputBox
    A structure representing an input box that allows the user to enter text.
  • Label
    A structure representing a text label that can be drawn on a console at a specific position.