|
|
# Terminals
|
|
|
|
|
|
Notcurses attempts to provide an abstraction layer over the highly varied
|
|
|
world of terminals. First and foremost, Notcurses needs to know the terminal
|
|
|
on which it is running, so that has an accurate understanding of its
|
|
|
capabilities.
|
|
|
|
|
|
It is of course possible that Notcurses is not connected to an actual
|
|
|
terminal (e.g. when running daemonized). In such a case, many escapes
|
|
|
will not be emitted, and no querying is performed.
|
|
|
|
|
|
Notcurses determines terminal capabilities via a combination of (more-or-less)
|
|
|
standardized queries sent to the terminal, the `TERM` environment variable
|
|
|
used by `terminfo(5)`, and the `COLORTERM` environment variable.
|
|
|
|
|
|
## Queries
|
|
|
|
|
|
At startup, the Linux console is identified via `ioctl(2)`s specific it.
|
|
|
Otherwise, if it is determined that the process is connected to a terminal
|
|
|
(see `isatty(3)`), Notcurses writes a series of queries to it. Several are
|
|
|
related to terminal identification:
|
|
|
|
|
|
* Send Tertiary Device Attributes (`CSI = c`)
|
|
|
* Identifies VTE and foot
|
|
|
* Send Secondary Device Attributes (`CSI > c`)
|
|
|
* Identifies Alacritty's version number
|
|
|
* `XTVERSION` (`CSI > 0 q`)
|
|
|
* Identifies XTerm, WezTerm, and Contour
|
|
|
* `XTGETTCAP` for the `TN` key (`DCS + q 544e ST`)
|
|
|
* Identifies Kitty and MLterm
|
|
|
* Send Primary Device Attributes (`CSI c`)
|
|
|
|
|
|
No terminals requiring special handling identify themselves via Primary Device
|
|
|
Attributes, but we send this because all known terminals respond to it with
|
|
|
*something*, preventing us from hanging, waiting for input (**if a terminal does
|
|
|
*not* reply in a recognizable way to Primary Device Attributes,
|
|
|
`notcurses_init()` will hang**).
|
|
|
|
|
|
Even if the terminal responds unambiguously to one of these queries, Notcurses
|
|
|
must have code to recognize the response, and bind it to some terminal
|
|
|
definition. Assuming the terminal to be thus identified, Notcurses enables or
|
|
|
disables certain capabilities based on built-in knowledge.
|
|
|
|
|
|
Terminal.App exports `TERM_PROGRAM=Apple_Terminal`.
|
|
|
|
|
|
## The `COLORTERM` environment variable
|
|
|
|
|
|
24-bit RGB for glyphs and cell backgrounds is fairly widely implemented. In
|
|
|
the Terminfo database, this is indicated via the `rgb` capability. It is
|
|
|
not uncommon for this capability to not be expressed, despite support being
|
|
|
present. Defining the `COLORTERM` environment variable with the value `24bit`
|
|
|
will instruct Notcurses to issue RGB sequences regardless.
|
|
|
|
|
|
## Terminfo and `TERM`
|
|
|
|
|
|
Even if the terminal is unambiguously determined via query, many capabilities
|
|
|
are acquired from the `terminfo(5)` database, keyed by the `TERM` environment
|
|
|
variable. It is critical that the `TERM` environment variable be correct for
|
|
|
your shell, and that the terminfo database entry keyed by this variable be
|
|
|
up-to-date.
|
|
|
|
|
|
The following have been established on a Debian Unstable workstation.
|
|
|
`ccc` is the Terminfo can-change-colors capability. "Blocks" refers to whether
|
|
|
the terminal provides its own implementation of block-drawing characters, or
|
|
|
relies on the font. Patches to correct/complete this table are very welcome!
|
|
|
|
|
|
| Terminal | Pixel `TIOCGWINSZ` | `ccc` | Blocks | Recommended environment | Notes |
|
|
|
| --------------- | ------------------ | ----- | ------ | ----------------------- | ----- |
|
|
|
| [Alacritty](https://github.com/alacritty/alacritty) | ✅ | ✅ |❌ |`TERM=alacritty` `COLORTERM=24bit` | [Sixel support WIP](https://github.com/ayosec/alacritty/tree/graphics) |
|
|
|
| [Contour](https://github.com/christianparpart/contour) | ❌ | ✅ |? |`TERM=contour-latest` ? | Claims Sixel support |
|
|
|
| [ETerm](https://github.com/mej/Eterm) | | | | `TERM=Eterm` | Doesn't reply to Send Device Attributes |
|
|
|
| [FBterm](https://github.com/zhangyuanwei/fbterm) | ❌ | ? |? |`TERM=fbterm` | 256 colors, no RGB color. |
|
|
|
| [foot](https://codeberg.org/dnkl/foot) | ✅ | ✅ |✅ |`TERM=foot` | Sixel support. |
|
|
|
| [Gnome Terminal](https://gitlab.gnome.org/GNOME/gnome-terminal) |❌ | ❌ |✅ |`TERM=gnome` `COLORTERM=24bit` | `ccc` support *is* available when run with `vte-256color`. |
|
|
|
| [Guake](https://github.com/Guake/guake) | | ? |? | | |
|
|
|
| [ITerm2](https://github.com/gnachman/iTerm2) | ✅ | ✅ |✅ |`TERM=xterm-256color` ||
|
|
|
| [Kitty](https://github.com/kovidgoyal/kitty) | ✅ | ✅ |✅ |`TERM=xterm-kitty` | See below. |
|
|
|
| [kmscon](https://github.com/dvdhrm/kmscon) | | ❌ | ❌ |`TERM=xterm-256color` | No RGB color AFAICT, nor any distinct terminfo entry. No actual `ccc` implementation. Sets `COLORTERM=kmscon`.|
|
|
|
| [Konsole](https://invent.kde.org/utilities/konsole) | ❌ | ❌ |? |`TERM=konsole-direct` | |
|
|
|
| Linux console | ❌ | ✅ |see [below](#the-linux-console) |`TERM=linux` `COLORTERM=24bit` | 8 (512 glyph fonts) or 16 (256 glyph fonts) colors max, but RGB values are downsampled to a 256-index palette. See below. |
|
|
|
| [mintty](https://github.com/mintty/mintty) | ? | ? | ? | ? | ? |
|
|
|
| [mlterm](https://github.com/arakiken/mlterm) | ✅ | ❌ |? |`TERM=mlterm-256color` | Do not set `COLORTERM`. `mlterm-direct` gives strange results. |
|
|
|
| [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) | | ❌ |❌ |`TERM=putty-256color` `COLORTERM=24bit` | |
|
|
|
| rxvt | ✅ | ? |? | | Seems unmaintained; many forks exist. |
|
|
|
| [Sakura](https://github.com/dabisu/sakura) | ✅ | ✅ |? |`TERM=vte-256color` `COLORTERM=24bit` | VTE-derived, no terminfo entry. |
|
|
|
| [GNU Screen](https://www.gnu.org/software/screen/) | ✅ | ❌ |n/a |`TERM=screen.OLDTERM` | Must be compiled with `--enable-256color`. `TERM` should typically be `screen.` suffixed by the appropriate `TERM` value for the true connected terminal, e.g. `screen.vte-256color`. See below. |
|
|
|
| [st ("suckless")](https://st.suckless.org/) | ✅ | ✅ |? |`TERM=st-256color` `COLORTERM=24bit` | Many features are maintained as external patches; users often roll their own instance, composing from these patches. |
|
|
|
| [Tabby](https://github.com/Eugeny/tabby) | ? | ? | ? | ? | |
|
|
|
| [Terminal.app](https://en.wikipedia.org/wiki/Terminal_(macOS)) | ✅ | ❌ | ❌ | `TERM=xterm-256color`| No RGB; no `ccc` despite wanting `xterm-256color`. |
|
|
|
| [Terminator](https://github.com/software-jessies-org/jessies/wiki/Terminatorhttps://github.com/software-jessies-org/jessies/wiki/Terminator) | ✅ | ? |? | ? | |
|
|
|
| [Terminology](https://github.com/borisfaure/terminology) | ❌ | ❌ |✅ | `TERM=terminology` | Identified via DA3. 256 colors, no RGB. |
|
|
|
| [Tilda](https://github.com/lanoxx/tilda) | | ? |? | ? | |
|
|
|
| [tmux](https://github.com/tmux/tmux/wiki) | ✅ | ❌ |n/a |`TERM=tmux-256color` `COLORTERM=24bit`| `tmux.conf` must apply `Tc`; see below. `bce` is available with the `tmux-256color-bce` definition. |
|
|
|
| [WezTerm](https://github.com/wez/wezterm) | ✅ | ✅ |? |`TERM=wezterm` `COLORTERM=24bit` | See below. |
|
|
|
| [Windows Terminal](https://github.com/microsoft/terminal)| | ? |? | `TERM=ms-terminal` `COLORTERM=24bit` | Nice [escape docs](https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences).|
|
|
|
| [wterm](https://github.com/majestrate/wterm) | | ? |? | ? | |
|
|
|
| [XFCE4 Terminal](https://gitlab.xfce.org/apps/xfce4-terminal) | ❌ | ✅ |✅ |`TERM=xfce` `COLORTERM=24bit` | No `xfce-direct` variant exists. |
|
|
|
| [XTerm](https://invisible-island.net/xterm/xterm.html) | ✅ | ? |❌ |`TERM=xterm+256color2` `COLORTERM=24bit` | See note about DirectColor. Must configure with `--enable-direct-color`. `TERM=xterm-direct` seems to have the undesirable effect of mapping low RGB values to a palette; I don't yet understand this well. The problem is not seen with the specified configuration. Sixel support when built with `--enable-sixel-graphics` and run in vt340 mode. |
|
|
|
| [Yakuake](https://github.com/KDE/yakuake) | | ? |? | ? | |
|
|
|
|
|
|
Note that `xfce4-terminal`, `gnome-terminal`, etc. are essentially skinning
|
|
|
atop the common GNOME [VTE ("Virtual TErminal")](https://gitlab.gnome.org/GNOME/vte) library.
|
|
|
|
|
|
### Kitty
|
|
|
|
|
|
Kitty has some interesting, atypical behaviors. Foremost among these is that
|
|
|
an RGB background color equivalent to the configured default background color
|
|
|
will be rendered as the default background. This means, for instance, that if
|
|
|
the configured default background color is RGB(0, 0, 0), and is translucent,
|
|
|
a background of RGB(0, 0, 0) will be translucent. To work around this, when
|
|
|
`TERM` begins with "kitty", we detect the default background color, and when
|
|
|
we would write this as RGB, we alter one of the colors by 1. See
|
|
|
https://github.com/kovidgoyal/kitty/issues/3185 and
|
|
|
https://github.com/dankamongmen/notcurses/issues/1117.
|
|
|
|
|
|
Kitty is furthermore the only terminal I know to lack the `bce` (Background
|
|
|
Color Erase) capability, but Notcurses never relies on `bce` behavior.
|
|
|
|
|
|
Kitty has introduced an unambiguous [keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/).
|
|
|
Notcurses supports this protocol when it is detected.
|
|
|
|
|
|
### WezTerm
|
|
|
|
|
|
WezTerm [implements](https://wezfurlong.org/wezterm/escape-sequences.html) some
|
|
|
interesting underline options, and both the Sixel and Kitty graphic protocols.
|
|
|
|
|
|
### GNU screen
|
|
|
|
|
|
GNU screen does have 24-bit color support, but only in the 5.X series. Note
|
|
|
that many distributions ship screen 4.X as of 2020. When built with truecolor
|
|
|
support, add `truecolor on` to your `screenrc`, or run it with `--truecolor`.
|
|
|
Attempting to force RGB color in screen 4.X **will not work**.
|
|
|
|
|
|
Add `defutf8 on` to your `screenrc`, or run screen with `-U`, to ensure UTF-8.
|
|
|
|
|
|
### tmux
|
|
|
|
|
|
`tmux` supports 24-bit color through its `Tc` (Truecolor) extension. You'll
|
|
|
need an entry in `tmux.conf` of the form:
|
|
|
|
|
|
`set -ga terminal-overrides ",EXTERNALTERM:Tc"`
|
|
|
|
|
|
Where `EXTERNALTERM` is your `TERM` variable at the time of attachment, e.g.:
|
|
|
|
|
|
`set -ga terminal-overrides ",vte-256color:Tc"`
|
|
|
|
|
|
You'll then need `COLORTERM=24bit` defined within your tmux environment.
|
|
|
|
|
|
### The Linux console
|
|
|
|
|
|
The Linux console supports concurrent virtual terminals, and is manipulated
|
|
|
by userspace via `ioctl()`s. These `ioctl()`s generally fail when applied to
|
|
|
a pseudotty device, as will happen if e.g. invoked upon one's controlling
|
|
|
terminal whilst running in a terminal emulator under X (it is still generally
|
|
|
possible to use them by explicitly specifying a console device, i.e.
|
|
|
`showconsolefont -C /dev/tty0`).
|
|
|
|
|
|
The VGA text console requires the kernel option `CONFIG_VGA_CONSOLE`. A
|
|
|
framebuffer console for VESA 2.0 is provided by `CONFIG_FB_VESA`, while
|
|
|
UEFI-compatible systems can use `CONFIG_FB_EFI`. So long as a framebuffer
|
|
|
driver is present, `CONFIG_FRAMEBUFFER_CONSOLE` will enable a graphics-mode
|
|
|
console using the framebuffer device.
|
|
|
|
|
|
The Linux console can be in either text or graphics mode. The mode can be
|
|
|
determined with the `KDGETMODE` `ioctl()`, and changed with `KDSETMODE`,
|
|
|
using the constants `KD_TEXT` and `KD_GRAPHICS`. Text mode supports a
|
|
|
rectangular matrix of multipixel cells, filled with glyphs from a font,
|
|
|
a foreground color, and a background color. Graphics ("All-Points-Addressable")
|
|
|
mode supports a rectangular matrix of pixels, each with a single color.
|
|
|
Note that both modes require appropriate hardware support (and kernel
|
|
|
configuration options), and might or might not be available on a given
|
|
|
installation. Non-x86 platforms often provide only a framebuffer (graphics)
|
|
|
console.
|
|
|
|
|
|
The kernel text mode loosely corresponds to the 1987 IBM VGA definition. At any
|
|
|
time, the display is configured with a monospace raster font, a palette, and
|
|
|
(when in Unicode mode) a mapping from multibyte sequences to font elements. Up
|
|
|
to 16 colors can be used with a font of 256 glyphs or fewer. Only 8 colors can
|
|
|
be used with fonts having more than 256 glyphs; the maximum font size in any
|
|
|
configuration is 512 glyphs. The keyboard is further configured with a keymap,
|
|
|
mapping keyboard scancodes to elements of the character set. These properties
|
|
|
are per-virtual console, not common to all of them. These limitations are not
|
|
|
typically present on framebuffer consoles.
|
|
|
|
|
|
Exporting `COLORTERM=24bit` and emitting RGB escapes to the Linux console
|
|
|
**does** work, though the RGB values provided are downsampled to a 256-slot
|
|
|
palette. Backgrounds don't seem to have the same degree of flexibility in this
|
|
|
situation as do foregrounds. The output is better, but not as much better as
|
|
|
one might expect. More research is necessary here.
|
|
|
|
|
|
The following more-or-less standard tools exist:
|
|
|
* `showconsolefont`: show the console font
|
|
|
* `setfont`: load console font
|
|
|
* `fbset`: show and modify framebuffer settings
|
|
|
* `fgconsole`: print name of foreground terminal
|
|
|
* `chvt`: change the foreground terminal
|
|
|
* `deallocvt`: destroy a virtual console
|
|
|
* `dumpkeys`: print all keycodes
|
|
|
* `loadkeys`: load scancode/keycode mapping (the keymap)
|
|
|
* `setkeycodes`: load scancode/keycode mappings one at a time
|
|
|
* `showkeys`: interactively print scancodes
|
|
|
* `kbd_mode`: show or set the keyboard mode
|
|
|
|
|
|
Both `mapscrn` and `loadunimap` are obsolete; their functionality is present
|
|
|
in `setfont`.
|
|
|
|
|
|
Note that Notcurses reprograms the console font table when running in the
|
|
|
Linux console (unless `NCOPTION_NO_FONT_CHANGES` is used). This adds support
|
|
|
for half blocks and quadrants.
|
|
|
|
|
|
### Windows Terminal
|
|
|
|
|
|
Ensure UTF-8 is being used for "Administrative language settings"
|
|
|
(see [README.md](README.md)). Codepage 65001 ought be used.
|
|
|
|
|
|
### 24-bit RGB
|
|
|
|
|
|
Many terminals support one or another form of non-indexed color encoding (also
|
|
|
known as DirectColor, RGB color, 24-bit color, or the similar but distinct
|
|
|
TrueColor), using either the semicolon-based presentation introduced by Konsole
|
|
|
or the colon-delimited presentation specified in ECMA-48 and ITU T.416. The
|
|
|
`rgb` termcap capability indicates support for such encodings via the
|
|
|
`set_a_foreground` and `set_b_foreground` capabilities. Not all terminals
|
|
|
implementing `rgb` use the 3x8bpc model; XTerm for instance:
|
|
|
|
|
|
> for values 0 through 7, it uses the “ANSI” control sequences, while
|
|
|
> for other values, it uses the 3-byte direct-color sequence introduced by Konsole.
|
|
|
> the number of colors is 224 while the number of color pairs is 216
|
|
|
|
|
|
Thus emitting `setaf` with an RGB value close to black can result, when
|
|
|
using `xterm-direct`'s `setaf` and `rgb` definitions, in a bright ANSI color.
|
|
|
|
|
|
24-bit RGB is always enabled for Kitty, Alacritty, Contour, WezTerm, iTerm2,
|
|
|
and foot.
|
|
|
|
|
|
### Problematic characters
|
|
|
|
|
|
Some characters seem to cause problems with one terminal or another. These
|
|
|
are best avoided until the problems are better understood:
|
|
|
|
|
|
* '' U+00AD SOFT HYPHEN (some terminals allocate it a cell, some don't)
|
|
|
* '' U+070F SYRIAC ABBREVIATION MARK
|
|
|
* '' U+06DD ARABIC END OF AYAH
|
|
|
* '' U+08E2 ARABIC DISPUTED END OF AYAH
|
|
|
* '﷽' U+FDFD ARABIC LIGATURE BISMILLAH AR-RAHMAN AR-RAHEEM
|
|
|
|
|
|
## Notes for terminal authors
|
|
|
|
|
|
The `notcurses-info` tool built as part of Notcurses can be used to inspect
|
|
|
how well your terminal supports Notcurses. It is generally desirable that:
|
|
|
|
|
|
* Your terminal draw Unicode's Line- and Box-Drawing characters itself,
|
|
|
rather than relying on the font.
|
|
|
* Your terminal support some graphics protocol, ideally Kitty's. If you
|
|
|
support Sixel instead, implement `XTSMGRAPHICS`.
|
|
|
* Implement a keyboard disambiguation protocol, ideally Kitty's.
|
|
|
* Implement `hpa`, for absolute horizontal positioning.
|
|
|
* Size EGCs according to the largest `wcwidth()` result returned for any
|
|
|
of the component characters.
|
|
|
* Honor Unicode rules for segmentation, including Zero-Width Joiners. Emit
|
|
|
either zero or one glyph per EGC.
|