= tcell
image:https://img.shields.io/travis/micro-editor/tcell.svg?label=linux[Linux Status,link="https://travis-ci.org/micro-editor/tcell"]
image:https://img.shields.io/appveyor/ci/micro-editor/tcell.svg?label=windows[Windows Status,link="https://ci.appveyor.com/project/micro-editor/tcell"]
image:https://img.shields.io/badge/license-APACHE2-blue.svg[Apache License,link="https://github.com/micro-editor/tcell/blob/master/LICENSE"]
image:https://img.shields.io/badge/godoc-reference-blue.svg[GoDoc,link="https://godoc.org/github.com/micro-editor/tcell"]
image:https://goreportcard.com/badge/micro-editor/tcell[Go Report Card,link="http://goreportcard.com/report/micro-editor/tcell"]
image:https://img.shields.io/discord/639503822733180969?label=discord[Discord,link="https://discord.gg/urTTxDN"]
image:https://codecov.io/gh/micro-editor/tcell/branch/master/graph/badge.svg[codecov,link="https://codecov.io/gh/micro-editor/tcell"]
[cols="2",grid="none"]
|===
|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.
a|[.right]
image::logos/tcell.png[float="right"]
|===
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/micro-editor/tcell.
== Examples
- https://github.com/gdamore/proxima5[proxima5] - space shooter (https://youtu.be/jNxKTCmY_bQ[video])
- https://github.com/gdamore/govisor[govisor] - service management UI (http://2.bp.blogspot.com/--OsvnfzSNow/Vf7aqMw3zXI/AAAAAAAAARo/uOMtOvw4Sbg/s1600/Screen%2BShot%2B2015-09-20%2Bat%2B9.08.41%2BAM.png[screenshot])
- mouse demo - included mouse test (http://2.bp.blogspot.com/-fWvW5opT0es/VhIdItdKqJI/AAAAAAAAATE/7Ojc0L1SpB0/s1600/Screen%2BShot%2B2015-10-04%2Bat%2B11.47.13%2BPM.png[screenshot])
- https://github.com/gdamore/gomatrix[gomatrix] - converted from Termbox
- https://github.com/zyedidia/micro/[micro] - lightweight text editor with syntax-highlighting and themes
- https://github.com/viktomas/godu[godu] - simple golang utility helping to discover large files/folders.
- https://github.com/rivo/tview/[tview] - rich interactive widgets for terminal UIs
- https://github.com/awesome-gocui/gocui[awesome gocui] - Go Console User Interface
- https://github.com/rgm3/gomandelbrot[gomandelbrot] - Mandelbrot!
- https://github.com/senorprogrammer/wtf[WTF]- Personal information dashboard for your terminal
- https://github.com/browsh-org/browsh[browsh] - A fully-modern text-based browser, rendering to TTY and browsers (https://www.youtube.com/watch?v=HZq86XfBoRo[video])
- https://github.com/sachaos/go-life[go-life] - Conway's Game of Life.
- https://github.com/gcla/gowid[gowid] - compositional widgets for terminal UIs, inspired by urwid
- https://termshark.io[termshark] - a terminal UI for tshark, inspired by Wireshark, built on gowid
- https://github.com/MichaelS11/go-tetris[go-tetris] - Go Tetris with AI option
- https://github.com/junegunn/fzf[fzf] - A command-line fuzzy finder
- https://github.com/esimov/ascii-fluid[ascii-fluid] - A terminal based ASCII fluid simulation controlled by webcam
- https://gitlab.com/tslocum/cbind[cbind] - Provides key event encoding, decoding and handling
- https://github.com/spinzed/tpong[tpong] - The old-school Pong remade in terminal
- https://git.sr.ht/~sircmpwn/aerc[aerc] - An email client for your terminal.
- https://github.com/ezeoleaf/tblogs[tblogs] - A terminal based development blogs reader
- https://github.com/lallassu/spinc[spinc] - An irssi inspired terminal chat application for Cisco Spark/WebEx
- https://github.com/lallassu/gorss[gorss] - A RSS/Atom feed reader for your terminal
- https://github.com/Bios-Marcel/memoryalike[memoryalike] - A game where you have to memorize runes and hit their respective keys
- https://github.com/gokcehan/lf[lf] - Terminal file manager
- https://github.com/bunyk/gokeybr[gokeybr] - program that helps to deliberately practice your typing.
- https://github.com/jbaramidze/gonano[gonano] - CLI test editor
- https://github.com/tmountain/uchess[uchess] - A UCI chess client for your terminal
- https://github.com/a-h/min[min] - A Gemini browser
- https://github.com/noborus/ov[ov] - Terminal pager
- https://github.com/gcla/tmux-wormhole[tmux-wormhole] - A tmux plugin to transfer files with magic wormhole
- https://github.com/anaseto/gruid-tcell[gruid-tcell] - A tcell driver for the grid based UI and game framework gruid.
- https://github.com/aretext/aretext[aretext] - Minimalist text editor with vim key bindings.
== Pure Go Terminfo Database
Tcell includes a full parser and expander for terminfo capability strings,
so that it can avoid hard coding escape strings for formatting. It also favors
portability, and includes support for all POSIX systems.
The database is also flexible & extensible, and can modified by either running
a program to build the entire database, or an entry for just a single terminal.
== More Portable
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.
== No Async IO
Tcell is able to operate without requiring SIGIO signals (unlike termbox),
or asynchronous I/O, and can instead use standard Go file
objects and Go routines.
This means it should be safe, especially for
use 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.
== Rich Unicode & non-Unicode support
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, and
on output Tcell even makes use of the alternate character set to facilitate
drawing certain characters.
== More Function Keys
Tcell also has richer support for a larger number of special keys that some terminals can send.
== Better Color Handling
Tcell will respect your terminal's color space as specified within your terminfo
entries, so that for example attempts to emit color sequences on VT100 terminals
won'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 some
conflation 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.)
== Better Mouse Support
Tcell supports enhanced mouse tracking mode, so your application can receive
regular 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 host
fired up with cmd.exe or PowerShell works fine however.)
== Termbox Compatibility
A compatibility layer for termbox is provided in the compat directory.
To use it, try importing github.com/micro-editor/tcell/termbox instead.
Most termbox-go programs will probably work without further modification.
== Working With Unicode
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 2MB.
If you're lazy, and want them all anyway, see the encoding sub-directory.
== Wide & Combining Characters
The SetContent() 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, but care must be
taken in the application to avoid explicitly attempting to set content in the
next cell, otherwise the results are undefined. (Normally wide character
is displayed, and the other character is not; do not depend on that behavior.)
Older terminal applications (especially on systems like Windows 8) lack support
for advanced Unicode, and thus may not fare well.
== Colors
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; it wouldn't be hard to add that if there is need.
== 24-bit Color
Tcell supports true color! (That is, if your terminal can support it,
Tcell can accurately display 24-bit color.)
NOTE: Technically the approach of using 24-bit RGB values for color is more
accurately described as "direct color", but most people use the term "true color",
and so 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 terminal
includes the RGB or Tc capabilities (or rather it did when the database
was updated.)
-
You can force this one by setting the COLORTERM environment variable to
"24-bit", "truecolor" or "24bit". This is the same method used
by most other terminal applications that support 24-bit color.
-
If you set your TERM environment variable to a value with the suffix -truecolor
then 24-bit color compatible with XTerm will be assumed (and the terminal will
otherwise use the same escape sequences as the base terminal definition.)
NOTE: This feature is for compatibility with older Tcell versions.
It is recommended to use one of other methods instead.
- You can disable 24-bit color by setting
TCELL_TRUECOLOR=disable in your
environment.
When using TrueColor, programs will display the colors that the programmer
intended, overriding any "themes" you may have set in your 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.)
== Performance
Reasonable attempts have been made to minimize sending data to terminals,
avoiding repeated sequences or drawing the same cell on refresh updates.
== Terminfo
(Not relevant for Windows users.)
The Terminfo implementation operates with a built-in database.
This should satisfy most users. However, it can also (on systems
with ncurses installed), dynamically parse the output from infocmp
for terminals it does not already know about.
See the terminfo/ directory for more information about generating
new entries for the built-in database.
Tcell requires that the terminal support the cup mode of cursor addressing.
Ancient terminals without the ability to position the cursor directly
are not supported.
This is unlikely to be a problem; such terminals have not been mass-produced
since the early 1970s.
== Mouse Support
Mouse support is detected via the kmous terminfo variable, however,
enablement/disablement and decoding mouse events is done using hard coded
sequences based on the XTerm X11 model. As of this writing all popular
terminals with mouse tracking support this model. (Full terminfo support
is 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 support
in terminal emulators, as well as support for various buttons and
live mouse tracking, varies widely. Modern xterm, macOS Terminal, and iTerm all work well.
== Bracketed Paste
Terminals that appear to support the XTerm mouse model also can support
bracketed paste, for applications that opt-in. See EnablePaste() for details.
== Testability
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.
== Platforms
=== POSIX (Linux, FreeBSD, macOS, Solaris, etc.)
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
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.)
=== Plan9, WASM, and others
These platforms won't work, but compilation stubs are supplied
for folks that want to include parts of this in software for those
platforms. The Simulation screen works, but as Tcell doesn't know how to
allocate 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.
=== Commercial Support
Tcell is absolutely free, but if you want to obtain commercial, professional support, there are options.
[cols="2",align="center",frame="none", grid="none"]
|===
^.^|
image:logos/tidelift.png[100,100]
a|
https://tidelift.com/[Tidelift] subscriptions include support for Tcell, as well as many other open source packages.
^.^|
image:logos/staysail.png[100,100]
a|
mailto:[email protected][Staysail Systems, Inc.] offers direct support, and custom development around Tcell on an hourly basis.
/tcell