implement legacy console API

Author: aschey

.github/workflows/ci.yml

@@ -3,7 +3,7 @@ on:
   pull_request:
   push:
 env:
-  MSRV: "1.70"
+  MSRV: "1.71"
 jobs:
   check:
     name: Check

Cargo.lock

@@ -7,11 +7,15 @@ readme = "README.md"
 repository = "https://github.com/helix-editor/termina"
 edition = "2021"
 license = "MIT OR MPL-2.0"
-rust-version = "1.70"
+rust-version = "1.71"
 
 [features]
 default = []
 event-stream = ["dep:futures-core"]
+windows-legacy = [
+  "windows-sys/Win32_UI_Input_KeyboardAndMouse",
+  "windows-sys/Win32_UI_WindowsAndMessaging",
+]
 
 [dependencies]
 parking_lot = "0.12"
@@ -33,7 +37,7 @@ features = [
 
 [target.'cfg(windows)'.dependencies.windows-sys]
 # TODO: this could probably be loosened.
-version = ">=0.59"
+version = ">=0.60"
 default-features = false
 # https://microsoft.github.io/windows-rs/features/#/0.59.0/search
 features = [
@@ -46,3 +50,7 @@ features = [
   "Win32_System_Threading",
   "Win32_Security",
 ]
+
+[[example]]
+name = "event-read"
+required-features = ["windows-legacy"]

Cargo.toml

@@ -5,10 +5,28 @@
 
 A cross-platform "virtual terminal" (VT) manipulation library.
 
-Termina only "speaks text/VT" but aims to work on Windows as well as *NIX. This is made possible by Microsoft's investment into [ConPTY](https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/). This means that Termina requires 64-bit Windows 10.0.17763 (released around Fall 2018) or later ([same as WezTerm](https://wezterm.org/install/windows.html)).
+Termina works on Windows as well as *NIX, but Windows requires some extra thought to choose the preferred way of handling input.
 
 Termina is a cross between [Crossterm](https://github.com/crossterm-rs/crossterm) and [TermWiz](https://github.com/wezterm/wezterm/blob/a87358516004a652ad840bc1661bdf65ffc89b43/termwiz/README.md) with a lower level API which exposes escape codes to consuming applications. The aim is to scale well in the long run as terminals introduce VT extensions like the [Kitty Keyboard Protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) or [Contour's Dark/Light mode detection](https://contour-terminal.org/vt-extensions/color-palette-update-notifications/) - requiring minimal changes in Termina and also allowing flexibility in how applications detect and handle these extensions. See `examples/event-read.rs` for a look at a basic API.
 
+## Input handling on Windows
+
+Termina is able to "speak text/VT" on Windows. This is made possible by Microsoft's investment into [ConPTY](https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/). This means that this input mode requires 64-bit Windows 10.0.17763 (released around Fall 2018) or later ([same as WezTerm](https://wezterm.org/install/windows.html)). However, using VT mode on Windows
+means the terminal you use needs to support the Kitty Keyboard Protocol in order to handle some complex key combinations.
+Windows Terminal, notably, does not implement this protocol. However, using the VT protocol allows for some newer features to work, such as bracketed paste.
+This means there is no single answer for which protocol to use - it depends on your use case.
+
+See feature comparison below.
+
+|                                                              | VTE Mode                                                  | Legacy Console Mode |
+| ------------------------------------------------------------ | --------------------------------------------------------- | ------------------- |
+| **Kitty Keyboard Protocol**                                  | ✓                                                         | ✕                   |
+| **Extended key events**                                      | terminal-dependent (must support Kitty Keyboard Protocol) | ✓                   |
+| **Bracketed paste**                                          | ✓                                                         | ✕                   |
+| **[AltGr](https://en.wikipedia.org/wiki/AltGr_key) Support** | ✓                                                         | ✕                   |
+
+The legacy input reader can be used by enabling the `windows-legacy` feature. See the `event-read` example for usage.
+
 ## Credit
 
 Termina contains significant code sourced and/or modified from other projects, especially Crossterm and TermWiz. See "CREDIT" comments in the source for details on what was copied and what modifications were made. Since all copied code is licensed under MIT, Termina is offered under the MIT license as well at your option.

README.md

@@ -2,10 +2,13 @@
 // modifications to adapt to the termina API.
 // <https://github.com/crossterm-rs/crossterm/blob/36d95b26a26e64b0f8c12edfe11f410a6d56a812/examples/event-read.rs>
 use std::{
+    env,
     io::{self, Write as _},
     time::Duration,
 };
 
+#[cfg(windows)]
+use termina::windows;
 use termina::{
     escape::csi::{self, KittyKeyboardFlags},
     event::{KeyCode, KeyEvent},
@@ -36,16 +39,36 @@ macro_rules! decreset {
 fn main() -> io::Result<()> {
     println!("{HELP}");
 
+    let args: Vec<_> = env::args().collect();
+    let windows_legacy = cfg!(windows) && args.iter().any(|a| a == "--windows-legacy");
+
+    #[cfg(windows)]
+    let mut terminal = PlatformTerminal::with_mode(if windows_legacy {
+        windows::InputReaderMode::Legacy
+    } else {
+        windows::InputReaderMode::Vte
+    })?;
+    #[cfg(not(windows))]
     let mut terminal = PlatformTerminal::new()?;
+
     terminal.enter_raw_mode()?;
 
+    let keyboard_flags = if windows_legacy {
+        // Enabling the kitty keyboard protocol in a supported terminal
+        // while using the legacy console API will result in incorrect key codes
+        // for some key combinations.
+        "".to_string()
+    } else {
+        csi::Csi::Keyboard(csi::Keyboard::PushFlags(
+            KittyKeyboardFlags::DISAMBIGUATE_ESCAPE_CODES
+                | KittyKeyboardFlags::REPORT_ALTERNATE_KEYS,
+        ))
+        .to_string()
+    };
     write!(
         terminal,
         "{}{}{}{}{}{}{}{}",
-        csi::Csi::Keyboard(csi::Keyboard::PushFlags(
-            KittyKeyboardFlags::DISAMBIGUATE_ESCAPE_CODES
-                | KittyKeyboardFlags::REPORT_ALTERNATE_KEYS
-        )),
+        keyboard_flags,
         decset!(FocusTracking),
         decset!(BracketedPaste),
         decset!(MouseTracking),
@@ -71,32 +94,43 @@ fn main() -> io::Result<()> {
                 code: KeyCode::Char('c'),
                 ..
             }) => {
-                write!(
-                    terminal,
-                    "{}",
-                    csi::Csi::Cursor(csi::Cursor::RequestActivePositionReport),
-                )?;
-                terminal.flush()?;
-                let filter = |event: &Event| {
-                    matches!(
-                        event,
-                        Event::Csi(csi::Csi::Cursor(csi::Cursor::ActivePositionReport { .. }))
-                    )
-                };
-                if terminal.poll(filter, Some(Duration::from_millis(50)))? {
-                    let Event::Csi(csi::Csi::Cursor(csi::Cursor::ActivePositionReport {
-                        line,
-                        col,
-                    })) = terminal.read(filter)?
-                    else {
-                        unreachable!()
-                    };
-                    println!(
-                        "Cursor position: {:?}\r",
-                        (line.get_zero_based(), col.get_zero_based())
-                    );
+                if windows_legacy {
+                    #[cfg(windows)]
+                    {
+                        let (line, col) = termina::windows::cursor_position()?;
+                        println!(
+                            "Cursor position: {:?}\r",
+                            (line.get_zero_based(), col.get_zero_based())
+                        );
+                    }
                 } else {
-                    eprintln!("Failed to read the cursor position within 50msec\r");
+                    write!(
+                        terminal,
+                        "{}",
+                        csi::Csi::Cursor(csi::Cursor::RequestActivePositionReport),
+                    )?;
+                    terminal.flush()?;
+                    let filter = |event: &Event| {
+                        matches!(
+                            event,
+                            Event::Csi(csi::Csi::Cursor(csi::Cursor::ActivePositionReport { .. }))
+                        )
+                    };
+                    if terminal.poll(filter, Some(Duration::from_millis(50)))? {
+                        let Event::Csi(csi::Csi::Cursor(csi::Cursor::ActivePositionReport {
+                            line,
+                            col,
+                        })) = terminal.read(filter)?
+                        else {
+                            unreachable!()
+                        };
+                        println!(
+                            "Cursor position: {:?}\r",
+                            (line.get_zero_based(), col.get_zero_based())
+                        );
+                    } else {
+                        eprintln!("Failed to read the cursor position within 50msec\r");
+                    }
                 }
             }
             Event::WindowResized(dimensions) => {
@@ -108,10 +142,15 @@ fn main() -> io::Result<()> {
         }
     }
 
+    let keyboard_flags = if windows_legacy {
+        "".to_string()
+    } else {
+        csi::Csi::Keyboard(csi::Keyboard::PopFlags(1)).to_string()
+    };
     write!(
         terminal,
         "{}{}{}{}{}{}{}{}",
-        csi::Csi::Keyboard(csi::Keyboard::PopFlags(1)),
+        keyboard_flags,
         decreset!(FocusTracking),
         decreset!(BracketedPaste),
         decreset!(MouseTracking),

examples/event-read.rs

@@ -7,7 +7,7 @@ use std::{io, os::windows::prelude::*, ptr, sync::Arc, time::Duration};
 
 use windows_sys::Win32::System::Threading;
 
-use crate::{event::Event, parse::Parser, terminal::InputHandle};
+use crate::{event::Event, parse::Parser, terminal::InputHandle, windows::InputReaderMode};
 
 use super::{EventSource, PollTimeout};
 
@@ -19,10 +19,10 @@ pub struct WindowsEventSource {
 }
 
 impl WindowsEventSource {
-    pub(crate) fn new(input: InputHandle) -> io::Result<Self> {
+    pub(crate) fn new(input: InputHandle, mode: InputReaderMode) -> io::Result<Self> {
         Ok(Self {
             input,
-            parser: Parser::default(),
+            parser: Parser::with_mode(mode),
             waker: Arc::new(EventHandle::new()?),
         })
     }

src/event/source/windows.rs

@@ -8,7 +8,10 @@ mod terminal;
 use std::{fmt, num::NonZeroU16};
 
 pub use event::{reader::EventReader, Event};
+#[cfg(windows)]
+pub use parse::windows;
 pub use parse::Parser;
+
 pub use terminal::{PlatformHandle, PlatformTerminal, Terminal};
 
 #[cfg(feature = "event-stream")]