Struct glerminal::TextBuffer

pub struct TextBuffer { /* private fields */ }

The TextBuffer acts as a “state machine” where you can set foreground color, background color and shakiness for the cursor, move the cursor around, clear the screen and write with the cursor (using the cursor’s styles). It’s often the most efficient way to write things, especially if you have a very structured way of displaying things, but for a more simple-to-use way of writing, that isn’t as structured ie. for a dialogue, you might want to use the Parser.

As of version 0.2.0, drawing multiple TextBuffers on top of eachother is also possible. As of this version writing 16-bit characters is also possible.

Parser is a struct added as a default feature, that is able to take in a piece of text and then parse it and change the cursor styles easily using the TextBuffer. The Parser can handle tags imilar to BBCode tags, and can change fg, bg and shake, meaning the following tags are available to use mid-text:

• [fg=color]
• [bg=color]
• [shake=decimal]
• optional closing/style-resetting tags: [/fg], [/bg] and [/shake]

The colors the Parser uses mid text must be pre-defined however with add_color.

Example usage of TextBuffer:

use glerminal::{TerminalBuilder, TextBuffer};

let terminal = TerminalBuilder::new()
    .with_title("Hello GLerminal!")
    .with_dimensions((1280, 720))
    .build();

let mut text_buffer;
match TextBuffer::new(&terminal, (80, 24)) {
  Ok(buffer) => text_buffer = buffer,
  Err(error) => panic!(format!("Failed to initialize text buffer: {}", error)),
}

// Test TextBuffer
text_buffer.change_cursor_fg_color([1.0, 0.0, 0.0, 1.0]);
text_buffer.change_cursor_bg_color([1.0, 1.0, 1.0, 1.0]);
text_buffer.change_cursor_shakiness(0.5);
text_buffer.move_cursor(0, 0);
text_buffer.write("This text is shaking in red in a white background!");

// Flush to "apply changes"
terminal.flush(&mut text_buffer);

Example usage of Parser

use glerminal::{TerminalBuilder, TextBuffer, Parser};

let terminal = TerminalBuilder::new()
    .with_title("Hello GLerminal!")
    .with_dimensions((1280, 720))
    .build();

let mut text_buffer;
match TextBuffer::new(&terminal, (80, 24)) {
  Ok(buffer) => text_buffer = buffer,
  Err(error) => panic!(format!("Failed to initialize text buffer: {}", error)),
}

// Test Parser
let mut parser = Parser::new();
parser.add_color("red", [1.0, 0.0, 0.0, 1.0]);
parser.add_color("white", [1.0, 1.0, 1.0, 1.0]);
parser.write(&mut text_buffer, "[fg=red][bg=white][shake=1.0]This text is also shaking in red in a white background![/fg][/bg][/shake]");
// Note: it is not necessary to close fg/bg/shake tags, parser will automatically revert colors in the TextBuffer.

// Flush to "apply changes"
terminal.flush(&mut text_buffer);

Simple example drawing multiple TextBuffers

use glerminal::{TerminalBuilder, TextBuffer};

let terminal = TerminalBuilder::new().build();

let mut background_text_buffer;
match TextBuffer::new(&terminal, (80, 24)) {
  Ok(buffer) => background_text_buffer = buffer,
  Err(error) => panic!(format!("Failed to initialize text buffer: {}", error)),
}

let mut foreground_text_buffer;
match TextBuffer::new(&terminal, (80, 24)) {
  Ok(buffer) => foreground_text_buffer = buffer,
  Err(error) => panic!(format!("Failed to initialize text buffer: {}", error)),
}

// Write to the background buffer
background_text_buffer.write("I am in the background");

// Write to the foreground buffer
foreground_text_buffer.write("I am in the foreground");

// Flush to "apply changes"
terminal.flush(&mut background_text_buffer);
terminal.flush(&mut foreground_text_buffer);

// Draw the text buffers
// The two texts will appear on top of eachother because they are written in the same location
terminal.draw(&background_text_buffer);
terminal.draw(&foreground_text_buffer);

Implementations

impl TextBuffer

pub fn new(
    terminal: &Terminal,
    dimensions: (i32, i32)
) -> Result<TextBuffer, String>

Creates a new text buffer with the given dimensions (width in characters, height in characters)

pub fn get_dimensions(&self) -> (i32, i32)

Get the dimensions of the text buffer (in characters). Returns (width, height)

pub fn set_char(&mut self, x: u32, y: u32, character: TermCharacter)

Sets the character at the specified position. It is the user’s responsibility to check if such a position exists.

pub fn get_character(&self, x: i32, y: i32) -> Option<TermCharacter>

Gets the TermChaacter in the given position

Returns None if x/y are out of bounds

pub fn clear(&mut self)

Clears the screen (makes every character empty and resets their style)

pub fn put_char(&mut self, character: char)

Puts a regular character to the current position of the cursor with the cursor’s style

pub fn put_raw_char(&mut self, character: u16)

Puts a raw 16-bit character to the current position of the cursor with the cursor’s style

pub fn write<T: Into<String>>(&mut self, text: T)

Puts the given text the same way as put_char

pub fn change_cursor_fg_color(&mut self, color: [f32; 4])

Changes the foreground color for the cursor

pub fn change_cursor_bg_color(&mut self, color: [f32; 4])

Changes the background color of the cursor

pub fn get_cursor_fg_color(&mut self) -> [f32; 4]

Returns the current foreground color of the cursor

pub fn get_cursor_bg_color(&mut self) -> [f32; 4]

Returns the current background color of the cursor

pub fn change_cursor_shakiness(&mut self, shakiness: f32)

Changes the shakiness of the cursor

pub fn get_cursor_shakiness(&mut self) -> f32

Gets the current shakiness of the cursor

pub fn move_cursor(&mut self, x: i32, y: i32)

Moves the cursor to a specified location in the terminal. If the location does not exist, nothing happens.

pub fn get_cursor_position(&self) -> (i32, i32)

Returns the current position of the cursor

pub fn set_limits(
    &mut self,
    x_min: Option<u32>,
    x_max: Option<u32>,
    y_min: Option<u32>,
    y_max: Option<u32>
)

Set the limits for drawing, other than the current screen. None means no limit in this direction.

pub fn get_limits(&self) -> TermLimits

Get the current term limits of the terminal.

pub fn is_dirty(&self) -> bool

Returns whether the TextBuffer is dirty or not (whether flush will have any effect or not)