cbind

README

!!! cbind has moved to code.rocketnine.space !!!

Please visit https://code.rocketnine.space/tslocum/cbind

---

cbind

Key event handling library for tcell

Features

• Set KeyEvent handlers
• Encode and decode KeyEvents as human-readable strings

Usage

// Create a new input configuration to store the key bindings.
c := NewConfiguration()

// Define save event handler.
handleSave := func(ev *tcell.EventKey) *tcell.EventKey {
    return nil
}

// Define open event handler.
handleOpen := func(ev *tcell.EventKey) *tcell.EventKey {
    return nil
}

// Define exit event handler.
handleExit := func(ev *tcell.EventKey) *tcell.EventKey {
    return nil
}

// Bind Alt+s.
if err := c.Set("Alt+s", handleSave); err != nil {
    log.Fatalf("failed to set keybind: %s", err)
}

// Bind Alt+o.
c.SetRune(tcell.ModAlt, 'o', handleOpen)

// Bind Escape.
c.SetKey(tcell.ModNone, tcell.KeyEscape, handleExit)

// Capture input. This will differ based on the framework in use (if any).
// When using tview or cview, call Application.SetInputCapture before calling
// Application.Run.
app.SetInputCapture(c.Capture)

Documentation

Documentation is available via gdooc.

The utility program whichkeybind is available to determine and validate key combinations.

go get code.rocketnine.space/tslocum/cbind/whichkeybind

Support

Please share issues and suggestions here.

Documentation

Overview

Package cbind provides tcell key event encoding, decoding and handling.

The NewConfiguration example demonstrates how to use cbind.

There are some limitations on reading keyboard input, which is explained in the tcell.EventKey documentation:

https://godoc.org/github.com/gdamore/tcell#EventKey

Index

• Constants
• Variables
• func Decode(s string) (mod tcell.ModMask, key tcell.Key, ch rune, err error)
• func Encode(mod tcell.ModMask, key tcell.Key, ch rune) (string, error)
• type Configuration
  • func NewConfiguration() *Configuration
  • func (c *Configuration) Capture(ev *tcell.EventKey) *tcell.EventKey
  • func (c *Configuration) Clear()
  • func (c *Configuration) Set(s string, handler func(ev *tcell.EventKey) *tcell.EventKey) error
  • func (c *Configuration) SetKey(mod tcell.ModMask, key tcell.Key, ...)
  • func (c *Configuration) SetRune(mod tcell.ModMask, ch rune, handler func(ev *tcell.EventKey) *tcell.EventKey)

Examples

• Configuration.Capture
• NewConfiguration

Constants

const (
	LabelCtrl  = "ctrl"
	LabelAlt   = "alt"
	LabelMeta  = "meta"
	LabelShift = "shift"
)

Modifier labels

Variables

var ErrInvalidKeyEvent = errors.New("invalid key event")

ErrInvalidKeyEvent is the error returned when encoding or decoding a key event fails.

var UnifyEnterKeys = true

UnifyEnterKeys is a flag that determines whether or not KPEnter (keypad enter) key events are interpreted as Enter key events. When enabled, Ctrl+J key events are also interpreted as Enter key events.

Functions

func Decode

func Decode(s string) (mod tcell.ModMask, key tcell.Key, ch rune, err error)

Decode decodes a string as a key or combination of keys.

func Encode

func Encode(mod tcell.ModMask, key tcell.Key, ch rune) (string, error)

Encode encodes a key or combination of keys a string.

Types

type Configuration

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

Configuration maps keys to event handlers and processes key events.

func NewConfiguration

func NewConfiguration() *Configuration

NewConfiguration returns a new input configuration.

Example

Example of creating and using an input configuration.

// Create a new input configuration to store the key bindings.
c := NewConfiguration()

handleSave := func(ev *tcell.EventKey) *tcell.EventKey {
	// Save
	return nil
}

handleOpen := func(ev *tcell.EventKey) *tcell.EventKey {
	// Open
	return nil
}

handleExit := func(ev *tcell.EventKey) *tcell.EventKey {
	// Exit
	return nil
}

// Bind Alt+s.
if err := c.Set("Alt+s", handleSave); err != nil {
	log.Fatalf("failed to set keybind: %s", err)
}

// Bind Alt+o.
c.SetRune(tcell.ModAlt, 'o', handleOpen)

// Bind Escape.
c.SetKey(tcell.ModNone, tcell.KeyEscape, handleExit)

// Capture input. This will differ based on the framework in use (if any).
// When using tview or cview, call Application.SetInputCapture before calling
// Application.Run.
// app.SetInputCapture(c.Capture)

func (*Configuration) Capture

func (c *Configuration) Capture(ev *tcell.EventKey) *tcell.EventKey

Capture handles key events.

Example

Example of capturing key events.

// See the end of the NewConfiguration example.

func (*Configuration) Clear

func (c *Configuration) Clear()

Clear removes all handlers.

func (*Configuration) Set

func (c *Configuration) Set(s string, handler func(ev *tcell.EventKey) *tcell.EventKey) error

Set sets the handler for a key event string.

func (*Configuration) SetKey

func (c *Configuration) SetKey(mod tcell.ModMask, key tcell.Key, handler func(ev *tcell.EventKey) *tcell.EventKey)

SetKey sets the handler for a key.

func (*Configuration) SetRune

func (c *Configuration) SetRune(mod tcell.ModMask, ch rune, handler func(ev *tcell.EventKey) *tcell.EventKey)

SetRune sets the handler for a rune.