tcell: github.com/gdamore/tcell Index | Files | Directories

package tcell

import "github.com/gdamore/tcell"

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 provides support for up to 256 colors, text attributes, and box drawing elements. A database of terminals built from a real terminfo database is provided, along with code to generate new database entries.

Tcell offers very rich support for mice, dependent upon the terminal of course. (Windows, XTerm, and iTerm 2 are known to work very well.)

If the environment is not Unicode by default, such as an ISO8859 based locale or GB18030, Tcell can convert input and output, so that your terminal can operate in whatever locale is most convenient, while the application program can just assume "everything is UTF-8". Reasonable defaults are used for updating characters to something suitable for display. Unicode box drawing characters will be converted to use the alternate character set of your terminal, if native conversions are not available. If no ACS is available, then some ASCII fallbacks will be used.

Note that support for non-UTF-8 locales (other than C) must be enabled by the application using RegisterEncoding() -- we don't have them all enabled by default to avoid bloating the application unneccessarily. (These days UTF-8 is good enough for almost everyone, and nobody should be using legacy locales anymore.) Also, actual glyphs for various code point will only be displayed if your terminal or emulator (or the font the emulator is using) supports them.

A rich set of keycodes is supported, with support for up to 65 function keys, and various other special keys.

Index

Package Files

attr.go cell.go charset_unix.go color.go colorfit.go console_stub.go doc.go encoding.go errors.go event.go interrupt.go key.go mouse.go resize.go runes.go screen.go simulation.go style.go tscreen.go tscreen_linux.go

Constants

const (
    ColorGrey           = ColorGray
    ColorDimGrey        = ColorDimGray
    ColorDarkGrey       = ColorDarkGray
    ColorDarkSlateGrey  = ColorDarkSlateGray
    ColorLightGrey      = ColorLightGray
    ColorLightSlateGrey = ColorLightSlateGray
    ColorSlateGrey      = ColorSlateGray
)

These are aliases for the color gray, because some of us spell it as grey.

