pub struct BufferedTerminal<T: Terminal> { /* private fields */ }Expand description
BufferedTerminal is a convenience wrapper around both
a Terminal and a Surface. It enables easier use of
the output optimization features available to Surface
and internally keeps track of the sequence number.
BufferedTerminal derefs to Surface and makes available
the surface API.
The flush method is used to compute the optimized set
of changes and actually render them to the underlying
Terminal. No output will be visible until it is flushed!
Implementations
sourceimpl<T: Terminal> BufferedTerminal<T>
impl<T: Terminal> BufferedTerminal<T>
sourcepub fn new(terminal: T) -> Result<Self>
pub fn new(terminal: T) -> Result<Self>
Create a new BufferedTerminal with a Surface of
a matching size.
sourcepub fn terminal(&mut self) -> &mut T
pub fn terminal(&mut self) -> &mut T
Get a mutable reference to the underlying terminal instance
sourcepub fn flush(&mut self) -> Result<()>
pub fn flush(&mut self) -> Result<()>
Compute the set of changes needed to update the screen to
match the current contents of the embedded Surface and
send them to the Terminal.
If some other process has output over the terminal screen,
or other artifacts are present, this routine has no way to
detect the lose of synchronization.
Applications typically build in a refresh function (CTRL-L
is common for unix applications) to request a repaint.
You can use the repaint function for that situation.
sourcepub fn repaint(&mut self) -> Result<()>
pub fn repaint(&mut self) -> Result<()>
Clears the screen and re-draws the surface contents onto the Terminal.
sourcepub fn check_for_resize(&mut self) -> Result<bool>
pub fn check_for_resize(&mut self) -> Result<bool>
Check to see if the Terminal has been resized by its user.
If it has, resize the surface to match the new dimensions
and return true. If the terminal was resized, the application
will typically want to apply changes to match the new size
and follow it up with a flush call to update the screen.
Why isn’t this automatic? On Unix systems the SIGWINCH signal is used to indicate that a terminal size has changed. This notification is completely out of band from the interactions with the underlying terminal device, and thus requires a function such as this one to be called after receipt of SIGWINCH, or just speculatively from time to time.
Attaching signal handlers unilaterally from a library is undesirable, as the embedding application may have strong opinions about how best to do such a thing, so we do not automatically configure a signal handler.
On Windows it is possible to receive notification about window
resizing by processing input events. Enabling those requires
manipulating the input mode and establishing a handler to
consume the input records. Such a thing is possible, but is
better suited for a higher level abstraction than this basic
BufferedTerminal interface.
Methods from Deref<Target = Surface>
sourcepub fn dimensions(&self) -> (usize, usize)
pub fn dimensions(&self) -> (usize, usize)
Returns the (width, height) of the surface
pub fn cursor_position(&self) -> (usize, usize)
pub fn cursor_shape(&self) -> Option<CursorShape>
pub fn cursor_visibility(&self) -> CursorVisibility
pub fn title(&self) -> &str
sourcepub fn resize(&mut self, width: usize, height: usize)
pub fn resize(&mut self, width: usize, height: usize)
Resize the Surface to the specified width and height.
If the width and/or height are smaller than previously, the rows and/or
columns are truncated. If the width and/or height are larger than
previously then an appropriate number of cells are added to the
buffer and filled with default attributes.
The resize event invalidates the change stream, discarding it and
causing a subsequent get_changes call to yield a full repaint.
If the cursor position would be outside the bounds of the newly resized
screen, it will be moved to be within the new bounds.
sourcepub fn add_changes(&mut self, changes: Vec<Change>) -> SequenceNo
pub fn add_changes(&mut self, changes: Vec<Change>) -> SequenceNo
Efficiently apply a series of changes Returns the sequence number at the end of the change.
sourcepub fn add_change<C: Into<Change>>(&mut self, change: C) -> SequenceNo
pub fn add_change<C: Into<Change>>(&mut self, change: C) -> SequenceNo
Apply a change and return the sequence number at the end of the change.
sourcepub fn screen_chars_to_string(&self) -> String
pub fn screen_chars_to_string(&self) -> String
Returns the entire contents of the screen as a string. Only the character data is returned. The end of each line is returned as a \n character. This function exists primarily for testing purposes.
sourcepub fn screen_cells(&mut self) -> Vec<&mut [Cell]>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
pub fn screen_cells(&mut self) -> Vec<&mut [Cell]>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
A: Allocator,
Returns the cell data for the screen. This is intended to be used for testing purposes.
pub fn screen_lines(&self) -> Vec<Cow<'_, Line>>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
A: Allocator,
sourcepub fn get_changes(&self, seq: SequenceNo) -> (SequenceNo, Cow<'_, [Change]>)
pub fn get_changes(&self, seq: SequenceNo) -> (SequenceNo, Cow<'_, [Change]>)
Returns a stream of changes suitable to update the screen
to match the model. The input seq argument should be 0
on the first call, or in any situation where the screen
contents may have been invalidated, otherwise it should
be set to the SequenceNo returned by the most recent call
to get_changes.
get_changes will use a heuristic to decide on the lower
cost approach to updating the screen and return some sequence
of Change entries that will update the display accordingly.
The worst case is that this function will fabricate a sequence
of Change entries to paint the screen from scratch.
pub fn has_changes(&self, seq: SequenceNo) -> bool
pub fn current_seqno(&self) -> SequenceNo
sourcepub fn flush_changes_older_than(&mut self, seq: SequenceNo)
pub fn flush_changes_older_than(&mut self, seq: SequenceNo)
After having called get_changes and processed the resultant
change stream, the caller can then pass the returned SequenceNo
value to this call to prune the list of changes and free up
resources from the change log.
sourcepub fn diff_region(
&self,
x: usize,
y: usize,
width: usize,
height: usize,
other: &Surface,
other_x: usize,
other_y: usize
) -> Vec<Change>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
pub fn diff_region(
&self,
x: usize,
y: usize,
width: usize,
height: usize,
other: &Surface,
other_x: usize,
other_y: usize
) -> Vec<Change>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
A: Allocator,
Computes the change stream required to make the region within self
at coordinates x, y and size width, height look like the
same sized region within other at coordinates other_x, other_y.
other and self may be the same, causing regions within the same
Surface to be differenced; this is used by the copy_region method.
The returned list of Changes can be passed to the add_changes method
to make the region within self match the region within other.
Panics
Will panic if the regions of interest are not within the bounds of
their respective Surface.
pub fn diff_lines(&self, other_lines: Vec<&Line>) -> Vec<Change>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
A: Allocator,
pub fn diff_against_numbered_line(
&self,
row_num: usize,
other_line: &Line
) -> Vec<Change>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
A: Allocator,
sourcepub fn diff_screens(&self, other: &Surface) -> Vec<Change>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
pub fn diff_screens(&self, other: &Surface) -> Vec<Change>ⓘNotable traits for Vec<u8, A>impl<A> Write for Vec<u8, A> where
A: Allocator,
A: Allocator,
Computes the change stream required to make self have the same
screen contents as other.
sourcepub fn draw_from_screen(
&mut self,
other: &Surface,
x: usize,
y: usize
) -> SequenceNo
pub fn draw_from_screen(
&mut self,
other: &Surface,
x: usize,
y: usize
) -> SequenceNo
Draw the contents of other into self at the specified coordinates.
The required updates are recorded as Change entries as well as stored
in the screen line/cell data.
Saves the cursor position and attributes that were in effect prior to
calling draw_from_screen and restores them after applying the changes
from the other surface.
sourcepub fn copy_region(
&mut self,
src_x: usize,
src_y: usize,
width: usize,
height: usize,
dest_x: usize,
dest_y: usize
) -> SequenceNo
pub fn copy_region(
&mut self,
src_x: usize,
src_y: usize,
width: usize,
height: usize,
dest_x: usize,
dest_y: usize
) -> SequenceNo
Copy the contents of the specified region to the same sized region elsewhere in the screen display. The regions may overlap.
Panics
The destination region must be the same size as the source (which is implied by the function parameters) and must fit within the width and height of the Surface or this operation will panic.
Trait Implementations
sourceimpl<T: Terminal> Deref for BufferedTerminal<T>
impl<T: Terminal> Deref for BufferedTerminal<T>
Auto Trait Implementations
impl<T> RefUnwindSafe for BufferedTerminal<T> where
T: RefUnwindSafe,
impl<T> Send for BufferedTerminal<T> where
T: Send,
impl<T> Sync for BufferedTerminal<T> where
T: Sync,
impl<T> Unpin for BufferedTerminal<T> where
T: Unpin,
impl<T> UnwindSafe for BufferedTerminal<T> where
T: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more