tcellterm

README

tcell-term

A virtual terminal widget for tcell

s, err := tcell.NewScreen()
if err != nil {
	panic(err)
}
quit := make(chan struct{})
termRedraw := make(chan struct{})

w, h := s.Size()
cmd := exec.Cmd("less", "/etc/hosts")
termWidth, termHeight := w / 2, h / 2
termX, termY := w / 4, h / 4
term := tcellterm.New()

//run command in term
go func() {
	term.Run(cmd, termRedraw, termWidth, termHeight)
	cmd.Wait()
	quit <- struct{}{}
}()

//event loop
go func() {
	for {
		ev := s.PollEvent()
		switch ev := ev.(type) {
		case *tcell.EventKey:
			//send key events to the terminal
			term.Event(ev)
		case *tcell.EventResize:
			w, h := s.Size()
			lh := h / 2
			lw := w / 2
			//resize event for the terminal
			term.Resize(lw, lh)
			s.Sync()
		}
	}
}()

//draw loop
loop:
for {
	select {
	case <-quit:
		break loop
	//terminal wants to be redrawn
	case <-termRedraw:
	}
	term.Draw(s, termX, termY)
}

s.Fini()

For general discussion or patches, use the mailing list: ~ghost08/tcell-term@lists.sr.ht.

Contributing

Anyone can contribute to tcell-term:

• Clone the repository.
• Patch the code.
• Make some tests.
• Ensure that your code is properly formatted with gofmt.
• Ensure that everything works as expected.
• Ensure that you did not break anything.
• Do not forget to update the docs.

Once you are happy with your work, you can create a commit (or several commits). Follow these general rules:

• Limit the first line (title) of the commit message to 60 characters.
• Use a short prefix for the commit title for readability with git log --oneline.
• Use the body of the commit message to actually explain what your patch does and why it is useful.
• Address only one issue/topic per commit.
• If you are fixing a ticket, use appropriate commit trailers.
• If you are fixing a regression introduced by another commit, add a Fixes: trailer with the commit id and its title.

There is a great reference for commit messages in the Linux kernel documentation.

Before sending the patch, you should configure your local clone with sane defaults:

git config format.subjectPrefix "PATCH tcell-term"
git config sendemail.to "~ghost08/tcell-term@lists.sr.ht"

And send the patch to the mailing list:

git sendemail --annotate -1

Wait for feedback. Address comments and amend changes to your original commit. Then you should send a v2:

git sendemail --in-reply-to=$first_message_id --annotate -v2 -1

Documentation

Index

• Variables
• type EventTitle
  • func (ev *EventTitle) Title() string
  • func (ev *EventTitle) When() time.Time
  • func (ev *EventTitle) Widget() views.Widget
• type Option
  • func WithPollInterval(interval int) Option
  • func WithWindowManipulator(wm termutil.WindowManipulator) Option
• type Terminal
  • func New(opts ...Option) *Terminal
  • func (t *Terminal) Close()
  • func (t *Terminal) Draw()
  • func (t *Terminal) GetCursor() (bool, int, int, tcell.CursorStyle)
  • func (t *Terminal) HandleEvent(e tcell.Event) bool
  • func (t *Terminal) Resize()
  • func (t *Terminal) Run(cmd *exec.Cmd) error
  • func (t *Terminal) RunWithAttrs(cmd *exec.Cmd, attr *syscall.SysProcAttr) error
  • func (t *Terminal) SetView(view views.View)
  • func (t *Terminal) Size() (int, int)
• type WinSize
  • func GetWinSize() (sz WinSize, err error)

Variables

