Skip to Content
bloom

Editing text

Make a Viewport an editing surface, with a caret kept in the model, moved by wrapped rows, pages, and words, typing with Replace, selecting from the keyboard and the mouse, copying, and undo with snapshots, at any length.

A viewport given a caret is an editing surface. The caret and what's selected are a bloom.Range in your model, and bloom draws it, puts the terminal cursor at it, and sets it from the mouse. What's left for you is a keymap and your own policy: what each key does to the buffer, and what to keep for undo.

Edits cost the same in a buffer of a million lines as in one of ten, so an editor built this way stays instant at any length. The editor example is all of this page in a few hundred lines, editing a million generated lines:

The editor example: typing at a click, selecting words with the keyboard and cutting them, pasting, a word double clicked and copied, a drag across wrapped rows, undo and redo, wrapping turned off and on, and typing at the end of a million lines

Make a viewport editable

Keep the buffer, the range, and where the viewport is scrolled to in the model, and give the viewport a pointer to the range with Caret:

type model struct {
	ui     *bloom.Root
	buf    *bloom.Buffer
	sel    bloom.Range
	pos    bloom.ViewportPos
	cursor *tea.Cursor
}

func newModel() *model {
	return &model{ui: bloom.New(), buf: bloom.NewBuffer(text), cursor: tea.NewCursor(0, 0)}
}

// In the layout:
bloom.Viewport(m.buf).ID(paneText).At(m.pos).Wrap(bloom.WrapWords).LineNumbers(muted).
	Caret(&m.sel).Cursor(m.cursor).
	OnScroll(func(p bloom.ViewportPos) tea.Cmd { m.pos = p; return nil })

The caret is the range's Head, and its Anchor is where the selection started; they're the same while nothing is selected. Cursor puts the terminal cursor at the caret while it's in sight, in the shape and color of the tea.Cursor you give it, and its position is ignored. Give it only while the viewport has focus, such as if m.focus.Is(paneText). Give the viewport an ID and Focusable() for a click to focus it.

The range is a pointer so that bloom reads it whenever it's asked, including in the same Update that changed it from the keyboard, and writes it from the mouse. A viewport with a caret is selectable without Selectable().

So that the caret has a cell at the end of a line as wide as the viewport, the lines are laid out one column narrower than it, the last column kept for the caret. An empty buffer shows the caret at its top-left, and takes edits as one empty line.

Type with Replace

Typing replaces what's selected, which is nothing at a caret, and puts the caret after what was typed, which the Change that Replace returns tells you:

func (m *model) replace(text string) {
	c := m.buf.Replace(m.sel.From(), m.sel.To(), text)
	m.sel = bloom.Range{Anchor: c.End(), Head: c.End()}
}

// In the keymap:
case "enter":
	m.replace("\n")
case "backspace":
	if m.sel.Empty() {
		m.sel.Anchor = m.buf.Prev(m.sel.Head)
	}
	m.replace("")
default:
	if msg.Text != "" {
		m.replace(msg.Text)
	}

Following the range through edits is yours to do, with the Change. bloom follows only the ranges it holds itself. If you change the buffer some other way, such as with SetContent, set the range again: one that's past the end of the buffer is clamped where it's drawn and read, so it's never out of the text, but it may not be where you meant.

Move the caret

The buffer moves positions through its text, and the viewport moves the caret through the rows it lays the text out in:

BufferGives
Next(p), Prev(p)one character on or back, a whole grapheme cluster such as a letter and its accent, across line ends
NextWord(p), PrevWord(p)the end of the word at or after p, or the start of the one at or before it, skipping spaces and punctuation, across line ends
WordAt(p)the start and end of the word at p
End(), Clamp(p)the end of the text, and the nearest place in it
TextIn(from, to)the text between, without styles, the lines joined with newlines
ViewportViewGives
MoveRows(sel, n, column)the caret n rows down, or up, at a column, by the rows lines wrap to
ScrollRows(sel, n, column)the same, and the viewport scrolled by as many rows, for a page
RowStart(sel), RowEnd(sel)the caret at the ends of the row it's on
Column(sel)the column of its row the caret is drawn at
Show(sel)the position scrolled as little as it takes for the caret to be in sight
CaretAt(cell), CaretCell(sel)the caret at a cell, as a click puts it, and the cell a caret is drawn at
PosAt(cell), CellOf(p)the same for a position alone

