Add terminal::supports_synchronized_output

This checks whether the terminal supports the synchronized outputs
feature according to https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036#feature-detection

Author: the-mikedavis

src/event.rs

@@ -312,6 +312,20 @@ bitflags! {
     }
 }
 
+/// The terminal's current mode of the synchronized output feature.
+///
+/// <https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036#feature-detection>
+#[derive(Debug, PartialOrd, PartialEq, Eq, Clone, Copy, Hash)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub enum SynchronizedOutputMode {
+    /// Screen updates are not shown to the user until mode is disabled.
+    Set,
+    /// Screen updates are shown as usual (e.g. as soon as they arrive).
+    Reset,
+    /// The terminal does not support synchronized output sequences.
+    NotSupported,
+}
+
 /// A command that enables mouse event capturing.
 ///
 /// Mouse events can be captured with [read](./fn.read.html)/[poll](./fn.poll.html).
@@ -1538,6 +1552,9 @@ pub(crate) enum InternalEvent {
     /// The progressive keyboard enhancement flags enabled by the terminal.
     #[cfg(unix)]
     KeyboardEnhancementFlags(KeyboardEnhancementFlags),
+    /// The terminal's current mode of the synchronized output feature.
+    #[cfg(unix)]
+    SynchronizedOutputMode(SynchronizedOutputMode),
     /// Attributes and architectural class of the terminal.
     #[cfg(unix)]
     PrimaryDeviceAttributes,

src/event/filter.rs

@@ -64,6 +64,23 @@ impl Filter for ThemeModeFilter {
     }
 }
 
+#[cfg(unix)]
+#[derive(Debug, Clone)]
+pub(crate) struct SynchronizedOutputModeFilter;
+
+#[cfg(unix)]
+impl Filter for SynchronizedOutputModeFilter {
+    fn eval(&self, event: &InternalEvent) -> bool {
+        // See `KeyboardEnhancementFlagsFilter` above: `PrimaryDeviceAttributes` is
+        // used to elicit a response from the terminal even if it doesn't support the
+        // synchronized output mode query.
+        matches!(
+            *event,
+            InternalEvent::SynchronizedOutputMode(_) | InternalEvent::PrimaryDeviceAttributes
+        )
+    }
+}
+
 #[derive(Debug, Clone)]
 pub(crate) struct EventFilter;
 

src/event/sys/unix/parse.rs

@@ -2,7 +2,8 @@ use std::io;
 
 use crate::event::{
     Event, KeyCode, KeyEvent, KeyEventKind, KeyEventState, KeyModifiers, KeyboardEnhancementFlags,
-    MediaKeyCode, ModifierKeyCode, MouseButton, MouseEvent, MouseEventKind, ThemeMode,
+    MediaKeyCode, ModifierKeyCode, MouseButton, MouseEvent, MouseEventKind, SynchronizedOutputMode,
+    ThemeMode,
 };
 
 use super::super::super::InternalEvent;
@@ -181,6 +182,7 @@ pub(crate) fn parse_csi(buffer: &[u8]) -> io::Result<Option<InternalEvent>> {
             b'u' => return parse_csi_keyboard_enhancement_flags(buffer),
             b'c' => return parse_csi_primary_device_attributes(buffer),
             b'n' => return parse_csi_theme_mode(buffer),
+            b'y' => return parse_csi_synchronized_output_mode(buffer),
             _ => None,
         },
         b'0'..=b'9' => {
@@ -327,6 +329,36 @@ fn parse_csi_theme_mode(buffer: &[u8]) -> io::Result<Option<InternalEvent>> {
     ))))
 }
 
