Tcell is a Go package that provides a cell based view for text terminals, like XTerm. It was inspired by termbox, but includes many additional improvements.
Please see here for an important message for the people of Russia.
NOTE: This is version 2 of Tcell. There are breaking changes relative to version 1.
Version 1.x remains available using the import github.com/gdamore/tcell.
A brief, and still somewhat rough, tutorial is available.
A number of example are posted up on our Gallery.
Let us know if you want to add your masterpiece to the list!
Tcell is portable to a wide variety of systems, and is pure Go, without any need for CGO. Tcell is believed to work with mainstream systems officially supported by golang.
Following the Go support policy, Tcell officially only supports the current ("stable") version of go, and the version immediately prior ("oldstable"). This policy is necessary to make sure that we can update dependencies to pick up security fixes and new features, and it allows us to adopt changes (such as library and language features) that are only supported in newer versions of Go.
Tcell includes enhanced support for Unicode, including wide characters and combining characters, provided your terminal can support them. Note that Windows terminals generally don't support the full Unicode repertoire.
It will also convert to and from Unicode locales, so that the program can work with UTF-8 internally, and get reasonable output in other locales. Tcell tries hard to convert to native characters on both input and output. On output Tcell even makes use of the alternate character set to facilitate drawing certain characters.
Tcell also has richer support for a larger number of special keys that some terminals can send.
Tcell supports enhanced mouse tracking mode, so your application can receive regular mouse motion events, and wheel events, if your terminal supports it.
A compatibility layer for termbox is provided in the compat directory.
To use it, try importing github.com/gdamore/tcell/termbox instead.
Most termbox-go programs will probably work without further modification.
Internally Tcell uses UTF-8, just like Go.
However, Tcell understands how to
convert to and from other character sets, using the capabilities of
the golang.org/x/text/encoding packages.
Your application must supply
them, as the full set of the most common ones bloats the program by about 2 MB.
If you're lazy, and want them all anyway, see the encoding sub-directory.
The SetContent() API takes a primary rune, and an optional list of combining runes.
If any of the runes is a wide (East Asian, Emoji, etc.) rune occupying two cells,
then the library will skip output from the following cell. Care must be
taken in the application to avoid explicitly attempting to set content in the
next cell, otherwise the results are undefined. (Normally the wide character
is displayed, and the other character is not; do not depend on that behavior.)
Tcell assumes the ANSI/XTerm color model, including the 256 color map that
XTerm uses when it supports 256 colors. The terminfo guidance will be
honored, with respect to the number of colors supported. Also, only
terminals which expose ANSI style setaf and setab will support color;
if you have a color terminal that only has setf and setb, please submit
a ticket.
Tcell supports 24-bit color! (That is, if your terminal can support it.)
There are a few ways you can enable (or disable) 24-bit color.
-
For many terminals, we can detect it automatically if your terminal includes the
RGBorTccapabilities (or rather it did when the database was updated.) -
You can force this one by setting the
COLORTERMenvironment variable to24-bit,truecoloror24bit. This is the same method used by most other terminal applications that support 24-bit color. -
If you set your
TERMenvironment variable to a value with the suffix-truecolorthen 24-bit color compatible with XTerm and ECMA-48 will be assumed. (This feature is deprecated. It is recommended to use one of other methods listed above.) -
You can disable 24-bit color by setting
TCELL_TRUECOLOR=disablein your environment.
When using 24-bit color, programs will display the colors that the programmer
intended, overriding any "themes" the user may have set in their terminal
emulator. (For some cases, accurate color fidelity is more important
than respecting themes. For other cases, such as typical text apps that
only use a few colors, its more desirable to respect the themes that
the user has established.)
Reasonable attempts have been made to minimize sending data to terminals, avoiding repeated sequences or drawing the same cell on refresh updates.
Mouse tracking, buttons, and even wheel mice works fine on most terminal emulators, as well as Windows.
Terminals that appear to support the XTerm mouse model also can support
bracketed paste, for applications that opt-in. See EnablePaste() for details.
There is a SimulationScreen, that can be used to simulate a real screen
for automated testing. The supplied tests do this. The simulation contains
event delivery, screen resizing support, and capabilities to inject events
and examine "physical" screen contents.
Everything works using pure Go on mainstream platforms. Some more esoteric platforms (e.g., AIX) may need to be added. Pull requests are welcome!
Windows console mode applications are supported.
Modern console applications like ConEmu and the Windows Terminal, support all the good features (resize, mouse tracking, etc.)
WASM is supported, but needs additional setup detailed in README-wasm.
Plan 9 is supported on a limited basis. The Plan 9 backend opens /dev/cons for I/O, enables raw mode by writing rawon/rawoff to /dev/consctl, watches /dev/wctl for resize notifications, and then constructs a terminfo-backed Screen (so NewScreen works as on other platforms). Typical usage is inside vt(1) with TERM=vt100. Expect monochrome text and no mouse reporting under stock vt(1) (it generally does not emit ANSI color or xterm mouse sequences). If a Plan 9 terminal supplies ANSI color escape sequences and xterm-style mouse reporting, color can be picked up via terminfo and mouse support could be added by wiring those sequences into the Plan 9 TTY path; contributions that improve terminal detection and broaden feature support are welcome.
Tcell is absolutely free, but if you want to obtain commercial, professional support, there are options.
- TideLift subscriptions include support for Tcell, as well as many other open source packages.
- Staysail Systems Inc. offers direct support, and custom development around Tcell on an hourly basis.
