This type represents a screen which could be in normal, raw and alternate modes.
Let's talk about the different modes a bit:
-
Alternate modes:
*Nix style applications often utilize an alternate screen buffer, so that they can modify the entire contents of the buffer, without affecting the application that started them.
The alternate buffer is exactly the dimensions of the window, without any scrollback region.
For an example of this behavior, consider when vim is launched from bash.
Vim uses the entirety of the screen to edit the file, then returning to bash leaves the original buffer unchanged.
-
RawModes
- No line buffering.
Normally the terminals use line buffering. This means that the input will be sent to the terminal line by line.
With raw mode the input will send one byte at a time.
- Input
All input has to be written manually by the programmer.
- Characters
The characters are not processed by the terminal driver but are sent straight through.
Special character have no meaning, like backspace will not be interpreted as backspace but instead will be directly sent to the terminal.
- Escape characters
Note that in raw modes
\n
\r
will move to the new line but the cursor will be at the same position as before on the new line therefor use \n\r
to start at the new line at the first cell.
You have to make sure that you pass the correct Screen
to the modules cursor, terminal, color, input, style
.
If you switch to alternate screen modes you will get some Screen
handle back. This Screen
handle represents the alternate screen.
Once you want to do coloring or such you need to pass the Screen
handle the library so that it could be used for coloring on the right screen.
let screen = Screen::default();
let mut screen = Screen::new(true);
let screen = Screen::new(false);
if let Ok(alternate_screen) = screen.enable_alternate_modes(true)
{
let crossterm = Crossterm::from_screen(&alternate_screen.screen);
crossterm.cursor();
crossterm.terminal();
let cursor = crossterm::cursor::from_screen(&alternate_screen.screen);
let terminal = crossterm::terminal::from_screen(&alternate_screen.screen);
let input = crossterm::input::from_screen(&alternate_screen.screen);
}
Note that using Screen
is preferred over manually using AlternateScreen
or RawScreen
.
Create a new instance of the Screen also specify if the current screen should be in raw mode or normal mode.
If you are not sure what raw mode is then passed false or use the Screen::default()
to create an instance.
Switch to alternate screen. This function will return an AlternateScreen
instance. If everything went well this type will give you control over the AlternateScreen
.
The bool 'raw_mode' specifies whether the alternate screen should be raw mode or not.
*Nix style applications often utilize an alternate screen buffer, so that they can modify the entire contents of the buffer, without affecting the application that started them.
The alternate buffer is exactly the dimensions of the window, without any scrollback region.
For an example of this behavior, consider when vim is launched from bash.
Vim uses the entirety of the screen to edit the file, then returning to bash leaves the original buffer unchanged.
Write buffer to an internal buffer. When you want to write the buffer to screen use flush_buf()
.
This function is useful if you want to build up some output and when you are ready you could flush the output to the screen.
let screen = Screen::default();
screen.write_buf(b"Some text");
screen.write_buf(b"Some more text");
screen.write_buf(b"Some more text");
Flush the internal buffer to the screen.
This will disable the drop which will cause raw modes not to be undone on the drop of Screen
.
If the current screen is in raw mode we need to disable it when the instance goes out of scope.
Create a new screen which will not be in raw mode or alternate mode.
Write a buffer into this writer, returning how many bytes were written. Read more
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
Attempts to write an entire buffer into this writer. Read more
Writes a formatted string into this writer, returning any error encountered. Read more
Creates a "by reference" adaptor for this instance of Write
. Read more
Create a screen with the given 'Arc'
Create a screen with the given Stdout
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
🔬 This is a nightly-only experimental API. (get_type_id
)
this method will likely be replaced by an associated static