var (
	LINUX_KEY_MAP = map[tcell.Key]string{
		tcell.KeyEnter:      "\r",
		tcell.KeyBackspace:  "\x7f",
		tcell.KeyBackspace2: "\x7f",
		tcell.KeyTab:        "\t",
		tcell.KeyEscape:     "\x1b",
		tcell.KeyDown:       "\x1b[B",
		tcell.KeyUp:         "\x1b[A",
		tcell.KeyRight:      "\x1b[C",
		tcell.KeyLeft:       "\x1b[D",
		tcell.KeyHome:       "\x1b[1~",
		tcell.KeyEnd:        "\x1b[4~",
		tcell.KeyPgUp:       "\x1b[5~",
		tcell.KeyPgDn:       "\x1b[6~",
		tcell.KeyDelete:     "\x1b[3~",
		tcell.KeyInsert:     "\x1b[2~",
		tcell.KeyF1:         "\x1bOP",
		tcell.KeyF2:         "\x1bOQ",
		tcell.KeyF3:         "\x1bOR",
		tcell.KeyF4:         "\x1bOS",
		tcell.KeyF5:         "\x1b[15~",
		tcell.KeyF6:         "\x1b[17~",
		tcell.KeyF7:         "\x1b[18~",
		tcell.KeyF8:         "\x1b[19~",
		tcell.KeyF9:         "\x1b[20~",
		tcell.KeyF10:        "\x1b[21~",
		tcell.KeyF12:        "\x1b[24~",
	}

	LINUX_CTRL_KEY_MAP = map[tcell.Key]string{
		tcell.KeyUp:    "\x1b[1;5A",
		tcell.KeyDown:  "\x1b[1;5B",
		tcell.KeyRight: "\x1b[1;5C",
		tcell.KeyLeft:  "\x1b[1;5D",
	}

	LINUX_CTRL_RUNE_MAP = map[rune]string{
		'@':  "\x00",
		'`':  "\x00",
		'[':  "\x1b",
		'{':  "\x1b",
		'\\': "\x1c",
		'|':  "\x1c",
		']':  "\x1d",
		'}':  "\x1d",
		'^':  "\x1e",
		'~':  "\x1e",
		'_':  "\x1f",
		'?':  "\x7f",
	}

	LINUX_ALT_KEY_MAP = map[tcell.Key]string{
		tcell.KeyUp:    "\x1b[1;3A",
		tcell.KeyDown:  "\x1b[1;3B",
		tcell.KeyRight: "\x1b[1;3C",
		tcell.KeyLeft:  "\x1b[1;3D",
	}
)

Types

type EventTitle

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

func (*EventTitle) Title

func (ev *EventTitle) Title() string

func (*EventTitle) When

func (ev *EventTitle) When() time.Time

func (*EventTitle) Widget

func (ev *EventTitle) Widget() views.Widget

type Option

type Option func(*Terminal)

func WithPollInterval

func WithPollInterval(interval int) Option

WithPollInterval sets the minimum time, in ms, between views.EventWidgetContent events, which signal the screen has updates which can be drawn.

Default: 8 ms

func WithWindowManipulator

func WithWindowManipulator(wm termutil.WindowManipulator) Option

type Terminal

type Terminal struct {
	views.WidgetWatchers
	// contains filtered or unexported fields
}

func New

func New(opts ...Option) *Terminal

func (*Terminal) Close

func (t *Terminal) Close()

func (*Terminal) Draw

func (t *Terminal) Draw()

func (*Terminal) GetCursor

func (t *Terminal) GetCursor() (bool, int, int, tcell.CursorStyle)

GetCursor returns if the cursor is visible, it's x and y position, and it's style. If the cursor is not visible, the coordinates will be -1,-1

func (*Terminal) HandleEvent

func (t *Terminal) HandleEvent(e tcell.Event) bool

func (*Terminal) Resize

func (t *Terminal) Resize()

Resize resizes the terminal to the dimensions of the terminals view

func (*Terminal) Run

func (t *Terminal) Run(cmd *exec.Cmd) error

func (*Terminal) RunWithAttrs

func (t *Terminal) RunWithAttrs(cmd *exec.Cmd, attr *syscall.SysProcAttr) error

func (*Terminal) SetView

func (t *Terminal) SetView(view views.View)

SetView sets the view for the terminal to draw to. This must be set before calling Draw

func (*Terminal) Size

func (t *Terminal) Size() (int, int)

type WinSize

type WinSize struct {
	Rows   int16 /* rows, in characters */
	Cols   int16 /* columns, in characters */
	XPixel int16 /* horizontal size, pixels */
	YPixel int16 /* vertical size, pixels */
}

func GetWinSize

func GetWinSize() (sz WinSize, err error)