Add synchronized output/update (#756)

examples/interactive-demo/src/main.rs

@@ -27,6 +27,7 @@ Available tests:
 2. color (foreground, background)
 3. attributes (bold, italic, ...)
 4. input
+5. synchronized output
 
 Select test to run ('1', '2', ...) or hit 'q' to quit.
 "#;
@@ -59,6 +60,7 @@ where
             '2' => test::color::run(w)?,
             '3' => test::attribute::run(w)?,
             '4' => test::event::run(w)?,
+            '5' => test::synchronized_output::run(w)?,
             'q' => break,
             _ => {}
         };

examples/interactive-demo/src/test.rs

@@ -2,3 +2,4 @@ pub mod attribute;
 pub mod color;
 pub mod cursor;
 pub mod event;
+pub mod synchronized_output;

examples/interactive-demo/src/test/synchronized_output.rs

@@ -0,0 +1,43 @@
+use std::io::Write;
+
+use crossterm::{cursor, execute, style::Print, SynchronizedUpdate};
+
+use crate::Result;
+
+fn render_slowly<W>(w: &mut W) -> Result<()>
+where
+    W: Write,
+{
+    for i in 1..10 {
+        execute!(w, Print(format!("{}", i)))?;
+        std::thread::sleep(std::time::Duration::from_millis(50));
+    }
+    Ok(())
+}
+
+fn test_slow_rendering<W>(w: &mut W) -> Result<()>
+where
+    W: Write,
+{
+    execute!(w, Print("Rendering without synchronized update:"))?;
+    execute!(w, cursor::MoveToNextLine(1))?;
+    std::thread::sleep(std::time::Duration::from_millis(50));
+    render_slowly(w)?;
+
+    execute!(w, cursor::MoveToNextLine(1))?;
+    execute!(w, Print("Rendering with synchronized update:"))?;
+    execute!(w, cursor::MoveToNextLine(1))?;
+    std::thread::sleep(std::time::Duration::from_millis(50));
+    w.sync_update(render_slowly)??;
+
+    execute!(w, cursor::MoveToNextLine(1))?;
+    Ok(())
+}
+
+pub fn run<W>(w: &mut W) -> Result<()>
+where
+    W: Write,
+{
+    run_tests!(w, test_slow_rendering,);
+    Ok(())
+}

src/command.rs

@@ -1,6 +1,8 @@
 use std::fmt;
 use std::io::{self, Write};
 
+use crate::terminal::{BeginSynchronizedUpdate, EndSynchronizedUpdate};
+
 use super::error::Result;
 
 /// An interface for a command that performs an action on the terminal.
@@ -184,6 +186,74 @@ impl<T: Write + ?Sized> ExecutableCommand for T {
     }
 }
 
+/// An interface for types that support synchronized updates.
+pub trait SynchronizedUpdate {
+    /// Performs a set of actions against the given type.
+    fn sync_update<T>(&mut self, operations: impl FnOnce(&mut Self) -> T) -> Result<T>;
+}
+
+impl<W: std::io::Write + ?Sized> SynchronizedUpdate for W {
+    /// Performs a set of actions within a synchronous update.
+    ///
+    /// Updates will be suspended in the terminal, the function will be executed against self,
+    /// updates will be resumed, and a flush will be performed.
+    ///
+    /// # Arguments
+    ///
+    /// - Function
+    ///
+    ///     A function that performs the operations that must execute in a synchronized update.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use std::io::{Write, stdout};
+    ///
+    /// use crossterm::{Result, ExecutableCommand, SynchronizedUpdate, style::Print};
+    ///
+    ///  fn main() -> Result<()> {
+    ///     let mut stdout = stdout();
+    ///
+    ///     stdout.sync_update(|stdout| {
+    ///         stdout.execute(Print("foo 1\n".to_string()))?;
+    ///         stdout.execute(Print("foo 2".to_string()))?;
+    ///         // The effects of the print command will not be present in the terminal
+    ///         // buffer, but not visible in the terminal.
+    ///         crossterm::Result::Ok(())
+    ///     })?;
+    ///
+    ///     // The effects of the commands will be visible.
+    ///
+    ///     Ok(())
+    ///
+    ///     // ==== Output ====
+    ///     // foo 1
+    ///     // foo 2
+    /// }
+    /// ```
+    ///
+    /// # Notes
+    ///
+    /// This command is performed only using ANSI codes, and will do nothing on terminals that do not support ANSI
+    /// codes, or this specific extension.
+    ///
+    /// When rendering the screen of the terminal, the Emulator usually iterates through each visible grid cell and
+    /// renders its current state. With applications updating the screen a at higher frequency this can cause tearing.
+    ///
+    /// This mode attempts to mitigate that.
+    ///
+    /// When the synchronization mode is enabled following render calls will keep rendering the last rendered state.
+    /// The terminal Emulator keeps processing incoming text and sequences. When the synchronized update mode is disabled
+    /// again the renderer may fetch the latest screen buffer state again, effectively avoiding the tearing effect
+    /// by unintentionally rendering in the middle a of an application screen update.
+    ///
+    fn sync_update<T>(&mut self, operations: impl FnOnce(&mut Self) -> T) -> Result<T> {
+        self.queue(BeginSynchronizedUpdate)?;
+        let result = operations(self);
+        self.execute(EndSynchronizedUpdate)?;
+        Ok(result)
+    }
+}
 /// Writes the ANSI representation of a command to the given writer.
 fn write_command_ansi<C: Command>(
     io: &mut (impl io::Write + ?Sized),

src/lib.rs

@@ -235,7 +235,7 @@
 //! [flush]: https://doc.rust-lang.org/std/io/trait.Write.html#tymethod.flush
 
 pub use crate::{
-    command::{Command, ExecutableCommand, QueueableCommand},
+    command::{Command, ExecutableCommand, QueueableCommand, SynchronizedUpdate},
     error::{ErrorKind, Result},
 };
 

src/terminal.rs

@@ -378,6 +378,112 @@ impl<T: fmt::Display> Command for SetTitle<T> {
     }
 }
 
