Migrating to Tcell v3

[joelim-work]

A new major version of the Tcell library has been recently been released, which includes breaking changes that need to be addressed in the code. I have analyzed the codebase briefly and compiled a list of potential changes that should be made:

• The PollEvent function should be replaced with the EventQ channel where terminal events can be directly read from.
• The Style.Decompose function has been removed, which means it might no longer be possible to implement the SGR 8 terminal sequence (concealed text) as Tcell does not support it directly. However I think it is a niche feature that isn't necessary to have, and the current implementation is a hacky workaround that sets the foreground color to the background color.
• KeyBackspace2 will no longer be sent, and will instead be mapped to KeyBackspace. This means that support for the <backspace2> key can dropped as <backspace> alone will be sufficient.
• EventKey now contains a string instead of a rune, and the code needs to be changed for both reading keys (EventKey to string) and pushing keys (string to EventKey).
• The special keys KeyCtrlSpace, KeyCtrlLeftSq, KeyCtrlRightSq, KeyCtrlBackslash, KeyCtrlCarat and KeyCtrlUnderscore have been removed, and are instead represented as a rune key with the ModCtrl mask. This is problematic because special keys and rune keys have different processing logic so it will have to be adjusted to handle the new changes. Perhaps it is worth creating utility functions for converting between EventKey and string, which can then be unit tested.
• The existing SetContent function is used to assign runes to individual cells, however there are now high-level PutStr/PutStrStyled functions for writing entire strings, and from my testing it appears to support terminal sequences inside those strings, but it may not work for every case. I am fine with leaving the existing win.print unchanged for now.

Some of these changes are straightforward, but that may not be the case for others. Fortunately I have just released a new version of lf, so there will be ample time to test the new changes before releasing them in the following version.

[CatsDeservePets]

• The Style.Decompose has been removed, which means it might no longer be possible to implement the SGR 8 terminal sequence (concealed text) as Tcell does not support it directly. However I think it is a niche feature that isn't necessary to have, and the current implementation is a hacky workaround that sets the foreground color to the background color.

For a second I did read OSC 8 instead of SGR 8 and thought of all the time that went into supporting it 😄.

Some of these changes are straightforward, but that may not be the case for others. Fortunately I have just released a new version of lf, so there will be ample time to test the new changes before releasing them in the following version.

It's probably for the better that you reverted the version bumps to ensure a stable release. I also got a little suspicious after all these PRs and had thoughts about stability but wasn't sure about it (I will now know better in the future).

Version r40 seems rather fitting for big changes like this.

[joelim-work]

Speaking of OSC 8, I found that the bug reported in #2243 (comment) seems to have been fixed in v3.

v2 (displays separate lines for words and spaces):

package main

import (
	"github.com/gdamore/tcell/v2"
)

func emitStr(screen tcell.Screen, x, y int, style tcell.Style, str string) {
	for i, c := range str {
		screen.SetContent(x+i, y, c, nil, style)
	}
}

func draw(screen tcell.Screen) {
	screen.Clear()
	style := tcell.StyleDefault.Url("https://www.example.com/")
	emitStr(screen, 0, 0, style, "hello world")
	screen.Show()
}

func main() {
	screen, err := tcell.NewScreen()
	if err != nil {
		panic(err)
	}

	if err := screen.Init(); err != nil {
		panic(err)
	}

	draw(screen)

	for {
		switch ev := screen.PollEvent().(type) {
		case *tcell.EventResize:
			screen.Sync()
			draw(screen)
		case *tcell.EventKey:
			if ev.Key() == tcell.KeyEscape {
				screen.Fini()
				return
			}
		}
	}
}

v3 (displays one single line):

package main

import (
	"github.com/gdamore/tcell/v3"
)

func emitStr(screen tcell.Screen, x, y int, style tcell.Style, str string) {
	for i, c := range str {
		screen.SetContent(x+i, y, c, nil, style)
	}
}

func draw(screen tcell.Screen) {
	screen.Clear()
	style := tcell.StyleDefault.Url("https://www.example.com/")
	emitStr(screen, 0, 0, style, "hello world")
	screen.Show()
}

func main() {
	screen, err := tcell.NewScreen()
	if err != nil {
		panic(err)
	}

	if err := screen.Init(); err != nil {
		panic(err)
	}

	draw(screen)

	for {
		switch ev := (<-screen.EventQ()).(type) {
		case *tcell.EventResize:
			screen.Sync()
			draw(screen)
		case *tcell.EventKey:
			if ev.Key() == tcell.KeyEscape {
				screen.Fini()
				return
			}
		}
	}
}

So I think the workaround of autogenerating IDs can be removed, though probably as a separate change afterwards.

[ossenthusiast]

Btw, Decompose has been removed and tcell now exposes Get{Background, Foreground, Attributes} in place of Decompose.

[joelim-work]

@ossenthusiast Thanks, I didn't realize there was a new alternative. I'm still a bit concerned about this kind of implementation for SGR 8 (i.e. concealing text by setting the foreground color to the background color), and it would be nice if it was supported directly in Tcell.

But anyway I will most likely just leave the current behavior as is since no users are complaining about it.

[ossenthusiast]

@ossenthusiast Thanks, I didn't realize there was a new alternative. I'm still a bit concerned about this kind of implementation for SGR 8 (i.e. concealing text by setting the foreground color to the background color), and it would be nice if it was supported directly in Tcell.

But anyway I will most likely just leave the current behavior as is since no users are complaining about it.

You can probably directly implement this by accessing underlying tty using (tcell.Screen).Tty and writing \e[8m code to the acquired tty.

[joelim-work]

Okay I think it's not worth making any changes to the SGR 8 implementation for the purposes of migrating to v3, thanks anyway for the info.

[ossenthusiast]

Also, {Get, Set}Content API is removed in favor of Get and Put* API, which support string instead of rune.

[joelim-work]

We have complex requirements when it comes to printing strings. Can the new Put/PutStr/PutStrStyled functions handle raw escape sequences in strings directly? Currently we parse the strings ourselves and then print each cell with the appropriate style.

I tried changing the win.print function to just forward to the PutStrStyled function directly and it has issues:

func (win *win) print(screen tcell.Screen, x, y int, st tcell.Style, s string) tcell.Style {
	screen.PutStrStyled(win.x+x, win.y+y, s, st)
	return st
}

I'm guessing that raw escape sequences aren't supported as it isn't documented, and furthermore a simple example like below fails to print bar at the intended location:

// screen.PutStr(0, 0, "foo")
screen.PutStr(0, 0, "\033[31mfoo\033[0m")
screen.PutStr(6, 0, "bar")

---

Also I'm aware that SetContent for the CellBuffer type is deprecated, but I wasn't aware that the same function for the Screen type was too.

EDIT: I have replaced SetContent calls completely with the new Put API, and updated the PR. Hopefully it works without introducing any regressions.