refactor: keyboard enhancements api improvements (#1534)
This commit is contained in:
parent
d9f7210a9e
commit
f03c467c1b
5 changed files with 123 additions and 75 deletions
|
|
@ -120,16 +120,11 @@ func (s *cursedRenderer) start() {
|
|||
if s.lastView.ProgressBar != nil {
|
||||
setProgressBar(s, s.lastView.ProgressBar)
|
||||
}
|
||||
if !s.lastView.DisableKeyEnhancements {
|
||||
kittyFlags := ansi.KittyDisambiguateEscapeCodes
|
||||
if s.lastView.KeyReleases {
|
||||
kittyFlags |= ansi.KittyReportEventTypes
|
||||
}
|
||||
if s.lastView.UniformKeyLayout {
|
||||
kittyFlags |= ansi.KittyReportAlternateKeys | ansi.KittyReportAllKeysAsEscapeCodes
|
||||
}
|
||||
_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
|
||||
kittyFlags := ansi.KittyDisambiguateEscapeCodes
|
||||
if s.lastView.KeyboardEnhancements.ReportEventTypes {
|
||||
kittyFlags |= ansi.KittyReportEventTypes
|
||||
}
|
||||
_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
|
||||
}
|
||||
|
||||
// close implements renderer.
|
||||
|
|
@ -193,10 +188,8 @@ func (s *cursedRenderer) close() (err error) {
|
|||
_, _ = s.scr.WriteString(ansi.ResetProgressBar)
|
||||
}
|
||||
|
||||
if s.lastView != nil && !s.lastView.DisableKeyEnhancements {
|
||||
// NOTE: This needs to happen after we exit the alt screen.
|
||||
_, _ = s.scr.WriteString(ansi.KittyKeyboard(0, 1))
|
||||
}
|
||||
// NOTE: This needs to happen after we exit the alt screen.
|
||||
_, _ = s.scr.WriteString(ansi.KittyKeyboard(0, 1))
|
||||
}
|
||||
|
||||
if err := s.scr.Flush(); err != nil {
|
||||
|
|
@ -287,26 +280,16 @@ func (s *cursedRenderer) flush(closing bool) error {
|
|||
}
|
||||
|
||||
// kitty keyboard protocol
|
||||
//nolint:nestif
|
||||
if s.lastView == nil || view.DisableKeyEnhancements != s.lastView.DisableKeyEnhancements ||
|
||||
view.KeyReleases != s.lastView.KeyReleases ||
|
||||
view.UniformKeyLayout != s.lastView.UniformKeyLayout ||
|
||||
if s.lastView == nil || view.KeyboardEnhancements != s.lastView.KeyboardEnhancements ||
|
||||
view.AltScreen != s.lastView.AltScreen {
|
||||
// NOTE: We need to reset the keyboard protocol when switching
|
||||
// between main and alt screen. This is because the specs specify
|
||||
// two different states for the main and alt screen.
|
||||
if view.DisableKeyEnhancements {
|
||||
_, _ = s.scr.WriteString(ansi.KittyKeyboard(0, 1))
|
||||
} else {
|
||||
kittyFlags := ansi.KittyDisambiguateEscapeCodes // always enable basic key disambiguation
|
||||
if view.KeyReleases {
|
||||
kittyFlags |= ansi.KittyReportEventTypes
|
||||
}
|
||||
if view.UniformKeyLayout {
|
||||
kittyFlags |= ansi.KittyReportAlternateKeys | ansi.KittyReportAllKeysAsEscapeCodes
|
||||
}
|
||||
_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
|
||||
kittyFlags := ansi.KittyDisambiguateEscapeCodes // always enable basic key disambiguation
|
||||
if view.KeyboardEnhancements.ReportEventTypes {
|
||||
kittyFlags |= ansi.KittyReportEventTypes
|
||||
}
|
||||
_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
|
||||
if !closing {
|
||||
// Request keyboard enhancements when they change
|
||||
_, _ = s.scr.WriteString(ansi.RequestKittyKeyboard)
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@ type styles struct {
|
|||
}
|
||||
|
||||
type model struct {
|
||||
supportsRelease bool
|
||||
supportsDisambiguation bool
|
||||
supportsEventTypes bool
|
||||
styles styles
|
||||
}
|
||||
|
||||
|
|
@ -28,14 +28,24 @@ func (m model) Init() tea.Cmd {
|
|||
|
||||
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
|
||||
switch msg := msg.(type) {
|
||||
// When tea.RequestKeyboardEnhancements is called, the program will receive
|
||||
// a tea.KeyboardEnhancementsMsg message. This means that an attempt to
|
||||
// enable keyboard enhancements was made, however it doesn't guarantee that
|
||||
// it was successful.
|
||||
// Bubble Tea will send a [tea.KeyboardEnhancementsMsg] on startup if the
|
||||
// terminal supports keyboard enhancements features.
|
||||
//
|
||||
// These features extend the capabilities of keyboard input beyond the basic legacy
|
||||
// support found in most terminals. This includes features like:
|
||||
// - Key disambiguation: Improved ability to distinguish between certain key presses
|
||||
// like "enter" and "shift+enter" or "tab" and "ctrl+i".
|
||||
// - Key event types: The ability to report different types of key events such as
|
||||
// key presses and key releases.
|
||||
//
|
||||
// This allows for more nuanced input handling in terminal applications.
|
||||
// You can ask Bubble Tea to request additional keyboard enhancements
|
||||
// features by setting fields on the [tea.View.KeyboardEnhancements] struct
|
||||
// in your [tea.View] method.
|
||||
case tea.KeyboardEnhancementsMsg:
|
||||
// Check which features were able to be enabled.
|
||||
m.supportsRelease = msg.SupportsKeyReleases()
|
||||
m.supportsDisambiguation = msg.SupportsKeyDisambiguation()
|
||||
m.supportsDisambiguation = true // This is always enabled when this msg is received.
|
||||
m.supportsEventTypes = msg.SupportsEventTypes()
|
||||
|
||||
case tea.KeyPressMsg:
|
||||
switch msg.String() {
|
||||
|
|
@ -58,15 +68,16 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
|
|||
func (m model) View() tea.View {
|
||||
var v tea.View
|
||||
var b strings.Builder
|
||||
fmt.Fprintf(&b, "Terminal supports key releases: %v\n", m.supportsRelease)
|
||||
fmt.Fprintf(&b, "Terminal supports key releases: %v\n", m.supportsEventTypes)
|
||||
fmt.Fprintf(&b, "Terminal supports key disambiguation: %v\n", m.supportsDisambiguation)
|
||||
fmt.Fprint(&b, "This demo logs key events. Press ctrl+c to quit.")
|
||||
v.SetContent(b.String() + "\n")
|
||||
|
||||
// Attempt to enable keyboard enhancements. By default, this just
|
||||
// enables key disabiguation. For key releases, you'll need to opt-in
|
||||
// to that feature.
|
||||
v.KeyReleases = true
|
||||
// Attempt to enable reporting key event types (key presses and key
|
||||
// releases). By default, only key disambiguation is enabled which improves
|
||||
// the ability to distinguish between certain key presses like "enter" and
|
||||
// "shift+enter" or "tab" and "ctrl+i".
|
||||
v.KeyboardEnhancements.ReportEventTypes = true
|
||||
|
||||
return v
|
||||
}
|
||||
|
|
|
|||
|
|
@ -15,10 +15,8 @@ func (m model) Init() tea.Cmd {
|
|||
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
|
||||
switch msg := msg.(type) {
|
||||
case tea.KeyboardEnhancementsMsg:
|
||||
return m, tea.Printf("Keyboard enhancements: Disambiguation: %v, ReleaseKeys: %v, Uniform keys: %v\n",
|
||||
msg.SupportsKeyDisambiguation(),
|
||||
msg.SupportsKeyReleases(),
|
||||
msg.SupportsUniformKeyLayout())
|
||||
return m, tea.Printf("Keyboard enhancements: EventTypes: %v\n",
|
||||
msg.SupportsEventTypes())
|
||||
case tea.KeyMsg:
|
||||
key := msg.Key()
|
||||
switch msg := msg.(type) {
|
||||
|
|
@ -41,8 +39,7 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
|
|||
|
||||
func (m model) View() tea.View {
|
||||
v := tea.NewView("Press any key to see its details printed to the terminal. Press 'ctrl+c' to quit.")
|
||||
v.KeyReleases = true
|
||||
v.UniformKeyLayout = true
|
||||
v.KeyboardEnhancements.ReportEventTypes = true
|
||||
return v
|
||||
}
|
||||
|
||||
|
|
|
|||
36
keyboard.go
36
keyboard.go
|
|
@ -7,25 +7,27 @@ import (
|
|||
// KeyboardEnhancementsMsg is a message that gets sent when the terminal
|
||||
// supports keyboard enhancements.
|
||||
type KeyboardEnhancementsMsg struct {
|
||||
// Flags is a bitmask of supported keyboard enhancement features.
|
||||
// See [ansi.KittyReportEventTypes] and other constants for details.
|
||||
//
|
||||
// Example:
|
||||
//
|
||||
// ```go
|
||||
// // The hard way
|
||||
// if msg.Flags&ansi.KittyReportEventTypes != 0 {
|
||||
// // Terminal supports reporting different key event types
|
||||
// }
|
||||
//
|
||||
// // The easy way
|
||||
// if msg.SupportsEventTypes() {
|
||||
// // Terminal supports reporting different key event types
|
||||
// }
|
||||
// ```
|
||||
Flags int
|
||||
}
|
||||
|
||||
// SupportsKeyDisambiguation returns whether the terminal supports reporting
|
||||
// disambiguous keys as escape codes.
|
||||
func (k KeyboardEnhancementsMsg) SupportsKeyDisambiguation() bool {
|
||||
return k.Flags&ansi.KittyDisambiguateEscapeCodes != 0
|
||||
}
|
||||
|
||||
// SupportsKeyReleases returns whether the terminal supports key release
|
||||
// events.
|
||||
func (k KeyboardEnhancementsMsg) SupportsKeyReleases() bool {
|
||||
// SupportsEventTypes returns whether the terminal supports reporting
|
||||
// different types of key events (press, release, and repeat).
|
||||
func (k KeyboardEnhancementsMsg) SupportsEventTypes() bool {
|
||||
return k.Flags&ansi.KittyReportEventTypes != 0
|
||||
}
|
||||
|
||||
// SupportsUniformKeyLayout returns whether the terminal supports reporting key
|
||||
// events as though they were on a PC-101 layout.
|
||||
func (k KeyboardEnhancementsMsg) SupportsUniformKeyLayout() bool {
|
||||
return k.SupportsKeyDisambiguation() &&
|
||||
k.Flags&ansi.KittyReportAlternateKeys != 0 &&
|
||||
k.Flags&ansi.KittyReportAllKeysAsEscapeCodes != 0
|
||||
}
|
||||
|
|
|
|||
79
tea.go
79
tea.go
|
|
@ -168,20 +168,75 @@ type View struct {
|
|||
// [MouseModeNone], [MouseModeCellMotion], or [MouseModeAllMotion].
|
||||
MouseMode MouseMode
|
||||
|
||||
// DisableKeyEnhancements disables all key enhancements for this view.
|
||||
DisableKeyEnhancements bool
|
||||
// KeyboardEnhancements describes what keyboard enhancement features Bubble
|
||||
// Tea should request from the terminal.
|
||||
//
|
||||
// Bubble Tea supports requesting the following keyboard enhancement features:
|
||||
// - ReportEventTypes: requests the terminal to report key repeat and
|
||||
// release events.
|
||||
//
|
||||
// If the terminal supports any of these features, your program will
|
||||
// receive a [KeyboardEnhancementsMsg] that indicates which features are
|
||||
// available.
|
||||
KeyboardEnhancements KeyboardEnhancements
|
||||
}
|
||||
|
||||
// KeyReleases enables support for reporting key release events. This is
|
||||
// useful for terminals that support the Kitty keyboard protocol "Report
|
||||
// event types" progressive enhancement feature.
|
||||
KeyReleases bool
|
||||
// KeyboardEnhancements describes the requested keyboard enhancement features.
|
||||
// If the terminal supports any of them, it will respond with a
|
||||
// [KeyboardEnhancementsMsg] that indicates which features are supported.
|
||||
|
||||
// UniformKeyLayout enables support for reporting key events as though they
|
||||
// were on a PC-101 layout. This is useful for uniform key event reporting
|
||||
// across different keyboard layouts. This is equivalent to the Kitty
|
||||
// keyboard protocol "Report alternate keys" and "Report all keys as escape
|
||||
// codes" progressive enhancement features.
|
||||
UniformKeyLayout bool
|
||||
// KeyboardEnhancements defines different keyboard enhancement features that
|
||||
// can be requested from the terminal.
|
||||
|
||||
// KeyboardEnhancements defines different keyboard enhancement features that
|
||||
// can be requested from the terminal.
|
||||
//
|
||||
// By default, Bubble Tea requests basic key disambiguation features from the
|
||||
// terminal. If the terminal supports keyboard enhancements, or any of its
|
||||
// additional features, it will respond with a [KeyboardEnhancementsMsg] that
|
||||
// indicates which features are supported.
|
||||
//
|
||||
// Example:
|
||||
//
|
||||
// ```go
|
||||
// func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
|
||||
// switch msg := msg.(type) {
|
||||
// case tea.KeyboardEnhancementsMsg:
|
||||
// // We have basic key disambiguation support.
|
||||
// // We can handle "shift+enter", "ctrl+i", etc.
|
||||
// m.keyboardEnhancements = msg
|
||||
// if msg.ReportEventTypes {
|
||||
// // Even better! We can now handle key repeat and release events.
|
||||
// }
|
||||
// case tea.KeyPressMsg:
|
||||
// switch msg.String() {
|
||||
// case "shift+enter":
|
||||
// // Handle shift+enter
|
||||
// // This would not be possible without keyboard enhancements.
|
||||
// case "ctrl+j":
|
||||
// // Handle ctrl+j
|
||||
// }
|
||||
// case tea.KeyReleaseMsg:
|
||||
// // Whoa! A key was released!
|
||||
// }
|
||||
//
|
||||
// return m, nil
|
||||
// }
|
||||
//
|
||||
// func (m model) View() tea.View {
|
||||
// v := tea.NewView("Press some keys!")
|
||||
// // Request reporting key repeat and release events.
|
||||
// v.KeyboardEnhancements.ReportEventTypes = true
|
||||
// return v
|
||||
// }
|
||||
// ```
|
||||
type KeyboardEnhancements struct {
|
||||
// ReportEventTypes requests the terminal to report key repeat and release
|
||||
// events.
|
||||
// If supported, your program will receive [KeyReleaseMsg]s and
|
||||
// [KeyPressMsg] with the [Key.IsRepeat] field set indicating that this is
|
||||
// a it's part of a key repeat sequence.
|
||||
ReportEventTypes bool
|
||||
}
|
||||
|
||||
// SetContent sets the content of the view to the value.
|
||||
|
|
|
|||
Loading…
Reference in a new issue