tui.txt (13737B)
1 *tui.txt* Nvim 2 3 4 NVIM REFERENCE MANUAL 5 6 7 Terminal UI *TUI* *tui* 8 9 By default when you run `nvim` (without |--embed| or |--headless|) it starts 10 the builtin "terminal UI" (TUI). This default UI is optional: you can run Nvim 11 as a "headless" server, or you can use a |GUI|. 12 13 Type |gO| to see the table of contents. 14 15 ============================================================================== 16 Startup *startup-tui* *startup-terminal* 17 18 Nvim has a client-server architecture: by default when you run `nvim`, this 19 starts the builtin UI client, which starts a `nvim --embed` server (child) 20 process that the UI client connects to. After attaching to the server, the UI 21 client calls |nvim_set_client_info()| (as recommended for all UIs |dev-ui|) 22 and sets these fields on its channel: > 23 24 client = { 25 attributes = { 26 license = 'Apache 2', 27 pid = …, 28 website = 'https://neovim.io', 29 }, 30 name = 'nvim-tui', 31 type = 'ui', 32 version = { … }, 33 } 34 35 Nvim guesses the terminal type when it starts (except in |--embed| and 36 |--headless| modes). The |$TERM| environment variable is the primary hint that 37 determines the terminal type. 38 39 *terminfo* *E557* *E558* *E559* 40 To display its user interface, Nvim reads a list of "terminal capabilities" 41 from the system terminfo database (or builtin defaults if terminfo is not 42 found). If that information is wrong, the screen may be messed up or keys may 43 not be recognized. 44 45 The Unibilium library (used to read terminfo) allows you to override the 46 system terminfo with one in the "$HOME/.terminfo/" directory. Building your 47 own terminfo is usually as simple as running this: 48 > 49 curl -LO https://invisible-island.net/datafiles/current/terminfo.src.gz 50 gunzip terminfo.src.gz 51 tic -x terminfo.src 52 < 53 *$TERM* 54 The $TERM environment variable must match the terminal you are using! 55 Otherwise Nvim cannot know what sequences your terminal expects, and weird 56 or sub-optimal behavior will result (scrolling quirks, wrong colors, etc.). 57 58 $TERM is also important because it is forwarded by SSH to the remote session, 59 unlike most other environment variables. 60 61 > 62 For this terminal Set $TERM to |builtin-terms| 63 ------------------------------------------------------------------------- 64 ansi (unknown) Y 65 Ghostty ghostty, xterm-ghostty Y 66 iTerm (original) iterm, iTerm.app N 67 iTerm2 (new capabilities) iterm2, iTerm2.app Y 68 Konsole konsole-256color N 69 libvte-based vte, vte-256color Y 70 (e.g. GNOME Terminal) (aliases: gnome, gnome-256color) 71 Linux virtual terminal linux, linux-256color Y 72 PuTTY putty, putty-256color Y 73 rxvt rxvt, rxvt-256color Y 74 screen screen, screen-256color Y 75 simple terminal (st) st, st-256color Y 76 Terminal.app nsterm N 77 tmux tmux, tmux-256color Y 78 Windows/ConEmu conemu Y 79 Windows/Cygwin-built Nvim cygwin Y 80 Windows/Interix interix Y 81 Windows/legacy console win32con Y 82 Windows/VTP console vtpcon Y 83 xterm or compatible xterm, xterm-256color Y 84 < 85 86 *builtin-terms* *builtin_terms* 87 Nvim will map |$TERM| to a builtin entry according to the above table if: 88 89 - a |terminfo| database is not available on the system 90 - no terminfo entry found for the current detected terminal 91 - Nvim was built without terminfo support (`has('terminfo')==0`) 92 93 The builtin terminfo is not combined with any external terminfo database, nor 94 can it be used in preference to one. You can thus entirely override any 95 omissions or out-of-date information in the builtin terminfo database by 96 supplying an external one with entries for the terminal type. 97 98 For example "TERM=putty-256color" will be mapped to the builtin "putty" entry. 99 See also |tui-colors|. 100 101 Settings depending on terminal *term-dependent-settings* 102 103 If you want to set terminal-dependent options or mappings, you can do this in 104 your init.vim. Example: >vim 105 106 if $TERM =~ '^\(rxvt\|screen\|interix\|putty\)\(-.*\)\?$' 107 set notermguicolors 108 elseif $TERM =~ '^\(tmux\|iterm\|vte\|gnome\)\(-.*\)\?$' 109 set termguicolors 110 elseif $TERM =~ '^\(xterm\)\(-.*\)\?$' 111 if $XTERM_VERSION != '' 112 set termguicolors 113 elseif $KONSOLE_PROFILE_NAME != '' 114 set termguicolors 115 elseif $VTE_VERSION != '' 116 set termguicolors 117 else 118 set notermguicolors 119 endif 120 elseif $TERM =~ ... 121 ... and so forth ... 122 endif 123 < 124 *scroll-region* *xterm-scroll-region* 125 Where possible, Nvim will use the terminal's ability to set a scroll region in 126 order to redraw faster when a window is scrolled. If the terminal's terminfo 127 description describes an ability to set top and bottom scroll margins, that is 128 used. 129 130 This will not speed up scrolling in a window that is not the full width of the 131 terminal. Xterm has an extra ability, not described by terminfo, to set left 132 and right scroll margins as well. If Nvim detects that the terminal is Xterm, 133 it will make use of this ability to speed up scrolling that is not the full 134 width of the terminal. 135 136 *tui-input* 137 Historically, terminal emulators could not distinguish between certain control 138 key modifiers and other keys. For example, <C-I> and <Tab> are represented in 139 the same way, as are <Esc> and <C-[>, <CR> and <C-M>, and <NL> and <C-J>. 140 141 Modern terminal emulators are able to distinguish between these pairs of keys 142 by encoding control modifiers differently. There are two common but distinct 143 ways of doing this, known as "modifyOtherKeys" and "CSI u". Nvim supports both 144 encoding methods and at startup will tell the terminal emulator that it 145 understands these key encodings. If your terminal emulator supports it then 146 this will allow you to map the key pairs listed above separately. |<Tab>| 147 148 Nvim uses libtermkey to convert terminal escape sequences to key codes. 149 |terminfo| is used first, and CSI sequences not in |terminfo| (including 150 extended keys a.k.a. "modifyOtherKeys" or "CSI u") can also be parsed. 151 152 For example, when running Nvim in tmux, this makes Nvim leave Insert mode and 153 go to the window below: > 154 tmux send-keys 'Escape' [ 2 7 u 'C-W' j 155 Where `'Escape' [ 2 7 u` is an unambiguous "CSI u" sequence for the <Esc> key. 156 157 The kitty keyboard protocol https://sw.kovidgoyal.net/kitty/keyboard-protocol/ 158 is partially supported, including keypad keys in Unicode Private Use Area. 159 For example, this sequence is recognized by Nvim as <C-kEnter>: > 160 CSI 57414 ; 5 u 161 and can be used differently from <C-CR> in mappings. 162 163 *tui-modifyOtherKeys* *tui-csiu* 164 At startup Nvim will query your terminal to see if it supports the "CSI u" 165 encoding by writing the sequence > 166 CSI ? u CSI c 167 If your terminal emulator responds with > 168 CSI ? <flags> u 169 this means your terminal supports the "CSI u" encoding and Nvim will tell your 170 terminal to enable it by writing the sequence > 171 CSI > 1 u 172 If your terminal does not support "CSI u" then Nvim will instead enable the 173 "modifyOtherKeys" encoding by writing the sequence > 174 CSI > 4 ; 2 m 175 176 When Nvim exits cleanly it will send the corresponding sequence to disable the 177 special key encoding. If Nvim does not exit cleanly then your terminal 178 emulator could be in a bad state. If this happens, simply run "reset". 179 180 *tui-colors* 181 Nvim uses 256 colours by default, ignoring |terminfo| for most terminal types, 182 including "linux" (whose virtual terminals have had 256-colour support since 183 4.8) and anything claiming to be "xterm". Also when $COLORTERM or $TERM 184 contain the string "256". 185 186 Nvim similarly assumes that any terminal emulator that sets $COLORTERM to any 187 value, is capable of at least 16-colour operation. 188 189 *true-color* *xterm-true-color* 190 Nvim emits true (24-bit) colours in the terminal, if 'termguicolors' is set. 191 192 It uses the "setrgbf" and "setrgbb" |terminfo| extensions (proposed by Rüdiger 193 Sonderfeld in 2013). If your terminfo definition is missing them, then Nvim 194 will decide whether to add them to your terminfo definition, using the ISO 195 8613-6:1994/ITU T.416:1993 control sequences for setting RGB colours (but 196 modified to use semicolons instead of colons unless the terminal is known to 197 follow the standard). 198 199 Another convention, pioneered in 2016 by tmux, is the "Tc" terminfo extension. 200 If terminfo has this flag, Nvim will add constructed "setrgbf" and "setrgbb" 201 capabilities as if they had been in the terminfo definition. 202 203 If terminfo does not (yet) have this flag, Nvim will fall back to $TERM and 204 other environment variables. It will add constructed "setrgbf" and "setrgbb" 205 capabilities in the case of the "rxvt", "linux", "st", "tmux", and "iterm" 206 terminal types, or when Konsole, genuine Xterm, a libvte terminal emulator 207 version 0.36 or later, or a terminal emulator that sets the COLORTERM 208 environment variable to "truecolor" is detected. 209 210 *xterm-resize* 211 Nvim can resize the terminal display on some terminals that implement an 212 extension pioneered by dtterm. |terminfo| does not have a flag for this 213 extension. So Nvim simply assumes that (all) "dtterm", "xterm", "teraterm", 214 "rxvt" terminal types, and Konsole, are capable of this. 215 216 *tui-cursor-shape* 217 Nvim will adjust the shape of the cursor from a block to a line when in insert 218 mode (or as specified by the 'guicursor' option), on terminals that support 219 it. It uses the same |terminfo| extensions that were pioneered by tmux for 220 this: "Ss" and "Se". 221 Similarly, if you set the cursor highlight group with blend=100, Nvim hides 222 the cursor through the "cvvis" and "civis" extensions. 223 224 If your terminfo definition is missing them, then Nvim will decide whether to 225 add them to your terminfo definition, by looking at $TERM and other 226 environment variables. For the "rxvt", "putty", "linux", "screen", 227 "teraterm", and "iterm" terminal types, or when Konsole, a libvte-based 228 terminal emulator, or genuine Xterm are detected, it will add constructed 229 "Ss" and "Se" capabilities. 230 231 *tui-cursor-tmux* 232 Within tmux it may appear that Nvim is not changing the cursor, but in fact it 233 is tmux receiving instructions from Nvim to change the cursor and not knowing 234 what to do in turn. tmux must translate what it receives from Nvim into 235 whatever control sequence is appropriate for the host terminal. It shares 236 a common mechanism with Nvim, of using the "Ss" and "Se" capabilities from 237 terminfo (for the output terminal) if they are present. Unlike Nvim, if they 238 are not in terminfo you must add them by setting "terminal-overrides" in 239 ~/.tmux.conf . 240 241 See the tmux(1) manual page for the details of how and what to do in the tmux 242 configuration file. It will look something like: >bash 243 set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q' 244 or (alas!) for Konsole 18.07.70 or older, something more complex like: >bash 245 set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007' 246 < 247 ============================================================================== 248 Window size *window-size* 249 250 [This is about the size of the whole window Vim is using, not a window that is 251 created with the ":split" command.] 252 253 On Unix systems, three methods are tried to get the window size: 254 255 - an ioctl call (TIOCGSIZE or TIOCGWINSZ, depends on your system) 256 - the environment variables "LINES" and "COLUMNS" 257 - from the |terminfo| entries "lines" and "columns" 258 259 If everything fails a default size of 24 lines and 80 columns is assumed. If 260 a window-resize signal is received the size will be set again. If the window 261 size is wrong you can use the 'lines' and 'columns' options to set the 262 correct values. See |:mode|. 263 264 ============================================================================== 265 Slow and fast terminals *slow-fast-terminal* 266 *slow-terminal* 267 268 If you have a slow terminal you may want to reset the 'showcmd' and 'ruler' 269 options. The command characters and cursor positions will not be shown in the 270 status line (which involves a lot of cursor motions and attribute changes for 271 every keypress or movement). If the terminal scrolls very slowly, set the 272 'scrolljump' to 5 or so. If the cursor is moved off the screen (e.g., with 273 "j") Vim will scroll 5 lines at a time. Another possibility is to reduce the 274 number of lines that Vim uses with the command "z{height}<CR>". 275 276 If the characters from the terminal are arriving with more than 1 second 277 between them you might want to set the 'timeout' and/or 'ttimeout' option. 278 279 If you are using a color terminal that is slow when displaying lines beyond 280 the end of a buffer, this is because Nvim is drawing the whitespace twice, in 281 two sets of colours and attributes. To prevent this, use this command: >vim 282 hi NonText cterm=NONE ctermfg=NONE 283 This draws the spaces with the default colours and attributes, which allows the 284 second pass of drawing to be optimized away. Note: Although in theory the 285 colours of whitespace are immaterial, in practice they change the colours of 286 cursors and selections that cross them. This may have a visible, but minor, 287 effect on some UIs. 288 289 290 vim:et:sw=2:tw=78:ts=8:ft=help:norl: