key

Documentation

Overview

Package key provides some types and functions for generating user-definable keymappings useful in Bubble Tea components. There are a few different ways you can define a keymapping with this package. Here's one example:

type KeyMap struct {
    Up key.Binding
    Down key.Binding
}

var DefaultKeyMap = KeyMap{
    Up: key.NewBinding(
        key.WithKeys("k", "up"),        // actual keybindings
        key.WithHelp("↑/k", "move up"), // corresponding help text
    ),
    Down: key.NewBinding(
        key.WithKeys("j", "down"),
        key.WithHelp("↓/j", "move down"),
    ),
}

func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        switch {
        case key.Matches(msg, DefaultKeyMap.Up):
            // The user pressed up
        case key.Matches(msg, DefaultKeyMap.Down):
            // The user pressed down
        }
    }

    // ...
}

The help information, which is not used in the example above, can be used to render help text for keystrokes in your views.

Index

• func Matches[Key fmt.Stringer](k Key, b ...Binding) bool
• type Binding
  • func NewBinding(opts ...BindingOpt) Binding
  • func (b Binding) Enabled() bool
  • func (b Binding) Help() Help
  • func (b Binding) Keys() []string
  • func (b *Binding) SetEnabled(v bool)
  • func (b *Binding) SetHelp(key, desc string)
  • func (b *Binding) SetKeys(keys ...string)
  • func (b *Binding) Unbind()
• type BindingOpt
  • func WithDisabled() BindingOpt
  • func WithHelp(key, desc string) BindingOpt
  • func WithKeys(keys ...string) BindingOpt
• type Help

Functions

func Matches

func Matches[Key fmt.Stringer](k Key, b ...Binding) bool

Matches checks if the given key matches the given bindings.

Types

type Binding

type Binding struct {
	// contains filtered or unexported fields
}

Binding describes a set of keybindings and, optionally, their associated help text.

func NewBinding

func NewBinding(opts ...BindingOpt) Binding

NewBinding returns a new keybinding from a set of BindingOpt options.

func (Binding) Enabled

func (b Binding) Enabled() bool

Enabled returns whether or not the keybinding is enabled. Disabled keybindings won't be activated and won't show up in help. Keybindings are enabled by default.

func (Binding) Help

func (b Binding) Help() Help

Help returns the Help information for the keybinding.

func (Binding) Keys

func (b Binding) Keys() []string

Keys returns the keys for the keybinding.

func (*Binding) SetEnabled

func (b *Binding) SetEnabled(v bool)

SetEnabled enables or disables the keybinding.

func (*Binding) SetHelp

func (b *Binding) SetHelp(key, desc string)

SetHelp sets the help text for the keybinding.

func (*Binding) SetKeys

func (b *Binding) SetKeys(keys ...string)

SetKeys sets the keys for the keybinding.

func (*Binding) Unbind

func (b *Binding) Unbind()

Unbind removes the keys and help from this binding, effectively nullifying it. This is a step beyond disabling it, since applications can enable or disable key bindings based on application state.

type BindingOpt

type BindingOpt func(*Binding)

BindingOpt is an initialization option for a keybinding. It's used as an argument to NewBinding.

func WithDisabled

func WithDisabled() BindingOpt

WithDisabled initializes a disabled keybinding.

func WithHelp

func WithHelp(key, desc string) BindingOpt

WithHelp initializes a keybinding with the given help text.

func WithKeys

func WithKeys(keys ...string) BindingOpt

WithKeys initializes a keybinding with the given keystrokes.

type Help

type Help struct {
	Key  string
	Desc string
}

Help is help information for a given keybinding.