From 44afd074430a7cb612f548e651df07651019e34c Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 18 Sep 2024 00:26:01 -0700 Subject: docs(tui): rename term.txt, nvim_terminal_emulator.txt #30398 Problem: It has long been a convention that references to the builtin terminal UI should mention "tui", not "term", in order to avoid ambiguity vs the builtin `:terminal` feature. The final step was to rename term.txt; let's that step. Solution: - rename term.txt => tui.txt - rename nvim_terminal_emulator.txt => terminal.txt - `gen_help_html.lua`: generate redirects for renamed pages. --- runtime/doc/nvim_terminal_emulator.txt | 633 --------------------------------- runtime/doc/term.txt | 437 ----------------------- runtime/doc/terminal.txt | 633 +++++++++++++++++++++++++++++++++ runtime/doc/tui.txt | 437 +++++++++++++++++++++++ 4 files changed, 1070 insertions(+), 1070 deletions(-) delete mode 100644 runtime/doc/nvim_terminal_emulator.txt delete mode 100644 runtime/doc/term.txt create mode 100644 runtime/doc/terminal.txt create mode 100644 runtime/doc/tui.txt (limited to 'runtime') diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt deleted file mode 100644 index 10658ff4ff..0000000000 --- a/runtime/doc/nvim_terminal_emulator.txt +++ /dev/null @@ -1,633 +0,0 @@ -*terminal_emulator.txt* Nvim - - - NVIM REFERENCE MANUAL by Thiago de Arruda - - -Terminal emulator *terminal* *terminal-emulator* - -Nvim embeds a VT220/xterm terminal emulator based on libvterm. The terminal is -presented as a special 'buftype', asynchronously updated as data is received -from the connected program. - -Terminal buffers behave like normal buffers, except: -- With 'modifiable', lines can be edited but not deleted. -- 'scrollback' controls how many lines are kept. -- Output is followed ("tailed") if cursor is on the last line. -- 'modified' is the default. You can set 'nomodified' to avoid a warning when - closing the terminal buffer. -- 'bufhidden' defaults to "hide". - - Type |gO| to see the table of contents. - -============================================================================== -Start *terminal-start* - -There are several ways to create a terminal buffer: - -- Run the |:terminal| command. -- Call the |nvim_open_term()| or |termopen()| function. -- Edit a "term://" buffer. Examples: >vim - :edit term://bash - :vsplit term://top - -< Note: To open a "term://" buffer from an autocmd, the |autocmd-nested| - modifier is required. >vim - autocmd VimEnter * ++nested split term://sh -< (This is only mentioned for reference; use |:terminal| instead.) - -When the terminal starts, the buffer contents are updated and the buffer is -named in the form of `term://{cwd}//{pid}:{cmd}`. This naming scheme is used -by |:mksession| to restore a terminal buffer (by restarting the {cmd}). - -The terminal environment is initialized as in |jobstart-env|. - -============================================================================== -Input *terminal-input* - -To send input, enter |Terminal-mode| with |i|, |I|, |a|, |A| or -|:startinsert|. In this mode all keys except are sent to the underlying -program. If is pressed, the next key is sent unless it is or . -Use to return to normal mode. |CTRL-\_CTRL-N| -Use to execute one normal mode command and then return to terminal -mode. *t_CTRL-\_CTRL-O* - -Terminal-mode forces these local options: - - 'cursorlineopt' = number - 'nocursorcolumn' - 'scrolloff' = 0 - 'sidescrolloff' = 0 - -Terminal-mode has its own |:tnoremap| namespace for mappings, this can be used -to automate any terminal interaction. - -To map to exit terminal-mode: >vim - :tnoremap - -To simulate |i_CTRL-R| in terminal-mode: >vim - :tnoremap '"'.nr2char(getchar()).'pi' - -To use `ALT+{h,j,k,l}` to navigate windows from any mode: >vim - :tnoremap h - :tnoremap j - :tnoremap k - :tnoremap l - :inoremap h - :inoremap j - :inoremap k - :inoremap l - :nnoremap h - :nnoremap j - :nnoremap k - :nnoremap l - -You can also create menus similar to terminal mode mappings, but you have to -use |:tlmenu| instead of |:tmenu|. - -Mouse input has the following behavior: - -- If the program has enabled mouse events, the corresponding events will be - forwarded to the program. -- If mouse events are disabled (the default), terminal focus will be lost and - the event will be processed as in a normal buffer. -- If another window is clicked, terminal focus will be lost and nvim will jump - to the clicked window -- If the mouse wheel is used while the mouse is positioned in another window, - the terminal won't lose focus and the hovered window will be scrolled. - -============================================================================== -Configuration *terminal-config* - -Options: 'modified', 'scrollback' -Events: |TermOpen|, |TermEnter|, |TermLeave|, |TermClose| -Highlight groups: |hl-TermCursor|, |hl-TermCursorNC| - -Terminal sets local defaults for some options, which may differ from your -global configuration. - -- 'list' is disabled -- 'wrap' is disabled - -You can change the defaults with a TermOpen autocommand: >vim - au TermOpen * setlocal list - -TERMINAL COLORS ~ - -The `{g,b}:terminal_color_x` variables control the terminal color palette, -where `x` is the color index between 0 and 15 inclusive. The variables are -read during |TermOpen|. The value must be a color name or hexadecimal string. -Example: >vim - let g:terminal_color_4 = '#ff0000' - let g:terminal_color_5 = 'green' -Only works for RGB UIs (see 'termguicolors'); for 256-color terminals the -color index is just forwarded. - -Editor highlighting (|syntax-highlighting|, |highlight-groups|, etc.) has -higher precedence: it is applied after terminal colors are resolved. - ------------------------------------------------------------------------------- -EVENTS *terminal-events* - -Applications running in a :terminal buffer can send requests, which Nvim -exposes via the |TermRequest| event. - -OSC 7: change working directory *terminal-osc7* - -To handle OSC 7 emitted from :terminal processes, this code will :cd to the -directory indicated in the request. >lua - - vim.api.nvim_create_autocmd({ 'TermRequest' }, { - desc = 'Handles OSC 7 dir change requests', - callback = function(ev) - if string.sub(vim.v.termrequest, 1, 4) == '\x1b]7;' then - local dir = string.gsub(vim.v.termrequest, '\x1b]7;file://[^/]*', '') - if vim.fn.isdirectory(dir) == 0 then - vim.notify('invalid dir: '..dir) - return - end - vim.api.nvim_buf_set_var(ev.buf, 'osc7_dir', dir) - if vim.o.autochdir and vim.api.nvim_get_current_buf() == ev.buf then - vim.cmd.cd(dir) - end - end - end - }) - vim.api.nvim_create_autocmd({ 'BufEnter', 'WinEnter', 'DirChanged' }, { - callback = function(ev) - if vim.b.osc7_dir and vim.fn.isdirectory(vim.b.osc7_dir) == 1 then - vim.cmd.cd(vim.b.osc7_dir) - end - end - }) - -To try it out, select the above code and source it with `:'<,'>lua`, then run -this command in a :terminal buffer: > - - printf "\033]7;file://./foo/bar\033\\" - -OSC 52: write to system clipboard *terminal-osc52* - -Applications in the :terminal buffer can write to the system clipboard by -emitting an OSC 52 sequence. Example: > - - printf '\033]52;;%s\033\\' "$(echo -n 'Hello world' | base64)" - -Nvim uses the configured |clipboard| provider to write to the system -clipboard. Reading from the system clipboard with OSC 52 is not supported, as -this would allow any arbitrary program in the :terminal to read the user's -clipboard. - -OSC 52 sequences sent from the :terminal buffer do not emit a |TermRequest| -event. The event is handled directly by Nvim and is not forwarded to plugins. - -============================================================================== -Status Variables *terminal-status* - -Terminal buffers maintain some buffer-local variables and options. The values -are initialized before TermOpen, so you can use them in a local 'statusline'. -Example: >vim - :autocmd TermOpen * setlocal statusline=%{b:term_title} - -- *b:term_title* Terminal title (user-writable), typically displayed in the - window title or tab title of a graphical terminal emulator. Terminal - programs can set this by emitting an escape sequence. -- |'channel'| Terminal PTY |job-id|. Can be used with |chansend()| to send - input to the terminal. -- The |TermClose| event gives the terminal job exit code in the |v:event| - "status" field. For example, this autocommand outputs the terminal's exit - code to |:messages|: >vim - autocmd TermClose * echom 'Terminal exited with status '..v:event.status - -Use |jobwait()| to check if the terminal job has finished: >vim - let running = jobwait([&channel], 0)[0] == -1 - -============================================================================== -:Termdebug plugin *terminal-debug* - -The Terminal debugging plugin can be used to debug a program with gdb and view -the source code in a Vim window. Since this is completely contained inside -Vim this also works remotely over an ssh connection. - -Starting ~ - *termdebug-starting* -Load the plugin with this command: >vim - packadd termdebug -When loading the plugin from the |vimrc| file, add the "!" attribute: >vim - packadd! termdebug -< *:Termdebug* -To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the -command name, for example: >vim - :Termdebug vim - -This opens two windows: - -gdb window A terminal window in which "gdb vim" is executed. Here you - can directly interact with gdb. - -program window A terminal window for the executed program. When "run" is - used in gdb the program I/O will happen in this window, so - that it does not interfere with controlling gdb. - -The current window is used to show the source code. When gdb pauses the -source file location will be displayed, if possible. A sign is used to -highlight the current position, using highlight group debugPC. - -If the buffer in the current window is modified, another window will be opened -to display the current gdb position. - -Focus the terminal of the executed program to interact with it. This works -the same as any command running in a terminal window. - -When the debugger ends, typically by typing "quit" in the gdb window, the two -opened windows are closed. - -Only one debugger can be active at a time. - *:TermdebugCommand* -If you want to give specific commands to the command being debugged, you can -use the `:TermdebugCommand` command followed by the command name and -additional parameters. >vim - :TermdebugCommand vim --clean -c ':set nu' - -Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang -argument to start the command right away, without pausing at the gdb window -(and cursor will be in the debugged window). For example: >vim - :TermdebugCommand! vim --clean - -To attach gdb to an already running executable or use a core file, pass extra -arguments. E.g.: >vim - :Termdebug vim core - :Termdebug vim 98343 - -If no argument is given, you'll end up in a gdb window, in which you need to -specify which command to run using e.g. the gdb `file` command. - - -Example session ~ - *termdebug-example* -Start in the Vim "src" directory and build Vim: > - % make -Start Vim: > - % ./vim -Load the termdebug plugin and start debugging Vim: >vim - :packadd termdebug - :Termdebug vim -You should now have three windows: - source - where you started - gdb - you can type gdb commands here - program - the executed program will use this window - -Put focus on the gdb window and type: > - break ex_help - run -Vim will start running in the program window. Put focus there and type: >vim - :help gui -Gdb will run into the ex_help breakpoint. The source window now shows the -ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the -breakpoint was set. The line where the debugger stopped is highlighted. You -can now step through the program. You will see the highlighting move as the -debugger executes a line of source code. - -Run ":Next" a few times until the for loop is highlighted. Put the cursor on -the end of "eap->arg", then call ":Eval". You will see this displayed: - "eap->arg": 0x555555e68855 "gui" ~ -This way you can inspect the value of local variables. You can also focus the -gdb window and use a "print" command, e.g.: > - print *eap -If mouse pointer movements are working, Vim will also show a balloon when the -mouse rests on text that can be evaluated by gdb. -You can also use the "K" mapping that will either use Nvim floating windows -to show the results. - -Now go back to the source window and put the cursor on the first line after -the for loop, then type: > - :Break -You will see a "1" marker appear, this indicates the new breakpoint. Now -run ":Cont" command and the code until the breakpoint will be executed. - -You can type more advanced commands in the gdb window. For example, type: > - watch curbuf -Now run ":Cont" (or type "cont" in the gdb window). Execution -will now continue until the value of "curbuf" changes, which is in do_ecmd(). -To remove this watchpoint again type in the gdb window: > - delete 3 - -You can see the stack by typing in the gdb window: > - where -Move through the stack frames, e.g. with: > - frame 3 -The source window will show the code, at the point where the call was made to -a deeper level. - - -Stepping through code ~ - *termdebug-stepping* -Put focus on the gdb window to type commands there. Some common ones are: -- CTRL-C interrupt the program -- next execute the current line and stop at the next line -- step execute the current line and stop at the next statement, - entering functions -- until execute until past the current cursor line or past a specified - position or the current stack frame returns -- finish execute until leaving the current function -- where show the stack -- frame N go to the Nth stack frame -- continue continue execution - - *:Run* *:Arguments* -In the window showing the source code these commands can be used to control -gdb: - `:Run` [args] run the program with [args] or the previous arguments - `:Arguments` {args} set arguments for the next `:Run` - - *:Break* set a breakpoint at the cursor position - :Break {position} - set a breakpoint at the specified position - *:Tbreak* set a temporary breakpoint at the cursor position - :Tbreak {position} - set a temporary breakpoint at the specified position - *:Clear* delete the breakpoint at the cursor position - - *:Step* execute the gdb "step" command - *:Over* execute the gdb "next" command (`:Next` is a Vim command) - *:Until* execute the gdb "until" command - *:Finish* execute the gdb "finish" command - *:Continue* execute the gdb "continue" command - *:Stop* interrupt the program - -If gdb stops at a source line and there is no window currently showing the -source code, a new window will be created for the source code. This also -happens if the buffer in the source code window has been modified and can't be -abandoned. - -Gdb gives each breakpoint a number. In Vim the number shows up in the sign -column, with a red background. You can use these gdb commands: -- info break list breakpoints -- delete N delete breakpoint N -You can also use the `:Clear` command if the cursor is in the line with the -breakpoint, or use the "Clear breakpoint" right-click menu entry. - - -Inspecting variables ~ - *termdebug-variables* *:Evaluate* - `:Evaluate` evaluate the expression under the cursor - `K` same (see |termdebug_map_K| to disable) - `:Evaluate` {expr} evaluate {expr} - `:'<,'>Evaluate` evaluate the Visually selected text - -This is similar to using "print" in the gdb window. -You can usually shorten `:Evaluate` to `:Ev`. -The result is displayed in a floating window. -You can move the cursor to this window by running `:Evaluate` (or `K`) again. - - -Navigating stack frames ~ - *termdebug-frames* *:Frame* *:Up* *:Down* - `:Frame` [frame] select frame [frame], which is a frame number, - address, or function name (default: current frame) - `:Up` [count] go up [count] frames (default: 1; the frame that - called the current) - `+` same (see |termdebug_map_plus| to disable) - `:Down` [count] go down [count] frames (default: 1; the frame called - by the current) - `-` same (see |termdebug_map_minus| to disable) - - -Other commands ~ - *termdebug-commands* - *:Gdb* jump to the gdb window - *:Program* jump to the window with the running program - *:Source* jump to the window with the source code, create it if there - isn't one - *:Asm* jump to the window with the disassembly, create it if there - isn't one - *:Var* jump to the window with the local and argument variables, - create it if there isn't one. This window updates whenever the - program is stopped - -Events ~ - *termdebug-events* -Four autocommands can be used: >vim - au User TermdebugStartPre echomsg 'debugging starting' - au User TermdebugStartPost echomsg 'debugging started' - au User TermdebugStopPre echomsg 'debugging stopping' - au User TermdebugStopPost echomsg 'debugging stopped' -< - *TermdebugStartPre* -TermdebugStartPre Before starting debugging. - Not triggered if the debugger is already - running or the debugger command cannot be - executed. - *TermdebugStartPost* -TermdebugStartPost After debugging has initialized. - If a "!" bang is passed to `:Termdebug` or - `:TermdebugCommand` the event is triggered - before running the provided command in gdb. - *TermdebugStopPre* -TermdebugStopPre Before debugging ends, when gdb is terminated, - most likely after issuing a "quit" command in - the gdb window. - *TermdebugStopPost* -TermdebugStopPost After debugging has ended, gdb-related windows - are closed, debug buffers wiped out and - the state before the debugging was restored. - - -Customizing ~ - *termdebug-customizing* *g:termdebug_config* -In the past several global variables were used for configuration. These are -deprecated and using the g:termdebug_config dictionary is preferred. When -g:termdebug_config exists the other global variables will NOT be used. -The recommended way is to start with an empty dictionary: >vim - let g:termdebug_config = {} - -Then you can add entries to the dictionary as mentioned below. The -deprecated global variable names are mentioned for completeness. If you are -switching over to using g:termdebug_config you can find the old variable name -and take over the value, then delete the deprecated variable. - - -Prompt mode ~ - *termdebug-prompt* -When on MS-Windows, gdb will run in a buffer with 'buftype' set to "prompt". -This works slightly differently: -- The gdb window will be in Insert mode while typing commands. Go to Normal - mode with , then you can move around in the buffer, copy/paste, etc. - Go back to editing the gdb command with any command that starts Insert mode, - such as `a` or `i`. -- A separate :terminal window will be opened to run the debugged program in. - - *termdebug_use_prompt* -Prompt mode can be used with: >vim - let g:termdebug_config['use_prompt'] = 1 -If there is no g:termdebug_config you can use: >vim - let g:termdebug_use_prompt = 1 -< -Mappings ~ -The termdebug plugin enables a few default mappings. All those mappings -are reset to their original values once the termdebug session concludes. - - *termdebug_map_K* *termdebug-mappings* -The K key is normally mapped to |:Evaluate| unless a buffer local (|:map-local|) -mapping to K already exists. If you do not want this use: >vim - let g:termdebug_config['map_K'] = 0 -If there is no g:termdebug_config you can use: >vim - let g:termdebug_map_K = 0 -< - *termdebug_map_minus* -The - key is normally mapped to |:Down| unless a buffer local mapping to the - -key already exists. If you do not want this use: >vim - let g:termdebug_config['map_minus'] = 0 -< - *termdebug_map_plus* -The + key is normally mapped to |:Up| unless a buffer local mapping to the + -key already exists. If you do not want this use: >vim - let g:termdebug_config['map_plus'] = 0 -< - *termdebug_disasm_window* -If you want the Asm window shown by default, set the "disasm_window" flag to -1. The "disasm_window_height" entry can be used to set the window height: >vim - let g:termdebug_config['disasm_window'] = 1 - let g:termdebug_config['disasm_window_height'] = 15 -If there is no g:termdebug_config you can use: >vim - let g:termdebug_disasm_window = 15 -Any value greater than 1 will set the Asm window height to that value. -If the current window has enough horizontal space, it will be vertically split -and the Asm window will be shown side by side with the source code window (and -the height option won't be used). - - *termdebug_variables_window* -If you want the Var window shown by default, set the "variables_window" flag -to 1. The "variables_window_height" entry can be used to set the window -height: >vim - let g:termdebug_config['variables_window'] = 1 - let g:termdebug_config['variables_window_height'] = 15 -If there is no g:termdebug_config you can use: >vim - let g:termdebug_variables_window = 15 -Any value greater than 1 will set the Var window height to that value. -If the current window has enough horizontal space, it will be vertically split -and the Var window will be shown side by side with the source code window (and -the height options won't be used). - -Communication ~ - *termdebug-communication* -There is another, hidden, buffer, which is used for Vim to communicate with -gdb. The buffer name is "gdb communication". Do not delete this buffer, it -will break the debugger. - -Gdb has some weird behavior, the plugin does its best to work around that. -For example, after typing "continue" in the gdb window a CTRL-C can be used to -interrupt the running program. But after using the MI command -"-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see -"continue" being used for the `:Continue` command, instead of using the -communication channel. - - -GDB command ~ - *g:termdebugger* -To change the name of the gdb command, set "debugger" entry in -g:termdebug_config or the "g:termdebugger" variable before invoking -`:Termdebug`: >vim - let g:termdebug_config['command'] = "mygdb" -If there is no g:termdebug_config you can use: >vim - let g:termdebugger = "mygdb" - -If the command needs an argument use a List: >vim - let g:termdebug_config['command'] = ['rr', 'replay', '--'] -If there is no g:termdebug_config you can use: >vim - let g:termdebugger = ['rr', 'replay', '--'] - -If you are a mouse person, you can also define a mapping using your right -click to one of the terminal command like evaluate the variable under the -cursor: >vim - nnoremap :Evaluate -or set/unset a breakpoint: >vim - nnoremap :Break - - -Several arguments will be added to make gdb work well for the debugger. -If you want to modify them, add a function to filter the argument list: >vim - let g:termdebug_config['command_filter'] = MyDebugFilter - -If you do not want the arguments to be added, but you do need to set the -"pty", use a function to add the necessary arguments: >vim - let g:termdebug_config['command_add_args'] = MyAddArguments -The function will be called with the list of arguments so far, and a second -argument that is the name of the pty. - *gdb-version* -Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI -interface. The "new-ui" command requires gdb version 7.12 or later. If you -get this error: - Undefined command: "new-ui". Try "help".~ -Then your gdb is too old. - - -Colors ~ - *hl-debugPC* *hl-debugBreakpoint* -The color of the signs can be adjusted with these highlight groups: -- debugPC the current position -- debugBreakpoint a breakpoint - -The defaults are, when 'background' is "light": - hi debugPC term=reverse ctermbg=lightblue guibg=lightblue - hi debugBreakpoint term=reverse ctermbg=red guibg=red - -When 'background' is "dark": - hi debugPC term=reverse ctermbg=darkblue guibg=darkblue - hi debugBreakpoint term=reverse ctermbg=red guibg=red - - -Shortcuts ~ - *termdebug_shortcuts* -You can define your own shortcuts (mappings) to control gdb, that can work in -any window, using the TermDebugSendCommand() function. Example: >vim - map ,w :call TermDebugSendCommand('where') -The argument is the gdb command. - - -Popup menu ~ - *termdebug_popup* -By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds -these entries to the popup menu: - Set breakpoint `:Break` - Clear breakpoint `:Clear` - Evaluate `:Evaluate` -If you don't want this then disable it with: >vim - let g:termdebug_config['popup'] = 0 -If there is no g:termdebug_config you can use: >vim - let g:termdebug_popup = 0 - - -Change default signs ~ - *termdebug_signs* -Termdebug uses the hex number of the breakpoint ID in the signcolumn to -represent breakpoints. if it is greater than "0xFF", then it will be displayed -as "F+", due to we really only have two screen cells for the sign. - -If you want to customize the breakpoint signs: >vim - let g:termdebug_config['sign'] = '>>' -If there is no g:terminal_config yet you can use: >vim - let g:termdebug_config = {'sign': '>>'} - -After this, breakpoints will be displayed as `>>` in the signcolumn. - - -Vim window width ~ - *termdebug_wide* -To change the width of the Vim window when debugging starts and use a vertical -split: >vim - let g:termdebug_config['wide'] = 163 -If there is no g:termdebug_config you can use: >vim - let g:termdebug_wide = 163 - -This will set 'columns' to 163 when `:Termdebug` is used. The value is -restored when quitting the debugger. - -If the wide value is set and 'columns' is already a greater value, then a -vertical split will be used without modifying 'columns'. - -Set the wide value to 1 to use a vertical split without ever changing -'columns'. This is useful when the terminal can't be resized by Vim. - - - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt deleted file mode 100644 index 8ef8675d13..0000000000 --- a/runtime/doc/term.txt +++ /dev/null @@ -1,437 +0,0 @@ -*term.txt* Nvim - - - NVIM REFERENCE MANUAL - - -Terminal UI *TUI* *tui* - -Nvim uses a list of terminal capabilities to display its user interface -(except in |--embed| and |--headless| modes). If that information is wrong, -the screen may be messed up or keys may not be recognized. - - Type |gO| to see the table of contents. - -============================================================================== -Startup *startup-terminal* - -Nvim guesses the terminal type when it starts (except in |--embed| and -|--headless| modes). The |$TERM| environment variable is the primary hint that -determines the terminal type. - - *terminfo* *E557* *E558* *E559* -The terminfo database is used if available. - -The Unibilium library (used by Nvim to read terminfo) allows you to override -the system terminfo with one in $HOME/.terminfo/ directory, in part or in -whole. - -Building your own terminfo is usually as simple as running this as -a non-superuser: -> - curl -LO https://invisible-island.net/datafiles/current/terminfo.src.gz - gunzip terminfo.src.gz - tic -x terminfo.src -< - *$TERM* -The $TERM environment variable must match the terminal you are using! -Otherwise Nvim cannot know what sequences your terminal expects, and weird -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 - (e.g. GNOME Terminal) (aliases: gnome, gnome-256color) - iTerm (original) iterm, iTerm.app N - iTerm2 (new capabilities) iterm2, iTerm2.app Y - Konsole konsole-256color N - Linux virtual terminal linux, linux-256color Y - PuTTY putty, putty-256color Y - rxvt rxvt, rxvt-256color Y - screen screen, screen-256color Y - simple terminal (st) st, st-256color Y - Terminal.app nsterm N - tmux tmux, tmux-256color Y - Windows/ConEmu conemu Y - Windows/Cygwin-built Nvim cygwin Y - Windows/Interix interix Y - 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 -terminal, Nvim will map |$TERM| to a builtin entry according to the above -table, or "ansi" if there is no match. For example "TERM=putty-256color" will -be mapped to the builtin "putty" entry. See also |tui-colors|. - -The builtin terminfo is not combined with any external terminfo database, nor -can it be used in preference to one. You can thus entirely override any -omissions or out-of-date information in the builtin terminfo database by -supplying an external one with entries for the terminal type. - -Settings depending on terminal *term-dependent-settings* - -If you want to set terminal-dependent options or mappings, you can do this in -your init.vim. Example: >vim - - if $TERM =~ '^\(rxvt\|screen\|interix\|putty\)\(-.*\)\?$' - set notermguicolors - elseif $TERM =~ '^\(tmux\|iterm\|vte\|gnome\)\(-.*\)\?$' - set termguicolors - elseif $TERM =~ '^\(xterm\)\(-.*\)\?$' - if $XTERM_VERSION != '' - set termguicolors - elseif $KONSOLE_PROFILE_NAME != '' - set termguicolors - elseif $VTE_VERSION != '' - set termguicolors - else - set notermguicolors - endif - elseif $TERM =~ ... - ... and so forth ... - endif -< - *scroll-region* *xterm-scroll-region* -Where possible, Nvim will use the terminal's ability to set a scroll region in -order to redraw faster when a window is scrolled. If the terminal's terminfo -description describes an ability to set top and bottom scroll margins, that is -used. - -This will not speed up scrolling in a window that is not the full width of the -terminal. Xterm has an extra ability, not described by terminfo, to set left -and right scroll margins as well. If Nvim detects that the terminal is Xterm, -it will make use of this ability to speed up scrolling that is not the full -width of the terminal. - - *tui-input* -Historically, terminal emulators could not distinguish between certain control -key modifiers and other keys. For example, and are represented in -the same way, as are and , and , and and . - -Modern terminal emulators are able to distinguish between these pairs of keys -by encoding control modifiers differently. There are two common but distinct -ways of doing this, known as "modifyOtherKeys" and "CSI u". Nvim supports both -encoding methods and at startup will tell the terminal emulator that it -understands these key encodings. If your terminal emulator supports it then -this will allow you to map the key pairs listed above separately. || - -Nvim uses libtermkey to convert terminal escape sequences to key codes. -|terminfo| is used first, and CSI sequences not in |terminfo| (including -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 -Where `'Escape' [ 2 7 u` is an unambiguous "CSI u" sequence for the 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 : > - CSI 57414 ; 5 u -and can be used differently from 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 -If your terminal emulator responds with > - CSI ? 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 -If your terminal does not support "CSI u" then Nvim will instead enable the -"modifyOtherKeys" encoding by writing the sequence > - 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 -emulator could be in a bad state. If this happens, simply run "reset". - - *tui-colors* -Nvim uses 256 colours by default, ignoring |terminfo| for most terminal types, -including "linux" (whose virtual terminals have had 256-colour support since -4.8) and anything claiming to be "xterm". Also when $COLORTERM or $TERM -contain the string "256". - -Nvim similarly assumes that any terminal emulator that sets $COLORTERM to any -value, is capable of at least 16-colour operation. - - *true-color* *xterm-true-color* -Nvim emits true (24-bit) colours in the terminal, if 'termguicolors' is set. - -It uses the "setrgbf" and "setrgbb" |terminfo| extensions (proposed by Rüdiger -Sonderfeld in 2013). If your terminfo definition is missing them, then Nvim -will decide whether to add them to your terminfo definition, using the ISO -8613-6:1994/ITU T.416:1993 control sequences for setting RGB colours (but -modified to use semicolons instead of colons unless the terminal is known to -follow the standard). - -Another convention, pioneered in 2016 by tmux, is the "Tc" terminfo extension. -If terminfo has this flag, Nvim will add constructed "setrgbf" and "setrgbb" -capabilities as if they had been in the terminfo definition. - -If terminfo does not (yet) have this flag, Nvim will fall back to $TERM and -other environment variables. It will add constructed "setrgbf" and "setrgbb" -capabilities in the case of the "rxvt", "linux", "st", "tmux", and "iterm" -terminal types, or when Konsole, genuine Xterm, a libvte terminal emulator -version 0.36 or later, or a terminal emulator that sets the COLORTERM -environment variable to "truecolor" is detected. - - *xterm-resize* -Nvim can resize the terminal display on some terminals that implement an -extension pioneered by dtterm. |terminfo| does not have a flag for this -extension. So Nvim simply assumes that (all) "dtterm", "xterm", "teraterm", -"rxvt" terminal types, and Konsole, are capable of this. - - *tui-cursor-shape* -Nvim will adjust the shape of the cursor from a block to a line when in insert -mode (or as specified by the 'guicursor' option), on terminals that support -it. It uses the same |terminfo| extensions that were pioneered by tmux for -this: "Ss" and "Se". -Similarly, if you set the cursor highlight group with blend=100, Nvim hides -the cursor through the "cvvis" and "civis" extensions. - -If your terminfo definition is missing them, then Nvim will decide whether to -add them to your terminfo definition, by looking at $TERM and other -environment variables. For the "rxvt", "putty", "linux", "screen", -"teraterm", and "iterm" terminal types, or when Konsole, a libvte-based -terminal emulator, or genuine Xterm are detected, it will add constructed -"Ss" and "Se" capabilities. - - *tui-cursor-tmux* -Within tmux it may appear that Nvim is not changing the cursor, but in fact it -is tmux receiving instructions from Nvim to change the cursor and not knowing -what to do in turn. tmux must translate what it receives from Nvim into -whatever control sequence is appropriate for the host terminal. It shares -a common mechanism with Nvim, of using the "Ss" and "Se" capabilities from -terminfo (for the output terminal) if they are present. Unlike Nvim, if they -are not in terminfo you must add them by setting "terminal-overrides" in -~/.tmux.conf . - -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' -bash - set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007' -< -============================================================================== -Window size *window-size* - -[This is about the size of the whole window Vim is using, not a window that is -created with the ":split" command.] - -On Unix systems, three methods are tried to get the window size: - -- an ioctl call (TIOCGSIZE or TIOCGWINSZ, depends on your system) -- the environment variables "LINES" and "COLUMNS" -- from the |terminfo| entries "lines" and "columns" - -If everything fails a default size of 24 lines and 80 columns is assumed. If -a window-resize signal is received the size will be set again. If the window -size is wrong you can use the 'lines' and 'columns' options to set the -correct values. See |:mode|. - -============================================================================== -Slow and fast terminals *slow-fast-terminal* - *slow-terminal* - -If you have a slow terminal you may want to reset the 'showcmd' and 'ruler' -options. The command characters and cursor positions will not be shown in the -status line (which involves a lot of cursor motions and attribute changes for -every keypress or movement). If the terminal scrolls very slowly, set the -'scrolljump' to 5 or so. If the cursor is moved off the screen (e.g., with -"j") Vim will scroll 5 lines at a time. Another possibility is to reduce the -number of lines that Vim uses with the command "z{height}". - -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 -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 -cursors and selections that cross them. This may have a visible, but minor, -effect on some UIs. - -============================================================================== -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 ~ - yes end yes - yes end yes "CTRL-]" (2) - yes no change yes "*" (2) ** - yes start or extend (1) no ** - yes start or extend (1) no - yes if not active no put - yes if active no yank and put - yes start or extend yes - yes start or extend blockw. yes ** - yes no change yes "#" (2) ** - no no change no "CTRL-T" - yes extend no ** - yes extend no ** - -Insert or Replace Mode: -event position selection change action ~ - cursor window ~ - yes (cannot be active) yes - yes (cannot be active) yes "CTRL-O^]" (2) - yes (cannot be active) yes "CTRL-O*" (2) - yes start or extend (1) no like CTRL-O (1) - yes start or extend (1) no like CTRL-O (1) - no (cannot be active) no put register - yes start or extend yes like CTRL-O - yes start or extend blockw. yes - yes (cannot be active) yes "CTRL-O#" (2) - 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 ~ - yes start or extend (1) no - yes start or extend blockw. no ** - no popup menu no - -Insert or Replace Mode: -event position selection change action ~ - cursor window ~ - yes start or extend (1) no like CTRL-O (1) - yes start or extend blockw. no - no popup menu no - -(1) only if mouse pointer moved since press -(2) only if click is in same buffer - -Clicking the left mouse button causes the cursor to be positioned. If the -click is in another window that window is made the active window. When -editing the command-line the cursor can only be positioned on the -command-line. When in Insert mode Vim remains in Insert mode. If 'scrolloff' -is set, and the cursor is positioned within 'scrolloff' lines from the window -border, the text is scrolled. - -A selection can be started by pressing the left mouse button on the first -character, moving the mouse to the last character, then releasing the mouse -button. You will not always see the selection until you release the button, -only in some versions (GUI, Win32) will the dragging be shown immediately. -Note that you can make the text scroll by moving the mouse at least one -character in the first/last line in the window when 'scrolloff' is non-zero. - -In Normal, Visual and Select mode clicking the right mouse button causes the -Visual area to be extended. When 'mousemodel' is "popup", the left button has -to be used while keeping the shift key pressed. When clicking in a window -which is editing another buffer, the Visual or Select mode is stopped. - -In Normal, Visual and Select mode clicking the right mouse button with the alt -key pressed causes the Visual area to become blockwise. When 'mousemodel' is -"popup" the left button has to be used with the alt key. Note that this won't -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, 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>* -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 -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("") - -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 -until the button is released, at which point the selection is per character -again. - -For scrolling with the mouse see |scroll-mouse-wheel|. - -In Insert mode, when a selection is started, Vim goes into Normal mode -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". - - ** ** -Mouse clicks can be mapped. The codes for mouse clicks are: - code mouse button normal action ~ - left pressed set cursor position - left moved while pressed extend selection - left released set selection end - middle pressed paste text at cursor position - middle moved while pressed - - middle released - - right pressed extend selection - right moved while pressed extend selection - right released set selection end - X1 button pressed - *X1Mouse* - X1 moved while pressed - *X1Drag* - X1 button release - *X1Release* - X2 button pressed - *X2Mouse* - X2 moved while pressed - *X2Drag* - X2 button release - *X2Release* - -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 -Paste at the position of the middle mouse button click (otherwise the paste -would be done at the cursor position). >vim - - :noremap y -Immediately yank the selection, when using Visual mode. - -Note the use of ":noremap" instead of "map" to avoid a recursive mapping. ->vim - :map - :map -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 - :noremap - :noremap - :noremap - :noremap - :noremap - :noremap g - :noremap g - :noremap! - :noremap! - :noremap! - :noremap! - :noremap! - :noremap! -< - vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt new file mode 100644 index 0000000000..5d8dd484f9 --- /dev/null +++ b/runtime/doc/terminal.txt @@ -0,0 +1,633 @@ +*terminal.txt* Nvim + + + NVIM REFERENCE MANUAL by Thiago de Arruda + + +Terminal emulator *terminal* *terminal-emulator* + +Nvim embeds a VT220/xterm terminal emulator based on libvterm. The terminal is +presented as a special 'buftype', asynchronously updated as data is received +from the connected program. + +Terminal buffers behave like normal buffers, except: +- With 'modifiable', lines can be edited but not deleted. +- 'scrollback' controls how many lines are kept. +- Output is followed ("tailed") if cursor is on the last line. +- 'modified' is the default. You can set 'nomodified' to avoid a warning when + closing the terminal buffer. +- 'bufhidden' defaults to "hide". + + Type |gO| to see the table of contents. + +============================================================================== +Start *terminal-start* + +There are several ways to create a terminal buffer: + +- Run the |:terminal| command. +- Call the |nvim_open_term()| or |termopen()| function. +- Edit a "term://" buffer. Examples: >vim + :edit term://bash + :vsplit term://top + +< Note: To open a "term://" buffer from an autocmd, the |autocmd-nested| + modifier is required. >vim + autocmd VimEnter * ++nested split term://sh +< (This is only mentioned for reference; use |:terminal| instead.) + +When the terminal starts, the buffer contents are updated and the buffer is +named in the form of `term://{cwd}//{pid}:{cmd}`. This naming scheme is used +by |:mksession| to restore a terminal buffer (by restarting the {cmd}). + +The terminal environment is initialized as in |jobstart-env|. + +============================================================================== +Input *terminal-input* + +To send input, enter |Terminal-mode| with |i|, |I|, |a|, |A| or +|:startinsert|. In this mode all keys except are sent to the underlying +program. If is pressed, the next key is sent unless it is or . +Use to return to normal mode. |CTRL-\_CTRL-N| +Use to execute one normal mode command and then return to terminal +mode. *t_CTRL-\_CTRL-O* + +Terminal-mode forces these local options: + + 'cursorlineopt' = number + 'nocursorcolumn' + 'scrolloff' = 0 + 'sidescrolloff' = 0 + +Terminal-mode has its own |:tnoremap| namespace for mappings, this can be used +to automate any terminal interaction. + +To map to exit terminal-mode: >vim + :tnoremap + +To simulate |i_CTRL-R| in terminal-mode: >vim + :tnoremap '"'.nr2char(getchar()).'pi' + +To use `ALT+{h,j,k,l}` to navigate windows from any mode: >vim + :tnoremap h + :tnoremap j + :tnoremap k + :tnoremap l + :inoremap h + :inoremap j + :inoremap k + :inoremap l + :nnoremap h + :nnoremap j + :nnoremap k + :nnoremap l + +You can also create menus similar to terminal mode mappings, but you have to +use |:tlmenu| instead of |:tmenu|. + +Mouse input has the following behavior: + +- If the program has enabled mouse events, the corresponding events will be + forwarded to the program. +- If mouse events are disabled (the default), terminal focus will be lost and + the event will be processed as in a normal buffer. +- If another window is clicked, terminal focus will be lost and nvim will jump + to the clicked window +- If the mouse wheel is used while the mouse is positioned in another window, + the terminal won't lose focus and the hovered window will be scrolled. + +============================================================================== +Configuration *terminal-config* + +Options: 'modified', 'scrollback' +Events: |TermOpen|, |TermEnter|, |TermLeave|, |TermClose| +Highlight groups: |hl-TermCursor|, |hl-TermCursorNC| + +Terminal sets local defaults for some options, which may differ from your +global configuration. + +- 'list' is disabled +- 'wrap' is disabled + +You can change the defaults with a TermOpen autocommand: >vim + au TermOpen * setlocal list + +TERMINAL COLORS ~ + +The `{g,b}:terminal_color_x` variables control the terminal color palette, +where `x` is the color index between 0 and 15 inclusive. The variables are +read during |TermOpen|. The value must be a color name or hexadecimal string. +Example: >vim + let g:terminal_color_4 = '#ff0000' + let g:terminal_color_5 = 'green' +Only works for RGB UIs (see 'termguicolors'); for 256-color terminals the +color index is just forwarded. + +Editor highlighting (|syntax-highlighting|, |highlight-groups|, etc.) has +higher precedence: it is applied after terminal colors are resolved. + +------------------------------------------------------------------------------ +EVENTS *terminal-events* + +Applications running in a :terminal buffer can send requests, which Nvim +exposes via the |TermRequest| event. + +OSC 7: change working directory *terminal-osc7* + +To handle OSC 7 emitted from :terminal processes, this code will :cd to the +directory indicated in the request. >lua + + vim.api.nvim_create_autocmd({ 'TermRequest' }, { + desc = 'Handles OSC 7 dir change requests', + callback = function(ev) + if string.sub(vim.v.termrequest, 1, 4) == '\x1b]7;' then + local dir = string.gsub(vim.v.termrequest, '\x1b]7;file://[^/]*', '') + if vim.fn.isdirectory(dir) == 0 then + vim.notify('invalid dir: '..dir) + return + end + vim.api.nvim_buf_set_var(ev.buf, 'osc7_dir', dir) + if vim.o.autochdir and vim.api.nvim_get_current_buf() == ev.buf then + vim.cmd.cd(dir) + end + end + end + }) + vim.api.nvim_create_autocmd({ 'BufEnter', 'WinEnter', 'DirChanged' }, { + callback = function(ev) + if vim.b.osc7_dir and vim.fn.isdirectory(vim.b.osc7_dir) == 1 then + vim.cmd.cd(vim.b.osc7_dir) + end + end + }) + +To try it out, select the above code and source it with `:'<,'>lua`, then run +this command in a :terminal buffer: > + + printf "\033]7;file://./foo/bar\033\\" + +OSC 52: write to system clipboard *terminal-osc52* + +Applications in the :terminal buffer can write to the system clipboard by +emitting an OSC 52 sequence. Example: > + + printf '\033]52;;%s\033\\' "$(echo -n 'Hello world' | base64)" + +Nvim uses the configured |clipboard| provider to write to the system +clipboard. Reading from the system clipboard with OSC 52 is not supported, as +this would allow any arbitrary program in the :terminal to read the user's +clipboard. + +OSC 52 sequences sent from the :terminal buffer do not emit a |TermRequest| +event. The event is handled directly by Nvim and is not forwarded to plugins. + +============================================================================== +Status Variables *terminal-status* + +Terminal buffers maintain some buffer-local variables and options. The values +are initialized before TermOpen, so you can use them in a local 'statusline'. +Example: >vim + :autocmd TermOpen * setlocal statusline=%{b:term_title} + +- *b:term_title* Terminal title (user-writable), typically displayed in the + window title or tab title of a graphical terminal emulator. Terminal + programs can set this by emitting an escape sequence. +- |'channel'| Terminal PTY |job-id|. Can be used with |chansend()| to send + input to the terminal. +- The |TermClose| event gives the terminal job exit code in the |v:event| + "status" field. For example, this autocommand outputs the terminal's exit + code to |:messages|: >vim + autocmd TermClose * echom 'Terminal exited with status '..v:event.status + +Use |jobwait()| to check if the terminal job has finished: >vim + let running = jobwait([&channel], 0)[0] == -1 + +============================================================================== +:Termdebug plugin *terminal-debug* + +The Terminal debugging plugin can be used to debug a program with gdb and view +the source code in a Vim window. Since this is completely contained inside +Vim this also works remotely over an ssh connection. + +Starting ~ + *termdebug-starting* +Load the plugin with this command: >vim + packadd termdebug +When loading the plugin from the |vimrc| file, add the "!" attribute: >vim + packadd! termdebug +< *:Termdebug* +To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the +command name, for example: >vim + :Termdebug vim + +This opens two windows: + +gdb window A terminal window in which "gdb vim" is executed. Here you + can directly interact with gdb. + +program window A terminal window for the executed program. When "run" is + used in gdb the program I/O will happen in this window, so + that it does not interfere with controlling gdb. + +The current window is used to show the source code. When gdb pauses the +source file location will be displayed, if possible. A sign is used to +highlight the current position, using highlight group debugPC. + +If the buffer in the current window is modified, another window will be opened +to display the current gdb position. + +Focus the terminal of the executed program to interact with it. This works +the same as any command running in a terminal window. + +When the debugger ends, typically by typing "quit" in the gdb window, the two +opened windows are closed. + +Only one debugger can be active at a time. + *:TermdebugCommand* +If you want to give specific commands to the command being debugged, you can +use the `:TermdebugCommand` command followed by the command name and +additional parameters. >vim + :TermdebugCommand vim --clean -c ':set nu' + +Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang +argument to start the command right away, without pausing at the gdb window +(and cursor will be in the debugged window). For example: >vim + :TermdebugCommand! vim --clean + +To attach gdb to an already running executable or use a core file, pass extra +arguments. E.g.: >vim + :Termdebug vim core + :Termdebug vim 98343 + +If no argument is given, you'll end up in a gdb window, in which you need to +specify which command to run using e.g. the gdb `file` command. + + +Example session ~ + *termdebug-example* +Start in the Vim "src" directory and build Vim: > + % make +Start Vim: > + % ./vim +Load the termdebug plugin and start debugging Vim: >vim + :packadd termdebug + :Termdebug vim +You should now have three windows: + source - where you started + gdb - you can type gdb commands here + program - the executed program will use this window + +Put focus on the gdb window and type: > + break ex_help + run +Vim will start running in the program window. Put focus there and type: >vim + :help gui +Gdb will run into the ex_help breakpoint. The source window now shows the +ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the +breakpoint was set. The line where the debugger stopped is highlighted. You +can now step through the program. You will see the highlighting move as the +debugger executes a line of source code. + +Run ":Next" a few times until the for loop is highlighted. Put the cursor on +the end of "eap->arg", then call ":Eval". You will see this displayed: + "eap->arg": 0x555555e68855 "gui" ~ +This way you can inspect the value of local variables. You can also focus the +gdb window and use a "print" command, e.g.: > + print *eap +If mouse pointer movements are working, Vim will also show a balloon when the +mouse rests on text that can be evaluated by gdb. +You can also use the "K" mapping that will either use Nvim floating windows +to show the results. + +Now go back to the source window and put the cursor on the first line after +the for loop, then type: > + :Break +You will see a "1" marker appear, this indicates the new breakpoint. Now +run ":Cont" command and the code until the breakpoint will be executed. + +You can type more advanced commands in the gdb window. For example, type: > + watch curbuf +Now run ":Cont" (or type "cont" in the gdb window). Execution +will now continue until the value of "curbuf" changes, which is in do_ecmd(). +To remove this watchpoint again type in the gdb window: > + delete 3 + +You can see the stack by typing in the gdb window: > + where +Move through the stack frames, e.g. with: > + frame 3 +The source window will show the code, at the point where the call was made to +a deeper level. + + +Stepping through code ~ + *termdebug-stepping* +Put focus on the gdb window to type commands there. Some common ones are: +- CTRL-C interrupt the program +- next execute the current line and stop at the next line +- step execute the current line and stop at the next statement, + entering functions +- until execute until past the current cursor line or past a specified + position or the current stack frame returns +- finish execute until leaving the current function +- where show the stack +- frame N go to the Nth stack frame +- continue continue execution + + *:Run* *:Arguments* +In the window showing the source code these commands can be used to control +gdb: + `:Run` [args] run the program with [args] or the previous arguments + `:Arguments` {args} set arguments for the next `:Run` + + *:Break* set a breakpoint at the cursor position + :Break {position} + set a breakpoint at the specified position + *:Tbreak* set a temporary breakpoint at the cursor position + :Tbreak {position} + set a temporary breakpoint at the specified position + *:Clear* delete the breakpoint at the cursor position + + *:Step* execute the gdb "step" command + *:Over* execute the gdb "next" command (`:Next` is a Vim command) + *:Until* execute the gdb "until" command + *:Finish* execute the gdb "finish" command + *:Continue* execute the gdb "continue" command + *:Stop* interrupt the program + +If gdb stops at a source line and there is no window currently showing the +source code, a new window will be created for the source code. This also +happens if the buffer in the source code window has been modified and can't be +abandoned. + +Gdb gives each breakpoint a number. In Vim the number shows up in the sign +column, with a red background. You can use these gdb commands: +- info break list breakpoints +- delete N delete breakpoint N +You can also use the `:Clear` command if the cursor is in the line with the +breakpoint, or use the "Clear breakpoint" right-click menu entry. + + +Inspecting variables ~ + *termdebug-variables* *:Evaluate* + `:Evaluate` evaluate the expression under the cursor + `K` same (see |termdebug_map_K| to disable) + `:Evaluate` {expr} evaluate {expr} + `:'<,'>Evaluate` evaluate the Visually selected text + +This is similar to using "print" in the gdb window. +You can usually shorten `:Evaluate` to `:Ev`. +The result is displayed in a floating window. +You can move the cursor to this window by running `:Evaluate` (or `K`) again. + + +Navigating stack frames ~ + *termdebug-frames* *:Frame* *:Up* *:Down* + `:Frame` [frame] select frame [frame], which is a frame number, + address, or function name (default: current frame) + `:Up` [count] go up [count] frames (default: 1; the frame that + called the current) + `+` same (see |termdebug_map_plus| to disable) + `:Down` [count] go down [count] frames (default: 1; the frame called + by the current) + `-` same (see |termdebug_map_minus| to disable) + + +Other commands ~ + *termdebug-commands* + *:Gdb* jump to the gdb window + *:Program* jump to the window with the running program + *:Source* jump to the window with the source code, create it if there + isn't one + *:Asm* jump to the window with the disassembly, create it if there + isn't one + *:Var* jump to the window with the local and argument variables, + create it if there isn't one. This window updates whenever the + program is stopped + +Events ~ + *termdebug-events* +Four autocommands can be used: >vim + au User TermdebugStartPre echomsg 'debugging starting' + au User TermdebugStartPost echomsg 'debugging started' + au User TermdebugStopPre echomsg 'debugging stopping' + au User TermdebugStopPost echomsg 'debugging stopped' +< + *TermdebugStartPre* +TermdebugStartPre Before starting debugging. + Not triggered if the debugger is already + running or the debugger command cannot be + executed. + *TermdebugStartPost* +TermdebugStartPost After debugging has initialized. + If a "!" bang is passed to `:Termdebug` or + `:TermdebugCommand` the event is triggered + before running the provided command in gdb. + *TermdebugStopPre* +TermdebugStopPre Before debugging ends, when gdb is terminated, + most likely after issuing a "quit" command in + the gdb window. + *TermdebugStopPost* +TermdebugStopPost After debugging has ended, gdb-related windows + are closed, debug buffers wiped out and + the state before the debugging was restored. + + +Customizing ~ + *termdebug-customizing* *g:termdebug_config* +In the past several global variables were used for configuration. These are +deprecated and using the g:termdebug_config dictionary is preferred. When +g:termdebug_config exists the other global variables will NOT be used. +The recommended way is to start with an empty dictionary: >vim + let g:termdebug_config = {} + +Then you can add entries to the dictionary as mentioned below. The +deprecated global variable names are mentioned for completeness. If you are +switching over to using g:termdebug_config you can find the old variable name +and take over the value, then delete the deprecated variable. + + +Prompt mode ~ + *termdebug-prompt* +When on MS-Windows, gdb will run in a buffer with 'buftype' set to "prompt". +This works slightly differently: +- The gdb window will be in Insert mode while typing commands. Go to Normal + mode with , then you can move around in the buffer, copy/paste, etc. + Go back to editing the gdb command with any command that starts Insert mode, + such as `a` or `i`. +- A separate :terminal window will be opened to run the debugged program in. + + *termdebug_use_prompt* +Prompt mode can be used with: >vim + let g:termdebug_config['use_prompt'] = 1 +If there is no g:termdebug_config you can use: >vim + let g:termdebug_use_prompt = 1 +< +Mappings ~ +The termdebug plugin enables a few default mappings. All those mappings +are reset to their original values once the termdebug session concludes. + + *termdebug_map_K* *termdebug-mappings* +The K key is normally mapped to |:Evaluate| unless a buffer local (|:map-local|) +mapping to K already exists. If you do not want this use: >vim + let g:termdebug_config['map_K'] = 0 +If there is no g:termdebug_config you can use: >vim + let g:termdebug_map_K = 0 +< + *termdebug_map_minus* +The - key is normally mapped to |:Down| unless a buffer local mapping to the - +key already exists. If you do not want this use: >vim + let g:termdebug_config['map_minus'] = 0 +< + *termdebug_map_plus* +The + key is normally mapped to |:Up| unless a buffer local mapping to the + +key already exists. If you do not want this use: >vim + let g:termdebug_config['map_plus'] = 0 +< + *termdebug_disasm_window* +If you want the Asm window shown by default, set the "disasm_window" flag to +1. The "disasm_window_height" entry can be used to set the window height: >vim + let g:termdebug_config['disasm_window'] = 1 + let g:termdebug_config['disasm_window_height'] = 15 +If there is no g:termdebug_config you can use: >vim + let g:termdebug_disasm_window = 15 +Any value greater than 1 will set the Asm window height to that value. +If the current window has enough horizontal space, it will be vertically split +and the Asm window will be shown side by side with the source code window (and +the height option won't be used). + + *termdebug_variables_window* +If you want the Var window shown by default, set the "variables_window" flag +to 1. The "variables_window_height" entry can be used to set the window +height: >vim + let g:termdebug_config['variables_window'] = 1 + let g:termdebug_config['variables_window_height'] = 15 +If there is no g:termdebug_config you can use: >vim + let g:termdebug_variables_window = 15 +Any value greater than 1 will set the Var window height to that value. +If the current window has enough horizontal space, it will be vertically split +and the Var window will be shown side by side with the source code window (and +the height options won't be used). + +Communication ~ + *termdebug-communication* +There is another, hidden, buffer, which is used for Vim to communicate with +gdb. The buffer name is "gdb communication". Do not delete this buffer, it +will break the debugger. + +Gdb has some weird behavior, the plugin does its best to work around that. +For example, after typing "continue" in the gdb window a CTRL-C can be used to +interrupt the running program. But after using the MI command +"-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see +"continue" being used for the `:Continue` command, instead of using the +communication channel. + + +GDB command ~ + *g:termdebugger* +To change the name of the gdb command, set "debugger" entry in +g:termdebug_config or the "g:termdebugger" variable before invoking +`:Termdebug`: >vim + let g:termdebug_config['command'] = "mygdb" +If there is no g:termdebug_config you can use: >vim + let g:termdebugger = "mygdb" + +If the command needs an argument use a List: >vim + let g:termdebug_config['command'] = ['rr', 'replay', '--'] +If there is no g:termdebug_config you can use: >vim + let g:termdebugger = ['rr', 'replay', '--'] + +If you are a mouse person, you can also define a mapping using your right +click to one of the terminal command like evaluate the variable under the +cursor: >vim + nnoremap :Evaluate +or set/unset a breakpoint: >vim + nnoremap :Break + + +Several arguments will be added to make gdb work well for the debugger. +If you want to modify them, add a function to filter the argument list: >vim + let g:termdebug_config['command_filter'] = MyDebugFilter + +If you do not want the arguments to be added, but you do need to set the +"pty", use a function to add the necessary arguments: >vim + let g:termdebug_config['command_add_args'] = MyAddArguments +The function will be called with the list of arguments so far, and a second +argument that is the name of the pty. + *gdb-version* +Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI +interface. The "new-ui" command requires gdb version 7.12 or later. If you +get this error: + Undefined command: "new-ui". Try "help".~ +Then your gdb is too old. + + +Colors ~ + *hl-debugPC* *hl-debugBreakpoint* +The color of the signs can be adjusted with these highlight groups: +- debugPC the current position +- debugBreakpoint a breakpoint + +The defaults are, when 'background' is "light": + hi debugPC term=reverse ctermbg=lightblue guibg=lightblue + hi debugBreakpoint term=reverse ctermbg=red guibg=red + +When 'background' is "dark": + hi debugPC term=reverse ctermbg=darkblue guibg=darkblue + hi debugBreakpoint term=reverse ctermbg=red guibg=red + + +Shortcuts ~ + *termdebug_shortcuts* +You can define your own shortcuts (mappings) to control gdb, that can work in +any window, using the TermDebugSendCommand() function. Example: >vim + map ,w :call TermDebugSendCommand('where') +The argument is the gdb command. + + +Popup menu ~ + *termdebug_popup* +By default the Termdebug plugin sets 'mousemodel' to "popup_setpos" and adds +these entries to the popup menu: + Set breakpoint `:Break` + Clear breakpoint `:Clear` + Evaluate `:Evaluate` +If you don't want this then disable it with: >vim + let g:termdebug_config['popup'] = 0 +If there is no g:termdebug_config you can use: >vim + let g:termdebug_popup = 0 + + +Change default signs ~ + *termdebug_signs* +Termdebug uses the hex number of the breakpoint ID in the signcolumn to +represent breakpoints. if it is greater than "0xFF", then it will be displayed +as "F+", due to we really only have two screen cells for the sign. + +If you want to customize the breakpoint signs: >vim + let g:termdebug_config['sign'] = '>>' +If there is no g:terminal_config yet you can use: >vim + let g:termdebug_config = {'sign': '>>'} + +After this, breakpoints will be displayed as `>>` in the signcolumn. + + +Vim window width ~ + *termdebug_wide* +To change the width of the Vim window when debugging starts and use a vertical +split: >vim + let g:termdebug_config['wide'] = 163 +If there is no g:termdebug_config you can use: >vim + let g:termdebug_wide = 163 + +This will set 'columns' to 163 when `:Termdebug` is used. The value is +restored when quitting the debugger. + +If the wide value is set and 'columns' is already a greater value, then a +vertical split will be used without modifying 'columns'. + +Set the wide value to 1 to use a vertical split without ever changing +'columns'. This is useful when the terminal can't be resized by Vim. + + + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/tui.txt b/runtime/doc/tui.txt new file mode 100644 index 0000000000..9d73341797 --- /dev/null +++ b/runtime/doc/tui.txt @@ -0,0 +1,437 @@ +*tui.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Terminal UI *TUI* *tui* + +Nvim uses a list of terminal capabilities to display its user interface +(except in |--embed| and |--headless| modes). If that information is wrong, +the screen may be messed up or keys may not be recognized. + + Type |gO| to see the table of contents. + +============================================================================== +Startup *startup-terminal* + +Nvim guesses the terminal type when it starts (except in |--embed| and +|--headless| modes). The |$TERM| environment variable is the primary hint that +determines the terminal type. + + *terminfo* *E557* *E558* *E559* +The terminfo database is used if available. + +The Unibilium library (used by Nvim to read terminfo) allows you to override +the system terminfo with one in $HOME/.terminfo/ directory, in part or in +whole. + +Building your own terminfo is usually as simple as running this as +a non-superuser: +> + curl -LO https://invisible-island.net/datafiles/current/terminfo.src.gz + gunzip terminfo.src.gz + tic -x terminfo.src +< + *$TERM* +The $TERM environment variable must match the terminal you are using! +Otherwise Nvim cannot know what sequences your terminal expects, and weird +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 + (e.g. GNOME Terminal) (aliases: gnome, gnome-256color) + iTerm (original) iterm, iTerm.app N + iTerm2 (new capabilities) iterm2, iTerm2.app Y + Konsole konsole-256color N + Linux virtual terminal linux, linux-256color Y + PuTTY putty, putty-256color Y + rxvt rxvt, rxvt-256color Y + screen screen, screen-256color Y + simple terminal (st) st, st-256color Y + Terminal.app nsterm N + tmux tmux, tmux-256color Y + Windows/ConEmu conemu Y + Windows/Cygwin-built Nvim cygwin Y + Windows/Interix interix Y + 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 +terminal, Nvim will map |$TERM| to a builtin entry according to the above +table, or "ansi" if there is no match. For example "TERM=putty-256color" will +be mapped to the builtin "putty" entry. See also |tui-colors|. + +The builtin terminfo is not combined with any external terminfo database, nor +can it be used in preference to one. You can thus entirely override any +omissions or out-of-date information in the builtin terminfo database by +supplying an external one with entries for the terminal type. + +Settings depending on terminal *term-dependent-settings* + +If you want to set terminal-dependent options or mappings, you can do this in +your init.vim. Example: >vim + + if $TERM =~ '^\(rxvt\|screen\|interix\|putty\)\(-.*\)\?$' + set notermguicolors + elseif $TERM =~ '^\(tmux\|iterm\|vte\|gnome\)\(-.*\)\?$' + set termguicolors + elseif $TERM =~ '^\(xterm\)\(-.*\)\?$' + if $XTERM_VERSION != '' + set termguicolors + elseif $KONSOLE_PROFILE_NAME != '' + set termguicolors + elseif $VTE_VERSION != '' + set termguicolors + else + set notermguicolors + endif + elseif $TERM =~ ... + ... and so forth ... + endif +< + *scroll-region* *xterm-scroll-region* +Where possible, Nvim will use the terminal's ability to set a scroll region in +order to redraw faster when a window is scrolled. If the terminal's terminfo +description describes an ability to set top and bottom scroll margins, that is +used. + +This will not speed up scrolling in a window that is not the full width of the +terminal. Xterm has an extra ability, not described by terminfo, to set left +and right scroll margins as well. If Nvim detects that the terminal is Xterm, +it will make use of this ability to speed up scrolling that is not the full +width of the terminal. + + *tui-input* +Historically, terminal emulators could not distinguish between certain control +key modifiers and other keys. For example, and are represented in +the same way, as are and , and , and and . + +Modern terminal emulators are able to distinguish between these pairs of keys +by encoding control modifiers differently. There are two common but distinct +ways of doing this, known as "modifyOtherKeys" and "CSI u". Nvim supports both +encoding methods and at startup will tell the terminal emulator that it +understands these key encodings. If your terminal emulator supports it then +this will allow you to map the key pairs listed above separately. || + +Nvim uses libtermkey to convert terminal escape sequences to key codes. +|terminfo| is used first, and CSI sequences not in |terminfo| (including +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 +Where `'Escape' [ 2 7 u` is an unambiguous "CSI u" sequence for the 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 : > + CSI 57414 ; 5 u +and can be used differently from 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 +If your terminal emulator responds with > + CSI ? 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 +If your terminal does not support "CSI u" then Nvim will instead enable the +"modifyOtherKeys" encoding by writing the sequence > + 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 +emulator could be in a bad state. If this happens, simply run "reset". + + *tui-colors* +Nvim uses 256 colours by default, ignoring |terminfo| for most terminal types, +including "linux" (whose virtual terminals have had 256-colour support since +4.8) and anything claiming to be "xterm". Also when $COLORTERM or $TERM +contain the string "256". + +Nvim similarly assumes that any terminal emulator that sets $COLORTERM to any +value, is capable of at least 16-colour operation. + + *true-color* *xterm-true-color* +Nvim emits true (24-bit) colours in the terminal, if 'termguicolors' is set. + +It uses the "setrgbf" and "setrgbb" |terminfo| extensions (proposed by Rüdiger +Sonderfeld in 2013). If your terminfo definition is missing them, then Nvim +will decide whether to add them to your terminfo definition, using the ISO +8613-6:1994/ITU T.416:1993 control sequences for setting RGB colours (but +modified to use semicolons instead of colons unless the terminal is known to +follow the standard). + +Another convention, pioneered in 2016 by tmux, is the "Tc" terminfo extension. +If terminfo has this flag, Nvim will add constructed "setrgbf" and "setrgbb" +capabilities as if they had been in the terminfo definition. + +If terminfo does not (yet) have this flag, Nvim will fall back to $TERM and +other environment variables. It will add constructed "setrgbf" and "setrgbb" +capabilities in the case of the "rxvt", "linux", "st", "tmux", and "iterm" +terminal types, or when Konsole, genuine Xterm, a libvte terminal emulator +version 0.36 or later, or a terminal emulator that sets the COLORTERM +environment variable to "truecolor" is detected. + + *xterm-resize* +Nvim can resize the terminal display on some terminals that implement an +extension pioneered by dtterm. |terminfo| does not have a flag for this +extension. So Nvim simply assumes that (all) "dtterm", "xterm", "teraterm", +"rxvt" terminal types, and Konsole, are capable of this. + + *tui-cursor-shape* +Nvim will adjust the shape of the cursor from a block to a line when in insert +mode (or as specified by the 'guicursor' option), on terminals that support +it. It uses the same |terminfo| extensions that were pioneered by tmux for +this: "Ss" and "Se". +Similarly, if you set the cursor highlight group with blend=100, Nvim hides +the cursor through the "cvvis" and "civis" extensions. + +If your terminfo definition is missing them, then Nvim will decide whether to +add them to your terminfo definition, by looking at $TERM and other +environment variables. For the "rxvt", "putty", "linux", "screen", +"teraterm", and "iterm" terminal types, or when Konsole, a libvte-based +terminal emulator, or genuine Xterm are detected, it will add constructed +"Ss" and "Se" capabilities. + + *tui-cursor-tmux* +Within tmux it may appear that Nvim is not changing the cursor, but in fact it +is tmux receiving instructions from Nvim to change the cursor and not knowing +what to do in turn. tmux must translate what it receives from Nvim into +whatever control sequence is appropriate for the host terminal. It shares +a common mechanism with Nvim, of using the "Ss" and "Se" capabilities from +terminfo (for the output terminal) if they are present. Unlike Nvim, if they +are not in terminfo you must add them by setting "terminal-overrides" in +~/.tmux.conf . + +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' +bash + set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007' +< +============================================================================== +Window size *window-size* + +[This is about the size of the whole window Vim is using, not a window that is +created with the ":split" command.] + +On Unix systems, three methods are tried to get the window size: + +- an ioctl call (TIOCGSIZE or TIOCGWINSZ, depends on your system) +- the environment variables "LINES" and "COLUMNS" +- from the |terminfo| entries "lines" and "columns" + +If everything fails a default size of 24 lines and 80 columns is assumed. If +a window-resize signal is received the size will be set again. If the window +size is wrong you can use the 'lines' and 'columns' options to set the +correct values. See |:mode|. + +============================================================================== +Slow and fast terminals *slow-fast-terminal* + *slow-terminal* + +If you have a slow terminal you may want to reset the 'showcmd' and 'ruler' +options. The command characters and cursor positions will not be shown in the +status line (which involves a lot of cursor motions and attribute changes for +every keypress or movement). If the terminal scrolls very slowly, set the +'scrolljump' to 5 or so. If the cursor is moved off the screen (e.g., with +"j") Vim will scroll 5 lines at a time. Another possibility is to reduce the +number of lines that Vim uses with the command "z{height}". + +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 +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 +cursors and selections that cross them. This may have a visible, but minor, +effect on some UIs. + +============================================================================== +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 ~ + yes end yes + yes end yes "CTRL-]" (2) + yes no change yes "*" (2) ** + yes start or extend (1) no ** + yes start or extend (1) no + yes if not active no put + yes if active no yank and put + yes start or extend yes + yes start or extend blockw. yes ** + yes no change yes "#" (2) ** + no no change no "CTRL-T" + yes extend no ** + yes extend no ** + +Insert or Replace Mode: +event position selection change action ~ + cursor window ~ + yes (cannot be active) yes + yes (cannot be active) yes "CTRL-O^]" (2) + yes (cannot be active) yes "CTRL-O*" (2) + yes start or extend (1) no like CTRL-O (1) + yes start or extend (1) no like CTRL-O (1) + no (cannot be active) no put register + yes start or extend yes like CTRL-O + yes start or extend blockw. yes + yes (cannot be active) yes "CTRL-O#" (2) + 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 ~ + yes start or extend (1) no + yes start or extend blockw. no ** + no popup menu no + +Insert or Replace Mode: +event position selection change action ~ + cursor window ~ + yes start or extend (1) no like CTRL-O (1) + yes start or extend blockw. no + no popup menu no + +(1) only if mouse pointer moved since press +(2) only if click is in same buffer + +Clicking the left mouse button causes the cursor to be positioned. If the +click is in another window that window is made the active window. When +editing the command-line the cursor can only be positioned on the +command-line. When in Insert mode Vim remains in Insert mode. If 'scrolloff' +is set, and the cursor is positioned within 'scrolloff' lines from the window +border, the text is scrolled. + +A selection can be started by pressing the left mouse button on the first +character, moving the mouse to the last character, then releasing the mouse +button. You will not always see the selection until you release the button, +only in some versions (GUI, Win32) will the dragging be shown immediately. +Note that you can make the text scroll by moving the mouse at least one +character in the first/last line in the window when 'scrolloff' is non-zero. + +In Normal, Visual and Select mode clicking the right mouse button causes the +Visual area to be extended. When 'mousemodel' is "popup", the left button has +to be used while keeping the shift key pressed. When clicking in a window +which is editing another buffer, the Visual or Select mode is stopped. + +In Normal, Visual and Select mode clicking the right mouse button with the alt +key pressed causes the Visual area to become blockwise. When 'mousemodel' is +"popup" the left button has to be used with the alt key. Note that this won't +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, 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>* +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 +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("") + +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 +until the button is released, at which point the selection is per character +again. + +For scrolling with the mouse see |scroll-mouse-wheel|. + +In Insert mode, when a selection is started, Vim goes into Normal mode +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". + + ** ** +Mouse clicks can be mapped. The codes for mouse clicks are: + code mouse button normal action ~ + left pressed set cursor position + left moved while pressed extend selection + left released set selection end + middle pressed paste text at cursor position + middle moved while pressed - + middle released - + right pressed extend selection + right moved while pressed extend selection + right released set selection end + X1 button pressed - *X1Mouse* + X1 moved while pressed - *X1Drag* + X1 button release - *X1Release* + X2 button pressed - *X2Mouse* + X2 moved while pressed - *X2Drag* + X2 button release - *X2Release* + +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 +Paste at the position of the middle mouse button click (otherwise the paste +would be done at the cursor position). >vim + + :noremap y +Immediately yank the selection, when using Visual mode. + +Note the use of ":noremap" instead of "map" to avoid a recursive mapping. +>vim + :map + :map +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 + :noremap + :noremap + :noremap + :noremap + :noremap + :noremap g + :noremap g + :noremap! + :noremap! + :noremap! + :noremap! + :noremap! + :noremap! +< + vim:tw=78:ts=8:ft=help:norl: -- cgit