diff options
| -rw-r--r-- | runtime/doc/tui.txt | 222 | ||||
| -rw-r--r-- | scripts/gen_help_html.lua | 1 |
2 files changed, 120 insertions, 103 deletions
diff --git a/runtime/doc/tui.txt b/runtime/doc/tui.txt index 9d73341797..d2af878239 100644 --- a/runtime/doc/tui.txt +++ b/runtime/doc/tui.txt @@ -41,6 +41,7 @@ or sub-optimal behavior will result (scrolling quirks, wrong colors, etc.). $TERM is also important because it is forwarded by SSH to the remote session, unlike most other environment variables. +> For this terminal Set $TERM to |builtin-terms| ------------------------------------------------------------------------- anything libvte-based vte, vte-256color Y @@ -61,6 +62,7 @@ unlike most other environment variables. Windows/VTP console vtpcon Y Windows/legacy console win32con Y xterm or compatible xterm, xterm-256color Y +< *builtin-terms* *builtin_terms* If a |terminfo| database is not available or there is no entry for the current @@ -126,27 +128,27 @@ extended keys a.k.a. "modifyOtherKeys" or "CSI u") can also be parsed. For example, when running Nvim in tmux, this makes Nvim leave Insert mode and go to the window below: > - tmux send-keys 'Escape' [ 2 7 u 'C-W' j + tmux send-keys 'Escape' [ 2 7 u 'C-W' j Where `'Escape' [ 2 7 u` is an unambiguous "CSI u" sequence for the <Esc> key. The kitty keyboard protocol https://sw.kovidgoyal.net/kitty/keyboard-protocol/ is partially supported, including keypad keys in Unicode Private Use Area. For example, this sequence is recognized by Nvim as <C-kEnter>: > - CSI 57414 ; 5 u + CSI 57414 ; 5 u and can be used differently from <C-CR> in mappings. *tui-modifyOtherKeys* *tui-csiu* At startup Nvim will query your terminal to see if it supports the "CSI u" encoding by writing the sequence > - CSI ? u CSI c + CSI ? u CSI c If your terminal emulator responds with > - CSI ? <flags> u + CSI ? <flags> u this means your terminal supports the "CSI u" encoding and Nvim will tell your terminal to enable it by writing the sequence > - CSI > 1 u + CSI > 1 u If your terminal does not support "CSI u" then Nvim will instead enable the "modifyOtherKeys" encoding by writing the sequence > - CSI > 4 ; 2 m + CSI > 4 ; 2 m When Nvim exits cleanly it will send the corresponding sequence to disable the special key encoding. If Nvim does not exit cleanly then your terminal @@ -215,9 +217,9 @@ are not in terminfo you must add them by setting "terminal-overrides" in See the tmux(1) manual page for the details of how and what to do in the tmux configuration file. It will look something like: >bash - set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q' -<or (alas!) for Konsole 18.07.70 or older, something more complex like: >bash - set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007' + set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q' +or (alas!) for Konsole 18.07.70 or older, something more complex like: >bash + set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007' < ============================================================================== Window size *window-size* @@ -250,12 +252,11 @@ number of lines that Vim uses with the command "z{height}<CR>". If the characters from the terminal are arriving with more than 1 second between them you might want to set the 'timeout' and/or 'ttimeout' option. -See the "Options" chapter |options|. If you are using a color terminal that is slow when displaying lines beyond the end of a buffer, this is because Nvim is drawing the whitespace twice, in two sets of colours and attributes. To prevent this, use this command: >vim - hi NonText cterm=NONE ctermfg=NONE + hi NonText cterm=NONE ctermfg=NONE This draws the spaces with the default colours and attributes, which allows the second pass of drawing to be optimized away. Note: Although in theory the colours of whitespace are immaterial, in practice they change the colours of @@ -268,57 +269,65 @@ Using the mouse *mouse-using* *mouse-mode-table* *mouse-overview* Overview of what the mouse buttons do, when 'mousemodel' is "extend": -Normal Mode: -event position selection change action ~ - cursor window ~ -<LeftMouse> yes end yes -<C-LeftMouse> yes end yes "CTRL-]" (2) -<S-LeftMouse> yes no change yes "*" (2) *<S-LeftMouse>* -<LeftDrag> yes start or extend (1) no *<LeftDrag>* -<LeftRelease> yes start or extend (1) no -<MiddleMouse> yes if not active no put -<MiddleMouse> yes if active no yank and put -<RightMouse> yes start or extend yes -<A-RightMouse> yes start or extend blockw. yes *<A-RightMouse>* -<S-RightMouse> yes no change yes "#" (2) *<S-RightMouse>* -<C-RightMouse> no no change no "CTRL-T" -<RightDrag> yes extend no *<RightDrag>* -<RightRelease> yes extend no *<RightRelease>* - -Insert or Replace Mode: -event position selection change action ~ - cursor window ~ -<LeftMouse> yes (cannot be active) yes -<C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2) -<S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2) -<LeftDrag> yes start or extend (1) no like CTRL-O (1) -<LeftRelease> yes start or extend (1) no like CTRL-O (1) -<MiddleMouse> no (cannot be active) no put register -<RightMouse> yes start or extend yes like CTRL-O -<A-RightMouse> yes start or extend blockw. yes -<S-RightMouse> yes (cannot be active) yes "CTRL-O#" (2) -<C-RightMouse> no (cannot be active) no "CTRL-O CTRL-T" - -In a help window: -event position selection change action ~ - cursor window ~ -<2-LeftMouse> yes (cannot be active) no "^]" (jump to help tag) + *<S-LeftMouse>* *<A-RightMouse>* *<S-RightMouse>* *<RightDrag>* + *<RightRelease>* *<LeftDrag>* +Normal Mode: > + event position selection change action + cursor window + --------------------------------------------------------------------------- + <LeftMouse> yes end yes + <C-LeftMouse> yes end yes "CTRL-]" (2) + <S-LeftMouse> yes no change yes "*" (2) + <LeftDrag> yes start or extend (1) no + <LeftRelease> yes start or extend (1) no + <MiddleMouse> yes if not active no put + <MiddleMouse> yes if active no yank and put + <RightMouse> yes start or extend yes + <A-RightMouse> yes start or extend blockw. yes + <S-RightMouse> yes no change yes "#" (2) + <C-RightMouse> no no change no "CTRL-T" + <RightDrag> yes extend no + <RightRelease> yes extend no + +Insert or Replace Mode: > + event position selection change action + cursor window + --------------------------------------------------------------------------- + <LeftMouse> yes (cannot be active) yes + <C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2) + <S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2) + <LeftDrag> yes start or extend (1) no like CTRL-O (1) + <LeftRelease> yes start or extend (1) no like CTRL-O (1) + <MiddleMouse> no (cannot be active) no put register + <RightMouse> yes start or extend yes like CTRL-O + <A-RightMouse> yes start or extend blockw. yes + <S-RightMouse> yes (cannot be active) yes "CTRL-O#" (2) + <C-RightMouse> no (cannot be active) no "CTRL-O CTRL-T" + +In a help window: > + event position selection change action + cursor window + --------------------------------------------------------------------------- + <2-LeftMouse> yes (cannot be active) no "^]" (jump to help tag) When 'mousemodel' is "popup", these are different: -Normal Mode: -event position selection change action ~ - cursor window ~ -<S-LeftMouse> yes start or extend (1) no -<A-LeftMouse> yes start or extend blockw. no *<A-LeftMouse>* -<RightMouse> no popup menu no - -Insert or Replace Mode: -event position selection change action ~ - cursor window ~ -<S-LeftMouse> yes start or extend (1) no like CTRL-O (1) -<A-LeftMouse> yes start or extend blockw. no -<RightMouse> no popup menu no + *<A-LeftMouse>* +Normal Mode: > + event position selection change action + cursor window + --------------------------------------------------------------------------- + <S-LeftMouse> yes start or extend (1) no + <A-LeftMouse> yes start/extend blockw no + <RightMouse> no popup menu no + +Insert or Replace Mode: > + event position selection change action + cursor window + --------------------------------------------------------------------------- + <S-LeftMouse> yes start or extend (1) no like CTRL-O (1) + <A-LeftMouse> yes start/extend blockw no + <RightMouse> no popup menu no (1) only if mouse pointer moved since press (2) only if click is in same buffer @@ -348,16 +357,20 @@ key pressed causes the Visual area to become blockwise. When 'mousemodel' is work on systems where the window manager consumes the mouse events when the alt key is pressed (it may move the window). - *double-click* + *double-click* *<2-LeftMouse>* *<3-LeftMouse>* *<4-LeftMouse>* Double, triple and quadruple clicks are supported when the GUI is active, for Win32 and for an xterm. For selecting text, extra clicks extend the -selection: - click select ~ - double word or % match *<2-LeftMouse>* - triple line *<3-LeftMouse>* - quadruple rectangular block *<4-LeftMouse>* +selection: > + + click select + --------------------------------- + double word or % match + triple line + quadruple rectangular block + Exception: In a Help window a double click jumps to help for the word that is clicked on. + A double click on a word selects that word. 'iskeyword' is used to specify which characters are included in a word. A double click on a character that has a match selects until that match (like using "v%"). If the match is @@ -365,7 +378,7 @@ an #if/#else/#endif block, the selection becomes linewise. For MS-Windows and xterm the time for double clicking can be set with the 'mousetime' option. For the other systems this time is defined outside of Vim. An example, for using a double click to jump to the tag under the cursor: >vim - :map <2-LeftMouse> :exe "tag " .. expand("<cword>")<CR> + :map <2-LeftMouse> :exe "tag " .. expand("<cword>")<CR> Dragging the mouse with a double click (button-down, button-up, button-down and then drag) will result in whole words to be selected. This continues @@ -379,59 +392,62 @@ temporarily. When Visual or Select mode ends, it returns to Insert mode. This is like using CTRL-O in Insert mode. Select mode is used when the 'selectmode' option contains "mouse". - *<MiddleRelease>* *<MiddleDrag>* -Mouse clicks can be mapped. The codes for mouse clicks are: - code mouse button normal action ~ - <LeftMouse> left pressed set cursor position - <LeftDrag> left moved while pressed extend selection - <LeftRelease> left released set selection end - <MiddleMouse> middle pressed paste text at cursor position - <MiddleDrag> middle moved while pressed - - <MiddleRelease> middle released - - <RightMouse> right pressed extend selection - <RightDrag> right moved while pressed extend selection - <RightRelease> right released set selection end - <X1Mouse> X1 button pressed - *X1Mouse* - <X1Drag> X1 moved while pressed - *X1Drag* - <X1Release> X1 button release - *X1Release* - <X2Mouse> X2 button pressed - *X2Mouse* - <X2Drag> X2 moved while pressed - *X2Drag* - <X2Release> X2 button release - *X2Release* + *X1Mouse* *X1Drag* *X1Release* + *X2Mouse* *X2Drag* *X2Release* + *<MiddleRelease>* *<MiddleDrag>* +Mouse clicks can be mapped. The codes for mouse clicks are: > + code mouse button normal action + --------------------------------------------------------------------------- + <LeftMouse> left pressed set cursor position + <LeftDrag> left moved while pressed extend selection + <LeftRelease> left released set selection end + <MiddleMouse> middle pressed paste text at cursor position + <MiddleDrag> middle moved while pressed - + <MiddleRelease> middle released - + <RightMouse> right pressed extend selection + <RightDrag> right moved while pressed extend selection + <RightRelease> right released set selection end + <X1Mouse> X1 button pressed - + <X1Drag> X1 moved while pressed - + <X1Release> X1 button release - + <X2Mouse> X2 button pressed - + <X2Drag> X2 moved while pressed - + <X2Release> X2 button release - The X1 and X2 buttons refer to the extra buttons found on some mice. The 'Microsoft Explorer' mouse has these buttons available to the right thumb. Currently X1 and X2 only work on Win32 and X11 environments. Examples: >vim - :noremap <MiddleMouse> <LeftMouse><MiddleMouse> + :noremap <MiddleMouse> <LeftMouse><MiddleMouse> Paste at the position of the middle mouse button click (otherwise the paste would be done at the cursor position). >vim - :noremap <LeftRelease> <LeftRelease>y + :noremap <LeftRelease> <LeftRelease>y Immediately yank the selection, when using Visual mode. Note the use of ":noremap" instead of "map" to avoid a recursive mapping. >vim - :map <X1Mouse> <C-O> - :map <X2Mouse> <C-I> + :map <X1Mouse> <C-O> + :map <X2Mouse> <C-I> Map the X1 and X2 buttons to go forwards and backwards in the jump list, see |CTRL-O| and |CTRL-I|. *mouse-swap-buttons* To swap the meaning of the left and right mouse buttons: >vim - :noremap <LeftMouse> <RightMouse> - :noremap <LeftDrag> <RightDrag> - :noremap <LeftRelease> <RightRelease> - :noremap <RightMouse> <LeftMouse> - :noremap <RightDrag> <LeftDrag> - :noremap <RightRelease> <LeftRelease> - :noremap g<LeftMouse> <C-RightMouse> - :noremap g<RightMouse> <C-LeftMouse> - :noremap! <LeftMouse> <RightMouse> - :noremap! <LeftDrag> <RightDrag> - :noremap! <LeftRelease> <RightRelease> - :noremap! <RightMouse> <LeftMouse> - :noremap! <RightDrag> <LeftDrag> - :noremap! <RightRelease> <LeftRelease> + :noremap <LeftMouse> <RightMouse> + :noremap <LeftDrag> <RightDrag> + :noremap <LeftRelease> <RightRelease> + :noremap <RightMouse> <LeftMouse> + :noremap <RightDrag> <LeftDrag> + :noremap <RightRelease> <LeftRelease> + :noremap g<LeftMouse> <C-RightMouse> + :noremap g<RightMouse> <C-LeftMouse> + :noremap! <LeftMouse> <RightMouse> + :noremap! <LeftDrag> <RightDrag> + :noremap! <LeftRelease> <RightRelease> + :noremap! <RightMouse> <LeftMouse> + :noremap! <RightDrag> <LeftDrag> + :noremap! <RightRelease> <LeftRelease> < - vim:tw=78:ts=8:ft=help:norl: + vim:et:sw=2:tw=78:ts=8:ft=help:norl: diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index 51048c9803..f088f706d6 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -76,6 +76,7 @@ local new_layout = { ['news-0.10.txt'] = true, ['nvim.txt'] = true, ['provider.txt'] = true, + ['tui.txt'] = true, ['ui.txt'] = true, ['vim_diff.txt'] = true, } |