Repository files navigation

Tcell is aGo package that provides a cell based view for text terminals, likeXTerm.It was inspired bytermbox, but includes many additional improvements.

Please seehere for an important message for the people of Russia.

NOTE: This is version 2 ofTcell. There are breaking changes relative to version 1.Version 1.x remains available using the importgithub.com/gdamore/tcell.

A brief, and still somewhat rough,tutorial is available.

• proxima5 - space shooter (video)
• govisor - service management UI (screenshot)
• mouse demo - included mouse test (screenshot)
• gomatrix - converted from Termbox
• micro - lightweight text editor with syntax-highlighting and themes
• godu - utility to discover large files/folders
• tview - rich interactive widgets
• cview - user interface toolkit (fork oftview)
• awesome gocui - Go Console User Interface
• gomandelbrot - Mandelbrot!
• WTF - personal information dashboard
• browsh - modern web browser (video)
• go-life - Conway's Game of Life
• gowid - compositional widgets for terminal UIs, inspired byurwid
• termshark - interface fortshark, inspired by Wireshark, built ongowid
• go-tetris - Go Tetris with AI option
• fzf - command-line fuzzy finder
• ascii-fluid - fluid simulation controlled by webcam
• cbind - key event encoding, decoding and handling
• tpong - old-school Pong
• aerc - email client
• tblogs - development blogs reader
• spinc -irssi inspired chat application for Cisco Spark/WebEx
• gorss - RSS/Atom feed reader
• memoryalike - memorization game
• lf - file manager
• goful - CUI file manager
• gokeybr - deliberately practice your typing
• gonano - editor, mimicsnano
• uchess - UCI chess client
• min - Gemini browser
• ov - file pager
• tmux-wormhole -tmux plugin to transfer files
• gruid-tcell - driver for the grid based UI and game framework
• aretext - minimalist text editor withvim key bindings
• sync - GitHub repo synchronization tool
• statusbar - statusbar motivation tool for tracking periodic tasks/goals
• todo - simple todo app
• gosnakego - a snake game
• gbb - A classical bulletin board app for tildes or public unix servers
• lil - A simple and flexible interface for any service by implementing only list and get operations
• hero.go - 2d monster shooter (video)
• go-tetris - simple tetris game for native terminal and WASM using github actions+pages
• oddshub - A TUI designed for analyzing sports betting odds

Tcell includes a full parser and expander for terminfo capability strings,so that it can avoid hard coding escape strings for formatting. It also favorsportability, and includes support for all POSIX systems.

The database is also flexible & extensible, and can be modified by either runninga program to build the entire database, or an entry for just a single terminal.

Tcell is portable to a wide variety of systems, and is pure Go, withoutany need for CGO.Tcell is believed to work with mainstream systems officially supported by golang.

Tcell is able to operate without requiringSIGIO signals (unliketermbox),or asynchronous I/O, and can instead use standard Go file objects and Go routines.This means it should be safe, especially foruse with programs that use exec, or otherwise need to manipulate the tty streams.This model is also much closer to idiomatic Go, leading to fewer surprises.

Tcell includes enhanced support for Unicode, including wide characters andcombining characters, provided your terminal can support them.Note thatWindows terminals generally don't support the full Unicode repertoire.

It will also convert to and from Unicode locales, so that the programcan 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 outputTcell even makes use of the alternate character set to facilitatedrawing certain characters.

Tcell also has richer support for a larger number of special keys that someterminals can send.

Tcell will respect your terminal's color space as specified within your terminfo entries.For example attempts to emit color sequences on VT100 terminalswon't result in unintended consequences.

In legacy Windows mode,Tcell supports 16 colors, bold, dim, and reverse,instead of just termbox's 8 colors with reverse. (Note that there is someconflation with bold/dim and colors.)Modern Windows 10 can benefit from much richer colors however.

Tcell maps 16 colors down to 8, for terminals that need it.(The upper 8 colors are just brighter versions of the lower 8.)

Tcell supports enhanced mouse tracking mode, so your application can receiveregular mouse motion events, and wheel events, if your terminal supports it.

(Note: The Windows 10 Terminal application suffers from a flaw in this regard,and does not support mouse interaction. The stock Windows 10 console hostfired up with cmd.exe or PowerShell works fine however.)

