Struct mortal::screen::Screen

pub struct Screen(_);

Provides operations on an underlying terminal device in screen mode.

Screen uses an internal buffer to store rendered text, colors, and style.

Each set of changes must be followed by a call to refresh to flush these changes to the terminal device.

Concurrency

Access to read and write operations is controlled by two internal locks: One for reading and one for writing. Each lock may be held independently of the other.

If any one thread wishes to hold both locks, the read lock must be acquired first, in order to prevent deadlocks.

Implementations

impl Screen

pub fn new(config: PrepareConfig) -> Result<Screen>

Opens a new screen interface on stdout.

pub fn stderr(config: PrepareConfig) -> Result<Screen>

Opens a new screen interface on stderr.

pub fn with_terminal(term: Terminal, config: PrepareConfig) -> Result<Screen>

Begins a new screen session using the given Terminal instance.

pub fn name(&self) -> &str

Returns the name of the terminal.

Notes

On Unix, this method returns the contents of the TERM environment variable.

On Windows, this method always returns the string "windows-console".

pub fn lock_read(&self) -> LockResult<ScreenReadGuard<'_>>

Attempts to acquire an exclusive lock on terminal read operations.

The current thread will block until the lock can be acquired.

pub fn lock_write(&self) -> LockResult<ScreenWriteGuard<'_>>

Attempts to acquire an exclusive lock on terminal write operations.

The current thread will block until the lock can be acquired.

pub fn try_lock_read(&self) -> TryLockResult<ScreenReadGuard<'_>>

Attempts to acquire an exclusive lock on terminal read operations.

If the lock cannot be acquired immediately, Err(_) is returned.

pub fn try_lock_write(&self) -> TryLockResult<ScreenWriteGuard<'_>>

Attempts to acquire an exclusive lock on terminal write operations.

If the lock cannot be acquired immediately, Err(_) is returned.

impl Screen

Locking

The following methods internally acquire the read lock.

The lock is released before the method returns.

These methods are also implemented on ScreenReadGuard, which holds the Screen read lock until the value is dropped.

pub fn wait_event(&self, timeout: Option<Duration>) -> Result<bool>

Waits for an event from the terminal.

Returns Ok(false) if timeout elapses without an event occurring.

If timeout is None, this method will wait indefinitely.

Notes

Some low-level terminal events may not generate an Event value. Therefore, this method may return Ok(true), while a follow-up call to read_event may not immediately return an event.

pub fn read_event(&self, timeout: Option<Duration>) -> Result<Option<Event>>

Reads an event from the terminal.

If timeout elapses without an event occurring, this method will return Ok(None).

If timeout is None, this method will wait indefinitely.

impl Screen

Locking

The following methods internally acquire the write lock.

The lock is released before the method returns.

These methods are also implemented on ScreenWriteGuard, which holds the Screen write lock until the value is dropped.

pub fn size(&self) -> Size

Returns the current size of the terminal screen.

pub fn cursor(&self) -> Cursor

Returns the current cursor position.

pub fn set_cursor<C: Into<Cursor>>(&self, pos: C)

Sets the cursor position.

pub fn next_line(&self, column: usize)

Moves the cursor to the given column on the next line.

pub fn set_cursor_mode(&self, mode: CursorMode) -> Result<()>

Set the current cursor mode.

This setting is a visible hint to the user. It produces no change in behavior.

Notes

On Unix systems, this setting may have no effect.

pub fn clear_screen(&self)

Clears the internal screen buffer.

pub fn add_style(&self, style: Style)

Adds a set of Style flags to the current style setting.

pub fn remove_style(&self, style: Style)

Removes a set of Style flags to the current style setting.

pub fn set_style<S: Into<Option<Style>>>(&self, style: S)

Sets the current style setting to the given set of flags.

pub fn set_fg<C: Into<Option<Color>>>(&self, fg: C)

Sets or removes foreground text color.

pub fn set_bg<C: Into<Option<Color>>>(&self, bg: C)

Sets or removes background text color.

pub fn set_theme(&self, theme: Theme)

Sets all attributes for the screen.

pub fn clear_attributes(&self)

Removes color and style attributes.

pub fn bold(&self)

Adds bold to the current style setting.

This is equivalent to self.add_style(Style::BOLD).

pub fn italic(&self)

Adds italic to the current style setting.

This is equivalent to self.add_style(Style::ITALIC).

pub fn underline(&self)

Adds underline to the current style setting.

This is equivalent to self.add_style(Style::UNDERLINE).

pub fn reverse(&self)

Adds reverse to the current style setting.

This is equivalent to self.add_style(Style::REVERSE).

pub fn refresh(&self) -> Result<()>

Renders the internal buffer to the terminal screen.

pub fn write_at<C>(&self, position: C, text: &str) where
    C: Into<Cursor>, 

Writes text at the given position within the screen buffer.

Any non-printable characters, such as escape sequences, will be ignored.

pub fn write_styled<F, B, S>(&self, fg: F, bg: B, style: S, text: &str) where
    F: Into<Option<Color>>,
    B: Into<Option<Color>>,
    S: Into<Option<Style>>, 

Writes text with the given attributes at the current cursor position.

Any non-printable characters, such as escape sequences, will be ignored.

pub fn write_styled_at<C, F, B, S>(
    &self,
    position: C,
    fg: F,
    bg: B,
    style: S,
    text: &str
) where
    C: Into<Cursor>,
    F: Into<Option<Color>>,
    B: Into<Option<Color>>,
    S: Into<Option<Style>>, 

Writes text with the given attributes at the given position within the screen buffer.

Any non-printable characters, such as escape sequences, will be ignored.

pub fn write_char(&self, ch: char)

Writes a single character at the cursor position using the current style and color settings.

If the character is a non-printable character, it will be ignored.

pub fn write_str(&self, s: &str)

Writes a string at the cursor position using the current style and color settings.

Any non-printable characters, such as escape sequences, will be ignored.

pub fn write_fmt(&self, args: Arguments<'_>)

Writes formatted text at the cursor position using the current style and color settings.

This method enables Screen to be used as the receiver to the write! and writeln! macros.

Any non-printable characters, such as escape sequences, will be ignored.

Examples

let screen = Screen::new(Default::default())?;

writeln!(screen, "Hello, world!");

Trait Implementations

impl TerminalExt for Screen

fn read_raw(
    &mut self,
    buf: &mut [u8],
    timeout: Option<Duration>
) -> Result<Option<Event>>

Reads raw data from the terminal.