OrgGo/tcell
1
0
Fork 0
mirror of https://github.com/gdamore/tcell.git synced 2025-04-26 13:48:53 +08:00
Code Issues Projects Releases Wiki Activity

Update documentation for V2.

Browse Source
This commit is contained in:
Garrett D'Amore 2020-10-16 00:05:26 -07:00
parent 197faf3eae
commit 260932a7ea
2 changed files with 57 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
CHANGESv2.adoc
View File

@ -4,13 +4,16 @@ A number of changes were made to _Tcell_ for version two, and some of these
are breaking. are breaking.
=== Import Path === Import Path
The import path for tcell has changed to `github.com/gdamore/tcell/v2` to reflect a new major version. The import path for tcell has changed to `github.com/gdamore/tcell/v2` to reflect a new major version.
=== Style Is Not Numeric === Style Is Not Numeric
The type `Style` has changed to a structure, to allow us to add additional data such as flags for color setting, more attribute bits, and so forth. The type `Style` has changed to a structure, to allow us to add additional data such as flags for color setting, more attribute bits, and so forth.
Applications that relied on being a number will need to be updated to use the accessor methods. Applications that relied on this being a number will need to be updated to use the accessor methods.
=== Mouse Event Changes === Mouse Event Changes
The middle mouse button was reported as button 2 on Linux, but as button 3 on Windows, The middle mouse button was reported as button 2 on Linux, but as button 3 on Windows,
and the right mouse button was reported the reverse way. and the right mouse button was reported the reverse way.
_Tcell_ now always reports the right mouse button as button 2, and the middle button as button 3. _Tcell_ now always reports the right mouse button as button 2, and the middle button as button 3.
@ -21,15 +24,16 @@ Usually the left button will be considered the Primary, and the right will be th
Applications may need to adjust their handling of mouse buttons 2 and 3 accordingly. Applications may need to adjust their handling of mouse buttons 2 and 3 accordingly.
=== Terminals Removed === Terminals Removed
A number of terminals have been removed. A number of terminals have been removed.
These are mostly ancient definitions unlikey to be used by anyone, such as `adm3a`. These are mostly ancient definitions unlikely to be used by anyone, such as `adm3a`.
=== High Number Function Keys === High Number Function Keys
Historically terminfo reported function keys with modifiers set as a different Historically terminfo reported function keys with modifiers set as a different
function key altogether. For example, Shift-F1 was reported as F13 on xterm. function key altogether. For example, Shift-F1 was reported as F13 on XTerm.
_Tcell_ now prefers to report these using the base key (such as F1) with modifiers added. _Tcell_ now prefers to report these using the base key (such as F1) with modifiers added.
This works on xterm and VTE based emulators, but some emulators may not support this. This works on XTerm and VTE based emulators, but some emulators may not support this.
The new behavior more closely aligns with behavior on Windows platforms. The new behavior more closely aligns with behavior on Windows platforms.
== New Features in _Tcell_ v2 == New Features in _Tcell_ v2
@ -49,8 +53,7 @@ use that palette entry as is; this should avoid some inconsistency and undesirab
overriding of colors where colors would override settings made in the terminal. overriding of colors where colors would override settings made in the terminal.
When true fidelity to RGB values is needed, the new `TrueColor()` API can be used When true fidelity to RGB values is needed, the new `TrueColor()` API can be used
to create a color that is precisely the direct color, which bypasses the palette to create a direct color, which bypasses the palette altogether.
altogether.
=== Automatic TrueColor Detection === Automatic TrueColor Detection
@ -59,7 +62,7 @@ _Tcell_ will automatically assume the terminal supports 24-bit color.
=== ColorReset === ColorReset
A new color value, `ColorReset` can be used on the foreground or the background A new color value, `ColorReset` can be used on the foreground or background
to reset the color the default used by the terminal. to reset the color the default used by the terminal.
=== tmux Support === tmux Support
@ -69,3 +72,11 @@ _Tcell_ now has improved support for tmux, when the `$TERM` variable is set to "
=== Strikethrough Support === Strikethrough Support
_Tcell_ has support for strikethrough when the terminal supports it, using the new `StrikeThrough()` API. _Tcell_ has support for strikethrough when the terminal supports it, using the new `StrikeThrough()` API.
=== Bracketed Paste Support
_Tcell_ provides the long requested capability to discriminate paste event by using the
bracketed-paste capability present in some terminals. This is automatically available on
terminals that support XTerm style mouse handling, but applications must opt-in to this
by using the new `EnablePaste()` function. A new `EventPaste` type of event will be
delivered when starting and finishing a paste operation.

