Struct screen_printer::printer::Printer

pub struct Printer { /* private fields */ }

Screen Printer

Screen Printer is a rust crate that will allow you to build and print arrays of data into a grid format.

The purpose of this crate is to make it easier to print rectangular blocks of text to the terminal. Including features like:

• DynamicPrint, which only prints any characters that changed from any previously printed grid*.
• PrintingPosition, which allows you to print your string to different places on the terminal, such as the center.

* If the grid changes in size or position it is reprinted in its entirety.

Examples

Using the dynamic print method to print a grid

The core part of this crate is the dynamic_print method. This will take a rectangular grid of characters, and print only the parts of the grid that have changed since the last print.

use screen_printer::printer::*;

const WIDTH: usize = 3;
const HEIGHT: usize = 3;

fn main() {
  print!("\u{1b}[2J"); // Clear all text on the terminal
  // The default printing position is the bottom left of the terminal
  let mut printer = Printer::new_with_printing_position(PrintingPosition::default());

  // Create the first grid to be printed.
  let grid_1 = "abc\n123\nxyz".to_string();
  // print the first grid.
  printer.dynamic_print(grid_1).unwrap();

  // Wait before printing the second grid.
  std::thread::sleep(std::time::Duration::from_millis(500));

  // Create the second grid to be printed.
  let grid_2 = "abc\n789\nxyz".to_string();
  // Print the second grid.
  // This will only end up printing the difference between the two grids/
  printer.dynamic_print(grid_2).unwrap();
}

This will result in

abc
123
xyz

Into

abc
789 < only line that was actually printed
xyz

Printing Position

Another feature shown in the above example, the PrintingPosition.

This will print the grid in any of the 9 defined positions on the terminal. These are split by the X and Y axes:

• Left/Top,
• Middle, and;
• Right/Bottom.

Implementations

impl Printer

pub fn new() -> Self

Creates a new printer for the dynamic_print() method.

Uses the default PrintingPosition

pub fn new_with_printing_position(printing_position: PrintingPosition) -> Self

Creates a new printer for the dynamic_print() method with the given printing position.

PrintingPositons tell the printer where to print any grids passed into it. Refer to PrintingPosition for more information;

pub fn replace_printing_position(&mut self, printing_position: PrintingPosition)

pub fn replace_x_printing_position( &mut self, new_x_printing_position: XPrintingPosition ) -> Result<(), PrintingError>

Errors

• There is no defined printing position

pub fn replace_y_printing_position( &mut self, new_y_printing_position: YPrintingPosition ) -> Result<(), PrintingError>

Errors

• There is no defined printing position

pub fn get_current_printing_position(&self) -> &PrintingPosition

Returns a reference to the currently stored printing position.

pub fn create_grid_from_single_character( character: char, width: usize, height: usize ) -> String

Creates a grid of the given size with the given character.

Example

use screen_printer::printer::*;

let character = 'a';
let expected_grid = "aaa\naaa\naaa";

let grid = Printer::create_grid_from_single_character(character, 3, 3);

assert_eq!(expected_grid, grid);

pub fn create_grid_from_full_character_list<T>( characters: &Vec<T>, width: usize, height: usize ) -> Result<String, PrintingError>where T: Display,

Creates a grid of the given size with the given list of characters

Example

use screen_printer::printer::*;

let characters = vec!["a", "b", "c", "d", "e", "f", "g", "h", "i"];
let expected_grid = "abc\ndef\nghi";

let grid = Printer::create_grid_from_full_character_list(&characters, 3, 3).unwrap();

assert_eq!(expected_grid, grid);

Errors

• When the amount of characters passed in doesn’t fit the expected grid dimensions.

pub fn print_over_previous_grid(grid: String, height: usize)

Moves the cursor up by the given height and prints the given grid.

This is for printing over the previously printed grid. It’s recommended to add some whitespace before your first print so the grid doesn’t print into anything that was printed before this method was called.

Example

use screen_printer::printer::*;

let height = 10;
let width = 10;
let grid = Printer::create_grid_from_single_character('a', width, height);

print!("{}", "\n".repeat(height + 5)); // add some space for the grid
Printer::print_over_previous_grid(grid, height);

pub fn get_terminal_dimensions() -> Result<(usize, usize), PrintingError>

Returns the current dimensions of the terminal.

Errors

• Whenever termion::terminal_size can fail. They don’t document it themselves.

pub fn reset(&mut self)

Resets all data for the printer.

pub fn reset_and_retain_printing_position(&mut self)

Resets all data for the printer except for the current position.

pub fn reset_with_position(&mut self, printing_position: PrintingPosition)

Resets all data for the printer and assigns the given printing position.

Trait Implementations

impl Debug for Printer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Printer

fn default() -> Printer

Returns the “default value” for a type.

impl DynamicPrinter for Printer

fn dynamic_print(&mut self, new_grid: String) -> Result<(), PrintingError>

This method will print any grid to the terminal based on the PrintingPosition.

fn clear_grid(&mut self) -> Result<(), PrintingError>

Replaces every character in the grid with whitespace.