bubbletea/renderer.go

393 lines
11 KiB
Go
Raw Normal View History

2020-06-05 12:40:44 -04:00
package tea
import (
"bytes"
"io"
"strings"
2020-06-05 12:40:44 -04:00
"sync"
"time"
)
const (
2020-06-16 11:05:04 -04:00
// defaultFramerate specifies the maximum interval at which we should
// update the view.
defaultFramerate = time.Second / 60
2020-06-05 12:40:44 -04:00
)
2020-06-16 11:05:04 -04:00
// renderer is a timer-based renderer, updating the view at a given framerate
// to avoid overloading the terminal emulator.
//
// In cases where very high performance is needed the renderer can be told
// to exclude ranges of lines, allowing them to be written to directly.
2020-06-05 12:40:44 -04:00
type renderer struct {
out io.Writer
buf bytes.Buffer
framerate time.Duration
ticker *time.Ticker
mtx *sync.Mutex
2020-06-05 12:40:44 -04:00
done chan struct{}
lastRender string
linesRendered int
// essentially whether or not we're using the full size of the terminal
altScreenActive bool
2020-07-06 11:54:02 -04:00
// renderer dimensions; usually the size of the window
width int
height int
// lines not to render
ignoreLines map[int]struct{}
2020-06-05 12:40:44 -04:00
}
// newRenderer creates a new renderer. Normally you'll want to initialize it
2020-07-06 11:54:02 -04:00
// with os.Stdout as the first argument.
func newRenderer(out io.Writer, mtx *sync.Mutex) *renderer {
2020-06-05 12:40:44 -04:00
return &renderer{
out: out,
mtx: mtx,
2020-06-05 12:40:44 -04:00
framerate: defaultFramerate,
}
}
// start starts the renderer.
2020-06-05 12:40:44 -04:00
func (r *renderer) start() {
if r.ticker == nil {
r.ticker = time.NewTicker(r.framerate)
}
r.done = make(chan struct{})
go r.listen()
}
// stop permanently halts the renderer.
2020-06-05 12:40:44 -04:00
func (r *renderer) stop() {
r.flush()
r.done <- struct{}{}
}
2020-06-19 14:14:15 -04:00
// listen waits for ticks on the ticker, or a signal to stop the renderer.
2020-06-05 12:40:44 -04:00
func (r *renderer) listen() {
for {
select {
case <-r.ticker.C:
if r.ticker != nil {
r.flush()
}
case <-r.done:
r.mtx.Lock()
r.ticker.Stop()
r.ticker = nil
r.mtx.Unlock()
close(r.done)
return
}
}
}
// flush renders the buffer.
2020-06-05 12:40:44 -04:00
func (r *renderer) flush() {
if r.buf.Len() == 0 || r.buf.String() == r.lastRender {
// Nothing to do
return
}
2020-06-11 21:38:27 -04:00
// We have an opportunity here to limit the rendering to the terminal width
// and height, but this would mean a few things:
2020-06-08 12:43:24 -04:00
//
// 1) We'd need to maintain the terminal dimensions internally and listen
// for window size changes. [done]
2020-06-08 12:43:24 -04:00
//
2020-06-16 11:05:04 -04:00
// 2) We'd need to measure the width of lines, accounting for multi-cell
// rune widths, commonly found in Chinese, Japanese, Korean, emojis and so
// on. We'd use something like go-runewidth
2020-06-08 12:43:24 -04:00
// (http://github.com/mattn/go-runewidth).
//
// 3) We'd need to measure the width of lines excluding ANSI escape
// sequences and break lines in the right places accordingly.
//
// Because of the way this would complicate the renderer, this may not be
// the place to do that.
out := new(bytes.Buffer)
2020-06-05 12:40:44 -04:00
r.mtx.Lock()
defer r.mtx.Unlock()
2020-06-18 18:34:02 -04:00
// Clear any lines we painted in the last render.
2020-06-05 12:40:44 -04:00
if r.linesRendered > 0 {
2020-06-20 14:46:44 -04:00
for i := r.linesRendered - 1; i > 0; i-- {
2020-06-18 18:34:02 -04:00
// Check if we should skip rendering for this line. Clearing the
// line before painting is part of the standard rendering routine.
if _, exists := r.ignoreLines[i]; !exists {
clearLine(out)
}
2020-06-17 11:49:33 -04:00
cursorUp(out)
}
if _, exists := r.ignoreLines[0]; !exists {
// We need to return to the start of the line here to properly
// erase it. Going back the entire width of the terminal will
// usually be farther than we need to go, but terminal emulators
// will stop the cursor at the start of the line as a rule.
//
// We use this sequence in particular because it's part of the ANSI
// standard (whereas others are proprietary to, say, VT100/VT52).
2020-06-18 18:34:02 -04:00
// If cursor previous line (ESC[ + <n> + F) were better supported
// we could use that above to eliminate this step.
cursorBack(out, r.width)
2020-06-17 11:49:33 -04:00
clearLine(out)
}
2020-06-05 12:40:44 -04:00
}
2020-06-18 18:34:02 -04:00
2020-06-05 12:40:44 -04:00
r.linesRendered = 0
2020-06-18 18:34:02 -04:00
lines := strings.Split(r.buf.String(), "\n")
2020-06-05 12:40:44 -04:00
2020-06-18 18:34:02 -04:00
// Paint new lines
for i := 0; i < len(lines); i++ {
if _, exists := r.ignoreLines[r.linesRendered]; exists {
cursorDown(out) // skip rendering for this line.
2020-06-05 12:40:44 -04:00
} else {
2020-06-18 18:34:02 -04:00
_, _ = io.WriteString(out, lines[i])
if i != len(lines)-1 {
_, _ = io.WriteString(out, "\r\n")
}
2020-06-05 12:40:44 -04:00
}
2020-06-18 18:34:02 -04:00
r.linesRendered++
2020-06-05 12:40:44 -04:00
}
// Make sure the cursor is at the start of the last line to keep rendering
// behavior consistent.
if r.altScreenActive {
// We need this case to fix a bug in macOS terminal. In other terminals
// the below case seems to do the job regardless of whether or not we're
// using the full terminal window.
moveCursor(out, r.linesRendered, 0)
} else {
cursorBack(out, r.width)
}
2020-06-05 12:40:44 -04:00
_, _ = r.out.Write(out.Bytes())
r.lastRender = r.buf.String()
r.buf.Reset()
}
// write writes to the internal buffer. The buffer will be outputted via the
// ticker which calls flush().
func (r *renderer) write(s string) {
r.mtx.Lock()
defer r.mtx.Unlock()
r.buf.Reset()
_, _ = r.buf.WriteString(s)
}
// setIngoredLines speicifies lines not to be touched by the standard Bubble Tea
// renderer.
func (r *renderer) setIgnoredLines(from int, to int) {
// Lock if we're going to be clearing some lines since we don't want
// anything jacking our cursor.
if r.linesRendered > 0 {
r.mtx.Lock()
defer r.mtx.Unlock()
}
2020-06-18 12:19:36 -04:00
if r.ignoreLines == nil {
r.ignoreLines = make(map[int]struct{})
}
for i := from; i < to; i++ {
r.ignoreLines[i] = struct{}{}
}
// Erase ignored lines
if r.linesRendered > 0 {
out := new(bytes.Buffer)
for i := r.linesRendered - 1; i >= 0; i-- {
if _, exists := r.ignoreLines[i]; exists {
clearLine(out)
}
cursorUp(out)
}
moveCursor(out, r.linesRendered, 0) // put cursor back
_, _ = r.out.Write(out.Bytes())
}
}
// clearIgnoredLines returns control of any ignored lines to the standard
// Bubble Tea renderer. That is, any lines previously set to be ignored can be
// rendered to again.
func (r *renderer) clearIgnoredLines() {
2020-06-18 12:19:36 -04:00
r.ignoreLines = nil
}
// insertTop effectively scrolls up. It inserts lines at the top of a given
// area designated to be a scrollable region, pushing everything else down.
// This is roughly how ncurses does it.
//
// To call this function use command ScrollUp().
//
// For this to work renderer.ignoreLines must be set to ignore the scrollable
// region since we are bypassing the normal Bubble Tea renderer here.
//
// Because this method relies on the terminal dimensions, it's only valid for
// full-window applications (generally those that use the alternate screen
// buffer).
//
// This method bypasses the normal rendering buffer and is philisophically
// different than the normal way we approach rendering in Bubble Tea. It's for
// use in high-performance rendering, such as a pager that could potentially
// be rendering very complicated ansi. In cases where the content is simpler
// standard Bubble Tea rendering should suffice.
func (r *renderer) insertTop(lines []string, topBoundary, bottomBoundary int) {
r.mtx.Lock()
defer r.mtx.Unlock()
b := new(bytes.Buffer)
changeScrollingRegion(b, topBoundary, bottomBoundary)
moveCursor(b, topBoundary, 0)
insertLine(b, len(lines))
2020-06-18 14:35:04 -04:00
_, _ = io.WriteString(b, strings.Join(lines, "\r\n"))
changeScrollingRegion(b, 0, r.height)
// Move cursor back to where the main rendering routine expects it to be
moveCursor(b, r.linesRendered, 0)
_, _ = r.out.Write(b.Bytes())
}
// insertBottom effectively scrolls down. It inserts lines at the bottom of
// a given area designated to be a scrollable region, pushing everything else
// up. This is roughly how ncurses does it.
//
// To call this function use the command ScrollDown().
//
// See note in insertTop() for caveats, how this function only makes sense for
// full-window applications, and how it differs from the noraml way we do
// rendering in Bubble Tea.
func (r *renderer) insertBottom(lines []string, topBoundary, bottomBoundary int) {
r.mtx.Lock()
defer r.mtx.Unlock()
b := new(bytes.Buffer)
changeScrollingRegion(b, topBoundary, bottomBoundary)
2020-06-17 20:24:43 -04:00
moveCursor(b, bottomBoundary, 0)
_, _ = io.WriteString(b, "\r\n"+strings.Join(lines, "\r\n"))
changeScrollingRegion(b, 0, r.height)
// Move cursor back to where the main rendering routine expects it to be
moveCursor(b, r.linesRendered, 0)
_, _ = r.out.Write(b.Bytes())
2020-06-05 12:40:44 -04:00
}
2020-06-18 12:19:36 -04:00
// handleMessages handles internal messages for the renderer.
func (r *renderer) handleMessages(msg Msg) {
switch msg := msg.(type) {
case WindowSizeMsg:
r.width = msg.Width
r.height = msg.Height
case clearScrollAreaMsg:
r.clearIgnoredLines()
// Force a repaint on the area where the scrollable stuff was in this
// update cycle
r.mtx.Lock()
r.lastRender = ""
r.mtx.Unlock()
case syncScrollAreaMsg:
// Re-render scrolling area
r.clearIgnoredLines()
r.setIgnoredLines(msg.topBoundary, msg.bottomBoundary)
r.insertTop(msg.lines, msg.topBoundary, msg.bottomBoundary)
// Force non-scrolling stuff to repaint in this update cycle
r.mtx.Lock()
r.lastRender = ""
r.mtx.Unlock()
case scrollUpMsg:
r.insertTop(msg.lines, msg.topBoundary, msg.bottomBoundary)
case scrollDownMsg:
2020-06-17 20:24:43 -04:00
r.insertBottom(msg.lines, msg.topBoundary, msg.bottomBoundary)
}
}
// HIGH-PERFORMANCE RENDERING STUFF
type syncScrollAreaMsg struct {
lines []string
topBoundary int
bottomBoundary int
}
2020-07-29 20:49:20 -04:00
// 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).
2020-06-19 14:14:15 -04:00
//
// For high-performance, scroll-based rendering only.
func SyncScrollArea(lines []string, topBoundary int, bottomBoundary int) Cmd {
return func() Msg {
return syncScrollAreaMsg{
lines: lines,
topBoundary: topBoundary,
bottomBoundary: bottomBoundary,
}
}
}
type clearScrollAreaMsg struct{}
2020-06-19 14:14:15 -04:00
// ClearScrollArea deallocates the scrollable region and returns the control of
// those lines to the main rendering routine.
//
// For high-performance, scroll-based rendering only.
func ClearScrollArea() Msg {
return clearScrollAreaMsg{}
}
type scrollUpMsg struct {
lines []string
topBoundary int
bottomBoundary int
}
2020-07-29 20:49:20 -04:00
// 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.
2020-06-19 14:14:15 -04:00
//
// For high-performance, scroll-based rendering only.
func ScrollUp(newLines []string, topBoundary, bottomBoundary int) Cmd {
return func() Msg {
return scrollUpMsg{
lines: newLines,
topBoundary: topBoundary,
bottomBoundary: bottomBoundary,
}
}
}
type scrollDownMsg struct {
lines []string
topBoundary int
bottomBoundary int
}
2020-07-29 20:49:20 -04:00
// 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.
2020-06-19 14:14:15 -04:00
//
// For high-performance, scroll-based rendering only.
func ScrollDown(newLines []string, topBoundary, bottomBoundary int) Cmd {
return func() Msg {
return scrollDownMsg{
lines: newLines,
topBoundary: topBoundary,
bottomBoundary: bottomBoundary,
}
}
}