The buffer's methods take and give positions. The viewport's take the range and give it back with its Head moved and its Anchor kept, because where a line wraps the caret has two places on screen, and the range tells which: see where a line wraps. The rows are those of the buffer as it is when you call the methods, so a view read from the last frame works on text you changed since.

Each key moves the Head, and then, unless shift is held, collapses the range to it. WithHead moves the Head to a position from the buffer, and Collapse sets the Anchor to the Head:

case tea.KeyPressMsg:
	v, _ := m.ui.Frame().Viewport(paneText)
	// With shift, the keys that move the caret select as they move.
	key := msg.String()
	extend := strings.Contains(key, "shift+")
	sel := m.sel
	switch strings.Replace(key, "shift+", "", 1) {
	case "left":
		sel = sel.WithHead(m.buf.Prev(sel.Head))
	case "ctrl+right":
		sel = sel.WithHead(m.buf.NextWord(sel.Head))
	case "home":
		sel = v.RowStart(sel)
	case "end":
		sel = v.RowEnd(sel)
	case "ctrl+end":
		sel = sel.WithHead(m.buf.End())
	}
	if !extend {
		sel = sel.Collapse()
	}
	m.sel = sel

Words

Words are found as Unicode text segmentation finds them, so don't and 3.14 are one word each, and are joined across a buffer's word characters, which keep a path or a URL one word by default. The same words are found by NextWord, PrevWord, WordAt, and a double click in the viewport, so ctrl and the arrows stop where a double click selects. For words as an editor of code has them, set the characters for the buffer:

m.buf.SetWordChars("_")

With "", words are as Unicode finds them. A buffer never given any takes the Root's WithWordChars from the first frame its viewport is drawn in, for its own methods as for a double click, and bloom's default set until then. Finding a word reads only the text around it, up to the whitespace either side, however long its line is.

Keep the column while moving up and down

Moving down through a short row and on to a long one should come back to the column it started at. Keep the column from before the first move, and forget it when anything else moves the caret:

func (m *model) column(v bloom.ViewportView) int {
	if m.goal < 0 {
		m.goal = v.Column(m.sel)
	}
	return m.goal
}

// In the keymap, with m.goal = -1 for every other key:
case "up":
	sel = v.MoveRows(sel, -1, m.column(v))
case "down":
	sel = v.MoveRows(sel, 1, m.column(v))

MoveRows lands on the character boundary nearest the column, never inside a wide character or a tab, and at the end of a row too short for it. Up from the first row goes to the start of the text, and down from the last row to its end, as in most editors.

The mouse moves the caret too. OnCaret tells you when it does, after it writes the range, so you can forget the column there:

bloom.Viewport(m.buf).Caret(&m.sel).OnCaret(func(bloom.Range) tea.Cmd { m.goal = -1; return nil })

Page up and down

A page should move the caret and scroll the text under it by as much, so that the caret stays on its row of the screen. ScrollRows moves the caret as MoveRows does and gives the position to scroll to as well:

case "pgdown":
	m.sel, m.pos = v.ScrollRows(m.sel, v.Rows-1, m.column(v))

Near the top or the bottom, it scrolls as far as it can and the caret still moves, and the position it gives always has the caret in sight, so there's no need to Show it after. Collapse the range, or not, as for any other key.

Where a line wraps

