mirror of https://github.com/gdamore/tcell.git
Convert documentation to Markdown.
While asciidoc is probably technically more flexible, some sites (such as pkg.go.dev) do not support it well. For the basic docs we have here, the extra richness from asciidoc is not needed, and we would prefer not to sacrifice the broader support that MarkDown enjoys. While here the text was cleaned up, made consistent, with grammar and spelling fixes. The Tutorial was revised somewhat to provide more accurate guidance for readers.
This commit is contained in:
Garrett D'Amore
parent
b60a903b98
commit
0de353bdce
|
|
@ -1,18 +1,18 @@
|
|||
== Breaking Changes in _Tcell_ v2
|
||||
## Breaking Changes in _Tcell_ v2
|
||||
|
||||
A number of changes were made to _Tcell_ for version two, and some of these
|
||||
are breaking.
|
||||
A number of changes were made to _Tcell_ for version two, and some of these 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.
|
||||
|
||||
=== 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 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,
|
||||
and the right mouse button was reported the reverse way.
|
||||
|
|
@ -23,12 +23,12 @@ To help make this clearer, new symbols `ButtonPrimary`, `ButtonSecondary`, and
|
|||
Usually the left button will be considered the Primary, and the right will be the Secondary.)
|
||||
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.
|
||||
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
|
||||
function key altogether. For example, Shift-F1 was reported as F13 on XTerm.
|
||||
|
|
@ -36,44 +36,44 @@ _Tcell_ now prefers to report these using the base key (such as F1) with modifie
|
|||
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.
|
||||
|
||||
== New Features in _Tcell_ v2
|
||||
## New Features in _Tcell_ v2
|
||||
|
||||
These features are not breaking, but are introduced in version 2.
|
||||
|
||||
=== Improved Modifier Support
|
||||
### Improved Modifier Support
|
||||
|
||||
For terminals that appear to behave like the venerable XTerm, _tcell_
|
||||
automatically adds modifier reporting for ALT, CTRL, SHIFT, and META keys
|
||||
when the terminal reports them.
|
||||
|
||||
=== Better Support for Palettes (Themes)
|
||||
### Better Support for Palettes (Themes)
|
||||
|
||||
When using a color by its name or palette entry, _Tcell_ now tries to
|
||||
use that palette entry as is; this should avoid some inconsistency and undesirable
|
||||
overriding of colors where colors would override settings made in the terminal.
|
||||
use that palette entry as is; this should avoid some inconsistency and respect
|
||||
terminal themes correctly.
|
||||
|
||||
When true fidelity to RGB values is needed, the new `TrueColor()` API can be used
|
||||
to create a direct color, which bypasses the palette altogether.
|
||||
|
||||
=== Automatic TrueColor Detection
|
||||
### Automatic TrueColor Detection
|
||||
|
||||
For some terminals, if the `Tc` or `RGB` properties are present in terminfo,
|
||||
_Tcell_ will automatically assume the terminal supports 24-bit color.
|
||||
|
||||
=== ColorReset
|
||||
### ColorReset
|
||||
|
||||
A new color value, `ColorReset` can be used on the foreground or background
|
||||
to reset the color the default used by the terminal.
|
||||
|
||||
=== tmux Support
|
||||
### tmux Support
|
||||
|
||||
_Tcell_ now has improved support for tmux, when the `$TERM` variable is set to "tmux".
|
||||
|
||||
=== Strikethrough Support
|
||||
### Strikethrough Support
|
||||
|
||||
_Tcell_ has support for strikethrough when the terminal supports it, using the new `StrikeThrough()` API.
|
||||
|
||||
=== Bracketed Paste Support
|
||||
### 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
|
||||
|
|
@ -1,88 +1,81 @@
|
|||
= tcell
|
||||
|
||||
# 
|
||||
|
||||
image:https://img.shields.io/travis/gdamore/tcell.svg?label=linux[Linux Status,link="https://travis-ci.org/gdamore/tcell"]
|
||||
image:https://img.shields.io/appveyor/ci/gdamore/tcell.svg?label=windows[Windows Status,link="https://ci.appveyor.com/project/gdamore/tcell"]
|
||||
image:https://img.shields.io/badge/license-APACHE2-blue.svg[Apache License,link="https://github.com/gdamore/tcell/blob/master/LICENSE"]
|
||||
image:https://img.shields.io/badge/godoc-reference-blue.svg[GoDoc,link="https://godoc.org/github.com/gdamore/tcell"]
|
||||
image:https://goreportcard.com/badge/gdamore/tcell[Go Report Card,link="http://goreportcard.com/report/gdamore/tcell"]
|
||||
image:https://img.shields.io/discord/639503822733180969?label=discord[Discord,link="https://discord.gg/urTTxDN"]
|
||||
image:https://codecov.io/gh/gdamore/tcell/branch/master/graph/badge.svg[codecov,link="https://codecov.io/gh/gdamore/tcell"]
|
||||
|
||||
[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.
|
||||
a|[.right]
|
||||
image::logos/tcell.png[float="right"]
|
||||
|===
|
||||
|
||||
[](https://travis-ci.org/gdamore/tcell)
|
||||
[](https://ci.appveyor.com/project/gdamore/tcell)
|
||||
[](https://github.com/gdamore/tcell/blob/master/LICENSE)
|
||||
[](https://pkg.go.dev/github.com/gdamore/tcell/v2)
|
||||
[](http://goreportcard.com/report/gdamore/tcell/v2)
|
||||
[](https://discord.gg/urTTxDN)
|
||||
[](https://codecov.io/gh/gdamore/tcell)
|
||||
|
||||
|
||||
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`.
|
||||
|
||||
== Examples
|
||||
## 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.
|
||||
* [proxima5](https://github.com/gdamore/proxima5) - space shooter ([video](https://youtu.be/jNxKTCmY_bQ))
|
||||
* [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))
|
||||
* 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))
|
||||
* [gomatrix](https://github.com/gdamore/gomatrix) - converted from Termbox
|
||||
* [micro](https://github.com/zyedidia/micro/) - lightweight text editor with syntax-highlighting and themes
|
||||
* [godu](https://github.com/viktomas/godu) - utility to discover large files/folders
|
||||
* [tview](https://github.com/rivo/tview/) - rich interactive widgets
|
||||
* [awsome gocui](https://github.com/awesome-gocui/gocui) - Go Console User Interface
|
||||
* [gomandelbrot](https://github.com/rgm3/gomandelbrot) - Mandelbrot!
|
||||
* [WTF](https://github.com/senorprogrammer/wtf) - personal information dashboard
|
||||
* [browsh](https://github.com/browsh-org/browsh) - modern web browser ([video](https://www.youtube.com/watch?v=HZq86XfBoRo))
|
||||
* [go-life](https://github.com/sachaos/go-life) - Conway's Game of Life
|
||||
* [gowid](https://github.com/gcla/gowid) - compositional widgets for terminal UIs, inspired by _urwid_
|
||||
* [termshark](https://termshark.io) - interface for _tshark_, inspired by Wireshark, built on _gowid_
|
||||
* [go-tetris](https://github.com/MichaelS11/go-tetris) - Go Tetris with AI option
|
||||
* [fzf](https://github.com/junegunn/fzf) - command-line fuzzy finder
|
||||
* [ascii-fluid](https://github.com/esimov/ascii-fluid) - fluid simulation controlled by webcam
|
||||
* [cbind](https://gitlab.com/tslocum/cbind) - provides key event encoding, decoding and handling
|
||||
* [tpong](https://github.com/spinzed/tpong) - old-school Pong
|
||||
* [aerc](https://git.sr.ht/~sircmpwn/aerc) - email client
|
||||
* [tblogs](https://github.com/ezeoleaf/tblogs) - development blogs reader
|
||||
* [spinc](https://github.com/lallassu/spinc) - _irssi_ inspired chat application for Cisco Spark/WebEx
|
||||
* [gorss](https://github.com/lallassu/gorss) - RSS/Atom feed reader
|
||||
* [memoryalike](https://github.com/Bios-Marcel/memoryalike) - memorization game
|
||||
* [lf](https://github.com/gokcehan/lf) - file manager
|
||||
* [gokeybr](https://github.com/bunyk/gokeybr) - deliberately practice your typing
|
||||
* [gonano](https://github.com/jbaramidze/gonano) - editor, mimics _nano_
|
||||
* [uchess](https://github.com/tmountain/uchess) - UCI chess client
|
||||
* [min](https://github.com/a-h/min) - Gemini browser
|
||||
* [ov](https://github.com/noborus/ov) - file pager
|
||||
* [tmux-wormhole](https://github.com/gcla/tmux-wormhole) - _tmux_ plugin to transfer files
|
||||
* [gruid-tcell](https://github.com/anaseto/gruid-tcell) - driver for the grid based UI and game framework
|
||||
* [aretext](https://github.com/aretext/aretext) - minimalist text editor with _vim_ key bindings
|
||||
|
||||
== Pure Go Terminfo Database
|
||||
## 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
|
||||
The database is also flexible & extensible, and can be modified by either running
|
||||
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, and is pure Go, without
|
||||
any need for CGO.
|
||||
_Tcell_ is believed to work with mainstream systems officially supported by golang.
|
||||
|
||||
== No Async IO
|
||||
## 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.
|
||||
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.
|
||||
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
|
||||
## Rich Unicode & non-Unicode support
|
||||
|
||||
_Tcell_ includes enhanced support for Unicode, including wide characters and
|
||||
combining characters, provided your terminal can support them.
|
||||
|
|
@ -91,18 +84,19 @@ 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
|
||||
_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.
|
||||
|
||||
== More Function Keys
|
||||
## More Function Keys
|
||||
|
||||
_Tcell_ also has richer support for a larger number of special keys that some terminals can send.
|
||||
_Tcell_ also has richer support for a larger number of special keys that some
|
||||
terminals can send.
|
||||
|
||||
== Better Color Handling
|
||||
## 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
|
||||
_Tcell_ will respect your terminal's color space as specified within your terminfo entries.
|
||||
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,
|
||||
|
|
@ -113,7 +107,7 @@ 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
|
||||
## 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.
|
||||
|
|
@ -122,51 +116,50 @@ regular mouse motion events, and wheel events, if your terminal supports it.
|
|||
and does not support mouse interaction. The stock Windows 10 console host
|
||||
fired up with cmd.exe or PowerShell works fine however.)
|
||||
|
||||
== _Termbox_ Compatibility
|
||||
## _Termbox_ Compatibility
|
||||
|
||||
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.
|
||||
|
||||
== Working With Unicode
|
||||
## Working With Unicode
|
||||
|
||||
Internally Tcell uses UTF-8, just like Go.
|
||||
However, Tcell understands how to
|
||||
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.
|
||||
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.
|
||||
|
||||
== Wide & Combining Characters
|
||||
## 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
|
||||
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 wide character
|
||||
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.)
|
||||
|
||||
Older terminal applications (especially on systems like Windows 8) lack support
|
||||
for advanced Unicode, and thus may not fare well.
|
||||
|
||||
== Colors
|
||||
## 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.
|
||||
a ticket.
|
||||
|
||||
== 24-bit Color
|
||||
## 24-bit Color
|
||||
|
||||
_Tcell_ _supports true color_! (That is, if your terminal can support it,
|
||||
_Tcell_ can accurately display 24-bit color.)
|
||||
_Tcell_ _supports 24-bit color!_ (That is, if your terminal can support it.)
|
||||
|
||||
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.
|
||||
accurately 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.
|
||||
|
||||
|
|
@ -175,15 +168,13 @@ 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
|
||||
`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.
|
||||
then 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=disable` in your
|
||||
environment.
|
||||
|
|
@ -195,12 +186,12 @@ 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
|
||||
## Performance
|
||||
|
||||
Reasonable attempts have been made to minimize sending data to terminals,
|
||||
avoiding repeated sequences or drawing the same cell on refresh updates.
|
||||
|
||||
== Terminfo
|
||||
## Terminfo
|
||||
|
||||
(Not relevant for Windows users.)
|
||||
|
||||
|
|
@ -218,11 +209,11 @@ 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
|
||||
|
||||
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
|
||||
sequences based on the XTerm X11 model. All popular
|
||||
terminals with mouse tracking support this model. (Full terminfo support
|
||||
is not possible as terminfo sequences are not defined.)
|
||||
|
||||
|
|
@ -230,35 +221,36 @@ 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.
|
||||
live mouse tracking, varies widely.
|
||||
Modern _xterm_, macOS _Terminal_, and _iTerm_ all work well.
|
||||
|
||||
== Bracketed Paste
|
||||
## 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
|
||||
## 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
|
||||
## Platforms
|
||||
|
||||
=== POSIX (Linux, FreeBSD, macOS, Solaris, etc.)
|
||||
### 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!
|
||||
platforms (e.g., AIX) may need to be added. Pull requests are welcome!
|
||||
|
||||
=== Windows
|
||||
### 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
|
||||
### 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
|
||||
|
|
@ -268,18 +260,9 @@ 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
|
||||
### 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:info@staysail.tech[Staysail Systems, Inc.] offers direct support, and custom development around _Tcell_ on an hourly basis.
|
||||
* [TideLift](https://tidelift.com/) subscriptions include support for _Tcell_, as well as many other open source packages.
|
||||
* [Staysail Systems Inc.](mailto:info@staysail.tech) offers direct support, and custom development around _Tcell_ on an hourly basis.
|
||||
|
|
@ -1,30 +1,32 @@
|
|||
= tcell tutorial
|
||||
# _Tcell_ Tutorial
|
||||
|
||||
tcell provides a low-level, portable API for building terminal-based programs.
|
||||
A https://en.wikipedia.org/wiki/Terminal_emulator[terminal emulator] is used to
|
||||
interact with such a program.
|
||||
_Tcell_ provides a low-level, portable API for building terminal-based programs.
|
||||
A [terminal emulator](https://en.wikipedia.org/wiki/Terminal_emulator)
|
||||
(or a real terminal such as a DEC VT-220) is used to interact with such a program.
|
||||
|
||||
Applications typically initialize a screen and enter an event loop, then
|
||||
finalize the screen before exiting.
|
||||
_Tcell_'s interface is fairly low-level.
|
||||
While it provides a reasonably portable way of dealing with all the usual terminal
|
||||
features, it may be easier to utilize a higher level framework.
|
||||
A number of such frameworks are listed on the _Tcell_ main [README](README.md).
|
||||
|
||||
Application frameworks such as https://github.com/rivo/tview[tview] and
|
||||
https://gitlab.com/tslocum/cview[cview] provide widgets and additional features.
|
||||
This tutorial provides the details of _Tcell_, and is appropriate for developers
|
||||
wishing to create their own application frameworks or needing more direct access
|
||||
to the terminal capabilities.
|
||||
|
||||
== Resize events
|
||||
## Resize events
|
||||
|
||||
Applications receive an event of type `EventResize` when they are first initialized and each time the terminal is resized.
|
||||
The new size is available as `Size`.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
switch ev := ev.(type) {
|
||||
case *tcell.EventResize:
|
||||
w, h := ev.Size()
|
||||
logMessage(fmt.Sprintf("Resized to %dx%d", w, h))
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
== Key events
|
||||
## Key events
|
||||
|
||||
When a key is pressed, applications receive an event of type `EventKey`.
|
||||
This event describes the modifier keys pressed (if any) and the pressed key or rune.
|
||||
|
|
@ -33,16 +35,15 @@ When a rune key is pressed, an event with its `Key` set to `KeyRune` is dispatch
|
|||
|
||||
When a non-rune key is pressed, it is available as the `Key` of the event.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
switch ev := ev.(type) {
|
||||
case *tcell.EventKey:
|
||||
mod, key, ch := ev.Mod(), ev.Key(), ev.Rune()
|
||||
logMessage(fmt.Sprintf("EventKey Modifiers: %d Key: %d Rune: %d", mod, key, ch))
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
=== Key event restrictions
|
||||
### Key event restrictions
|
||||
|
||||
Terminal-based programs have less visibility into keyboard activity than graphical applications.
|
||||
|
||||
|
|
@ -53,12 +54,7 @@ Key release events are not available.
|
|||
It is not possible to distinguish runes typed while holding shift and runes typed using caps lock.
|
||||
Capital letters are reported without the Shift modifier.
|
||||
|
||||
=== Key event handling library
|
||||
|
||||
https://gitlab.com/tslocum/cbind[cbind] provides key event encoding and decoding
|
||||
to and from human-readable strings. It also provides keybinding-based input handling.
|
||||
|
||||
== Mouse events
|
||||
## Mouse events
|
||||
|
||||
Applications receive an event of type `EventMouse` when the mouse moves, or a mouse button is pressed or released.
|
||||
Mouse events are only delivered if
|
||||
|
|
@ -66,8 +62,7 @@ Mouse events are only delivered if
|
|||
|
||||
The mouse buttons being pressed (if any) are available as `Buttons`, and the position of the mouse is available as `Position`.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
switch ev := ev.(type) {
|
||||
case *tcell.EventMouse:
|
||||
mod := ev.Modifiers()
|
||||
|
|
@ -75,46 +70,23 @@ case *tcell.EventMouse:
|
|||
x, y := ev.Position()
|
||||
logMessage(fmt.Sprintf("EventMouse Modifiers: %d Buttons: %d Position: %d,%d", mod, btns, x, y))
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
=== Mouse buttons
|
||||
### Mouse buttons
|
||||
|
||||
[cols=3*,options=header]
|
||||
|===
|
||||
Identifier | Alias | Description
|
||||
-----------|-----------------|-----------
|
||||
Button1 | ButtonPrimary | Left button
|
||||
Button2 | ButtonSecondary | Right button
|
||||
Button3 | ButtonMiddle | Middle button
|
||||
Button4 | | Side button (thumb/next)
|
||||
Button5 | | Side button (thumb/prev)
|
||||
|
||||
|Identifier
|
||||
|Alias
|
||||
|Description
|
||||
|
||||
|Button1
|
||||
|ButtonPrimary
|
||||
|Left button
|
||||
|
||||
|Button2
|
||||
|ButtonSecondary
|
||||
|Right button
|
||||
|
||||
|Button3
|
||||
|ButtonMiddle
|
||||
|Middle button
|
||||
|
||||
|Button4
|
||||
|
|
||||
|Side button (thumb/next)
|
||||
|
||||
|Button5
|
||||
|
|
||||
|Side button (thumb/prev)
|
||||
|
||||
|===
|
||||
|
||||
== Usage
|
||||
## Usage
|
||||
|
||||
To create a tcell application, first initialize a screen to hold it.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
// Initialize screen
|
||||
```golang
|
||||
s, err := tcell.NewScreen()
|
||||
if err != nil {
|
||||
log.Fatalf("%+v", err)
|
||||
|
|
@ -129,21 +101,19 @@ s.SetStyle(defStyle)
|
|||
|
||||
// Clear screen
|
||||
s.Clear()
|
||||
----
|
||||
```
|
||||
|
||||
Text may be drawn on the screen using `SetContent`.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
s.SetContent(0, 0, 'H', nil, defStyle)
|
||||
s.SetContent(1, 0, 'i', nil, defStyle)
|
||||
s.SetContent(2, 0, '!', nil, defStyle)
|
||||
----
|
||||
```
|
||||
|
||||
To draw text more easily, define a render function.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
func drawText(s tcell.Screen, x1, y1, x2, y2 int, style tcell.Style, text string) {
|
||||
row := y1
|
||||
col := x1
|
||||
|
|
@ -159,12 +129,11 @@ func drawText(s tcell.Screen, x1, y1, x2, y2 int, style tcell.Style, text string
|
|||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
Lastly, define an event loop to handle user input and update application state.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
quit := func() {
|
||||
s.Fini()
|
||||
os.Exit(0)
|
||||
|
|
@ -186,14 +155,13 @@ for {
|
|||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
```
|
||||
|
||||
== Demo application
|
||||
## Demo application
|
||||
|
||||
The following demonstrates how to initialize a screen, draw text/graphics and handle user input.
|
||||
|
||||
[source,go]
|
||||
----
|
||||
```golang
|
||||
package main
|
||||
|
||||
import (
|
||||
|
|
@ -322,4 +290,4 @@ func main() {
|
|||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
```
|
||||
Loading…
Reference in New Issue