+/// A command that instructs the terminal emulator to being a synchronized frame.
+///
+/// # Notes
+///
+/// * Commands must be executed/queued for execution otherwise they do nothing.
+/// * Use [EndSynchronizedUpdate](./struct.EndSynchronizedUpdate.html) command to leave the entered alternate screen.
+///
+/// When rendering the screen of the terminal, the Emulator usually iterates through each visible grid cell and
+/// renders its current state. With applications updating the screen a at higher frequency this can cause tearing.
+///
+/// This mode attempts to mitigate that.
+///
+/// When the synchronization mode is enabled following render calls will keep rendering the last rendered state.
+/// The terminal Emulator keeps processing incoming text and sequences. When the synchronized update mode is disabled
+/// again the renderer may fetch the latest screen buffer state again, effectively avoiding the tearing effect
+/// by unintentionally rendering in the middle a of an application screen update.
+///
+/// # Examples
+///
+/// ```no_run
+/// use std::io::{stdout, Write};
+/// use crossterm::{execute, Result, terminal::{BeginSynchronizedUpdate, EndSynchronizedUpdate}};
+///
+/// fn main() -> Result<()> {
+///     execute!(stdout(), BeginSynchronizedUpdate)?;
+///
+///     // Anything performed here will not be rendered until EndSynchronizedUpdate is called.
+///
+///     execute!(stdout(), EndSynchronizedUpdate)?;
+///     Ok(())
+/// }
+/// ```
+///
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct BeginSynchronizedUpdate;
+
+impl Command for BeginSynchronizedUpdate {
+    fn write_ansi(&self, f: &mut impl fmt::Write) -> fmt::Result {
+        f.write_str(csi!("?2026h"))
+    }
+
+    #[cfg(windows)]
+    fn execute_winapi(&self) -> Result<()> {
+        Ok(())
+    }
+
+    #[cfg(windows)]
+    #[inline]
+    fn is_ansi_code_supported(&self) -> bool {
+        true
+    }
+}
+
+/// A command that instructs the terminal to end a synchronized frame.
+///
+/// # Notes
+///
+/// * Commands must be executed/queued for execution otherwise they do nothing.
+/// * Use [BeginSynchronizedUpdate](./struct.BeginSynchronizedUpdate.html) to enter the alternate screen.
+///
+/// When rendering the screen of the terminal, the Emulator usually iterates through each visible grid cell and
+/// renders its current state. With applications updating the screen a at higher frequency this can cause tearing.
+///
+/// This mode attempts to mitigate that.
+///
+/// When the synchronization mode is enabled following render calls will keep rendering the last rendered state.
+/// The terminal Emulator keeps processing incoming text and sequences. When the synchronized update mode is disabled
+/// again the renderer may fetch the latest screen buffer state again, effectively avoiding the tearing effect
+/// by unintentionally rendering in the middle a of an application screen update.
+///
+/// # Examples
+///
+/// ```no_run
+/// use std::io::{stdout, Write};
+/// use crossterm::{execute, Result, terminal::{BeginSynchronizedUpdate, EndSynchronizedUpdate}};
+///
+/// fn main() -> Result<()> {
+///     execute!(stdout(), BeginSynchronizedUpdate)?;
+///
+///     // Anything performed here will not be rendered until EndSynchronizedUpdate is called.
+///
+///     execute!(stdout(), EndSynchronizedUpdate)?;
+///     Ok(())
+/// }
+/// ```
+///
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct EndSynchronizedUpdate;
+
+impl Command for EndSynchronizedUpdate {
+    fn write_ansi(&self, f: &mut impl fmt::Write) -> fmt::Result {
+        f.write_str(csi!("?2026l"))
+    }
+
+    #[cfg(windows)]
+    fn execute_winapi(&self) -> Result<()> {
+        Ok(())
+    }
+
+    #[cfg(windows)]
+    #[inline]
+    fn is_ansi_code_supported(&self) -> bool {
+        true
+    }
+}
+
 impl_display!(for ScrollUp);
 impl_display!(for ScrollDown);
 impl_display!(for SetSize);