const (
    // EncodingFallbackFail behavior causes GetEncoding to fail
    // when it cannot find an encoding.
    EncodingFallbackFail = iota

    // EncodingFallbackASCII behaviore causes GetEncoding to fall back
    // to a 7-bit ASCII encoding, if no other encoding can be found.
    EncodingFallbackASCII

    // EncodingFallbackUTF8 behavior causes GetEncoding to assume
    // UTF8 can pass unmodified upon failure.  Note that this behavior
    // is not recommended, unless you are sure your terminal can cope
    // with real UTF8 sequences.
    EncodingFallbackUTF8
)
const (
    KeyBackspace  = KeyBS
    KeyTab        = KeyTAB
    KeyEsc        = KeyESC
    KeyEscape     = KeyESC
    KeyEnter      = KeyCR
    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.

Variables

var (
    // ErrTermNotFound indicates that a suitable terminal entry could
    // not be found.  This can result from either not having TERM set,
    // or from the TERM failing to support certain minimal functionality,
    // in particular absolute cursor addressability (the cup capability)
    // is required.  For example, legacy "adm3" lacks this capability,
    // whereas the slightly newer "adm3a" supports it.  This failure
    // occurs most often with "dumb".
    ErrTermNotFound = terminfo.ErrTermNotFound

    // 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 nacl),
    // 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 = map[string]Color{ /* 146 elements not displayed */

}

ColorNames holds the written names of colors. Useful to present a list of recognized named colors.

var ColorValues = map[Color]int32{ /* 379 elements not displayed */

}

ColorValues maps color constants to their RGB values.

var KeyNames = map[Key]string{ /* 118 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.

func GetEncoding Uses

func GetEncoding(charset string) encoding.Encoding

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 Uses

func RegisterEncoding(charset string, enc encoding.Encoding)

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.

Windows systems use Unicode natively, and do not need any of the encoding subsystem when using Windows Console screens.

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:

import "golang.org/x/text/encoding/charmap"

  ...
  RegisterEncoding("ISO8859-15", charmap.ISO8859_15)

Aliases can be registered as well, for example "8859-15" could be an alias for "ISO8859-15".

For POSIX systems, the tcell 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.)

Modern POSIX systems and terminal emulators may use UTF-8, and for those systems, this API is also unnecessary. For example, Darwin (MacOS X) and modern Linux running modern xterm generally will out of the box without any of this. Use of UTF-8 is recommended when possible, as it saves quite a lot processing overhead.

Note that some encodings are quite large (for example GB18030 which is a superset of Unicode) and so the application size can be expected ot increase quite a bit as each encoding is added. The East Asian encodings have been seen to add 100-200K per encoding to the application size.

func SetEncodingFallback Uses

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.

type AttrMask Uses

type AttrMask int

AttrMask represents a mask of text attributes, apart from color. Note that support for attributes may vary widely across terminals.

const (
    AttrBold AttrMask = 1 << (25 + iota)
    AttrBlink
    AttrReverse
    AttrUnderline
    AttrDim
    AttrNone AttrMask = 0 // Just normal text.
)

Attributes are not colors, but affect the display of text. They can be combined.

type ButtonMask Uses

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 left mouse button.
    Button2                        // Usually the middle mouse button.
    Button3                        // Usually the right 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.
)

These are the actual button values.

type CellBuffer Uses

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 implementors; 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 Uses

func (cb *CellBuffer) Dirty(x, y int) bool

Dirty checks if a character at the given location needs an 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 Uses

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.

func (*CellBuffer) GetContent Uses

func (cb *CellBuffer) GetContent(x, y int) (rune, []rune, Style, int)

GetContent returns the contents of a character cell, including the primary rune, any combining character runes (which will usually be nil), the style, and the display width in cells. (The width can be either 1, normally, or 2 for East Asian full-width characters.)

func (*CellBuffer) Invalidate Uses

func (cb *CellBuffer) Invalidate()

Invalidate marks all characters within the buffer as dirty.

func (*CellBuffer) Resize Uses

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) SetContent Uses

func (cb *CellBuffer) SetContent(x int, y int,
    mainc rune, combc []rune, style Style)

SetContent sets the contents (primary rune, combining runes, and style) for a cell at a given location.

func (*CellBuffer) SetDirty Uses

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 Uses

func (cb *CellBuffer) Size() (int, int)

Size returns the (width, height) in cells of the buffer.

type Color Uses

type Color int32

Color represents a color. The low numeric values are the same as used by ECMA-48, and beyond that XTerm. A 24-bit RGB value may be used by adding in the ColorIsRGB flag. For Color names we use the W3C approved color names.

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.

const (
    // ColorDefault is used to leave the Color unchanged from whatever
    // system or teminal default may exist.
    ColorDefault Color = -1

    // ColorIsRGB is used to indicate that the numeric value is not
    // a known color constant, but rather an RGB value.  The lower
    // order 3 bytes are RGB.
    ColorIsRGB Color = 1 << 24
)
const (
    ColorBlack Color = iota
    ColorMaroon
    ColorGreen
    ColorOlive
    ColorNavy
    ColorPurple
    ColorTeal
    ColorSilver
    ColorGray
    ColorRed
    ColorLime
    ColorYellow
    ColorBlue
    ColorFuchsia
    ColorAqua
    ColorWhite
    Color16
    Color17
    Color18
    Color19
    Color20
    Color21
    Color22
    Color23
    Color24
    Color25
    Color26
    Color27
    Color28
    Color29
    Color30
    Color31
    Color32
    Color33
    Color34
    Color35
    Color36
    Color37
    Color38
    Color39
    Color40
    Color41
    Color42
    Color43
    Color44
    Color45
    Color46
    Color47
    Color48
    Color49
    Color50
    Color51
    Color52
    Color53
    Color54
    Color55
    Color56
    Color57
    Color58
    Color59
    Color60
    Color61
    Color62
    Color63
    Color64
    Color65
    Color66
    Color67
    Color68
    Color69
    Color70
    Color71
    Color72
    Color73
    Color74
    Color75
    Color76
    Color77
    Color78
    Color79
    Color80
    Color81
    Color82
    Color83
    Color84
    Color85
    Color86
    Color87
    Color88
    Color89
    Color90
    Color91
    Color92
    Color93
    Color94
    Color95
    Color96
    Color97
    Color98
    Color99
    Color100
    Color101
    Color102
    Color103
    Color104
    Color105
    Color106
    Color107
    Color108
    Color109
    Color110
    Color111
    Color112
    Color113
    Color114
    Color115
    Color116
    Color117
    Color118
    Color119
    Color120
    Color121
    Color122
    Color123
    Color124
    Color125
    Color126
    Color127
    Color128
    Color129
    Color130
    Color131
    Color132
    Color133
    Color134
    Color135
    Color136
    Color137
    Color138
    Color139
    Color140
    Color141
    Color142
    Color143
    Color144
    Color145
    Color146
    Color147
    Color148
    Color149
    Color150
    Color151
    Color152
    Color153
    Color154
    Color155
    Color156
    Color157
    Color158
    Color159
    Color160
    Color161
    Color162
    Color163
    Color164
    Color165
    Color166
    Color167
    Color168
    Color169
    Color170
    Color171
    Color172
    Color173
    Color174
    Color175
    Color176
    Color177
    Color178
    Color179
    Color180
    Color181
    Color182
    Color183
    Color184
    Color185
    Color186
    Color187
    Color188
    Color189
    Color190
    Color191
    Color192
    Color193
    Color194
    Color195
    Color196
    Color197
    Color198
    Color199
    Color200
    Color201
    Color202
    Color203
    Color204
    Color205
    Color206
    Color207
    Color208
    Color209
    Color210
    Color211
    Color212
    Color213
    Color214
    Color215
    Color216
    Color217
    Color218
    Color219
    Color220
    Color221
    Color222
    Color223
    Color224
    Color225
    Color226
    Color227
    Color228
    Color229
    Color230
    Color231
    Color232
    Color233
    Color234
    Color235
    Color236
    Color237
    Color238
    Color239
    Color240
    Color241
    Color242
    Color243
    Color244
    Color245
    Color246
    Color247
    Color248
    Color249
    Color250
    Color251
    Color252
    Color253
    Color254
    Color255
    ColorAliceBlue
    ColorAntiqueWhite
    ColorAquaMarine
    ColorAzure
    ColorBeige
    ColorBisque
    ColorBlanchedAlmond
    ColorBlueViolet
    ColorBrown
    ColorBurlyWood
    ColorCadetBlue
    ColorChartreuse
    ColorChocolate
    ColorCoral
    ColorCornflowerBlue
    ColorCornsilk
    ColorCrimson
    ColorDarkBlue
    ColorDarkCyan
    ColorDarkGoldenrod
    ColorDarkGray
    ColorDarkGreen
    ColorDarkKhaki
    ColorDarkMagenta
    ColorDarkOliveGreen
    ColorDarkOrange
    ColorDarkOrchid
    ColorDarkRed
    ColorDarkSalmon
    ColorDarkSeaGreen
    ColorDarkSlateBlue
    ColorDarkSlateGray
    ColorDarkTurquoise
    ColorDarkViolet
    ColorDeepPink
    ColorDeepSkyBlue
    ColorDimGray
    ColorDodgerBlue
    ColorFireBrick
    ColorFloralWhite
    ColorForestGreen
    ColorGainsboro
    ColorGhostWhite
    ColorGold
    ColorGoldenrod
    ColorGreenYellow
    ColorHoneydew
    ColorHotPink
    ColorIndianRed
    ColorIndigo
    ColorIvory
    ColorKhaki
    ColorLavender
    ColorLavenderBlush
    ColorLawnGreen
    ColorLemonChiffon
    ColorLightBlue
    ColorLightCoral
    ColorLightCyan
    ColorLightGoldenrodYellow
    ColorLightGray
    ColorLightGreen
    ColorLightPink
    ColorLightSalmon
    ColorLightSeaGreen
    ColorLightSkyBlue
    ColorLightSlateGray
    ColorLightSteelBlue
    ColorLightYellow
    ColorLimeGreen
    ColorLinen
    ColorMediumAquamarine
    ColorMediumBlue
    ColorMediumOrchid
    ColorMediumPurple
    ColorMediumSeaGreen
    ColorMediumSlateBlue
    ColorMediumSpringGreen
    ColorMediumTurquoise
    ColorMediumVioletRed
    ColorMidnightBlue
    ColorMintCream
    ColorMistyRose
    ColorMoccasin
    ColorNavajoWhite
    ColorOldLace
    ColorOliveDrab
    ColorOrange
    ColorOrangeRed
    ColorOrchid
    ColorPaleGoldenrod
    ColorPaleGreen
    ColorPaleTurquoise
    ColorPaleVioletRed
    ColorPapayaWhip
    ColorPeachPuff
    ColorPeru
    ColorPink
    ColorPlum
    ColorPowderBlue
    ColorRebeccaPurple
    ColorRosyBrown
    ColorRoyalBlue
    ColorSaddleBrown
    ColorSalmon
    ColorSandyBrown
    ColorSeaGreen
    ColorSeashell
    ColorSienna
    ColorSkyblue
    ColorSlateBlue
    ColorSlateGray
    ColorSnow
    ColorSpringGreen
    ColorSteelBlue
    ColorTan
    ColorThistle
    ColorTomato
    ColorTurquoise
    ColorViolet
    ColorWheat
    ColorWhiteSmoke
    ColorYellowGreen
)

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.

func FindColor Uses

func FindColor(c Color, palette []Color) Color

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.

func GetColor Uses

func GetColor(name string) Color

GetColor creates a Color from a color name (W3C name). A hex value may be supplied as a string in the format "#ffffff".

func NewHexColor Uses

func NewHexColor(v int32) Color

NewHexColor returns a color using the given 24-bit RGB value.

func NewRGBColor Uses

func NewRGBColor(r, g, b int32) Color

NewRGBColor returns a new color with the given red, green, and blue values. Each value must be represented in the range 0-255.

func (Color) Hex Uses

func (c Color) Hex() int32

Hex returns the color's hexadecimal RGB 24-bit value with each component consisting of a single byte, ala R << 16 | G << 8 | B. If the color is unknown or unset, -1 is returned.

func (Color) RGB Uses

func (c Color) RGB() (int32, int32, int32)

RGB returns the red, green, and blue components of the color, with each component represented as a value 0-255. In the event that the color cannot be broken up (not set usually), -1 is returned for each value.

type EncodingFallback Uses

type EncodingFallback int

EncodingFallback describes how the system behavees 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.)

type Event Uses

type Event interface {
    // When reports the time when the event was generated.
    When() time.Time
}

Event is a generic interface used for passing around Events. Concrete types follow.

type EventError Uses

type EventError struct {
    // contains filtered or unexported fields
}

An EventError is an event representing some sort of error, and carries an error payload.

func NewEventError Uses

func NewEventError(err error) *EventError

NewEventError creates an ErrorEvent with the given error payload.

func (*EventError) Error Uses

func (ev *EventError) Error() string

Error implements the error.

func (*EventError) When Uses

func (ev *EventError) When() time.Time

When returns the time when the event was created.

type EventHandler Uses

type EventHandler interface {
    HandleEvent(Event) bool
}

EventHandler is anything that handles events. If the handler has consumed the event, it should return true. False otherwise.

type EventInterrupt Uses

type EventInterrupt struct {
    // 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 Uses

func NewEventInterrupt(data interface{}) *EventInterrupt

NewEventInterrupt creates an EventInterrupt with the given payload.

func (*EventInterrupt) Data Uses

func (ev *EventInterrupt) Data() interface{}

Data is used to obtain the opaque event payload.

func (*EventInterrupt) When Uses

func (ev *EventInterrupt) When() time.Time

When returns the time when this event was created.

type EventKey Uses

type EventKey struct {
    // 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 with the Rune() 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 Uses

func NewEventKey(k Key, ch rune, mod ModMask) *EventKey

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 Uses

func (ev *EventKey) Key() 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 Rune() function.

func (*EventKey) Modifiers Uses

func (ev *EventKey) Modifiers() ModMask

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.

func (*EventKey) Name Uses

func (ev *EventKey) Name() string

Name returns a printable value or the key stroke. This can be used when printing the event, for example.

func (*EventKey) Rune Uses

func (ev *EventKey) Rune() rune

Rune returns the rune corresponding to the key press, if it makes sense. The result is only defined if the value of Key() is KeyRune.

func (*EventKey) When Uses

func (ev *EventKey) When() time.Time

When returns the time when this Event was created, which should closely match the time when the key was pressed.

type EventMouse Uses

type EventMouse struct {
    // 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 Uses

func NewEventMouse(x, y int, btn ButtonMask, mod ModMask) *EventMouse

NewEventMouse is used to create a new mouse event. Applications shouldn't need to use this; its mostly for screen implementors.

func (*EventMouse) Buttons Uses

func (ev *EventMouse) Buttons() ButtonMask

Buttons returns the list of buttons that were pressed or wheel motions.

func (*EventMouse) Modifiers Uses

func (ev *EventMouse) Modifiers() ModMask

Modifiers returns a list of keyboard modifiers that were pressed with the mouse button(s).

func (*EventMouse) Position Uses

func (ev *EventMouse) Position() (int, int)

Position returns the mouse position in character cells. The origin 0, 0 is at the upper left corner.

func (*EventMouse) When Uses

func (ev *EventMouse) When() time.Time

When returns the time when this EventMouse was created.

type EventResize Uses

type EventResize struct {
    // contains filtered or unexported fields
}

EventResize is sent when the window size changes.

func NewEventResize Uses

func NewEventResize(width, height int) *EventResize

NewEventResize creates an EventResize with the new updated window size, which is given in character cells.

func (*EventResize) Size Uses

func (ev *EventResize) Size() (int, int)

Size returns the new window size as width, height in character cells.

func (*EventResize) When Uses

func (ev *EventResize) When() time.Time

When returns the time when the Event was created.

type EventTime Uses

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 Uses

func (e *EventTime) SetEventNow()

SetEventNow sets the time of occurrence for the event to the current time.

func (*EventTime) SetEventTime Uses

func (e *EventTime) SetEventTime(t time.Time)

SetEventTime sets the time of occurrence for the event.

func (*EventTime) When Uses

func (e *EventTime) When() time.Time

When returns the time stamp when the event occurred.

type Key Uses

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 Rune() 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
)

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 (
    KeyCtrlSpace Key = iota
    KeyCtrlA
    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
    KeyCtrlLeftSq // Escape
    KeyCtrlBackslash
    KeyCtrlRightSq
    KeyCtrlCarat
    KeyCtrlUnderscore
)

These are the control keys. Note that they overlap with other keys, perhaps. For example, KeyCtrlH is the same as KeyBackspace.

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 ModMask Uses

type ModMask int16

ModMask is a mask of modifier keys. Note that it will not always be possible to report modifier keys.

const (
    ModShift ModMask = 1 << iota
    ModCtrl
    ModAlt
    ModMeta
    ModNone ModMask = 0
)

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 Screen Uses

type Screen interface {
    // Init initializes the screen for use.
    Init() error

    // Fini finalizes the screen also releasing resources.
    Fini()

    // Clear erases the screen.  The contents of any screen buffers
    // will also be cleared.  This has the logical effect of
    // filling the screen with spaces, using the global default style.
    Clear()

    // Fill fills the screen with the given character and style.
    Fill(rune, Style)

    // SetCell is an older API, and will be removed.  Please use
    // SetContent instead; SetCell is implemented in terms of SetContent.
    SetCell(x int, y int, style Style, ch ...rune)

    // GetContent returns 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 require two cells.
    GetContent(x, y int) (mainc rune, combc []rune, 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 displayd until Show() or Sync() is called.
    //
    // Note that wide (East Asian full width) 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, mainc rune, combc []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.  Its an alias for
    // ShowCursor(-1, -1).
    HideCursor()

    // Size returns the screen size as width, height.  This changes in
    // response to a call to Clear or Flush.
    Size() (int, int)

    // PollEvent waits for events to arrive.  Main application loops
    // must spin on this to prevent the application from stalling.
    // Furthermore, this will return nil if the Screen is finalized.
    PollEvent() Event

    // PostEvent tries to post an event into the event stream.  This
    // can fail if the event queue is full.  In that case, the event
    // is dropped, and ErrEventQFull is returned.
    PostEvent(ev Event) error

    // PostEventWait is like PostEvent, but if the queue is full, it
    // blocks until there is space in the queue, making delivery
    // reliable.  However, it is VERY important that this function
    // never be called from within whatever event loop is polling
    // with PollEvent(), otherwise a deadlock may arise.
    //
    // For this reason, when using this function, the use of a
    // Goroutine is recommended to ensure no deadlock can occur.
    PostEventWait(ev Event)

    // EnableMouse enables the mouse.  (If your terminal supports it.)
    EnableMouse()

    // DisableMouse disables the mouse.
    DisableMouse()

    // HasMouse returns true if the terminal (apparently) supports a
    // mouse.  Note that the a return value of true doesn't guarantee that
    // a mouse/pointing device is present; a false return definitely
    // indicates no mouse support is available.
    HasMouse() bool

    // 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

    // 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)

    // CanDisplay returns true if the given rune can be displayed on
    // this screen.  Note that this is a best guess effort -- whether
    // your fonts support the character or not may be questionable.
    // Mostly this is for folks who work outside of Unicode.
    //
    // If checkFallbacks is true, then if any (possibly imperfect)
    // fallbacks are registered, this will return true.  This will
    // also return true if the terminal can replace the glyph with
    // one that is visually indistinguishable from the one requested.
    CanDisplay(r rune, checkFallbacks bool) bool

    // Resize does nothing, since its generally not possible to
    // ask a screen to resize, but it allows the Screen to implement
    // the View interface.
    Resize(int, int, int, int)

    // HasKey returns true if the keyboard is believed to have the
    // key.  In some cases a keyboard may have keys with this name
    // but no support for them, while in others a key may be reported
    // as supported but not actually be usable (such as some emulators
    // that hijack certain keys).  Its best not to depend to strictly
    // on this function, but it can be used for hinting when building
    // menus, displayed hot-keys, etc.  Note that KeyRune (literal
    // runes) is always true.
    HasKey(Key) bool
}

Screen represents the physical (or emulated) screen. This can be a terminal window or a physical console. Platforms implement this differerently.

func NewConsoleScreen Uses

func NewConsoleScreen() (Screen, error)

NewConsoleScreen returns a console based screen. This platform doesn't have support for any, so it returns nil and a suitable error.

func NewScreen Uses

func NewScreen() (Screen, error)

NewScreen returns a default Screen suitable for the user's terminal environment.

func NewTerminfoScreen Uses

func NewTerminfoScreen() (Screen, error)

NewTerminfoScreen returns a Screen that uses the stock TTY interface and POSIX termios, 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.

type SimCell Uses

type SimCell struct {
    // Bytes is the actual character bytes.  Normally this is
    // rune data, but it could be be data in another encoding system.
    Bytes []byte

    // Style is the style used to display the data.
    Style Style

    // Runes is the list of runes, unadulterated, in UTF-8.
    Runes []rune
}

SimCell represents a simulated screen cell. The purpose of this is to track on screen content.

type SimulationScreen Uses

type SimulationScreen interface {
    // InjectKeyBytes injects a stream of bytes corresponding to
    // the native encoding (see charset).  It turns true if the entire
    // set of bytes were processed and delivered as KeyEvents, false
    // if any bytes were not fully understood.  Any bytes that are not
    // fully converted are discarded.
    InjectKeyBytes(buf []byte) bool

    // InjectKey injects a key event.  The rune is a UTF-8 rune, post
    // any translation.
    InjectKey(key Key, r rune, mod ModMask)

    // InjectMouse injects a mouse event.
    InjectMouse(x, y int, buttons ButtonMask, mod ModMask)

    // SetSize resizes the underlying physical screen.  It also causes
    // a resize event to be injected during the next Show() or Sync().
    // A new physical contents array will be allocated (with data from
    // the old copied), so any prior value obtained with GetContents
    // won't be used anymore
    SetSize(width, height int)

    // GetContents returns screen contents as an array of
    // cells, along with the physical width & height.   Note that the
    // physical contents will be used until the next time SetSize()
    // is called.
    GetContents() (cells []SimCell, width int, height int)

    // GetCursor returns the cursor details.
    GetCursor() (x int, y int, visible bool)

    Screen
}

SimulationScreen represents a screen simulation. This is intended to be a superset of normal Screens, but also adds some important interfaces for testing.

func NewSimulationScreen Uses

func NewSimulationScreen(charset string) SimulationScreen

NewSimulationScreen returns a SimulationScreen. Note that SimulationScreen is also a Screen.

type Style Uses

type Style int64

Style represents a complete text style, including both foreground and background color. We encode it in a 64-bit int for efficiency. The coding is (MSB): <7b flags><1b><24b fgcolor><7b attr><1b><24b bgcolor>. The <1b> is set true to indicate that the color is an RGB color, rather than a named index.

This gives 24bit color options, if it ever becomes truly necessary. However, applications must not rely on this encoding.

Note that not all terminals can display all colors or attributes, and many might have specific incompatibilities between specific attributes and color combinations.

The intention is to extend styles to support paletting, in which case some flag bit(s) would be set, and the foreground and background colors would be replaced with a palette number and palette index.

To use Style, just declare a variable of its type.

const StyleDefault Style = 0

StyleDefault represents a default style, based upon the context. It is the zero value.

func (Style) Background Uses

func (s Style) Background(c Color) Style

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 (s Style) Blink(on bool) Style

Blink returns a new style based on s, with the blink attribute set as requested.

func (Style) Bold Uses

func (s Style) Bold(on bool) Style

Bold returns a new style based on s, with the bold attribute set as requested.

func (Style) Decompose Uses

func (s Style) Decompose() (fg Color, bg Color, attr AttrMask)

Decompose breaks a style up, returning the foreground, background, and other attributes.

func (Style) Dim Uses

func (s Style) Dim(on bool) Style

Dim returns a new style based on s, with the dim attribute set as requested.

func (Style) Foreground Uses

func (s Style) Foreground(c Color) Style

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) Normal Uses

func (s Style) Normal() Style

Normal returns the style with all attributes disabled.

func (Style) Reverse Uses

func (s Style) Reverse(on bool) Style

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) Underline Uses

func (s Style) Underline(on bool) Style

Underline returns a new style based on s, with the underline attribute set as requested.

Directories

PathSynopsis
_demosboxes just displays random colored boxes on your terminal screen.
encoding
termboxPackage termbox is a compatibility layer to allow tcells to emulate the github.com/nsf/termbox package.
terminfo
views
views/_demos

Package tcell imports 20 packages (graph) and is imported by 143 packages. Updated 2018-10-30. Refresh now. Tools for package owners.