+fn parse_csi_synchronized_output_mode(buffer: &[u8]) -> io::Result<Option<InternalEvent>> {
+    // ESC [ ? 2026 ; 0 $ y
+    assert!(buffer.starts_with(b"\x1B[?"));
+    assert!(buffer.ends_with(b"y"));
+
+    let s = std::str::from_utf8(&buffer[3..buffer.len() - 1])
+        .map_err(|_| could_not_parse_event_error())?;
+    let s = match s.strip_suffix('$') {
+        Some(s) => s,
+        None => return Ok(None),
+    };
+
+    let mut split = s.split(';');
+
+    if next_parsed::<u16>(&mut split)? != 2026 {
+        return Ok(None);
+    }
+
+    let synchronized_output_mode = match next_parsed::<u8>(&mut split)? {
+        1 => SynchronizedOutputMode::Set,
+        2 => SynchronizedOutputMode::Reset,
+        0 | 4 => SynchronizedOutputMode::NotSupported,
+        _ => return Ok(None),
+    };
+
+    Ok(Some(InternalEvent::SynchronizedOutputMode(
+        synchronized_output_mode,
+    )))
+}
+
 fn parse_modifiers(mask: u8) -> KeyModifiers {
     let modifier_mask = mask.saturating_sub(1);
     let mut modifiers = KeyModifiers::empty();

src/terminal.rs

@@ -101,6 +101,7 @@ pub(crate) mod sys;
 #[cfg(feature = "events")]
 pub use sys::{
     query_keyboard_enhancement_flags, query_terminal_theme_mode, supports_keyboard_enhancement,
+    supports_synchronized_output,
 };
 
 /// Tells whether the raw mode is enabled.

src/terminal/sys.rs

@@ -8,6 +8,7 @@ pub(crate) use self::unix::{
 #[cfg(feature = "events")]
 pub use self::unix::{
     query_keyboard_enhancement_flags, query_terminal_theme_mode, supports_keyboard_enhancement,
+    supports_synchronized_output,
 };
 #[cfg(all(windows, test))]
 pub(crate) use self::windows::temp_screen_buffer;
@@ -20,6 +21,7 @@ pub(crate) use self::windows::{
 #[cfg(feature = "events")]
 pub use self::windows::{
     query_keyboard_enhancement_flags, query_terminal_theme_mode, supports_keyboard_enhancement,
+    supports_synchronized_output,
 };
 
 #[cfg(windows)]

src/terminal/sys/unix.rs

@@ -245,6 +245,76 @@ fn query_terminal_theme_mode_raw() -> io::Result<Option<ThemeMode>> {
     }
 }
 
+#[cfg(feature = "events")]
+fn supports_synchronized_output_raw() -> io::Result<bool> {
+    use crate::event::{
+        filter::{PrimaryDeviceAttributesFilter, SynchronizedOutputModeFilter},
+        poll_internal, read_internal, InternalEvent, SynchronizedOutputMode,
+    };
+    use std::io::Write;
+    use std::time::Duration;
+
+    // ESC [ ? 2026 $ p      DECRQM request for synchronized output state
+    // ESC [ c               Query primary device attributes (widely supported)
+    const QUERY: &[u8] = b"\x1B[?2026$p\x1B[c";
+
+    let result = File::open("/dev/tty").and_then(|mut file| {
+        file.write_all(QUERY)?;
+        file.flush()
+    });
+    if result.is_err() {
+        let mut stdout = io::stdout();
+        stdout.write_all(QUERY)?;
+        stdout.flush()?;
+    }
+
+    loop {
+        match poll_internal(
+            Some(Duration::from_millis(2000)),
+            &SynchronizedOutputModeFilter,
+        ) {
+            Ok(true) => match read_internal(&SynchronizedOutputModeFilter) {
+                Ok(InternalEvent::SynchronizedOutputMode(
+                    SynchronizedOutputMode::Set | SynchronizedOutputMode::Reset,
+                )) => {
+                    // Flush the PrimaryDeviceAttributes out of the event queue.
+                    read_internal(&PrimaryDeviceAttributesFilter).ok();
+                    return Ok(true);
+                }
+                _ => return Ok(false),
+            },
+            Ok(false) => {
+                return Err(io::Error::new(
+                    io::ErrorKind::Other,
+                    "Synchronized output mode could not be read in a normal duration",
+                ));
+            }
+            Err(_) => {}
+        }
+    }
+}
+
+#[cfg(feature = "events")]
+fn supports_synchronized_output_nonraw() -> io::Result<bool> {
+    enable_raw_mode()?;
+    let is_supported = supports_synchronized_output_raw();
+    disable_raw_mode()?;
+    is_supported
+}
+
+/// Queries the terminal's support for synchronized output sequences.
+///
+/// On unix systems, this function will block and possibly time out while
+/// [`crossterm::event::read`](crate::event::read) or [`crossterm::event::poll`](crate::event::poll) are being called.
+#[cfg(feature = "events")]
+pub fn supports_synchronized_output() -> io::Result<bool> {
+    if is_raw_mode_enabled() {
+        supports_synchronized_output_raw()
+    } else {
+        supports_synchronized_output_nonraw()
+    }
+}
+
 /// Queries the terminal's support for progressive keyboard enhancement.
 ///
 /// On unix systems, this function will block and possibly time out while

src/terminal/sys/windows.rs

@@ -70,6 +70,14 @@ pub(crate) fn window_size() -> io::Result<WindowSize> {
     ))
 }
 
+/// Queries the terminal's support for synchronized output sequences.
+///
+/// This always returns `Ok(false)` on Windows.
+#[cfg(feature = "events")]
+pub fn supports_synchronized_output() -> io::Result<bool> {
+    Ok(false)
+}
+
 /// Queries the terminal's support for progressive keyboard enhancement.
 ///
 /// This always returns `Ok(false)` on Windows.