tcell

Tcell is a pure Go package (no CGO required) and supports various platforms:

• POSIX (Linux, macOS, FreeBSD, etc.): Works out of the box.
• Windows: Supported; see README-windows.md for details.
• WASM: Supported; requires additional setup as detailed in README-wasm.md.
• Plan 9: Supported on a best-effort basis; see README-plan9.md.

When upgrading to Tcell v3, the following API changes are required to support multi-rune grapheme clusters:

• Replace SetCell and SetContents with Put.
• Replace GetContents with Get.

The vt/layouts directory contains packages for implementing keyboard layouts used by the emulator subsystem. This subsystem is designed for developers writing their own terminal emulators or simulation (mock) terminal emulators used to test TCell.

Note: If you are not implementing a terminal emulator, you do not need to use these packages.

Tcell version 3 is the current major version and contains breaking changes relative to v1 and v2. To use version 3, import the package using the v3 suffix.

Note: Version 2 is available via github.com/gdamore/tcell/v2. Version 1 is unmaintained and should not be used.

The layout subsystem is extensible and supports inheritance, allowing you to implement only the differences between layouts.

To design a new layout:

1. Start by examining the us/ package.
2. Use the US International Layout as a reference, as it extends the vanilla ANSI layout.
3. Note that the ANSI layout is always available as a base.

The default vt(1) mode is VT100, which provides only basic monochrome text. To improve functionality, you can attempt to emulate more modern terminals by using specific flags with the vt command and setting the TERM environment variable:

• For basic monochrome text: Set TERM=vt100.
• For enhanced features (untested): Use the -x flag with vt and set TERM=xterm. This may enable color and mouse support.
• Other emulation options: You can also try -2 (VT220) or -a (ANSI) flags with vt.

If TERM is not set in the environment, Tcell will assume XTerm-like functionality.

Tcell v3 has removed NewConsoleScreen and support for the legacy Windows console mode. It now uses modern Windows VT modes.

Requirement: Tcell on Windows requires at least Windows 10 build 1703 (the Creators Update).

For the best experience with tcell on Windows, use the following terminal emulators:

• Windows Terminal (Recommended): The preferred emulator for Windows 11. It is the main test target and is recommended if you encounter issues with third-party applications.
• Alacritty: Works reasonably well with support for modern key reporting, mouse events, and bracketed paste, though advanced Unicode support is limited.

Avoid these emulators:

• ConEmu or mintty: These do not support modern APIs or terminal standards and provide a suboptimal experience.
• Termius: Not recommended for local sessions as it provides a poor experience.

Remote Session Support: WezTerm, Termius, Putty, and MobaXterm work reasonably for remote sessions but may lack support for newer keyboard protocols and may not work well for local sessions.

To use tcell on Windows, you must use one of the following operating systems:

• Windows 10 version 1703 (Creators Update) or later
• Windows Server 2016 or later

Note: Windows 8 and earlier versions are not supported.

You can display your Tcell WASM project in two ways:

Standalone

Serve the directory containing your files using any web server. For example, using a simple Go file server:

// server.go
package main

import (
	"log"
	"net/http"
)

func main() {
	log.Fatal(http.ListenAndServe(":8080",
		http.FileServer(http.Dir("/path/to/dir/to/serve")),
	))
}

Then navigate to localhost:8080/tcell.html.

Embedding

To embed the Tcell application into an existing webpage, use an <iframe>:

<iframe src="tcell.html" title="Tcell app"></iframe>

Tcell is supported on Plan 9 on a best-effort basis. The backend operates by:

• Opening /dev/cons for I/O.
• Enabling raw mode by writing rawon/rawoff to /dev/consctl.
• Watching /dev/wctl for resize notifications.

Note that the main Tcell development team does not have a Plan 9 environment, so support is not guaranteed.

To start a Tcell application, you must initialize a screen using tcell.NewScreen() and then call s.Init(). It is recommended to set a default style and clear the screen immediately after initialization. To clean up and exit properly, call s.Fini().

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(color.Reset).Foreground(color.Reset)
s.SetStyle(defStyle)

// Clear screen
s.Clear()