README.md (14978B)
1 <img src="logos/tcell.png" style="float: right"/> 2 3 # Tcell 4 5 _Tcell_ is a _Go_ package that provides a cell based view for text terminals, like _XTerm_. 6 It was inspired by _termbox_, but includes many additional improvements. 7 8 [](https://stand-with-ukraine.pp.ua) 9 [](https://github.com/gdamore/tcell/actions/workflows/linux.yml) 10 [](https://github.com/gdamore/tcell/actions/workflows/windows.yml) 11 [](https://github.com/gdamore/tcell/blob/master/LICENSE) 12 [](https://pkg.go.dev/github.com/gdamore/tcell/v2) 13 [](https://discord.gg/urTTxDN) 14 [](https://codecov.io/gh/gdamore/tcell) 15 [](https://goreportcard.com/report/github.com/gdamore/tcell/v2) 16 17 Please see [here](UKRAINE.md) for an important message for the people of Russia. 18 19 NOTE: This is version 2 of _Tcell_. There are breaking changes relative to version 1. 20 Version 1.x remains available using the import `github.com/gdamore/tcell`. 21 22 ## Tutorial 23 24 A brief, and still somewhat rough, [tutorial](TUTORIAL.md) is available. 25 26 ## Examples 27 28 - [proxima5](https://github.com/gdamore/proxima5) - space shooter ([video](https://youtu.be/jNxKTCmY_bQ)) 29 - [govisor](https://github.com/gdamore/govisor) - service management UI ([screenshot](http://2.bp.blogspot.com/--OsvnfzSNow/Vf7aqMw3zXI/AAAAAAAAARo/uOMtOvw4Sbg/s1600/Screen%2BShot%2B2015-09-20%2Bat%2B9.08.41%2BAM.png)) 30 - mouse demo - included mouse test ([screenshot](http://2.bp.blogspot.com/-fWvW5opT0es/VhIdItdKqJI/AAAAAAAAATE/7Ojc0L1SpB0/s1600/Screen%2BShot%2B2015-10-04%2Bat%2B11.47.13%2BPM.png)) 31 - [gomatrix](https://github.com/gdamore/gomatrix) - converted from Termbox 32 - [micro](https://github.com/zyedidia/micro/) - lightweight text editor with syntax-highlighting and themes 33 - [godu](https://github.com/viktomas/godu) - utility to discover large files/folders 34 - [tview](https://github.com/rivo/tview/) - rich interactive widgets 35 - [cview](https://code.rocketnine.space/tslocum/cview) - user interface toolkit (fork of _tview_) 36 - [awesome gocui](https://github.com/awesome-gocui/gocui) - Go Console User Interface 37 - [gomandelbrot](https://github.com/rgm3/gomandelbrot) - Mandelbrot! 38 - [WTF](https://github.com/senorprogrammer/wtf) - personal information dashboard 39 - [browsh](https://github.com/browsh-org/browsh) - modern web browser ([video](https://www.youtube.com/watch?v=HZq86XfBoRo)) 40 - [go-life](https://github.com/sachaos/go-life) - Conway's Game of Life 41 - [gowid](https://github.com/gcla/gowid) - compositional widgets for terminal UIs, inspired by _urwid_ 42 - [termshark](https://termshark.io) - interface for _tshark_, inspired by Wireshark, built on _gowid_ 43 - [go-tetris](https://github.com/MichaelS11/go-tetris) - Go Tetris with AI option 44 - [fzf](https://github.com/junegunn/fzf) - command-line fuzzy finder 45 - [ascii-fluid](https://github.com/esimov/ascii-fluid) - fluid simulation controlled by webcam 46 - [cbind](https://code.rocketnine.space/tslocum/cbind) - key event encoding, decoding and handling 47 - [tpong](https://github.com/spinzed/tpong) - old-school Pong 48 - [aerc](https://git.sr.ht/~sircmpwn/aerc) - email client 49 - [tblogs](https://github.com/ezeoleaf/tblogs) - development blogs reader 50 - [spinc](https://github.com/lallassu/spinc) - _irssi_ inspired chat application for Cisco Spark/WebEx 51 - [gorss](https://github.com/lallassu/gorss) - RSS/Atom feed reader 52 - [memoryalike](https://github.com/Bios-Marcel/memoryalike) - memorization game 53 - [lf](https://github.com/gokcehan/lf) - file manager 54 - [goful](https://github.com/anmitsu/goful) - CUI file manager 55 - [gokeybr](https://github.com/bunyk/gokeybr) - deliberately practice your typing 56 - [gonano](https://github.com/jbaramidze/gonano) - editor, mimics _nano_ 57 - [uchess](https://github.com/tmountain/uchess) - UCI chess client 58 - [min](https://github.com/a-h/min) - Gemini browser 59 - [ov](https://github.com/noborus/ov) - file pager 60 - [tmux-wormhole](https://github.com/gcla/tmux-wormhole) - _tmux_ plugin to transfer files 61 - [gruid-tcell](https://github.com/anaseto/gruid-tcell) - driver for the grid based UI and game framework 62 - [aretext](https://github.com/aretext/aretext) - minimalist text editor with _vim_ key bindings 63 - [sync](https://github.com/kyprifog/sync) - GitHub repo synchronization tool 64 - [statusbar](https://github.com/kyprifog/statusbar) - statusbar motivation tool for tracking periodic tasks/goals 65 - [todo](https://github.com/kyprifog/todo) - simple todo app 66 - [gosnakego](https://github.com/liweiyi88/gosnakego) - a snake game 67 - [gbb](https://github.com/sdemingo/gbb) - A classical bulletin board app for tildes or public unix servers 68 - [lil](https://github.com/andrievsky/lil) - A simple and flexible interface for any service by implementing only list and get operations 69 - [hero.go](https://github.com/barisbll/hero.go) - 2d monster shooter ([video](https://user-images.githubusercontent.com/40062673/277157369-240d7606-b471-4aa1-8c54-4379a513122b.mp4)) 70 - [go-tetris](https://github.com/aaronriekenberg/go-tetris) - simple tetris game for native terminal and WASM using github actions+pages 71 - [oddshub](https://github.com/dos-2/oddshub) - A TUI designed for analyzing sports betting odds 72 73 ## Pure Go Terminfo Database 74 75 _Tcell_ includes a full parser and expander for terminfo capability strings, 76 so that it can avoid hard coding escape strings for formatting. It also favors 77 portability, and includes support for all POSIX systems. 78 79 The database is also flexible & extensible, and can be modified by either running 80 a program to build the entire database, or an entry for just a single terminal. 81 82 ## More Portable 83 84 _Tcell_ is portable to a wide variety of systems, and is pure Go, without 85 any need for CGO. 86 _Tcell_ is believed to work with mainstream systems officially supported by golang. 87 88 ## No Async IO 89 90 _Tcell_ is able to operate without requiring `SIGIO` signals (unlike _termbox_), 91 or asynchronous I/O, and can instead use standard Go file objects and Go routines. 92 This means it should be safe, especially for 93 use with programs that use exec, or otherwise need to manipulate the tty streams. 94 This model is also much closer to idiomatic Go, leading to fewer surprises. 95 96 ## Rich Unicode & non-Unicode support 97 98 _Tcell_ includes enhanced support for Unicode, including wide characters and 99 combining characters, provided your terminal can support them. 100 Note that 101 Windows terminals generally don't support the full Unicode repertoire. 102 103 It will also convert to and from Unicode locales, so that the program 104 can work with UTF-8 internally, and get reasonable output in other locales. 105 _Tcell_ tries hard to convert to native characters on both input and output. 106 On output _Tcell_ even makes use of the alternate character set to facilitate 107 drawing certain characters. 108 109 ## More Function Keys 110 111 _Tcell_ also has richer support for a larger number of special keys that some 112 terminals can send. 113 114 ## Better Color Handling 115 116 _Tcell_ will respect your terminal's color space as specified within your terminfo entries. 117 For example attempts to emit color sequences on VT100 terminals 118 won't result in unintended consequences. 119 120 In legacy Windows mode, _Tcell_ supports 16 colors, bold, dim, and reverse, 121 instead of just termbox's 8 colors with reverse. (Note that there is some 122 conflation with bold/dim and colors.) 123 Modern Windows 10 can benefit from much richer colors however. 124 125 _Tcell_ maps 16 colors down to 8, for terminals that need it. 126 (The upper 8 colors are just brighter versions of the lower 8.) 127 128 ## Better Mouse Support 129 130 _Tcell_ supports enhanced mouse tracking mode, so your application can receive 131 regular mouse motion events, and wheel events, if your terminal supports it. 132 133 (Note: The Windows 10 Terminal application suffers from a flaw in this regard, 134 and does not support mouse interaction. The stock Windows 10 console host 135 fired up with cmd.exe or PowerShell works fine however.) 136 137 ## _Termbox_ Compatibility 138 139 A compatibility layer for _termbox_ is provided in the `compat` directory. 140 To use it, try importing `github.com/gdamore/tcell/termbox` instead. 141 Most _termbox-go_ programs will probably work without further modification. 142 143 ## Working With Unicode 144 145 Internally _Tcell_ uses UTF-8, just like Go. 146 However, _Tcell_ understands how to 147 convert to and from other character sets, using the capabilities of 148 the `golang.org/x/text/encoding` packages. 149 Your application must supply 150 them, as the full set of the most common ones bloats the program by about 2 MB. 151 If you're lazy, and want them all anyway, see the `encoding` sub-directory. 152 153 ## Wide & Combining Characters 154 155 The `SetContent()` API takes a primary rune, and an optional list of combining runes. 156 If any of the runes is a wide (East Asian) rune occupying two cells, 157 then the library will skip output from the following cell. Care must be 158 taken in the application to avoid explicitly attempting to set content in the 159 next cell, otherwise the results are undefined. (Normally the wide character 160 is displayed, and the other character is not; do not depend on that behavior.) 161 162 Older terminal applications (especially on systems like Windows 8) lack support 163 for advanced Unicode, and thus may not fare well. 164 165 ## Colors 166 167 _Tcell_ assumes the ANSI/XTerm color model, including the 256 color map that 168 XTerm uses when it supports 256 colors. The terminfo guidance will be 169 honored, with respect to the number of colors supported. Also, only 170 terminals which expose ANSI style `setaf` and `setab` will support color; 171 if you have a color terminal that only has `setf` and `setb`, please submit 172 a ticket. 173 174 ## 24-bit Color 175 176 _Tcell_ _supports 24-bit color!_ (That is, if your terminal can support it.) 177 178 NOTE: Technically the approach of using 24-bit RGB values for color is more 179 accurately described as "direct color", but most people use the term "true color". 180 We follow the (inaccurate) common convention. 181 182 There are a few ways you can enable (or disable) true color. 183 184 - For many terminals, we can detect it automatically if your terminal 185 includes the `RGB` or `Tc` capabilities (or rather it did when the database 186 was updated.) 187 188 - You can force this one by setting the `COLORTERM` environment variable to 189 `24-bit`, `truecolor` or `24bit`. This is the same method used 190 by most other terminal applications that support 24-bit color. 191 192 - If you set your `TERM` environment variable to a value with the suffix `-truecolor` 193 then 24-bit color compatible with XTerm and ECMA-48 will be assumed. 194 (This feature is deprecated. 195 It is recommended to use one of other methods listed above.) 196 197 - You can disable 24-bit color by setting `TCELL_TRUECOLOR=disable` in your 198 environment. 199 200 When using TrueColor, programs will display the colors that the programmer 201 intended, overriding any "`themes`" you may have set in your terminal 202 emulator. (For some cases, accurate color fidelity is more important 203 than respecting themes. For other cases, such as typical text apps that 204 only use a few colors, its more desirable to respect the themes that 205 the user has established.) 206 207 ## Performance 208 209 Reasonable attempts have been made to minimize sending data to terminals, 210 avoiding repeated sequences or drawing the same cell on refresh updates. 211 212 ## Terminfo 213 214 (Not relevant for Windows users.) 215 216 The Terminfo implementation operates with a built-in database. 217 This should satisfy most users. However, it can also (on systems 218 with ncurses installed), dynamically parse the output from `infocmp` 219 for terminals it does not already know about. 220 221 See the `terminfo/` directory for more information about generating 222 new entries for the built-in database. 223 224 _Tcell_ requires that the terminal support the `cup` mode of cursor addressing. 225 Ancient terminals without the ability to position the cursor directly 226 are not supported. 227 This is unlikely to be a problem; such terminals have not been mass-produced 228 since the early 1970s. 229 230 ## Mouse Support 231 232 Mouse support is detected via the `kmous` terminfo variable, however, 233 enablement/disablement and decoding mouse events is done using hard coded 234 sequences based on the XTerm X11 model. All popular 235 terminals with mouse tracking support this model. (Full terminfo support 236 is not possible as terminfo sequences are not defined.) 237 238 On Windows, the mouse works normally. 239 240 Mouse wheel buttons on various terminals are known to work, but the support 241 in terminal emulators, as well as support for various buttons and 242 live mouse tracking, varies widely. 243 Modern _xterm_, macOS _Terminal_, and _iTerm_ all work well. 244 245 ## Bracketed Paste 246 247 Terminals that appear to support the XTerm mouse model also can support 248 bracketed paste, for applications that opt-in. See `EnablePaste()` for details. 249 250 ## Testability 251 252 There is a `SimulationScreen`, that can be used to simulate a real screen 253 for automated testing. The supplied tests do this. The simulation contains 254 event delivery, screen resizing support, and capabilities to inject events 255 and examine "`physical`" screen contents. 256 257 ## Platforms 258 259 ### POSIX (Linux, FreeBSD, macOS, Solaris, etc.) 260 261 Everything works using pure Go on mainstream platforms. Some more esoteric 262 platforms (e.g., AIX) may need to be added. Pull requests are welcome! 263 264 ### Windows 265 266 Windows console mode applications are supported. 267 268 Modern console applications like ConEmu and the Windows 10 terminal, 269 support all the good features (resize, mouse tracking, etc.) 270 271 ### WASM 272 273 WASM is supported, but needs additional setup detailed in [README-wasm](README-wasm.md). 274 275 ### Plan9 and others 276 277 These platforms won't work, but compilation stubs are supplied 278 for folks that want to include parts of this in software for those 279 platforms. The Simulation screen works, but as _Tcell_ doesn't know how to 280 allocate a real screen object on those platforms, `NewScreen()` will fail. 281 282 If anyone has wisdom about how to improve support for these, 283 please let me know. PRs are especially welcome. 284 285 ### Commercial Support 286 287 _Tcell_ is absolutely free, but if you want to obtain commercial, professional support, there are options. 288 289 - [TideLift](https://tidelift.com/) subscriptions include support for _Tcell_, as well as many other open source packages. 290 - [Staysail Systems Inc.](mailto:info@staysail.tech) offers direct support, and custom development around _Tcell_ on an hourly basis.