uncurses/event/decode/
flags.rs

1//! Decoder behavior flags for ambiguous legacy input bytes.
2//!
3//! ## Purpose
4//!
5//! [`DecoderFlags`] toggles byte sequences that have more than one historical
6//! interpretation when the terminal is not using an unambiguous keyboard
7//! protocol. With no flags set, the decoder favors semantic keys such as Tab,
8//! Enter, Escape, Backspace, Home, and End.
9//!
10//! ## Affected paths
11//!
12//! The flags affect C0 controls, a timed-out lone `ESC`, Delete/Backspace, and
13//! VT220 Find/Select tilde codes. They do not change richer keyboard encodings
14//! that carry explicit key identity.
15//!
16//! ## Gotchas
17//!
18//! These flags select legacy key interpretations. Choose them to match the
19//! bindings your application exposes. Backarrow mode supplies the baseline;
20//! the flags select explicit overrides.
21use bitflags::bitflags;
22
23bitflags! {
24    /// Optional disambiguation knobs for the input decoder.
25    ///
26    /// With no flag set and Backarrow mode reset, the decoder reports:
27    ///
28    /// * `0x00` → `Ctrl+Space`
29    /// * `0x08` → `Ctrl+h`
30    /// * `0x09` → `Tab`
31    /// * `0x0a` → `Ctrl+j`
32    /// * `0x0d` → `Enter`
33    /// * `0x7f` → `Backspace`
34    /// * `CSI 1 ~` → `Home`
35    /// * `CSI 4 ~` → `End`
36    ///
37    /// Set the corresponding flag to swap each mapping to its alternative
38    /// reading.
39    ///
40    /// In raw mode, terminals normally send LF for Ctrl+J and CR for Enter.
41    /// An `ESC` prefix adds Alt to the selected interpretation.
42    ///
43    /// Backarrow mode (DECBKM) defaults to reset. When set, `0x08` reads as
44    /// Backspace and `0x7f` as Ctrl+Backspace. These are legacy byte
45    /// interpretations: terminals can send the same bytes for different keys.
46    ///
47    /// [`CTRL_H`](Self::CTRL_H) overrides `0x08` in either mode and takes
48    /// precedence over [`CTRL_BACKSPACE`](Self::CTRL_BACKSPACE).
49    /// [`DEL_IS_DELETE`](Self::DEL_IS_DELETE) overrides `0x7f` in either mode.
50    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
51    pub struct DecoderFlags: u16 {
52        /// Report `0x00` as `Ctrl+@` instead of `Ctrl+Space`.
53        const CTRL_AT             = 1 << 0;
54        /// Report `0x09` as `Ctrl+i` instead of `Tab`.
55        const CTRL_I              = 1 << 1;
56        /// Report `0x0d` as `Ctrl+m` instead of `Enter`.
57        const CTRL_M              = 1 << 2;
58        /// Report a lone `0x1b` as `Ctrl+[` instead of `Escape`.
59        ///
60        /// Wherever that byte resolves as a key of its own: an
61        /// [`EventSource`](crate::event::EventSource) reaching its escape
62        /// deadline, whether the `ESC` was alone or at the head of a
63        /// sequence that never finished, and the inner `ESC` of a run of
64        /// them, which reads as `Alt+Ctrl+[`.
65        const CTRL_OPEN_BRACKET   = 1 << 3;
66        /// Report `0x7f` as `Delete` instead of `Backspace`.
67        ///
68        /// Takes precedence over Backarrow mode, including when `0x7f`
69        /// would otherwise read as Ctrl+Backspace.
70        const DEL_IS_DELETE       = 1 << 4;
71        /// Report `CSI 1 ~` as the VT220 `Find` key instead of `Home`.
72        const FIND_KEY            = 1 << 5;
73        /// Report `CSI 4 ~` as the VT220 `Select` key instead of `End`.
74        const SELECT_KEY          = 1 << 6;
75        /// Report `0x0a` (LF) as `Enter` instead of `Ctrl+j`.
76        ///
77        /// An `ESC` prefix reports `Alt+Enter`. This is useful for input
78        /// with CR-to-LF conversion enabled. CR keeps its own interpretation,
79        /// selected by [`CTRL_M`](Self::CTRL_M).
80        const LF_IS_ENTER         = 1 << 7;
81        /// Report `0x08` as `Ctrl+h` in either Backarrow mode.
82        ///
83        /// Takes precedence over [`CTRL_BACKSPACE`](Self::CTRL_BACKSPACE)
84        /// and the mode's Backspace interpretation.
85        const CTRL_H              = 1 << 8;
86        /// Report `0x08` as Ctrl+Backspace when Backarrow mode is reset.
87        ///
88        /// When the mode is set, `0x08` reads as Backspace and `0x7f`
89        /// already reads as Ctrl+Backspace. [`CTRL_H`](Self::CTRL_H) and
90        /// [`DEL_IS_DELETE`](Self::DEL_IS_DELETE) retain their precedence.
91        const CTRL_BACKSPACE      = 1 << 9;
92    }
93}
uncurses/event/decode/flags.rs

uncurses/event/decode/
flags.rs
