pub struct Screen(_);
Expand description
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§
source§impl Screen
impl Screen
sourcepub fn new(config: PrepareConfig) -> Result<Screen>
pub fn new(config: PrepareConfig) -> Result<Screen>
Opens a new screen interface on stdout
.
sourcepub fn stderr(config: PrepareConfig) -> Result<Screen>
pub fn stderr(config: PrepareConfig) -> Result<Screen>
Opens a new screen interface on stderr
.
sourcepub fn with_terminal(term: Terminal, config: PrepareConfig) -> Result<Screen>
pub fn with_terminal(term: Terminal, config: PrepareConfig) -> Result<Screen>
Begins a new screen session using the given Terminal
instance.
sourcepub fn name(&self) -> &str
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"
.
sourcepub fn lock_read(&self) -> LockResult<ScreenReadGuard<'_>>
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.
sourcepub fn lock_write(&self) -> LockResult<ScreenWriteGuard<'_>>
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.
sourcepub fn try_lock_read(&self) -> TryLockResult<ScreenReadGuard<'_>>
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.
sourcepub fn try_lock_write(&self) -> TryLockResult<ScreenWriteGuard<'_>>
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.
source§impl Screen
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.
sourcepub fn wait_event(&self, timeout: Option<Duration>) -> Result<bool>
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.
source§impl Screen
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.
sourcepub fn set_cursor<C: Into<Cursor>>(&self, pos: C)
pub fn set_cursor<C: Into<Cursor>>(&self, pos: C)
Sets the cursor position.
sourcepub fn set_cursor_mode(&self, mode: CursorMode) -> Result<()>
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.
sourcepub fn clear_screen(&self)
pub fn clear_screen(&self)
Clears the internal screen buffer.
sourcepub fn remove_style(&self, style: Style)
pub fn remove_style(&self, style: Style)
Removes a set of Style
flags to the current style setting.
sourcepub fn set_style<S: Into<Option<Style>>>(&self, style: S)
pub fn set_style<S: Into<Option<Style>>>(&self, style: S)
Sets the current style setting to the given set of flags.
sourcepub fn clear_attributes(&self)
pub fn clear_attributes(&self)
Removes color and style attributes.
sourcepub fn bold(&self)
pub fn bold(&self)
Adds bold to the current style setting.
This is equivalent to self.add_style(Style::BOLD)
.
sourcepub fn italic(&self)
pub fn italic(&self)
Adds italic to the current style setting.
This is equivalent to self.add_style(Style::ITALIC)
.
sourcepub fn underline(&self)
pub fn underline(&self)
Adds underline to the current style setting.
This is equivalent to self.add_style(Style::UNDERLINE)
.
sourcepub fn reverse(&self)
pub fn reverse(&self)
Adds reverse to the current style setting.
This is equivalent to self.add_style(Style::REVERSE)
.
sourcepub fn write_at<C>(&self, position: C, text: &str)where
C: Into<Cursor>,
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.
sourcepub 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>>,
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.
sourcepub 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>>,
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.
sourcepub fn write_char(&self, ch: char)
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.
sourcepub fn write_str(&self, s: &str)
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.
sourcepub fn write_fmt(&self, args: Arguments<'_>)
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!");