mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-12-08 07:32:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: graduate tui.txt to "flow layout" #30413

Browse Source
This commit is contained in:
Justin M. Keyes
2024-09-18 01:28:00 -07:00
committed by GitHub
parent 83a7d97d64
commit 22553e1f38
2 changed files with 117 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

216
runtime/doc/tui.txt
View File

@@ -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, $TERM is also important because it is forwarded by SSH to the remote session,
unlike most other environment variables. unlike most other environment variables.
>
For this terminal Set $TERM to |builtin-terms| For this terminal Set $TERM to |builtin-terms|
------------------------------------------------------------------------- -------------------------------------------------------------------------
anything libvte-based vte, vte-256color Y anything libvte-based vte, vte-256color Y
@@ -61,6 +62,7 @@ unlike most other environment variables.
Windows/VTP console vtpcon Y Windows/VTP console vtpcon Y
Windows/legacy console win32con Y Windows/legacy console win32con Y
xterm or compatible xterm, xterm-256color Y xterm or compatible xterm, xterm-256color Y
<
*builtin-terms* *builtin_terms* *builtin-terms* *builtin_terms*
If a |terminfo| database is not available or there is no entry for the current 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 For example, when running Nvim in tmux, this makes Nvim leave Insert mode and
go to the window below: > 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. 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/ The kitty keyboard protocol https://sw.kovidgoyal.net/kitty/keyboard-protocol/
is partially supported, including keypad keys in Unicode Private Use Area. is partially supported, including keypad keys in Unicode Private Use Area.
For example, this sequence is recognized by Nvim as <C-kEnter>: > 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. and can be used differently from <C-CR> in mappings.
*tui-modifyOtherKeys* *tui-csiu* *tui-modifyOtherKeys* *tui-csiu*
At startup Nvim will query your terminal to see if it supports the "CSI u" At startup Nvim will query your terminal to see if it supports the "CSI u"
encoding by writing the sequence > encoding by writing the sequence >
CSI ? u CSI c CSI ? u CSI c
If your terminal emulator responds with > 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 this means your terminal supports the "CSI u" encoding and Nvim will tell your
terminal to enable it by writing the sequence > 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 If your terminal does not support "CSI u" then Nvim will instead enable the
"modifyOtherKeys" encoding by writing the sequence > "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 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 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 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 configuration file. It will look something like: >bash
set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q' 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 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 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007'
< <
============================================================================== ==============================================================================
Window size *window-size* 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 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. 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 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 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 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 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 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 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* *mouse-mode-table* *mouse-overview*
Overview of what the mouse buttons do, when 'mousemodel' is "extend": Overview of what the mouse buttons do, when 'mousemodel' is "extend":
Normal Mode: *<S-LeftMouse>* *<A-RightMouse>* *<S-RightMouse>* *<RightDrag>*
event position selection change action ~ *<RightRelease>* *<LeftDrag>*
cursor window ~ Normal Mode: >
<LeftMouse> yes end yes event position selection change action
<C-LeftMouse> yes end yes "CTRL-]" (2) cursor window
<S-LeftMouse> yes no change yes "*" (2) *<S-LeftMouse>* ---------------------------------------------------------------------------
<LeftDrag> yes start or extend (1) no *<LeftDrag>* <LeftMouse> yes end yes
<LeftRelease> yes start or extend (1) no <C-LeftMouse> yes end yes "CTRL-]" (2)
<MiddleMouse> yes if not active no put <S-LeftMouse> yes no change yes "*" (2)
<MiddleMouse> yes if active no yank and put <LeftDrag> yes start or extend (1) no
<RightMouse> yes start or extend yes <LeftRelease> yes start or extend (1) no
<A-RightMouse> yes start or extend blockw. yes *<A-RightMouse>* <MiddleMouse> yes if not active no put
<S-RightMouse> yes no change yes "#" (2) *<S-RightMouse>* <MiddleMouse> yes if active no yank and put
<C-RightMouse> no no change no "CTRL-T" <RightMouse> yes start or extend yes
<RightDrag> yes extend no *<RightDrag>* <A-RightMouse> yes start or extend blockw. yes
<RightRelease> yes extend no *<RightRelease>* <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: Insert or Replace Mode: >
event position selection change action ~ event position selection change action
cursor window ~ cursor window
<LeftMouse> yes (cannot be active) yes ---------------------------------------------------------------------------
<C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2) <LeftMouse> yes (cannot be active) yes
<S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2) <C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2)
<LeftDrag> yes start or extend (1) no like CTRL-O (1) <S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2)
<LeftRelease> yes start or extend (1) no like CTRL-O (1) <LeftDrag> yes start or extend (1) no like CTRL-O (1)
<MiddleMouse> no (cannot be active) no put register <LeftRelease> yes start or extend (1) no like CTRL-O (1)
<RightMouse> yes start or extend yes like CTRL-O <MiddleMouse> no (cannot be active) no put register
<A-RightMouse> yes start or extend blockw. yes <RightMouse> yes start or extend yes like CTRL-O
<S-RightMouse> yes (cannot be active) yes "CTRL-O#" (2) <A-RightMouse> yes start or extend blockw. yes
<C-RightMouse> no (cannot be active) no "CTRL-O CTRL-T" <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: In a help window: >
event position selection change action ~ event position selection change action
cursor window ~ cursor window
<2-LeftMouse> yes (cannot be active) no "^]" (jump to help tag) ---------------------------------------------------------------------------
<2-LeftMouse> yes (cannot be active) no "^]" (jump to help tag)
When 'mousemodel' is "popup", these are different: When 'mousemodel' is "popup", these are different:
Normal Mode: *<A-LeftMouse>*
event position selection change action ~ Normal Mode: >
cursor window ~ event position selection change action
<S-LeftMouse> yes start or extend (1) no cursor window
<A-LeftMouse> yes start or extend blockw. no *<A-LeftMouse>* ---------------------------------------------------------------------------
<RightMouse> no popup menu no <S-LeftMouse> yes start or extend (1) no
<A-LeftMouse> yes start/extend blockw no
<RightMouse> no popup menu no
Insert or Replace Mode: Insert or Replace Mode: >
event position selection change action ~ event position selection change action
cursor window ~ cursor window
<S-LeftMouse> yes start or extend (1) no like CTRL-O (1) ---------------------------------------------------------------------------
<A-LeftMouse> yes start or extend blockw. no <S-LeftMouse> yes start or extend (1) no like CTRL-O (1)
<RightMouse> no popup menu no <A-LeftMouse> yes start/extend blockw no
<RightMouse> no popup menu no
(1) only if mouse pointer moved since press (1) only if mouse pointer moved since press
(2) only if click is in same buffer (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 work on systems where the window manager consumes the mouse events when the
alt key is pressed (it may move the window). 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 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 Win32 and for an xterm. For selecting text, extra clicks extend the
selection: selection: >
click select ~
double word or % match *<2-LeftMouse>* click select
triple line *<3-LeftMouse>* ---------------------------------
quadruple rectangular block *<4-LeftMouse>* 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 Exception: In a Help window a double click jumps to help for the word that is
clicked on. clicked on.
A double click on a word selects that word. 'iskeyword' is used to specify 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 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 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 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. '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 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 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 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 This is like using CTRL-O in Insert mode. Select mode is used when the
'selectmode' option contains "mouse". 'selectmode' option contains "mouse".
*<MiddleRelease>* *<MiddleDrag>* *X1Mouse* *X1Drag* *X1Release*
Mouse clicks can be mapped. The codes for mouse clicks are: *X2Mouse* *X2Drag* *X2Release*
code mouse button normal action ~ *<MiddleRelease>* *<MiddleDrag>*
<LeftMouse> left pressed set cursor position Mouse clicks can be mapped. The codes for mouse clicks are: >
<LeftDrag> left moved while pressed extend selection code mouse button normal action
<LeftRelease> left released set selection end ---------------------------------------------------------------------------
<MiddleMouse> middle pressed paste text at cursor position <LeftMouse> left pressed set cursor position
<MiddleDrag> middle moved while pressed - <LeftDrag> left moved while pressed extend selection
<MiddleRelease> middle released - <LeftRelease> left released set selection end
<RightMouse> right pressed extend selection <MiddleMouse> middle pressed paste text at cursor position
<RightDrag> right moved while pressed extend selection <MiddleDrag> middle moved while pressed -
<RightRelease> right released set selection end <MiddleRelease> middle released -
<X1Mouse> X1 button pressed - *X1Mouse* <RightMouse> right pressed extend selection
<X1Drag> X1 moved while pressed - *X1Drag* <RightDrag> right moved while pressed extend selection
<X1Release> X1 button release - *X1Release* <RightRelease> right released set selection end
<X2Mouse> X2 button pressed - *X2Mouse* <X1Mouse> X1 button pressed -
<X2Drag> X2 moved while pressed - *X2Drag* <X1Drag> X1 moved while pressed -
<X2Release> X2 button release - *X2Release* <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 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. 'Microsoft Explorer' mouse has these buttons available to the right thumb.
Currently X1 and X2 only work on Win32 and X11 environments. Currently X1 and X2 only work on Win32 and X11 environments.
Examples: >vim Examples: >vim
:noremap <MiddleMouse> <LeftMouse><MiddleMouse> :noremap <MiddleMouse> <LeftMouse><MiddleMouse>
Paste at the position of the middle mouse button click (otherwise the paste Paste at the position of the middle mouse button click (otherwise the paste
would be done at the cursor position). >vim would be done at the cursor position). >vim
:noremap <LeftRelease> <LeftRelease>y :noremap <LeftRelease> <LeftRelease>y
Immediately yank the selection, when using Visual mode. Immediately yank the selection, when using Visual mode.
Note the use of ":noremap" instead of "map" to avoid a recursive mapping. Note the use of ":noremap" instead of "map" to avoid a recursive mapping.
>vim >vim
:map <X1Mouse> <C-O> :map <X1Mouse> <C-O>
:map <X2Mouse> <C-I> :map <X2Mouse> <C-I>
Map the X1 and X2 buttons to go forwards and backwards in the jump list, see Map the X1 and X2 buttons to go forwards and backwards in the jump list, see
|CTRL-O| and |CTRL-I|. |CTRL-O| and |CTRL-I|.
*mouse-swap-buttons* *mouse-swap-buttons*
To swap the meaning of the left and right mouse buttons: >vim To swap the meaning of the left and right mouse buttons: >vim
:noremap <LeftMouse> <RightMouse> :noremap <LeftMouse> <RightMouse>
:noremap <LeftDrag> <RightDrag> :noremap <LeftDrag> <RightDrag>
:noremap <LeftRelease> <RightRelease> :noremap <LeftRelease> <RightRelease>
:noremap <RightMouse> <LeftMouse> :noremap <RightMouse> <LeftMouse>
:noremap <RightDrag> <LeftDrag> :noremap <RightDrag> <LeftDrag>
:noremap <RightRelease> <LeftRelease> :noremap <RightRelease> <LeftRelease>
:noremap g<LeftMouse> <C-RightMouse> :noremap g<LeftMouse> <C-RightMouse>
:noremap g<RightMouse> <C-LeftMouse> :noremap g<RightMouse> <C-LeftMouse>
:noremap! <LeftMouse> <RightMouse> :noremap! <LeftMouse> <RightMouse>
:noremap! <LeftDrag> <RightDrag> :noremap! <LeftDrag> <RightDrag>
:noremap! <LeftRelease> <RightRelease> :noremap! <LeftRelease> <RightRelease>
:noremap! <RightMouse> <LeftMouse> :noremap! <RightMouse> <LeftMouse>
:noremap! <RightDrag> <LeftDrag> :noremap! <RightDrag> <LeftDrag>
:noremap! <RightRelease> <LeftRelease> :noremap! <RightRelease> <LeftRelease>
< <
vim:tw=78:ts=8:ft=help:norl: vim:et:sw=2:tw=78:ts=8:ft=help:norl:

1
scripts/gen_help_html.lua
View File

@@ -76,6 +76,7 @@ local new_layout = {
['news-0.10.txt'] = true, ['news-0.10.txt'] = true,
['nvim.txt'] = true, ['nvim.txt'] = true,
['provider.txt'] = true, ['provider.txt'] = true,
['tui.txt'] = true,
['ui.txt'] = true, ['ui.txt'] = true,
['vim_diff.txt'] = true, ['vim_diff.txt'] = true,
} }