Project: Loggie (Observability and Analysis / Observability)
File: TUTORIAL.md

Tcell provides a low-level, portable API for building terminal-based programs. A (or a real terminal such as a DEC VT-220) is used to interact with such a program. Tcell's interface is fairly low-level. While it provides a reasonably portable way of dealing with all the usual terminal features, it may be easier to utilize a higher level framework. A number of such frameworks are listed on the Tcell main . This tutorial provides the details of Tcell, and is appropriate for developers wishing to create their own application frameworks or needing more direct access to the terminal capabilities. Applications receive an event of type `EventResize` when they are first initialized and each time the terminal is resized. The new size is available as `Size`. ```golang switch ev := ev.(type) { case *tcell.EventResize: w, h := ev.Size() logMessage(fmt.Sprintf("Resized to %dx%d", w, h)) } ``` When a key is pressed, applications receive an event of type `EventKey`. This event describes the modifier keys pressed (if any) and the pressed key or rune. When a rune key is pressed, an event with its `Key` set to `KeyRune` is dispatched. When a non-rune key is pressed, it is available as the `Key` of the event. ```golang switch ev := ev.(type) { case *tcell.EventKey: mod, key, ch := ev.Mod(), ev.Key(), ev.Rune() logMessage(fmt.Sprintf("EventKey Modifiers: %d Key: %d Rune: %d", mod, key, ch)) } ``` Terminal-based programs have less visibility into keyboard activity than graphical applications. When a key is pressed and held, additional key press events are sent by the terminal emulator. The rate of these repeated events depends on the emulator's configuration. Key release events are not available. It is not possible to distinguish runes typed while holding shift and runes typed using caps lock. Capital letters are reported without the Shift modifier. Applications receive an event of type `EventMouse` when the mouse moves, or a mouse button is pressed or released. Mouse events are only delivered if `EnableMouse` has been called. The mouse buttons being pressed (if any) are available as `Buttons`, and the position of the mouse is available as `Position`. ```golang switch ev := ev.(type) { case *tcell.EventMouse: mod := ev.Modifiers() btns := ev.Buttons() x, y := ev.Position() logMessage(fmt.Sprintf("EventMouse Modifiers: %d Buttons: %d Position: %d,%d", mod, btns, x, y)) } ``` Identifier | Alias | Description --|--|-- Button1 | ButtonPrimary | Left button Button2 | ButtonSecondary | Right button Button3 | ButtonMiddle | Middle button Button4 | | Side button (thumb/next) Button5 | | Side button (thumb/prev) To create a tcell application, first initialize a screen to hold it. ```golang s, err := tcell.NewScreen() if err != nil { log.Fatalf("%+v", err) } if err := s.Init(); err != nil { log.Fatalf("%+v", err) } // Set default text style defStyle := tcell.StyleDefault.Background(tcell.ColorReset).Foreground(tcell.ColorReset) s.SetStyle(defStyle) // Clear screen s.Clear() ``` Text may be drawn on the screen using `SetContent`. ```golang s.SetContent(0, 0, 'H', nil, defStyle) s.SetContent(1, 0, 'i', nil, defStyle) s.SetContent(2, 0, '!', nil, defStyle) ``` To draw text more easily, define a render function. ```golang func drawText(s tcell.Screen, x1, y1, x2, y2 int, style

text string) { row := y1 col := x1 for _, r := range []rune(text) { s.SetContent(col, row, r, nil, style) col++ if col >= x2 { row++ col = x1 } if row > y2 { break } } } ``` Lastly, define an event loop to handle user input and update application state. ```golang quit := func() { s.Fini() os.Exit(0) } for { // Update screen s.Show() // Poll event ev := s.PollEvent() // Process event switch ev := ev.(type) { case *tcell.EventResize: s.Sync() case *tcell.EventKey: if ev.Key() == tcell.KeyEscape || ev.Key() == tcell.KeyCtrlC { quit() } } } ``` The following demonstrates how to initialize a screen, draw text/graphics and handle user input. ```golang package main import ( "fmt" "log" "os" "github.com/gdamore/tcell/v2" ) func drawText(s tcell.Screen, x1, y1, x2, y2 int, style tcell.Style, text string) { row := y1 col := x1 for _, r := range []rune(text) { s.SetContent(col, row, r, nil, style) col++ if col >= x2 { row++ col = x1 } if row > y2 { break } } } func drawBox(s tcell.Screen, x1, y1, x2, y2 int, style tcell.Style, text string) { if y2 < y1 { y1, y2 = y2, y1 } if x2 < x1 { x1, x2 = x2, x1 } // Fill background for row := y1; row <= y2; row++ { for col := x1; col <= x2; col++ { s.SetContent(col, row, ' ', nil, style) } } // Draw borders for col := x1; col <= x2; col++ { s.SetContent(col, y1, tcell.RuneHLine, nil, style) s.SetContent(col, y2, tcell.RuneHLine, nil, style) } for row := y1 + 1; row < y2; row++ { s.SetContent(x1, row, tcell.RuneVLine, nil, style) s.SetContent(x2, row, tcell.RuneVLine, nil, style) } // Only draw corners if necessary if y1 != y2 && x1 != x2 { s.SetContent(x1, y1, tcell.RuneULCorner, nil, style) s.SetContent(x2, y1, tcell.RuneURCorner, nil, style) s.SetContent(x1, y2, tcell.RuneLLCorner, nil, style) s.SetContent(x2, y2, tcell.RuneLRCorner, nil, style) } drawText(s, x1+1, y1+1, x2-1, y2-1, style, text) } func main() { defStyle := tcell.StyleDefault.Background(tcell.ColorReset).Foreground(tcell.ColorReset) boxStyle := tcell.StyleDefault.Foreground(tcell.ColorWhite).Background(tcell.ColorPurple) // Initialize screen s, err := tcell.NewScreen() if err != nil { log.Fatalf("%+v", err) } if err := s.Init(); err != nil { log.Fatalf("%+v", err) } s.SetStyle(defStyle) s.EnableMouse() s.EnablePaste() s.Clear() // Draw initial boxes drawBox(s, 1, 1, 42, 7, boxStyle, "Click and drag to draw a box") drawBox(s, 5, 9, 32, 14, boxStyle, "Press C to reset") // Event loop ox, oy := -1, -1 quit := func() { s.Fini() os.Exit(0) } for { // Update screen s.Show() // Poll event ev := s.PollEvent() // Process event switch ev := ev.(type) { case *tcell.EventResize: s.Sync() case *tcell.EventKey: if ev.Key() == tcell.KeyEscape || ev.Key() == tcell.KeyCtrlC { quit() } else if ev.Key() == tcell.KeyCtrlL { s.Sync() } else if ev.Rune() == 'C' || ev.Rune() == 'c' { s.Clear() } case *tcell.EventMouse: x, y := ev.Position() button := ev.Buttons() // Only process button events, not wheel events button &= tcell.ButtonMask(0xff) if button != tcell.ButtonNone && ox < 0 { ox, oy = x, y } switch ev.Buttons() { case tcell.ButtonNone: if ox >= 0 { label := fmt.Sprintf("%d,%d to %d,%d", ox, oy, x, y) drawBox(s, ox, oy, x, y, boxStyle, label) ox, oy = -1, -1 } } } } } ```