Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

(v2) keyboard docs #1169

Open
wants to merge 1 commit into
base: v2-exp
Choose a base branch
from
Open

(v2) keyboard docs #1169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 37 additions & 3 deletions keyboard.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,25 @@ func withKeyDisambiguation(k *keyboardEnhancements) {

type enableKeyboardEnhancementsMsg []KeyboardEnhancement

// EnableKeyboardEnhancements is a command that enables keyboard enhancements
// in the terminal.
// EnableKeyboardEnhancements is a [Cmd] for enables keyboard enhancements, in
// supporting terminals. By default, keyboard enhancements do a couple things:
//
// - It enables you to match all modifier keys such as super.
// - It enables you to match all keys that are ambiguous such as ctrl+i,
// which normally would be indistinguishable from tab.
//
// You can also enable specific enhancements, such as key releases, by passing
// them as arguments to the command:
//
// cmd := EnableKeyboardEnhancements(WithKeyReleases)
//
// For available enhancements options see [KeyboardEnhancement].
//
// Note that not all terminals support these features. You can check if the
// terminal supports these features by matching on the
// [KeyboardEnhancementsMsg] message.
//
// This feature is enabled by default on Windows.
func EnableKeyboardEnhancements(enhancements ...KeyboardEnhancement) Cmd {
return func() Msg {
return enableKeyboardEnhancementsMsg(append(enhancements, withKeyDisambiguation))
Expand All @@ -80,7 +97,24 @@ func DisableKeyboardEnhancements() Msg {
}

// KeyboardEnhancementsMsg is a message that gets sent when the terminal
// supports keyboard enhancements.
// supports keyboard enhancements. For some background on what this does, see
// the [EnableKeyboardEnhancements] command.
//
// Keyboard enhancements can be enabled when constructing a [Program] by using
// the [WithKeyboardEnhancements] option:
//
// p := tea.NewProgram(initialModel, tea.WithKeyboardEnhancements())
//
// Or with the [EnableKeyboardEnhancements] command:
//
// cmd := EnableKeyboardEnhancements()
//
// You can also enable specific enhancements by passing them as arguments to
// the [EnableKeyboardEnhancements] command:
//
// cmd := EnableKeyboardEnhancements(WithKeyReleases, WithKeyDisambiguation)
//
// For available enhancements options see [KeyboardEnhancement].
type KeyboardEnhancementsMsg keyboardEnhancements

// SupportsKeyDisambiguation returns whether the terminal supports reporting
Expand Down
24 changes: 19 additions & 5 deletions options.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,12 +251,26 @@ func WithReportFocus() ProgramOption {
}
}

// WithKeyboardEnhancements enables support for enhanced keyboard features. You
// can enable different keyboard features by passing one or more
// KeyboardEnhancement functions.
// WithKeyboardEnhancements is a program option that enables higher fidelity
// keyboard input, in supporting terminals. By default, this means a couple
// things:
//
// This is not supported on all terminals. On Windows, these features are
// enabled by default.
// - It enables you to match all modifier keys such as super.
// - It enables you to match all keys that are ambiguous such as ctrl+i,
// which normally would be indistinguishable from tab.
//
// You can also enable specific enhancements, such as key releases, by passing
// them as arguments to the command:
//
// cmd := EnableKeyboardEnhancements(WithKeyReleases)
//
// For available enhancements options see [KeyboardEnhancement].
//
// Note that not all terminals support these features. You can check if the
// terminal supports these features by matching on the
// [KeyboardEnhancementsMsg] message.
//
// This feature is enabled by default on Windows.
func WithKeyboardEnhancements(enhancements ...KeyboardEnhancement) ProgramOption {
var ke keyboardEnhancements
for _, e := range append(enhancements, withKeyDisambiguation) {
Expand Down
Loading