The place a line wraps is one position in its text, but two places on screen: the end of one row and the start of the next. A range's EndOfRow tells which: set, the caret is drawn at the end of the row before the wrap; unset, at the start of the row after. It means nothing anywhere else, and the text selected and copied doesn't depend on it.

RowEnd on a row the line wraps after goes to the place it wraps, after any spaces that hang off a row wrapped at words, with EndOfRow set, so end reaches the true end of the row and the caret stays on it. MoveRows sets it when it lands at the end of such a row, and a click past the end of one sets it too, so the caret stays on the row clicked. WithHead clears it, since a position from the buffer is drawn at the start of a row, and Collapse and Change.MapRange keep it. When you set a range yourself from a position, leave it unset.

Keep the caret in sight

After each key, scroll as little as it takes to show the caret. Show scrolls down or up, and sideways while lines don't wrap:

if v, ok := m.ui.Frame().Viewport(paneText); ok {
	m.pos = v.Show(m.sel)
}

Select from the keyboard and the mouse

shift with a key that moves the caret moves the Head and keeps the Anchor, which is the range left as the move gave it, not collapsed. A range you make becomes the selection as soon as bloom sees it, and clears any other on the screen, so m.ui.Selection() returns its text in the same Update. The mouse writes the range as an editor does:

GestureDoes
clickputs the caret before the character under the pointer, or past the end of a row, at its end
shift held with a clickmoves the caret there, and keeps the anchor
dragselects from the caret at the press to the caret under the pointer, scrolling past an edge through OnScroll
double click, triple clickselects the word, even one wrapped across rows, or the line

A range that holds text is drawn in the selection's style, and a caret alone is not. m.ui.SelectAll(paneText) selects all of the buffer, and m.ui.ClearSelection() collapses the range to its caret. Starting a selection anywhere else on the screen collapses it too.

Copy, cut, and paste

CopySelection copies the range, leaves it selected, and sweeps the copy flash across it. To cut, copy and then take the text out, which ends the flash at once:

case "ctrl+c":
	if cmd := m.ui.CopySelection(); cmd != nil {
		return m, cmd
	}
	return m, tea.Quit
case "ctrl+x":
	if cmd := m.ui.CopySelection(); cmd != nil {
		m.replace("")
		return m, cmd
	}

What the terminal pastes, such as with ctrl+shift+v, comes as a tea.PasteMsg:

case tea.PasteMsg:
	m.replace(msg.Content)

Undo with snapshots

A snapshot costs a step to take and to restore, however long the text is. Keep the range with it, so that undo puts the caret back too, and keep where you are on the other stack before going back, so that redo can return:

type step struct {
	text bloom.Snapshot
	sel  bloom.Range
}

func (m *model) replace(text string) {
	m.undo = append(m.undo, step{text: m.buf.Snapshot(), sel: m.sel})
	m.redo = m.redo[:0]
	c := m.buf.Replace(m.sel.From(), m.sel.To(), text)
	m.sel = bloom.Range{Anchor: c.End(), Head: c.End()}
}

func (m *model) undoStep() {
	if len(m.undo) == 0 {
		return
	}
	m.redo = append(m.redo, step{text: m.buf.Snapshot(), sel: m.sel})
	s := m.undo[len(m.undo)-1]
	m.undo = m.undo[:len(m.undo)-1]
	m.buf.Restore(s.text)
	m.sel = s.sel
}

To undo typing in a row as one step, skip the snapshot while the edit before was typing too, and note that anything else, such as moving the caret, ends the run.

What it costs

Each key is an edit, a few moves of the caret, and a frame, and none of them grows with the buffer. An edit costs a step per level of the buffer's tree, a few microseconds in a million lines, and measures again only the lines it changes. The frame lays out and draws only the rows in sight.

The one exception is a very long line. Positions count bytes of a line, so moving through a line of many kilobytes that holds styles or characters beyond ASCII reads it from its start, and costs more for each key than a short one does.

Last updated on

On this page