keybind

package
v0.6.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 22, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package keybind provides key binding and command routing helpers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CommandShortcuts 

func CommandShortcuts(keymaps ...*Keymap) map[string][]Key

CommandShortcuts builds a map of command IDs to key sequences.

func FormatChord 

func FormatChord(chord string) string

FormatChord formats a chord description string (e.g. "ctrl+k ctrl+c") into a display string (e.g. "Ctrl+K Ctrl+C").

func FormatKey 

func FormatKey(key terminal.KeyEvent) string

FormatKey formats a terminal.KeyEvent as a human-readable string like "Ctrl+K".

func FormatKeyPress 

func FormatKeyPress(press KeyPress) string

FormatKeyPress formats a single key press for display.

func FormatKeySequence 

func FormatKeySequence(key Key) string

FormatKeySequence formats a key sequence for display.

func FormatKeySequences 

func FormatKeySequences(keys []Key) string

FormatKeySequences formats multiple key sequences for display.

func ParseKey 

func ParseKey(desc string) (terminal.KeyEvent, error)

ParseKey parses a key description like "ctrl+k", "shift+enter", "alt+a", "F5" into a terminal.KeyEvent.

func RegisterClipboardCommands 

func RegisterClipboardCommands(registry *CommandRegistry)

RegisterClipboardCommands registers clipboard commands for focused widgets.

func RegisterScrollCommands 

func RegisterScrollCommands(registry *CommandRegistry)

RegisterScrollCommands registers scroll commands for focused widgets.

func RegisterStandardCommands 

func RegisterStandardCommands(registry *CommandRegistry)

RegisterStandardCommands registers common runtime commands.

Types

type Binding 

type Binding struct {
	Key     Key
	Command string
	When    Condition
}

Binding maps a key sequence to a command.

type Chord 

type Chord []terminal.KeyEvent

Chord represents a multi-key sequence (e.g., Ctrl+K followed by Ctrl+C).

type ChordHandler 

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

ChordHandler manages multi-key chord recognition. It maintains a set of chord bindings and tracks pending key presses, applying a configurable timeout between keys.

func NewChordHandler 

func NewChordHandler() *ChordHandler

NewChordHandler creates a ChordHandler with default settings.

func (*ChordHandler) Bind 

func (h *ChordHandler) Bind(chord string, action func())

Bind registers a chord sequence to an action. The chord format uses space-separated key descriptions, e.g. "ctrl+k ctrl+c".

func (*ChordHandler) HandleKey 

func (h *ChordHandler) HandleKey(key terminal.KeyEvent) ChordState

HandleKey processes a key event. It returns the chord state:

  • ChordIdle if the key does not match any chord or prefix
  • ChordPending if the key extends a partial chord match
  • ChordCompleted if the key completed a chord (action was invoked)

func (*ChordHandler) PendingKeys 

func (h *ChordHandler) PendingKeys() string

PendingKeys returns the current pending key sequence as a display string, or an empty string if no chord is in progress.

func (*ChordHandler) Reset 

func (h *ChordHandler) Reset()

Reset clears any pending chord sequence.

func (*ChordHandler) SetTimeout 

func (h *ChordHandler) SetTimeout(d time.Duration)

SetTimeout sets the maximum time between chord key presses.

func (*ChordHandler) Unbind 

func (h *ChordHandler) Unbind(chord string)

Unbind removes a chord binding.

type ChordState 

type ChordState int

ChordState indicates the current state of chord recognition. 

const (
	// ChordIdle means no chord is in progress.
	ChordIdle ChordState = iota
	// ChordPending means a partial chord prefix has been recognized.
	ChordPending
	// ChordCompleted means a chord was fully matched and its action was invoked.
	ChordCompleted
)

type Command 

type Command struct {
	ID          string
	Title       string
	Description string
	Category    string
	Handler     func(ctx Context)
	Enabled     func(ctx Context) bool
}

Command represents a named action.

type CommandRegistry 

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

CommandRegistry stores registered commands.

func NewRegistry 

func NewRegistry() *CommandRegistry

NewRegistry returns an empty registry.

func (*CommandRegistry) Execute 

func (r *CommandRegistry) Execute(id string, ctx Context) bool

Execute runs a command if registered and enabled.

func (*CommandRegistry) Get 

func (r *CommandRegistry) Get(id string) (Command, bool)

Get returns a command by ID.

func (*CommandRegistry) List 

func (r *CommandRegistry) List() []Command

List returns registered commands.

func (*CommandRegistry) Register 

func (r *CommandRegistry) Register(cmd Command)

Register registers or replaces a command.

func (*CommandRegistry) RegisterAll 

func (r *CommandRegistry) RegisterAll(cmds ...Command)

RegisterAll registers multiple commands.

type Condition 

type Condition func(ctx Context) bool

Condition gates a binding based on runtime context.

func All 

func All(conditions ...Condition) Condition

All combines conditions with logical AND.

func Any 

func Any(conditions ...Condition) Condition

Any combines conditions with logical OR.

func Not 

func Not(condition Condition) Condition

Not negates a condition.

func WhenFocused 

func WhenFocused() Condition

WhenFocused returns true when a widget is focused.

func WhenFocusedAccessible 

func WhenFocusedAccessible(fn func(accessibility.Accessible) bool) Condition

WhenFocusedAccessible checks a predicate against the focused accessible widget.

func WhenFocusedClipboardTarget 

func WhenFocusedClipboardTarget() Condition

WhenFocusedClipboardTarget matches widgets that support clipboard operations.

func WhenFocusedNotClipboardTarget 

