README
¶
Tcell
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.
[!NOTE] This is version 3 of Tcell. There are breaking changes relative to versions 1 and 2. Version 2 remains available using the import
github.com/gdamore/tcell/v2. Version 1 Version 1.x remains available using the importgithub.com/gdamore/tcell, but is unmaintained and should not be used.
Tutorial
A brief, and still somewhat rough, tutorial is available.
Examples
A number of example are posted up on our Gallery. That's a wiki, and please do submit updates if you have something you want to showcase.
There are also demonstration programs in the ./demos directory, as well as some in ./_demos.
More Portable
Tcell is portable to a wide variety of systems, and is pure Go, without any need for CGO. Tcell works with mainstream systems officially supported by golang.
Following the Go support policy, Tcell officially only supports the current ("stable") version of go, and the version immediately prior ("oldstable"). This policy is necessary to make sure that we can update dependencies to pick up security fixes and new features, and it allows us to adopt changes (such as library and language features) that are only supported in newer versions of Go.
Rich Unicode & non-Unicode support
Tcell includes enhanced support for Unicode, including wide characters and grapheme clusters, provided your terminal can support them.
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. On output Tcell even makes use of the alternate character set to facilitate drawing certain characters.
Better Keyboard Support
Tcell also has richer support for a larger number of special keys that some terminals can send. On modern terminal emulators we can also support a rich set of modifiers, and can discriminate between e.g. CTRL-I and TAB. (This does require the terminal emulator to support one of the modern keyboard protocols.)
Better Mouse Support
Tcell supports enhanced mouse tracking mode, so your application can receive regular mouse motion events, click-drag, and wheel events, if your terminal supports it.
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 2 MB.
If you're lazy, and want them all anyway, see the encoding sub-directory.
Wide & Combining Characters
The Put() API takes a string, which should be legal UTF-8, and displays
the first grapheme cluster (which may composed of multiple runes).
It returns the actual width displayed, which can be used to advance the column positiion
for the next display grapheme. Alternatively, PutStr() or PutStrStyled()
can be used to display a single line of text (which will be clipped at the
edge of the screen).
If a second character is displayed immediately in the cell adjacent to a wide character (offset by one instead of by two), then the results are undefined.
Colors
Tcell assumes the ANSI/XTerm color palette for up to 256 colors, although terminals such as legacy ANSI terminals may only support 8 colors.
24-bit Color
Tcell supports 24-bit color! (That is, if your terminal can support it.)
There are a few ways you can enable (or disable) 24-bit color.
-
You can force this one by setting the
COLORTERMenvironment variable totruecolor. This environment variable is frequently set by terminal emulators that support 24-bit color. -
On Windows, 24-bit color support is assumed. (All modern Windows terminal emulators support it.)
-
If you set your
TERMenvironment variable to a value with the suffix-truecoloror-direct, then 24-bit color compatible with XTerm and ECMA-48 will be assumed. -
You can disable 24-bit color by setting
TCELL_TRUECOLOR=disablein your environment.
When using 24-bit color, programs will display the colors that the programmer
intended, overriding any "themes" the user may have set in their 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.
Mouse Support
Mouse tracking, buttons, and even wheel mice are supported on most terminal emulators, as well as Windows.
Bracketed Paste
Terminals that support support it, can use bracketed paste.
See EnablePaste() for details.
Breaking Changes in v3
There are a number of changes in Tcell version 3, which break compatibility with version 2 and version 1.
Your application will almost certainly need some minor updates to work with version 3.
Please see the CHANGESv3 document for a list.
Platforms
POSIX (Linux, FreeBSD, macOS, Solaris, etc.)
Everything works using pure Go on mainstream platforms. Esoteric platforms (e.g. zOS or AIX) are supported on a best-effort only basis. Pull requests to fix any issues found are welcome!
Windows
Modern Windows is supported. Please see the README-windows document for much more detailed information.
WASM
WASM is supported, but needs additional setup detailed in README-wasm.
Plan 9
Plan 9 is supported on a best-effort basis. Please see the README-plan9 document for more information.
Commercial Support
Tcell is absolutely free, but if you want to obtain commercial, professional support, there are options.
- TideLift subscriptions include support for Tcell, as well as many other open source packages.
- Staysail Systems Inc. offers direct support, and custom development around Tcell on an hourly basis.
Documentation
¶
Overview ¶
Package tcell provides a lower-level, portable API for building programs that interact with terminals or consoles. It works with both common (and many uncommon!) terminals or terminal emulators, and Windows console implementations.
It supports rich color, and modern terminal capabilities such as rich key reporting, mouse tracking, bracketed paste, desktop notifications and 24-bit color, when the underlying terminal supports it.
Index ¶
- Constants
- Variables
- func GetEncoding(charset string) encoding.Encoding
- func RegisterEncoding(charset string, enc encoding.Encoding)
- func SetEncodingFallback(fb EncodingFallback)
- func ShimScreen(s Screen)
- type AttrMask
- type ButtonMask
- type CellBuffer
- func (cb *CellBuffer) Dirty(x, y int) bool
- func (cb *CellBuffer) Fill(r rune, style Style)
- func (cb *CellBuffer) Get(x, y int) (string, Style, int)
- func (cb *CellBuffer) Invalidate()
- func (cb *CellBuffer) LockCell(x, y int)
- func (cb *CellBuffer) Put(x int, y int, str string, style Style) (string, int)
- func (cb *CellBuffer) Resize(w, h int)
- func (cb *CellBuffer) SetDirty(x, y int, dirty bool)
- func (cb *CellBuffer) Size() (int, int)
- func (cb *CellBuffer) UnlockCell(x, y int)
- type Color
- type CursorStyle
- type EncodingFallback
- type Event
- type EventClipboard
- type EventError
- type EventFocus
- type EventHandler
- type EventInterrupt
- type EventKey
- type EventMouse
- type EventPaste
- type EventResize
- type EventTime
- type Key
- type KittyKbdMode
- type ModMask
- type MouseFlags
- type OptColors
- type OptTerm
- type Screen
- type Style
- func (s Style) Attributes(attrs AttrMask) Styledeprecated
- func (s Style) Background(c color.Color) Style
- func (s Style) Blink(on bool) Style
- func (s Style) Bold(on bool) Style
- func (s Style) Dim(on bool) Style
- func (s Style) Foreground(c color.Color) Style
- func (s Style) GetAttributes() AttrMask
- func (s Style) GetBackground() color.Color
- func (s Style) GetForeground() color.Color
- func (s Style) GetUnderlineColor() color.Color
- func (s Style) GetUnderlineStyle() UnderlineStyle
- func (s Style) GetUrl() (id string, url string)
- func (s Style) HasBlink() bool
- func (s Style) HasBold() bool
- func (s Style) HasDim() bool
- func (s Style) HasItalic() bool
- func (s Style) HasReverse() bool
- func (s Style) HasStrikeThrough() bool
- func (s Style) HasUnderline() bool
- func (s Style) Italic(on bool) Style
- func (s Style) Normal() Style
- func (s Style) Reverse(on bool) Style
- func (s Style) StrikeThrough(on bool) Style
- func (s Style) Underline(params ...any) Style
- func (s Style) Url(url string) Style
- func (s Style) UrlId(id string) Style
- type TerminfoScreenOption
- type Tty
- type UnderlineStyle
- type WindowSize
- type XtermKbdMode
Examples ¶
Constants ¶
const ( // ColorDefault is used to leave the Color unchanged from whatever // system or terminal default may exist. It's also the zero value. ColorDefault = color.Default // ColorValid is used to indicate the color value is actually // valid (initialized). // Deprecated: Use color.IsValid instead. ColorValid = color.IsValid // ColorIsRGB is used to indicate that the numeric value is not // a known color constant, but rather an RGB value. // Deprecated: Use color.IsRGB instead. ColorIsRGB = color.IsRGB // ColorSpecial is a flag used to indicate that the values have // special meaning, and live outside of the color space(s). // Deprecated. ColorSpecial = color.IsSpecial )
const ( ColorBlack = color.XTerm0 ColorMaroon = color.XTerm1 ColorGreen = color.XTerm2 ColorOlive = color.XTerm3 ColorPurple = color.XTerm5 ColorTeal = color.XTerm6 ColorSilver = color.XTerm7 ColorGray = color.XTerm8 ColorRed = color.XTerm9 ColorLime = color.XTerm10 ColorYellow = color.XTerm11 ColorBlue = color.XTerm12 ColorFuchsia = color.XTerm13 ColorAqua = color.XTerm14 ColorWhite = color.XTerm15 Color16 = color.XTerm16 Color17 = color.XTerm17 Color18 = color.XTerm18 Color19 = color.XTerm19 Color20 = color.XTerm20 Color21 = color.XTerm21 Color22 = color.XTerm22 Color23 = color.XTerm23 Color24 = color.XTerm24 Color25 = color.XTerm25 Color26 = color.XTerm26 Color27 = color.XTerm27 Color28 = color.XTerm28 Color29 = color.XTerm29 Color30 = color.XTerm30 Color31 = color.XTerm31 Color32 = color.XTerm32 Color33 = color.XTerm33 Color34 = color.XTerm34 Color35 = color.XTerm35 Color36 = color.XTerm36 Color37 = color.XTerm37 Color38 = color.XTerm38 Color39 = color.XTerm39 Color40 = color.XTerm40 Color41 = color.XTerm41 Color42 = color.XTerm42 Color43 = color.XTerm43 Color44 = color.XTerm44 Color45 = color.XTerm45 Color46 = color.XTerm46 Color47 = color.XTerm47 Color48 = color.XTerm48 Color49 = color.XTerm49 Color50 = color.XTerm50 Color51 = color.XTerm51 Color52 = color.XTerm52 Color53 = color.XTerm53 Color54 = color.XTerm54 Color55 = color.XTerm55 Color56 = color.XTerm56 Color57 = color.XTerm57 Color58 = color.XTerm58 Color59 = color.XTerm59 Color60 = color.XTerm60 Color61 = color.XTerm61 Color62 = color.XTerm62 Color63 = color.XTerm63 Color64 = color.XTerm64 Color65 = color.XTerm65 Color66 = color.XTerm66 Color67 = color.XTerm67 Color68 = color.XTerm68 Color69 = color.XTerm69 Color70 = color.XTerm70 Color71 = color.XTerm71 Color72 = color.XTerm72 Color73 = color.XTerm73 Color74 = color.XTerm74 Color75 = color.XTerm75 Color76 = color.XTerm76 Color77 = color.XTerm77 Color78 = color.XTerm78 Color79 = color.XTerm79 Color80 = color.XTerm80 Color81 = color.XTerm81 Color82 = color.XTerm82 Color83 = color.XTerm83 Color84 = color.XTerm84 Color85 = color.XTerm85 Color86 = color.XTerm86 Color87 = color.XTerm87 Color88 = color.XTerm88 Color89 = color.XTerm89 Color90 = color.XTerm90 Color91 = color.XTerm91 Color92 = color.XTerm92 Color93 = color.XTerm93 Color94 = color.XTerm94 Color95 = color.XTerm95 Color96 = color.XTerm96 Color97 = color.XTerm97 Color98 = color.XTerm98 Color99 = color.XTerm99 Color100 = color.XTerm100 Color101 = color.XTerm101 Color102 = color.XTerm102 Color103 = color.XTerm103 Color104 = color.XTerm104 Color105 = color.XTerm105 Color106 = color.XTerm106 Color107 = color.XTerm107 Color108 = color.XTerm108 Color109 = color.XTerm109 Color110 = color.XTerm110 Color111 = color.XTerm111 Color112 = color.XTerm112 Color113 = color.XTerm113 Color114 = color.XTerm114 Color115 = color.XTerm115 Color116 = color.XTerm116 Color117 = color.XTerm117 Color118 = color.XTerm118 Color119 = color.XTerm119 Color120 = color.XTerm120 Color121 = color.XTerm121 Color122 = color.XTerm122 Color123 = color.XTerm123 Color124 = color.XTerm124 Color125 = color.XTerm125 Color126 = color.XTerm126 Color127 = color.XTerm127 Color128 = color.XTerm128 Color129 = color.XTerm129 Color130 = color.XTerm130 Color131 = color.XTerm131 Color132 = color.XTerm132 Color133 = color.XTerm133 Color134 = color.XTerm134 Color135 = color.XTerm135 Color136 = color.XTerm136 Color137 = color.XTerm137 Color138 = color.XTerm138 Color139 = color.XTerm139 Color140 = color.XTerm140 Color141 = color.XTerm141 Color142 = color.XTerm142 Color143 = color.XTerm143 Color144 = color.XTerm144 Color145 = color.XTerm145 Color146 = color.XTerm146 Color147 = color.XTerm147 Color148 = color.XTerm148 Color149 = color.XTerm149 Color150 = color.XTerm150 Color151 = color.XTerm151 Color152 = color.XTerm152 Color153 = color.XTerm153 Color154 = color.XTerm154 Color155 = color.XTerm155 Color156 = color.XTerm156 Color157 = color.XTerm157 Color158 = color.XTerm158 Color159 = color.XTerm159 Color160 = color.XTerm160 Color161 = color.XTerm161 Color162 = color.XTerm162 Color163 = color.XTerm163 Color164 = color.XTerm164 Color165 = color.XTerm165 Color166 = color.XTerm166 Color167 = color.XTerm167 Color168 = color.XTerm168 Color169 = color.XTerm169 Color170 = color.XTerm170 Color171 = color.XTerm171 Color172 = color.XTerm172 Color173 = color.XTerm173 Color174 = color.XTerm174 Color175 = color.XTerm175 Color176 = color.XTerm176 Color177 = color.XTerm177 Color178 = color.XTerm178 Color179 = color.XTerm179 Color180 = color.XTerm180 Color181 = color.XTerm181 Color182 = color.XTerm182 Color183 = color.XTerm183 Color184 = color.XTerm184 Color185 = color.XTerm185 Color186 = color.XTerm186 Color187 = color.XTerm187 Color188 = color.XTerm188 Color189 = color.XTerm189 Color190 = color.XTerm190 Color191 = color.XTerm191 Color192 = color.XTerm192 Color193 = color.XTerm193 Color194 = color.XTerm194 Color195 = color.XTerm195 Color196 = color.XTerm196 Color197 = color.XTerm197 Color198 = color.XTerm198 Color199 = color.XTerm199 Color200 = color.XTerm200 Color201 = color.XTerm201 Color202 = color.XTerm202 Color203 = color.XTerm203 Color204 = color.XTerm204 Color205 = color.XTerm205 Color206 = color.XTerm206 Color207 = color.XTerm207 Color208 = color.XTerm208 Color209 = color.XTerm209 Color210 = color.XTerm210 Color211 = color.XTerm211 Color212 = color.XTerm212 Color213 = color.XTerm213 Color214 = color.XTerm214 Color215 = color.XTerm215 Color216 = color.XTerm216 Color217 = color.XTerm217 Color218 = color.XTerm218 Color219 = color.XTerm219 Color220 = color.XTerm220 Color221 = color.XTerm221 Color222 = color.XTerm222 Color223 = color.XTerm223 Color224 = color.XTerm224 Color225 = color.XTerm225 Color226 = color.XTerm226 Color227 = color.XTerm227 Color228 = color.XTerm228 Color229 = color.XTerm229 Color230 = color.XTerm230 Color231 = color.XTerm231 Color232 = color.XTerm232 Color233 = color.XTerm233 Color234 = color.XTerm234 Color235 = color.XTerm235 Color236 = color.XTerm236 Color237 = color.XTerm237 Color238 = color.XTerm238 Color239 = color.XTerm239 Color240 = color.XTerm240 Color241 = color.XTerm241 Color242 = color.XTerm242 Color243 = color.XTerm243 Color244 = color.XTerm244 Color245 = color.XTerm245 Color246 = color.XTerm246 Color247 = color.XTerm247 Color248 = color.XTerm248 Color249 = color.XTerm249 Color250 = color.XTerm250 Color251 = color.XTerm251 Color252 = color.XTerm252 Color253 = color.XTerm253 Color254 = color.XTerm254 Color255 = color.XTerm255 ColorAliceBlue = color.AliceBlue ColorAntiqueWhite = color.AntiqueWhite ColorAquaMarine = color.AquaMarine ColorAzure = color.Azure ColorBeige = color.Beige ColorBisque = color.Bisque ColorBlanchedAlmond = color.BlanchedAlmond ColorBlueViolet = color.BlueViolet ColorBrown = color.Brown ColorBurlyWood = color.BurlyWood ColorCadetBlue = color.CadetBlue ColorChartreuse = color.Chartreuse ColorChocolate = color.Chocolate ColorCoral = color.Coral ColorCornflowerBlue = color.CornflowerBlue ColorCornsilk = color.Cornsilk ColorCrimson = color.Crimson ColorDarkBlue = color.DarkBlue ColorDarkCyan = color.DarkCyan ColorDarkGoldenrod = color.DarkGoldenrod ColorDarkGray = color.DarkGray ColorDarkGreen = color.DarkGreen ColorDarkKhaki = color.DarkKhaki ColorDarkMagenta = color.DarkMagenta ColorDarkOliveGreen = color.DarkOliveGreen ColorDarkOrange = color.DarkOrange ColorDarkOrchid = color.DarkOrchid ColorDarkRed = color.DarkRed ColorDarkSalmon = color.DarkSalmon ColorDarkSeaGreen = color.DarkSeaGreen ColorDarkSlateBlue = color.DarkSlateBlue ColorDarkSlateGray = color.DarkSlateGray ColorDarkTurquoise = color.DarkTurquoise ColorDarkViolet = color.DarkViolet ColorDeepPink = color.DeepPink ColorDeepSkyBlue = color.DeepSkyBlue ColorDimGray = color.DimGray ColorDodgerBlue = color.DodgerBlue ColorFireBrick = color.FireBrick ColorFloralWhite = color.FloralWhite ColorForestGreen = color.ForestGreen ColorGainsboro = color.Gainsboro ColorGhostWhite = color.GhostWhite ColorGold = color.Gold ColorGoldenrod = color.Goldenrod ColorGreenYellow = color.GreenYellow ColorHoneydew = color.Honeydew ColorHotPink = color.HotPink ColorIndianRed = color.IndianRed ColorIndigo = color.Indigo ColorIvory = color.Ivory ColorKhaki = color.Khaki ColorLavender = color.Lavender ColorLavenderBlush = color.LavenderBlush ColorLawnGreen = color.LawnGreen ColorLemonChiffon = color.LemonChiffon ColorLightBlue = color.LightBlue ColorLightCoral = color.LightCoral ColorLightCyan = color.LightCyan ColorLightGoldenrodYellow = color.LightGoldenrodYellow ColorLightGray = color.LightGray ColorLightGreen = color.LightGreen ColorLightPink = color.LightPink ColorLightSalmon = color.LightSalmon ColorLightSeaGreen = color.LightSeaGreen ColorLightSkyBlue = color.LightSkyBlue ColorLightSlateGray = color.LightSlateGray ColorLightSteelBlue = color.LightSteelBlue ColorLightYellow = color.LightYellow ColorLimeGreen = color.LimeGreen ColorLinen = color.Linen ColorMediumAquamarine = color.MediumAquamarine ColorMediumBlue = color.MediumBlue ColorMediumOrchid = color.MediumOrchid ColorMediumPurple = color.MediumPurple ColorMediumSeaGreen = color.MediumSeaGreen ColorMediumSlateBlue = color.MediumSlateBlue ColorMediumSpringGreen = color.MediumSpringGreen ColorMediumTurquoise = color.MediumTurquoise ColorMediumVioletRed = color.MediumVioletRed ColorMidnightBlue = color.MidnightBlue ColorMintCream = color.MintCream ColorMistyRose = color.MistyRose ColorMoccasin = color.Moccasin ColorOldLace = color.OldLace ColorOliveDrab = color.OliveDrab ColorOrange = color.Orange ColorOrangeRed = color.OrangeRed ColorOrchid = color.Orchid ColorPaleGoldenrod = color.PaleGoldenrod ColorPaleGreen = color.PaleGreen ColorPaleTurquoise = color.PaleTurquoise ColorPaleVioletRed = color.PaleVioletRed ColorPapayaWhip = color.PapayaWhip ColorPeachPuff = color.PeachPuff ColorPeru = color.Peru ColorPink = color.Pink ColorPlum = color.Plum ColorPowderBlue = color.PowderBlue ColorRebeccaPurple = color.RebeccaPurple ColorRosyBrown = color.RosyBrown ColorRoyalBlue = color.RoyalBlue ColorSaddleBrown = color.SaddleBrown ColorSalmon = color.Salmon ColorSandyBrown = color.SandyBrown ColorSeaGreen = color.SeaGreen ColorSeashell = color.Seashell ColorSienna = color.Sienna ColorSkyblue = color.Skyblue ColorSlateBlue = color.SlateBlue ColorSlateGray = color.SlateGray ColorSnow = color.Snow ColorSpringGreen = color.SpringGreen ColorSteelBlue = color.SteelBlue ColorTan = color.Tan ColorThistle = color.Thistle ColorTomato = color.Tomato ColorTurquoise = color.Turquoise ColorViolet = color.Violet ColorWheat = color.Wheat ColorWhiteSmoke = color.WhiteSmoke ColorYellowGreen = color.YellowGreen )
Note that the order of these options is important -- it follows the definitions used by ECMA and XTerm. Hence any further named colors must begin at a value not less than 256.
Deprecated: Use color.XXX symbols instead.
const ( ColorGrey = color.Gray ColorDimGrey = color.DimGray ColorDarkGrey = color.DarkGray ColorDarkSlateGrey = color.DarkSlateGray ColorLightGrey = color.LightGray ColorLightSlateGrey = color.LightSlateGray ColorSlateGrey = color.SlateGray )
These are aliases for the color gray, because some of us spell it as grey. Deprecated: Use color values.
const ( // ColorReset is used to indicate that the color should use the // vanilla terminal colors. (Basically go back to the defaults.) // Deprecated: Use color.Reset. ColorReset = color.Reset // ColorNone indicates that we should not change the color from // whatever is already displayed. This can only be used in limited // circumstances. // Deprecated: Use color.None. ColorNone = color.None )
Special colors.
const ( // EncodingFallbackUTF8 behavior causes GetEncoding to assume // UTF8 can pass unmodified upon failure. EncodingFallbackUTF8 = iota // EncodingFallbackFail behavior causes GetEncoding to fail // when it cannot find an encoding. EncodingFallbackFail // EncodingFallbackASCII behavior causes GetEncoding to fall back // to a 7-bit ASCII encoding, if no other encoding can be found. EncodingFallbackASCII )
const ( KittyKbdModeOff = KittyKbdMode(0) // Disable Kitty keyboard mode KittyKbdModeBase = KittyKbdMode(1) // Enable disambiguated keys KittyKbdModeEvents = KittyKbdMode(2) // Report event types (e.g. key release) KittyKbdModeAlternate = KittyKbdMode(4) // Report alternate keys KittyKbdModeAll = KittyKbdMode(8) // Report all keys using kitty keyboard protocol KittyKbdModeText = KittyKbdMode(16) // Report associated text )
const ( XtermKbdModeOff = XtermKbdMode(0) // Disabled XtermKbdModeBase = XtermKbdMode(1) // Enabled except for ones with legacy behavior XtermKbdModeExt = XtermKbdMode(2) // Enabled for all modified keys XtermKbdModeAll = XtermKbdMode(3) // Send all keys (including unmodified) )
const ( KeyBackspace = KeyBS KeyTab = KeyTAB KeyEsc = KeyESC KeyEscape = KeyESC KeyEnter = KeyCR // NB: This key will be translated to KeyBackspace KeyBackspace2 = KeyDEL )
These keys are aliases for other names.
const ( RuneSterling = '£' RuneDArrow = '↓' RuneLArrow = '←' RuneRArrow = '→' RuneUArrow = '↑' RuneBullet = '·' RuneBoard = '░' RuneCkBoard = '▒' RuneDegree = '°' RuneDiamond = '◆' RuneGEqual = '≥' RunePi = 'π' RuneHLine = '─' RuneLantern = '§' RunePlus = '┼' RuneLEqual = '≤' RuneLLCorner = '└' RuneLRCorner = '┘' RuneNEqual = '≠' RunePlMinus = '±' RuneS1 = '⎺' RuneS3 = '⎻' RuneS7 = '⎼' RuneS9 = '⎽' RuneBlock = '█' RuneTTee = '┬' RuneRTee = '┤' RuneLTee = '├' RuneBTee = '┴' RuneULCorner = '┌' RuneURCorner = '┐' RuneVLine = '│' )
The names of these constants are chosen to match Terminfo names, modulo case, and changing the prefix from ACS_ to Rune. These are the runes we provide extra special handling for, with ASCII fallbacks for terminals that lack them.
const ( MouseButtonEvents = MouseFlags(1) // Click events only MouseDragEvents = MouseFlags(2) // Click-drag events (includes button events) MouseMotionEvents = MouseFlags(4) // All mouse events (includes click and drag events) )
const ( CursorStyleDefault = CursorStyle(iota) // The default CursorStyleBlinkingBlock CursorStyleSteadyBlock CursorStyleBlinkingUnderline CursorStyleSteadyUnderline CursorStyleBlinkingBar CursorStyleSteadyBar )
const ( UnderlineStyleNone = UnderlineStyle(iota) UnderlineStyleSolid UnderlineStyleDouble UnderlineStyleCurly UnderlineStyleDotted UnderlineStyleDashed )
Variables ¶
var ( // ErrNoScreen indicates that no suitable screen could be found. // This may result from attempting to run on a platform where there // is no support for either termios or console I/O (such as js), // or from running in an environment where there is no access to // a suitable console/terminal device. (For example, running on // without a controlling TTY or with no /dev/tty on POSIX platforms.) ErrNoScreen = errors.New("no suitable screen available") // ErrNoCharset indicates that the locale environment the // program is not supported by the program, because no suitable // encoding was found for it. This problem never occurs if // the environment is UTF-8 or UTF-16. ErrNoCharset = errors.New("character set not supported") // ErrEventQFull indicates that the event queue is full, and // cannot accept more events. ErrEventQFull = errors.New("event queue full") )
var ColorNames = color.Names
ColorNames holds the written names of colors. Useful to present a list of recognized named colors. Deprecated: Use color.Names.
var ColorValues = color.ColorValues
ColorValues maps color constants to their RGB values.
var KeyNames = map[Key]string{}/* 120 elements not displayed */
KeyNames holds the written names of special keys. Useful to echo back a key name, or to look up a key from a string value.
var RuneFallbacks = map[rune]string{ RuneSterling: "f", RuneDArrow: "v", RuneLArrow: "<", RuneRArrow: ">", RuneUArrow: "^", RuneBullet: "o", RuneBoard: "#", RuneCkBoard: ":", RuneDegree: "\\", RuneDiamond: "+", RuneGEqual: ">", RunePi: "*", RuneHLine: "-", RuneLantern: "#", RunePlus: "+", RuneLEqual: "<", RuneLLCorner: "+", RuneLRCorner: "+", RuneNEqual: "!", RunePlMinus: "#", RuneS1: "~", RuneS3: "-", RuneS7: "-", RuneS9: "_", RuneBlock: "#", RuneTTee: "+", RuneRTee: "+", RuneLTee: "+", RuneBTee: "+", RuneULCorner: "+", RuneURCorner: "+", RuneVLine: "|", }
RuneFallbacks is the default map of fallback strings that will be used to replace a rune when no other more appropriate transformation is available, and the rune cannot be displayed directly.
New entries may be added to this map over time, as it becomes clear that such is desirable. Characters that represent either letters or numbers should not be added to this list unless it is certain that the meaning will still convey unambiguously.
As an example, it would be appropriate to add an ASCII mapping for the full width form of the letter 'A', but it would not be appropriate to do so a glyph representing the country China.
Programs that desire richer fallbacks may register additional ones, or change or even remove these mappings with Screen.RegisterRuneFallback Screen.UnregisterRuneFallback methods.
Note that Unicode is presumed to be able to display all glyphs. This is a pretty poor assumption, but there is no easy way to figure out which glyphs are supported in a given font. Hence, some care in selecting the characters you support in your application is still appropriate.
Functions ¶
func GetEncoding ¶
GetEncoding is used by Screen implementors who want to locate an encoding for the given character set name. Note that this will return nil for either the Unicode (UTF-8) or ASCII encodings, since we don't use encodings for them but instead have our own native methods.
func RegisterEncoding ¶
RegisterEncoding may be called by the application to register an encoding. The presence of additional encodings will facilitate application usage with terminal environments where the I/O subsystem does not support Unicode.
Modern systems and terminal emulators usually use UTF-8, and for those systems, this API is also unnecessary. For example, Windows, macOS, and modern Linux systems generally will work out of the box without any of this.
Use of UTF-8 is recommended when possible, as it saves quite a lot processing overhead.
Aliases can be registered as well, for example "8859-15" could be an alias for "ISO8859-15".
For POSIX systems, this package will check the environment variables LC_ALL, LC_CTYPE, and LANG (in that order) to determine the character set. These are expected to have the following pattern:
$language[.$codeset[@$variant]
We extract only the $codeset part, which will usually be something like UTF-8 or ISO8859-15 or KOI8-R. Note that if the locale is either "POSIX" or "C", then we assume US-ASCII (the POSIX 'portable character set' and assume all other characters are somehow invalid.)
Please see the Go documentation for golang.org/x/text/encoding -- most of the common ones exist already as stock variables. For example, ISO8859-15 can be registered using the following code:
Note that some encodings are quite large (for example GB18030 which is a superset of Unicode) and so the application size can be expected to increase quite a bit as each encoding is added.
The East Asian encodings have been seen to add 100-200K per encoding to the size of the resulting binary.
Example ¶
RegisterEncoding("GBK", simplifiedchinese.GBK)
enc := GetEncoding("GBK")
glyph, _ := enc.NewDecoder().Bytes([]byte{0x82, 0x74})
fmt.Println(string(glyph))
Output: 倀
func SetEncodingFallback ¶
func SetEncodingFallback(fb EncodingFallback)
SetEncodingFallback changes the behavior of GetEncoding when a suitable encoding is not found. The default is EncodingFallbackFail, which causes GetEncoding to simply return nil.
func ShimScreen ¶
func ShimScreen(s Screen)
ShimScreen allows an application to override the screen that will be returned by NewScreen. Typically this is used for testing, where the test code calls this once before running an example. It could also be used to intercept a regular Screen.
Types ¶
type AttrMask ¶
type AttrMask uint16
AttrMask represents a mask of text attributes, apart from color. Note that support for attributes may vary widely across terminals. Deprecated: This should not be used directly by applications. Instead use the accessor functions on the style. (In particular the details of the encoding are subject to change.)
const ( AttrBold AttrMask = 1 << iota AttrBlink AttrReverse AttrDim AttrItalic AttrStrikeThrough AttrInvalid AttrMask = 1 << 15 // Mark the style or attributes invalid AttrNone AttrMask = 0 // Just normal text. )
Attributes are not colors, but affect the display of text. They can be combined, in some cases, but not others. (E.g. you can have Dim Italic, but only CurlyUnderline cannot be mixed with DottedUnderline.)
type ButtonMask ¶
type ButtonMask int16
ButtonMask is a mask of mouse buttons and wheel events. Mouse button presses are normally delivered as both press and release events. Mouse wheel events are normally just single impulse events. Windows supports up to eight separate buttons plus all four wheel directions, but XTerm can only support mouse buttons 1-3 and wheel up/down. Its not unheard of for terminals to support only one or two buttons (think Macs). Old terminals, and true emulations (such as vt100) won't support mice at all, of course.
const ( Button1 ButtonMask = 1 << iota // Usually the left (primary) mouse button. Button2 // Usually the right (secondary) mouse button. Button3 // Usually the middle mouse button. Button4 // Often a side button (thumb/next). Button5 // Often a side button (thumb/prev). Button6 Button7 Button8 WheelUp // Wheel motion up/away from user. WheelDown // Wheel motion down/towards user. WheelLeft // Wheel motion to left. WheelRight // Wheel motion to right. ButtonNone ButtonMask = 0 // No button or wheel events. ButtonPrimary = Button1 ButtonSecondary = Button2 ButtonMiddle = Button3 )
These are the actual button values. Note that tcell version 1.x reversed buttons two and three on *nix based terminals. We use button 1 as the primary, and button 2 as the secondary, and button 3 (which is often missing) as the middle.
type CellBuffer ¶
type CellBuffer struct {
// contains filtered or unexported fields
}
CellBuffer represents a two-dimensional array of character cells. This is primarily intended for use by Screen implementers; it contains much of the common code they need. To create one, just declare a variable of its type; no explicit initialization is necessary.
CellBuffer is not thread safe.
func (*CellBuffer) Dirty ¶
func (cb *CellBuffer) Dirty(x, y int) bool
Dirty checks if a character at the given location needs to be refreshed on the physical display. This returns true if the cell content is different since the last time it was marked clean.
func (*CellBuffer) Fill ¶
func (cb *CellBuffer) Fill(r rune, style Style)
Fill fills the entire cell buffer array with the specified character and style. Normally choose ' ' to clear the screen. This API doesn't support combining characters, or characters with a width larger than one. If either the foreground or background are ColorNone, then the respective color is unchanged.
func (*CellBuffer) Get ¶
func (cb *CellBuffer) Get(x, y int) (string, Style, int)
Get the contents of a character cell (or two adjacent cells), including the the style and the display width in cells. (The width can be either 1, normally, or 2 for East Asian full-width characters. If the width is 0, then the cell is is empty.)
func (*CellBuffer) Invalidate ¶
func (cb *CellBuffer) Invalidate()
Invalidate marks all characters within the buffer as dirty.
func (*CellBuffer) LockCell ¶
func (cb *CellBuffer) LockCell(x, y int)
LockCell locks a cell from being drawn, effectively marking it "clean" until the lock is removed. This can be used to prevent tcell from drawing a given cell, even if the underlying content has changed. For example, when drawing a sixel graphic directly to a TTY screen an implementer must lock the region underneath the graphic to prevent tcell from drawing on top of the graphic.
func (*CellBuffer) Put ¶
Put a single styled grapheme using the given string and style at the same location. Note that only the first grapheme in the string will be displayed, using only the 1 or 2 (depending on width) cells located at x, y. It returns the rest of the string, and the width used.
func (*CellBuffer) Resize ¶
func (cb *CellBuffer) Resize(w, h int)
Resize is used to resize the cells array, with different dimensions, while preserving the original contents. The cells will be invalidated so that they can be redrawn.
func (*CellBuffer) SetDirty ¶
func (cb *CellBuffer) SetDirty(x, y int, dirty bool)
SetDirty is normally used to indicate that a cell has been displayed (in which case dirty is false), or to manually force a cell to be marked dirty.
func (*CellBuffer) Size ¶
func (cb *CellBuffer) Size() (int, int)
Size returns the (width, height) in cells of the buffer.
func (*CellBuffer) UnlockCell ¶
func (cb *CellBuffer) UnlockCell(x, y int)
UnlockCell removes a lock from the cell and marks it as dirty
type Color ¶
Color represents a color. The low numeric values are the same as used by ECMA-48, and beyond that XTerm.
Note that on various terminals colors may be approximated however, or not supported at all. If no suitable representation for a color is known, the library will simply not set any color, deferring to whatever default attributes the terminal uses.
func FindColor ¶
FindColor attempts to find a given color, or the best match possible for it, from the palette given. This is an expensive operation, so results should be cached by the caller. Deprecated: Use color.Find.
func FromImageColor ¶
FromImageColor converts an image/color.Color into Color. Deprecated: Use color.FromImageColor.
func GetColor ¶
GetColor creates a Color from a color name (W3C name). A hex value may be supplied as a string in the format "#ffffff". Deprecated: Use color.GetColor.
func NewHexColor ¶
NewHexColor returns a color using the given 24-bit RGB value. Deprecated: Use color.NewHexColor.
func NewRGBColor ¶
NewRGBColor returns a new color with the given red, green, and blue values. Each value must be represented in the range 0-255. Deprecated: Use color.NewRGBColor.
func PaletteColor ¶
PaletteColor creates a color based on the palette index. Deprecated: Use color.PaletteColor.
type CursorStyle ¶
type CursorStyle int
CursorStyle represents a given cursor style, which can include the shape and whether the cursor blinks or is solid. Support for changing this is not universal.
type EncodingFallback ¶
type EncodingFallback int
EncodingFallback describes how the system behaves when the locale requires a character set that we do not support. The system always supports UTF-8 and US-ASCII. On Windows consoles, UTF-16LE is also supported automatically. Other character sets must be added using the RegisterEncoding API. (A large group of nearly all of them can be added using the RegisterAll function in the encoding sub package.) The default action will be to fallback to UTF-8.
type EventClipboard ¶
type EventClipboard struct {
// contains filtered or unexported fields
}
EventClipboard represents data from the clipboard, in response to a GetClipboard request.
func NewEventClipboard ¶
func NewEventClipboard(data []byte) *EventClipboard
NewEventClipboard returns a new NewEventClipboard with a data payload
func (*EventClipboard) Data ¶
func (ev *EventClipboard) Data() []byte
Data returns the attached binary data.
func (*EventClipboard) When ¶
func (ev *EventClipboard) When() time.Time
When returns the time when this event was created.
type EventError ¶
type EventError struct {
EventTime
// contains filtered or unexported fields
}
An EventError is an event representing some sort of error, and carries an error payload.
func NewEventError ¶
func NewEventError(err error) *EventError
NewEventError creates an ErrorEvent with the given error payload.
type EventFocus ¶
type EventFocus struct {
EventTime
// True if the window received focus, false if it lost focus
Focused bool
}
EventFocus is a focus event. It is sent when the terminal window (or tab) gets or loses focus.
func NewEventFocus ¶
func NewEventFocus(focused bool) *EventFocus
type EventHandler ¶
EventHandler is anything that handles events. If the handler has consumed the event, it should return true. False otherwise.
type EventInterrupt ¶
type EventInterrupt struct {
EventTime
// contains filtered or unexported fields
}
EventInterrupt is a generic wakeup event. Its can be used to to request a redraw. It can carry an arbitrary payload, as well.
func NewEventInterrupt ¶
func NewEventInterrupt(data any) *EventInterrupt
NewEventInterrupt creates an EventInterrupt with the given payload.
func (*EventInterrupt) Data ¶
func (ev *EventInterrupt) Data() any
Data is used to obtain the opaque event payload.
type EventKey ¶
type EventKey struct {
EventTime
// contains filtered or unexported fields
}
EventKey represents a key press. Usually this is a key press followed by a key release, but since terminal programs don't have a way to report key release events, we usually get just one event. If a key is held down then the terminal may synthesize repeated key presses at some predefined rate. We have no control over that, nor visibility into it.
In some cases, we can have a modifier key, such as ModAlt, that can be generated with a key press. (This usually is represented by having the high bit set, or in some cases, by sending an ESC prior to the rune.)
If the value of Key() is KeyRune, then the actual key value will be available (as a grapheme cluster) with the Str() method. This will be the case for most keys.
In most situations, the modifiers will not be set. For example, if the rune is 'A', this will be reported without the ModShift bit set, since really can't tell if the Shift key was pressed (it might have been CAPSLOCK, or a terminal that only can send capitals, or keyboard with separate capital letters from lower case letters).
Generally, terminal applications have far less visibility into keyboard activity than graphical applications. Hence, they should avoid depending overly much on availability of modifiers, or the availability of any specific keys.
func NewEventKey ¶
NewEventKey attempts to create a suitable event. It parses the various ASCII control sequences if KeyRune is passed for Key, but if the caller has more precise information it should set that specifically. Callers that aren't sure about modifier state (most) should just pass ModNone.
func (*EventKey) Key ¶
Key returns a virtual key code. We use this to identify specific key codes, such as KeyEnter, etc. Most control and function keys are reported with unique Key values. Normal alphanumeric and punctuation keys will generally return KeyRune here; the specific key can be further decoded using the Str() function.
func (*EventKey) Modifiers ¶
Modifiers returns the modifiers that were present with the key press. Note that not all platforms and terminals support this equally well, and some cases we will not not know for sure. Hence, applications should avoid using this in most circumstances.
type EventMouse ¶
type EventMouse struct {
EventTime
// contains filtered or unexported fields
}
EventMouse is a mouse event. It is sent on either mouse up or mouse down events. It is also sent on mouse motion events - if the terminal supports it. We make every effort to ensure that mouse release events are delivered. Hence, click drag can be identified by a motion event with the mouse down, without any intervening button release. On some terminals only the initiating press and terminating release event will be delivered.
Mouse wheel events, when reported, may appear on their own as individual impulses; that is, there will normally not be a release event delivered for mouse wheel movements.
Most terminals cannot report the state of more than one button at a time -- and some cannot report motion events unless a button is pressed.
Applications can inspect the time between events to resolve double or triple clicks.
func NewEventMouse ¶
func NewEventMouse(x, y int, btn ButtonMask, mod ModMask, esc string) *EventMouse
NewEventMouse is used to create a new mouse event. Applications shouldn't need to use this; its mostly for screen implementers.
func (*EventMouse) Buttons ¶
func (ev *EventMouse) Buttons() ButtonMask
Buttons returns the list of buttons that were pressed or wheel motions.
func (*EventMouse) EscSeq ¶
func (ev *EventMouse) EscSeq() string
func (*EventMouse) Modifiers ¶
func (ev *EventMouse) Modifiers() ModMask
Modifiers returns a list of keyboard modifiers that were pressed with the mouse button(s).
func (*EventMouse) Position ¶
func (ev *EventMouse) Position() (int, int)
Position returns the mouse position in character cells. The origin 0, 0 is at the upper left corner.
type EventPaste ¶
type EventPaste struct {
// contains filtered or unexported fields
}
EventPaste is used to mark the start and end of a bracketed paste.
An event with .Start() true will be sent to mark the start of a bracketed paste, followed by a number of keys (string data) for the content, ending with the an event with .End() true.
func NewEventPaste ¶
func NewEventPaste(start bool) *EventPaste
NewEventPaste returns a new EventPaste.
func (*EventPaste) End ¶
func (ev *EventPaste) End() bool
End returns true if this is the end of a paste.
func (*EventPaste) Start ¶
func (ev *EventPaste) Start() bool
Start returns true if this is the start of a paste.
func (*EventPaste) When ¶
func (ev *EventPaste) When() time.Time
When returns the time when this EventPaste was created.
type EventResize ¶
type EventResize struct {
EventTime
// contains filtered or unexported fields
}
EventResize is sent when the window size changes.
func NewEventResize ¶
func NewEventResize(width, height int) *EventResize
NewEventResize creates an EventResize with the new updated window size, which is given in character cells.
func (*EventResize) PixelSize ¶
func (ev *EventResize) PixelSize() (int, int)
PixelSize returns the new window size as width, height in pixels. The size will be 0,0 if the screen doesn't support this feature
func (*EventResize) Size ¶
func (ev *EventResize) Size() (int, int)
Size returns the new window size as width, height in character cells.
type EventTime ¶
type EventTime struct {
// contains filtered or unexported fields
}
EventTime is a simple base event class, suitable for easy reuse. It can be used to deliver actual timer events as well.
func (*EventTime) SetEventNow ¶
func (e *EventTime) SetEventNow()
SetEventNow sets the time of occurrence for the event to the current time.
func (*EventTime) SetEventTime ¶
SetEventTime sets the time of occurrence for the event.
type Key ¶
type Key int16
Key is a generic value for representing keys, and especially special keys (function keys, cursor movement keys, etc.) For normal keys, like ASCII letters, we use KeyRune, and then expect the application to inspect the Str() member of the EventKey.
const ( KeyRune Key = iota + 256 KeyUp KeyDown KeyRight KeyLeft KeyUpLeft KeyUpRight KeyDownLeft KeyDownRight KeyCenter KeyPgUp KeyPgDn KeyHome KeyEnd KeyInsert KeyDelete KeyHelp KeyExit KeyClear KeyCancel KeyPrint KeyPause KeyBacktab KeyF1 KeyF2 KeyF3 KeyF4 KeyF5 KeyF6 KeyF7 KeyF8 KeyF9 KeyF10 KeyF11 KeyF12 KeyF13 KeyF14 KeyF15 KeyF16 KeyF17 KeyF18 KeyF19 KeyF20 KeyF21 KeyF22 KeyF23 KeyF24 KeyF25 KeyF26 KeyF27 KeyF28 KeyF29 KeyF30 KeyF31 KeyF32 KeyF33 KeyF34 KeyF35 KeyF36 KeyF37 KeyF38 KeyF39 KeyF40 KeyF41 KeyF42 KeyF43 KeyF44 KeyF45 KeyF46 KeyF47 KeyF48 KeyF49 KeyF50 KeyF51 KeyF52 KeyF53 KeyF54 KeyF55 KeyF56 KeyF57 KeyF58 KeyF59 KeyF60 KeyF61 KeyF62 KeyF63 KeyF64 KeyMenu KeyCapsLock KeyScrollLock KeyNumLock )
This is the list of named keys. KeyRune is special however, in that it is a place holder key indicating that a printable character was sent. The actual value of the rune will be transported in the Rune of the associated EventKey.
const ( KeyCtrlA Key = iota + 65 KeyCtrlB KeyCtrlC KeyCtrlD KeyCtrlE KeyCtrlF KeyCtrlG KeyCtrlH KeyCtrlI KeyCtrlJ KeyCtrlK KeyCtrlL KeyCtrlM KeyCtrlN KeyCtrlO KeyCtrlP KeyCtrlQ KeyCtrlR KeyCtrlS KeyCtrlT KeyCtrlU KeyCtrlV KeyCtrlW KeyCtrlX KeyCtrlY KeyCtrlZ )
These are the control keys, they will also be reported with the rune (lower case) and control modifier. If the shift key or other modifiers are present then these will *NOT* be reported, but reported instead as KeyRune.
const ( KeyNUL Key = iota KeySOH KeySTX KeyETX KeyEOT KeyENQ KeyACK KeyBEL KeyBS KeyTAB KeyLF KeyVT KeyFF KeyCR KeySO KeySI KeyDLE KeyDC1 KeyDC2 KeyDC3 KeyDC4 KeyNAK KeySYN KeyETB KeyCAN KeyEM KeySUB KeyESC KeyFS KeyGS KeyRS KeyUS KeyDEL Key = 0x7F )
These are the defined ASCII values for key codes. They generally match with KeyCtrl values.
type KittyKbdMode ¶
type KittyKbdMode uint16
type ModMask ¶
type ModMask int16
ModMask is a mask of modifier keys. Note that it will not always be possible to report modifier keys.
These are the modifiers keys that can be sent either with a key press, or a mouse event. Note that as of now, due to the confusion associated with Meta, and the lack of support for it on many/most platforms, the current implementations never use it. Instead, they use ModAlt, even for events that could possibly have been distinguished from ModAlt.
type MouseFlags ¶
type MouseFlags int
MouseFlags are options to modify the handling of mouse events. Actual events can be ORed together.
type OptColors ¶
type OptColors int
OptColors forces the number of colors, overriding the value of the color count that would be detected by the environment. If the value is 0, then color is forced off. Other reasonable values are 8, 16, 88, 256, or 1<<24. The latter case intrinsically enables 24-bit color as well.
type Screen ¶
type Screen interface {
// Init initializes the screen for use.
Init() error
// Fini finalizes the screen also releasing resources.
Fini()
// Clear logically erases the screen.
// This is effectively a short-cut for Fill(' ', StyleDefault).
Clear()
// Fill fills the screen with the given character and style.
// The effect of filling the screen is not visible until Show
// is called (or Sync).
Fill(rune, Style)
// Put writes the first grapheme of the given string with th
// given style at the given coordinates. (Only the first grapheme
// occupying either one or two cells is stored.) It returns the
// remainder of the string, and the width displayed.
Put(x int, y int, str string, style Style) (string, int)
// PutStr writes a string starting at the given position, using the
// default style. The content is clipped to the screen dimensions.
PutStr(x int, y int, str string)
// PutStrStyled writes a string starting at the given position, using
// the given style. The content is clipped to the screen dimensions.
PutStrStyled(x int, y int, str string, style Style)
// Get the contents at the given location. If the
// coordinates are out of range, then the values will be 0, nil,
// StyleDefault. Note that the contents returned are logical contents
// and may not actually be what is displayed, but rather are what will
// be displayed if Show() or Sync() is called. The width is the width
// in screen cells; most often this will be 1, but some East Asian
// characters and emoji require two cells.
Get(x, y int) (str string, style Style, width int)
// SetContent sets the contents of the given cell location. If
// the coordinates are out of range, then the operation is ignored.
//
// The first rune is the primary non-zero width rune. The array
// that follows is a possible list of combining characters to append,
// and will usually be nil (no combining characters.)
//
// The results are not displayed until Show() or Sync() is called.
//
// Note that wide (East Asian full width and emoji) runes occupy two cells,
// and attempts to place character at next cell to the right will have
// undefined effects. Wide runes that are printed in the
// last column will be replaced with a single width space on output.
SetContent(x int, y int, primary rune, combining []rune, style Style)
// SetStyle sets the default style to use when clearing the screen
// or when StyleDefault is specified. If it is also StyleDefault,
// then whatever system/terminal default is relevant will be used.
SetStyle(style Style)
// ShowCursor is used to display the cursor at a given location.
// If the coordinates -1, -1 are given or are otherwise outside the
// dimensions of the screen, the cursor will be hidden.
ShowCursor(x int, y int)
// HideCursor is used to hide the cursor. It's an alias for
// ShowCursor(-1, -1).sim
HideCursor()
// SetCursorStyle is used to set the cursor style. If the style
// is not supported (or cursor styles are not supported at all),
// then this will have no effect. Color will be changed if supplied,
// and the terminal supports doing so.
SetCursorStyle(CursorStyle, ...color.Color)
// Size returns the screen size as width, height. This changes in
// response to a call to Clear or Flush.
Size() (width, height int)
// EventQ returns the channel of events, and is usable just like
// any other channel. Events can be injected by writing to
// the channel, and they can be read by reading from it. The
// channel will remain open until the screen is completely shut down
// with Fini(). Consequently, applications must not write to this
// channel after Fini() is called.
EventQ() chan Event
// EnableMouse enables the mouse. (If your terminal supports it.)
// If no flags are specified, then all events are reported, if the
// terminal supports them.
EnableMouse(...MouseFlags)
// DisableMouse disables the mouse.
DisableMouse()
// EnablePaste enables bracketed paste mode, if supported.
EnablePaste()
// DisablePaste disables bracketed paste mode.
DisablePaste()
// EnableFocus enables reporting of focus events, if your terminal supports it.
EnableFocus()
// DisableFocus disables reporting of focus events.
DisableFocus()
// Colors returns the number of colors. All colors are assumed to
// use the ANSI color map. If a terminal is monochrome, it will
// return 0.
Colors() int
// Show makes all the content changes made using SetContent() visible
// on the display.
//
// It does so in the most efficient and least visually disruptive
// manner possible.
Show()
// Sync works like Show(), but it updates every visible cell on the
// physical display, assuming that it is not synchronized with any
// internal model. This may be both expensive and visually jarring,
// so it should only be used when believed to actually be necessary.
//
// Typically, this is called as a result of a user-requested redraw
// (e.g. to clear up on-screen corruption caused by some other program),
// or during a resize event.
Sync()
// CharacterSet returns information about the character set.
// This isn't the full locale, but it does give us the input/output
// character set. Note that this is just for diagnostic purposes,
// we normally translate input/output to/from UTF-8, regardless of
// what the user's environment is.
CharacterSet() string
// RegisterRuneFallback adds a fallback for runes that are not
// part of the character set -- for example one could register
// o as a fallback for ø. This should be done cautiously for
// characters that might be displayed ordinarily in language
// specific text -- characters that could change the meaning of
// written text would be dangerous. The intention here is to
// facilitate fallback characters in pseudo-graphical applications.
//
// If the terminal has fallbacks already in place via an alternate
// character set, those are used in preference. Also, standard
// fallbacks for graphical characters in the alternate character set
// terminfo string are registered implicitly.
//
// The display string should be the same width as original rune.
// This makes it possible to register two character replacements
// for full width East Asian characters, for example.
//
// It is recommended that replacement strings consist only of
// 7-bit ASCII, since other characters may not display everywhere.
RegisterRuneFallback(r rune, subst string)
// UnregisterRuneFallback unmaps a replacement. It will unmap
// the implicit ASCII replacements for alternate characters as well.
// When an unmapped char needs to be displayed, but no suitable
// glyph is available, '?' is emitted instead. It is not possible
// to "disable" the use of alternate characters that are supported
// by your terminal except by changing the terminal database.
UnregisterRuneFallback(r rune)
// Resize does nothing, since it's generally not possible to
// ask a screen to resize, but it allows the Screen to implement
// the View interface.
Resize(int, int, int, int)
// Suspend pauses input and output processing. It also restores the
// terminal settings to what they were when the application started.
// This can be used to, for example, run a sub-shell.
Suspend() error
// Resume resumes after Suspend().
Resume() error
// Beep attempts to sound an OS-dependent audible alert and returns an error
// when unsuccessful.
Beep() error
// SetSize attempts to resize the window. It also invalidates the cells and
// calls the resize function. Note that if the window size is changed, it will
// not be restored upon application exit.
//
// Many terminals cannot support this. Perversely, the "modern" Windows Terminal
// does not support application-initiated resizing, whereas the legacy terminal does.
// Also, some emulators can support this but may have it disabled by default.
SetSize(int, int)
// LockRegion sets or unsets a lock on a region of cells. A lock on a
// cell prevents the cell from being redrawn.
LockRegion(x, y, width, height int, lock bool)
// Tty returns the underlying Tty. If the screen is not a terminal, the
// returned bool will be false
Tty() (Tty, bool)
// SetTitle sets a window title on the screen.
// Terminals may be configured to ignore this, or unable to.
// Tcell may attempt to save and restore the window title on entry and exit, but
// the results may vary. Use of unicode characters may not be supported.
SetTitle(string)
// SetClipboard is used to post arbitrary data to the system clipboard.
// This need not be UTF-8 string data. It's up to the recipient to decode the
// data meaningfully. Terminals may prevent this for security reasons.
// An empty byte or nil can be used to clear the clipboard.
SetClipboard([]byte)
// GetClipboard is used to request the clipboard contents. It may be ignored.
// If the terminal is willing, it will be post the clipboard contents using an
// EventPaste with the clipboard content as the Data() field. Terminals may
// prevent this for security reasons.
GetClipboard()
// HasClipboard is true if the screen claims to support the clipboard.
// Note that GetClipboard may still not work, but SetClipboard should be functional.
// Note that many terminals that support the clipboard don't actually report that they
// do, so a false indication is not necessarily conclusive.
HasClipboard() bool
// ShowNotification is used to show a desktop notification, when the terminal
// supports it. Right now only terminals supporting OSC 777 support this.
ShowNotification(title string, body string)
// Terminal returns the terminal name and version if known. If either of these
// are unknown, then empty strings are returned in their place. This is intended
// to facilitate debug, and also applications that wish to enable very specific
// behaviors for the terminal
Terminal() (string, string)
}
Screen represents the physical (or emulated) screen. This can be a terminal window or a physical console. Platforms implement this differently.
func NewTerminfoScreen ¶
func NewTerminfoScreen(opts ...TerminfoScreenOption) (Screen, error)
NewTerminfoScreen returns a Screen that uses the stock TTY interface and POSIX terminal control, combined with a terminfo description taken from the $TERM environment variable. It returns an error if the terminal is not supported for any reason.
For terminals that do not support dynamic resize events, the $LINES $COLUMNS environment variables can be set to the actual window size, otherwise defaults taken from the terminal database are used.
func NewTerminfoScreenFromTty ¶
func NewTerminfoScreenFromTty(tty Tty, opts ...TerminfoScreenOption) (Screen, error)
NewTerminfoScreenFromTty returns a Screen using a custom Tty implementation. If the passed in tty is nil, then a reasonable default (typically /dev/tty) is presumed, at least on UNIX hosts. (Windows hosts will typically fail this call altogether.)
type Style ¶
type Style struct {
// contains filtered or unexported fields
}
Style represents a complete text style, including both foreground color, background color, and additional attributes such as "bold" or "underline".
Note that not all terminals can display all colors or attributes, and many might have specific incompatibilities between specific attributes and color combinations.
To use Style, just declare a variable of its type.
var StyleDefault Style
StyleDefault represents a default style, based upon the context. It is the zero value.
func (Style) Attributes
deprecated
func (Style) Background ¶
Background returns a new style based on s, with the background color set as requested. ColorDefault can be used to select the global default.
func (Style) Blink ¶
Blink returns a new style based on s, with the blink attribute set as requested.
func (Style) Foreground ¶
Foreground returns a new style based on s, with the foreground color set as requested. ColorDefault can be used to select the global default.
func (Style) GetAttributes ¶
GetAttributes gets the attributes for a style. Deprecated: Use individual properties instead.
func (Style) GetBackground ¶
GetBackground returns the background color.
func (Style) GetForeground ¶
GetForeground returns the foreground (text) color.
func (Style) GetUnderlineColor ¶
GetUnderlineColor returns the underline color for the style.
func (Style) GetUnderlineStyle ¶
func (s Style) GetUnderlineStyle() UnderlineStyle
GetUnderlineStyle returns the underline style for the style.
func (Style) GetUrl ¶
GetUrl returns the URL (id and actual URL) associated with the style. This is a hyper link that will be used for cells marked up with this style.
func (Style) HasBold ¶
HasBold returns true if the style indicates bold text. Note that on some terminals bold text is simply brighter.
func (Style) HasReverse ¶
HasReverse returns true if the style indicates reverse video text.
func (Style) HasStrikeThrough ¶
HasStrikeThrough returns true if the style indicates crossed-out text.
func (Style) HasUnderline ¶
HasUnderline returns true if any underline style is set. Note that more detail is available via the GetUnderlineStyle and GetUnderlineColor methods.
func (Style) Italic ¶
Italic returns a new style based on s, with the italic attribute set as requested.
func (Style) Reverse ¶
Reverse returns a new style based on s, with the reverse attribute set as requested. (Reverse usually changes the foreground and background colors.)
func (Style) StrikeThrough ¶
StrikeThrough sets strike-through mode.
func (Style) Underline ¶
Underline returns a new style based on s, with the underline attribute set as requested. The parameters can be:
bool: on / off - enables just a simple underline UnderlineStyle: sets a specific style (should not coexist with the bool) Color: the color to use
func (Style) Url ¶
Url returns a style with the Url set. If the provided Url is not empty, and the terminal supports it, text will typically be marked up as a clickable link to that Url. If the Url is empty, then this mode is turned off.
type TerminfoScreenOption ¶
type TerminfoScreenOption interface {
// contains filtered or unexported methods
}
type Tty ¶
func NewDevTty ¶
NewDevTty obtains a default tty from the console or TTY (e.g. /dev/tty) for the process.
func NewDevTtyFromDev ¶
NewDevTtyFromDev obtains a tty from the given device path. Not supported on Windows.
type UnderlineStyle ¶
type UnderlineStyle uint8
Underline style. Modern terminals have the option of rendering the underline using different styles, and even different colors.
type WindowSize ¶
type WindowSize = tty.WindowSize
type XtermKbdMode ¶
type XtermKbdMode uint16
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package encoding is used to provide a fairly complete set of encodings for tcell applications.
|
Package encoding is used to provide a fairly complete set of encodings for tcell applications. |
|
layouts/all
Package all is used to import all keyboard layouts.
|
Package all is used to import all keyboard layouts. |