98
README.adoc
View File

@ -11,15 +11,14 @@ image:https://codecov.io/gh/gdamore/tcell/branch/master/graph/badge.svg[codecov,
[cols="2",grid="none"] [cols="2",grid="none"]
|=== |===
|_Tcell_ is a _Go_ package that provides a cell based view for text terminals, like _xterm_. |_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. It was inspired by _termbox_, but includes many additional improvements.
a|[.right] a|[.right]
image::logos/tcell.png[float="right"] image::logos/tcell.png[float="right"]
|=== |===
NOTE: Work has begun on version 2.0 of _Tcell_. There are breaking changes (and more coming.) NOTE: This is version 2 of _Tcell_. There are breaking changes relative to version 1.
Version 1.x is available using the import `github.com/gdamore/tcell`. Version 1.x remains available using the import `github.com/gdamore/tcell`.
The new work in progress is available using master and `github.com/gdamore/tcell/v2`.
== Examples == Examples
@ -60,12 +59,9 @@ a program to build the entire database, or an entry for just a single terminal.
== More Portable == More Portable
_Tcell_ is portable to a wide variety of systems. _Tcell_ is portable to a wide variety of systems, and is pure Go, without
_Tcell_ is believed any need for CGO.
to work with all of the systems officially supported by golang with _Tcell_ is believed to work with mainstream systems officially supported by golang.
the exception of nacl (which lacks any kind of a terminal interface).
(Plan9 is not supported by _Tcell_, but it is experimental status only
in golang.) _Tcell_ is pure Go, without any need for CGO.
== No Async IO == No Async IO
@ -143,9 +139,8 @@ taken in the application to avoid explicitly attempting to set content in the
next cell, otherwise the results are undefined. (Normally wide character next cell, otherwise the results are undefined. (Normally wide character
is displayed, and the other character is not; do not depend on that behavior.) is displayed, and the other character is not; do not depend on that behavior.)
Experience has shown that the vanilla Windows 8 console application does not Older terminal applications (especially on systems like Windows 8) lack support
support any of these characters properly, but at least some options like for advanced Unicode, and thus may not fare well.
_ConEmu_ do support Wide characters.
== Colors == Colors
@ -153,16 +148,16 @@ _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 XTerm uses when it supports 256 colors. The terminfo guidance will be
honored, with respect to the number of colors supported. Also, only honored, with respect to the number of colors supported. Also, only
terminals which expose ANSI style `setaf` and `setab` will support color; terminals which expose ANSI style `setaf` and `setab` will support color;
if you have a color terminal that only has `setf` and `setb`, please let me if you have a color terminal that only has `setf` and `setb`, please submit
know; it wouldn't be hard to add that if there is need. a ticket; it wouldn't be hard to add that if there is need.
== 24-bit Color == 24-bit Color
_Tcell_ _supports true color_! (That is, if your terminal can support it, _Tcell_ _supports true color_! (That is, if your terminal can support it,
_Tcell_ can accurately display 24-bit color.) _Tcell_ can accurately display 24-bit color.)
To use 24-bit color, you need to use a terminal that supports it. Modern To use 24-bit color, you need to use a terminal with support. Modern
xterm and similar teminal emulators can support this. As terminfo lacks any XTerm and similar terminal emulators can support this. As terminfo lacks any
way to describe this capability, we fabricate the capability for way to describe this capability, we fabricate the capability for
terminals with names ending in `*-truecolor`. The stock distribution ships terminals with names ending in `*-truecolor`. The stock distribution ships
with a database that defines `xterm-truecolor`. with a database that defines `xterm-truecolor`.
@ -189,27 +184,18 @@ avoiding repeated sequences or drawing the same cell on refresh updates.
(Not relevant for Windows users.) (Not relevant for Windows users.)
The Terminfo implementation operates with two forms of database. The first The Terminfo implementation operates with a built-in database.
is the built-in go database, which contains a number of real database entries This should satisfy most users. However, it can also (on systems
that are compiled into the program directly. This should minimize calling with ncurses installed), dynamically parse the output from `infocmp`
out to database file searches. for terminals it does not already know about.
The second is in the form of JSON files, that contain the same information, See the `terminfo/` directory for more information about generating
which can be located either by the `$TCELLDB` environment file, `$HOME/.tcelldb`, new entries for the built-in database.
or is located in the Go source directory as `database.json`.
These files (both the Go and the JSON files) can be generated using the
mkinfo.go program. If you need to regnerate the entire set for some reason,
run the mkdatabase.sh file. The generation uses the infocmp(1) program on
the system to collect the necessary information.
The `mkinfo.go` program can also be used to generate specific database entries
for named terminals, in case your favorite terminal is missing. (If you
find that this is the case, please let me know and I'll try to add it!)
_Tcell_ requires that the terminal support the `cup` mode of cursor addressing. _Tcell_ requires that the terminal support the `cup` mode of cursor addressing.
Terminals without absolute cursor addressability are not supported. Ancient terminals without the ability to position the cursor directly
This is unlikely to be a problem; such terminals have not been mass produced are not supported.
This is unlikely to be a problem; such terminals have not been mass-produced
since the early 1970s. since the early 1970s.
== Mouse Support == Mouse Support
@ -226,7 +212,12 @@ Mouse wheel buttons on various terminals are known to work, but the support
in terminal emulators, as well as support for various buttons and 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. live mouse tracking, varies widely. Modern _xterm_, macOS _Terminal_, and _iTerm_ all work well.
== Testablity == 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 There is a `SimulationScreen`, that can be used to simulate a real screen
for automated testing. The supplied tests do this. The simulation contains for automated testing. The supplied tests do this. The simulation contains
@ -237,34 +228,26 @@ and examine "`physical`" screen contents.
=== POSIX (Linux, FreeBSD, macOS, Solaris, etc.) === POSIX (Linux, FreeBSD, macOS, Solaris, etc.)
For mainstream systems with a suitably well defined system call interface Everything works using pure Go on mainstream platforms. Some more esoteric
to tty settings, everything works using pure Go. platforms (e.g. AIX) may need to be added. Pull requests are welcome!
For the remainder (right now means only Solaris/illumos) we use POSIX function
calls to manage termios, which implies that CGO is required on those platforms.
=== Windows === Windows
Windows console mode applications are supported. Unfortunately _mintty_ Windows console mode applications are supported. Unfortunately _mintty_
and other _cygwin_ style applications are not supported. and other _cygwin_ style applications are not supported, and are
unlikely to be supportable due to limitations in their design.
Modern console applications like ConEmu, as well as the Windows 10 Modern console applications like ConEmu and the Windows 10 terminal,
console itself, support all the good features (resize, mouse tracking, etc.) support all the good features (resize, mouse tracking, etc.)
I haven't figured out how to cleanly resolve the dichotomy between cygwin === Plan9, WASM, and others
style termios and the Windows Console API; it seems that perhaps nobody else
has either. If anyone has suggestions, let me know! Really, if you're
using a Windows application, you should use the native Windows console or a
fully compatible console implementation.
=== Plan9 and Native Client (Nacl) These platforms won't work, but compilation stubs are supplied
for folks that want to include parts of this in software for those
The nacl and plan9 platforms won't work, but compilation stubs are supplied platforms. The Simulation screen works, but as _Tcell_ doesn't know how to
for folks that want to include parts of this in software targetting 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. allocate a real screen object on those platforms, `NewScreen()` will fail.
If anyone has wisdom about how to improve support for either of these, If anyone has wisdom about how to improve support for these,
please let me know. PRs are especially welcome. please let me know. PRs are especially welcome.
=== Commercial Support === Commercial Support
@ -282,8 +265,3 @@ https://tidelift.com/[Tidelift] subscriptions include support for _Tcell_, as we
image:logos/staysail.png[100,100] image:logos/staysail.png[100,100]
a| a|
mailto:info@staysail.tech[Staysail Systems, Inc.] offers direct support, and custom development around _Tcell_ on an hourly basis. mailto:info@staysail.tech[Staysail Systems, Inc.] offers direct support, and custom development around _Tcell_ on an hourly basis.
^.^|
image:logos/patreon.png[100,100]
a|I also welcome donations at https://www.patreon.com/gedamore/[Patreon], if you just want to make a contribution.
|===