func WhenFocusedNotClipboardTarget() Condition

WhenFocusedNotClipboardTarget matches widgets that do not support clipboard operations.

func WhenFocusedRole 

func WhenFocusedRole(role accessibility.Role) Condition

WhenFocusedRole matches a specific accessibility role.

func WhenFocusedWidget 

func WhenFocusedWidget(fn func(runtime.Widget) bool) Condition

WhenFocusedWidget checks a predicate against the focused widget.

type Context 

type Context struct {
	FocusedWidget accessibility.Accessible
	Focused       runtime.Widget
	Keymap        *Keymap
	App           *runtime.App
}

Context provides data for key binding conditions and handlers.

type Handler 

type Handler interface {
	Keymap() *Keymap
}

Handler exposes a keymap for widgets.

type HandlerBase 

type HandlerBase struct {
	Map *Keymap
}

HandlerBase provides a simple keymap implementation.

func (*HandlerBase) Keymap 

func (h *HandlerBase) Keymap() *Keymap

Keymap returns the bound keymap.

type Key 

type Key struct {
	Sequence []KeyPress
}

Key describes a key sequence (single key or chord).

func MustParseKeySequence 

func MustParseKeySequence(input string) Key

MustParseKeySequence parses a key sequence and returns an empty Key on error.

func ParseKeySequence 

func ParseKeySequence(input string) (Key, error)

ParseKeySequence parses a key sequence like "ctrl+s" or "g g".

func (Key) HasPrefix 

func (k Key) HasPrefix(seq []KeyPress) bool

HasPrefix reports whether seq is a prefix of this key sequence.

func (Key) Matches 

func (k Key) Matches(seq []KeyPress) bool

Matches reports whether the sequence matches exactly.

func (Key) String 

func (k Key) String() string

String returns a formatted key sequence.

type KeyPress 

type KeyPress struct {
	Key   terminal.Key
	Rune  rune
	Alt   bool
	Ctrl  bool
	Shift bool
}

KeyPress represents a normalized key press.

func KeyPressFromKeyMsg 

func KeyPressFromKeyMsg(msg runtime.KeyMsg) KeyPress

KeyPressFromKeyMsg normalizes a runtime key message.

func KeyPressFromTerminal 

func KeyPressFromTerminal(event terminal.KeyEvent) KeyPress

KeyPressFromTerminal normalizes a terminal key event.

func (KeyPress) Equal 

func (k KeyPress) Equal(other KeyPress) bool

Equal reports whether two key presses match.

func (KeyPress) String 

func (k KeyPress) String() string

String returns a formatted key press.

type KeyRouter 

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

KeyRouter routes key presses to commands.

func NewKeyRouter 

func NewKeyRouter(registry *CommandRegistry, modes *ModeManager, keymaps *KeymapStack) *KeyRouter

NewKeyRouter constructs a router.

func (*KeyRouter) HandleKey 

func (r *KeyRouter) HandleKey(msg runtime.KeyMsg, ctx Context) bool

HandleKey handles a single key press.

func (*KeyRouter) Reset 

func (r *KeyRouter) Reset()

Reset clears any pending key sequence.

type Keymap 

type Keymap struct {
	Name     string
	Bindings []Binding
	Parent   *Keymap
}

Keymap groups related key bindings with an optional parent.

func DefaultKeymap 

func DefaultKeymap() *Keymap

DefaultKeymap returns a baseline global keymap.

func (*Keymap) Match 

func (k *Keymap) Match(seq []KeyPress, ctx Context) keyMatch

Match returns a binding match or prefix state for a sequence.

type KeymapStack 

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

KeymapStack manages a stack of keymaps.

func (*KeymapStack) All 

func (s *KeymapStack) All() []*Keymap

All returns a copy of the keymap stack.

func (*KeymapStack) Current 

func (s *KeymapStack) Current() *Keymap

Current returns the top keymap.

func (*KeymapStack) Match 

func (s *KeymapStack) Match(seq []KeyPress, ctx Context) keyMatch

Match searches the stack top-down for a match.

func (*KeymapStack) Pop 

func (s *KeymapStack) Pop() *Keymap

Pop removes the top keymap.

func (*KeymapStack) Push 

func (s *KeymapStack) Push(keymap *Keymap)

Push adds a keymap to the stack.

type ModeManager 

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

ModeManager manages keymap modes.

func NewModeManager 

func NewModeManager() *ModeManager

NewModeManager creates an empty mode manager.

func (*ModeManager) Current 

func (m *ModeManager) Current() *Keymap

Current returns the active keymap.

func (*ModeManager) CurrentName 

func (m *ModeManager) CurrentName() string

CurrentName returns the active mode name.

func (*ModeManager) Pop 

func (m *ModeManager) Pop()

Pop restores the previous mode.

func (*ModeManager) Push 

func (m *ModeManager) Push(mode string)

Push pushes the current mode onto the stack and switches to mode.

func (*ModeManager) Register 

func (m *ModeManager) Register(name string, keymap *Keymap)

Register associates a keymap with a mode name.

func (*ModeManager) Set 

func (m *ModeManager) Set(mode string)

Set switches to a mode without modifying the stack.

type RuntimeHandler 

type RuntimeHandler struct {
	Router *KeyRouter
}

RuntimeHandler adapts a KeyRouter for runtime.App.

func (*RuntimeHandler) HandleKey 

func (h *RuntimeHandler) HandleKey(app *runtime.App, msg runtime.KeyMsg, focused runtime.Widget) bool

HandleKey handles a runtime key message.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.