Documentation ¶
Overview ¶
Package tea provides a framework for building rich terminal user interfaces based on the paradigms of The Elm Architecture. It's well-suited for simple and complex terminal applications, either inline, full-window, or a mix of both. It's been battle-tested in several large projects and is production-ready.
A tutorial is available at https://github.com/charmbracelet/bubbletea/tree/master/tutorials
Example programs can be found at https://github.com/charmbracelet/bubbletea/tree/master/examples
Index ¶
- Constants
- func LogToFile(path string, prefix string) (*os.File, error)
- type Cmd
- func Batch(cmds ...Cmd) Cmd
- func Every(duration time.Duration, fn func(time.Time) Msg) Cmd
- func ScrollDown(newLines []string, topBoundary, bottomBoundary int) Cmd
- func ScrollUp(newLines []string, topBoundary, bottomBoundary int) Cmd
- func SyncScrollArea(lines []string, topBoundary int, bottomBoundary int) Cmd
- func Tick(d time.Duration, fn func(time.Time) Msg) Cmd
- type Init
- type Key
- type KeyMsg
- type KeyType
- type Model
- type MouseEvent
- type MouseEventType
- type MouseMsg
- type Msg
- type Program
- type Update
- type View
- type WindowSizeMsg
Constants ¶
const ( KeyNull = keyNUL KeyBreak = keyETX KeyEnter = keyCR KeyBackspace = keyBS KeyTab = keyHT KeySpace = keySP KeyEsc = keyESC KeyEscape = keyESC KeyDelete = keyDEL KeyCtrlAt = keyNUL // ctrl+@ KeyCtrlA = keySOH KeyCtrlB = keySTX KeyCtrlC = keyETX KeyCtrlD = keyEOT KeyCtrlE = keyENQ KeyCtrlF = keyACK KeyCtrlG = keyBEL KeyCtrlH = keyBS KeyCtrlI = keyHT KeyCtrlJ = keyLF KeyCtrlK = keyVT KeyCtrlL = keyFF KeyCtrlM = keyCR KeyCtrlN = keySO KeyCtrlO = keySI KeyCtrlP = keyDLE KeyCtrlQ = keyDC1 KeyCtrlR = keyDC2 KeyCtrlS = keyDC3 KeyCtrlT = keyDC4 KeyCtrlU = keyNAK KeyCtrlV = keySYN KeyCtrlW = keyETB KeyCtrlX = keyCAN KeyCtrlY = keyEM KeyCtrlZ = keySUB KeyCtrlOpenBracket = keyESC // ctrl+[ KeyCtrlBackslash = keyFS // ctrl+\ KeyCtrlCloseBracket = keyGS // ctrl+] KeyCtrlCaret = keyRS // ctrl+^ KeyCtrlUnderscore = keyUS // ctrl+_ KeyCtrlQuestionMark = keyDEL // ctrl+? )
Control key aliases.
const ( KeyRune = -(iota + 1) KeyUp KeyDown KeyRight KeyLeft KeyShiftTab KeyHome KeyEnd KeyPgUp KeyPgDown )
Other keys.
Variables ¶
This section is empty.
Functions ¶
func LogToFile ¶
LogToFile sets up default logging to log to a file. This is helpful as we can't print to the terminal since our TUI is occupying it. If the file doesn't exist it will be created.
Don't forget to close the file when you're done with it.
f, err := LogToFile("debug.log", "debug") if err != nil { fmt.Println("fatal:", err) os.Exit(1) } defer f.Close()
Types ¶
type Cmd ¶
type Cmd func() Msg
Cmd is an IO operation. If it's nil it's considered a no-op. Use it for things like HTTP requests, timers, saving and loading from disk, and so on.
There's almost never a need to use a command to send a message to another part of your program. Instead, it can almost always be done in the update function.
func Batch ¶
Batch peforms a bunch of commands concurrently with no ordering guarantees about the results.
func Every ¶
Every is a command that ticks in sync with the system clock. So, if you wanted to tick with the system clock every second, minute or hour you could use this. It's also handy for having different things tick in sync.
Because we're ticking with the system clock the tick will likely not run for the entire specified duration. For example, if we're ticking for one minute and the clock is at 12:34:20 then the next tick will happen at 12:35:00, 40 seconds later.
To produce the command, pass a duration and a function which returns a message containing the time at which the tick occurred.
type TickMsg time.Time cmd := Every(time.Second, func(t time.Time) Msg { return TickMsg(t) })
func ScrollDown ¶ added in v0.9.0
ScrollDown adds lines to the bottom of the scrollable region, pushing existing lines above up. Lines that are pushed out of the scrollable region disappear from view.
For high-performance, scroll-based rendering only.
func ScrollUp ¶ added in v0.9.0
ScrollUp adds lines to the top of the scrollable region, pushing existing lines below down. Lines that are pushed out the scrollable region disappear from view.
For high-performance, scroll-based rendering only.
func SyncScrollArea ¶ added in v0.9.0
SyncScrollArea performs a paint of the entire region designated to be the scrollable area. This is required to initialize the scrollable region and should also be called on resize (WindowSizeMsg).
For high-performance, scroll-based rendering only.
func Tick ¶
Tick produces a command at an interval independent of the system clock at the given duration. That is, the timer begins when precisely when invoked, and runs for its entire duration.
To produce the command, pass a duration and a function which returns a message containing the time at which the tick occurred.
type TickMsg time.Time cmd := Tick(time.Second, func(t time.Time) Msg { return TickMsg(t) })
type Init ¶
Init is the first function that will be called. It returns your initial model and runs an optional command.
type KeyMsg ¶
type KeyMsg Key
KeyMsg contains information about a keypress. KeyMsgs are always sent to the program's update function. There are a couple general patterns you could use to check for keypresses:
// Switch on the type (safer) switch msg := msg.(type) { case KeyMsg: switch msg.Type { case KeyEnter: fmt.Println("you pressed enter!") case KeyRune: switch msg.Rune { case 'a': fmt.Println("you pressed a!") } } } // Switch on the string representation of the key (shorter) switch msg := msg.(type) { case KeyMsg: switch msg.String() { case "enter": fmt.Println("you pressed enter!") case "a': fmt.Println("you pressed a!") } }
type KeyType ¶
type KeyType int
KeyType indicates the key pressed, such as KeyEnter or KeyBreak or KeyCtrlC. All other keys will be type KeyRune. To get the rune value, check the Rune method on a Key struct, or use the Key.String() method:
k := Key{Type: KeyRune, Rune: 'a', Alt: true} if k.Type == KeyRune { fmt.Println(k.Rune) // Output: a fmt.Println(k.String()) // Output: alt+a }
type MouseEvent ¶ added in v0.10.0
type MouseEvent struct { X int Y int Type MouseEventType Alt bool Ctrl bool }
MouseEvent represents a mouse event, which could be a click, a scroll wheel movement, a cursor movement, or a combination.
func (MouseEvent) String ¶ added in v0.10.0
func (m MouseEvent) String() (s string)
String returns a string representation of a mouse event.
type MouseEventType ¶ added in v0.10.5
type MouseEventType int
MouseEventType indicates the type of mouse event occurring.
const ( MouseUnknown MouseEventType = iota MouseLeft MouseRight MouseMiddle MouseRelease MouseWheelUp MouseWheelDown MouseMotion )
type MouseMsg ¶ added in v0.10.0
type MouseMsg MouseEvent
type Msg ¶
type Msg interface{}
Msg represents an action and is usually the result of an IO operation. It's triggers the Update function, and henceforth, the UI.
func ClearScrollArea ¶ added in v0.9.0
func ClearScrollArea() Msg
ClearScrollArea deallocates the scrollable region and returns the control of those lines to the main rendering routine.
For high-performance, scroll-based rendering only.
type Program ¶
type Program struct { // CatchPanics is incredibly useful for restoring the terminal to a useable // state after a panic occurs. When this is set, Bubble Tea will recover // from panics, print the stack trace, and disable raw mode. This feature // is on by default. CatchPanics bool // contains filtered or unexported fields }
Program is a terminal user interface.
func NewProgram ¶
NewProgram creates a new Program.
func (*Program) DisableMouseAllMotion ¶ added in v0.10.0
func (p *Program) DisableMouseAllMotion()
DisableMouseAllMotion disables All Motion mouse tracking. If you've enabled All Motion mouse tracking be sure you call this as your program is exiting or your users will be very upset!
func (*Program) DisableMouseCellMotion ¶ added in v0.10.0
func (p *Program) DisableMouseCellMotion()
DisableMouseCellMotion disables Mouse Cell Motion tracking. If you've enabled Cell Motion mouse trakcing be sure to call this as your program is exiting or your users will be very upset!
func (*Program) EnableMouseAllMotion ¶ added in v0.10.0
func (p *Program) EnableMouseAllMotion()
EnableMouseAllMotion enables mouse click, release, wheel and motion events, regardless of whether a button is pressed. Many modern terminals support this, but not all.
func (*Program) EnableMouseCellMotion ¶ added in v0.10.0
func (p *Program) EnableMouseCellMotion()
EnableMouseCellMotion enables mouse click, release, wheel and motion events if a button is pressed.
func (*Program) EnterAltScreen ¶ added in v0.10.0
func (p *Program) EnterAltScreen()
EnterAltScreen enters the alternate screen buffer, which consumes the entire terminal window. ExitAltScreen will return the terminal to its former state.
func (*Program) ExitAltScreen ¶ added in v0.10.0
func (p *Program) ExitAltScreen()
ExitAltScreen exits the alternate screen buffer.
type Update ¶
Update is called when a message is received. Use it to inspect messages and, in response, update the model and/or send a command.
type View ¶
View renders the program's UI, which is just a string. The view is rendered after every Update.
type WindowSizeMsg ¶ added in v0.9.0
WindowSizeMsg is used to report on the terminal size. It's sent to Update once initially and then on every terminal resize.