A compatibility layer fortermbox is provided in thecompat directory.To use it, try importinggithub.com/gdamore/tcell/termbox instead.Mosttermbox-go programs will probably work without further modification.

InternallyTcell uses UTF-8, just like Go.However,Tcell understands how toconvert to and from other character sets, using the capabilities ofthegolang.org/x/text/encoding packages.Your application must supplythem, 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 theencoding sub-directory.

TheSetContent() API takes a primary rune, and an optional list of combining runes.If any of the runes is a wide (East Asian) rune occupying two cells,then the library will skip output from the following cell. Care must betaken in the application to avoid explicitly attempting to set content in thenext cell, otherwise the results are undefined. (Normally the wide characteris displayed, and the other character is not; do not depend on that behavior.)

Older terminal applications (especially on systems like Windows 8) lack supportfor advanced Unicode, and thus may not fare well.

Tcell assumes the ANSI/XTerm color model, including the 256 color map thatXTerm uses when it supports 256 colors. The terminfo guidance will behonored, with respect to the number of colors supported. Also, onlyterminals which expose ANSI stylesetaf andsetab will support color;if you have a color terminal that only hassetf andsetb, please submita ticket.

Tcellsupports 24-bit color! (That is, if your terminal can support it.)

NOTE: Technically the approach of using 24-bit RGB values for color is moreaccurately described as "direct color", but most people use the term "true color".We follow the (inaccurate) common convention.

There are a few ways you can enable (or disable) true color.

• For many terminals, we can detect it automatically if your terminalincludes theRGB orTc capabilities (or rather it did when the databasewas updated.)

• You can force this one by setting theCOLORTERM environment variable to24-bit,truecolor or24bit. This is the same method usedby most other terminal applications that support 24-bit color.

• If you set yourTERM environment 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 settingTCELL_TRUECOLOR=disable in yourenvironment.

When using TrueColor, programs will display the colors that the programmerintended, overriding any "themes" you may have set in your terminalemulator. (For some cases, accurate color fidelity is more importantthan respecting themes. For other cases, such as typical text apps thatonly use a few colors, its more desirable to respect the themes thatthe 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.

(Not relevant for Windows users.)

The Terminfo implementation operates with a built-in database.This should satisfy most users. However, it can also (on systemswith ncurses installed), dynamically parse the output frominfocmpfor terminals it does not already know about.

See theterminfo/ directory for more information about generatingnew entries for the built-in database.

Tcell requires that the terminal support thecup mode of cursor addressing.Ancient terminals without the ability to position the cursor directlyare not supported.This is unlikely to be a problem; such terminals have not been mass-producedsince the early 1970s.

Mouse support is detected via thekmous terminfo variable, however,enablement/disablement and decoding mouse events is done using hard codedsequences based on the XTerm X11 model. All popularterminals with mouse tracking support this model. (Full terminfo supportis not possible as terminfo sequences are not defined.)

On Windows, the mouse works normally.

Mouse wheel buttons on various terminals are known to work, but the supportin terminal emulators, as well as support for various buttons andlive mouse tracking, varies widely.Modernxterm, macOSTerminal, andiTerm all work well.

Terminals that appear to support the XTerm mouse model also can supportbracketed paste, for applications that opt-in. SeeEnablePaste() for details.

There is aSimulationScreen, that can be used to simulate a real screenfor automated testing. The supplied tests do this. The simulation containsevent delivery, screen resizing support, and capabilities to inject eventsand examine "physical" screen contents.

Everything works using pure Go on mainstream platforms. Some more esotericplatforms (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 10 terminal,support all the good features (resize, mouse tracking, etc.)

WASM is supported, but needs additional setup detailed inREADME-wasm.

These platforms won't work, but compilation stubs are suppliedfor folks that want to include parts of this in software for thoseplatforms. The Simulation screen works, but asTcell doesn't know how toallocate a real screen object on those platforms,NewScreen() will fail.

If anyone has wisdom about how to improve support for these,please let me know. PRs are especially welcome.

Tcell is absolutely free, but if you want to obtain commercial, professional support, there are options.

• TideLift subscriptions include support forTcell, as well as many other open source packages.
• Staysail Systems Inc. offers direct support, and custom development aroundTcell on an hourly basis.