diff options
Diffstat (limited to 'runtime/doc')
| -rw-r--r-- | runtime/doc/autocmd.txt | 220 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 1 |
2 files changed, 111 insertions, 110 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 45bead968d..8006a45899 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -317,6 +317,7 @@ Name triggered by ~ |CursorMoved| the cursor was moved in Normal mode |CursorMovedI| the cursor was moved in Insert mode +|WinClosed| after closing a window |WinNew| after creating a new window |WinEnter| after entering another window |WinLeave| before leaving a window @@ -396,17 +397,18 @@ BufFilePost After changing the name of the current buffer BufFilePre Before changing the name of the current buffer with the ":file" or ":saveas" command. *BufHidden* -BufHidden Just before a buffer becomes hidden. That is, - when there are no longer windows that show - the buffer, but the buffer is not unloaded or - deleted. Not used for ":qa" or ":q" when - exiting Vim. +BufHidden Before a buffer becomes hidden: when there are + no longer windows that show the buffer, but + the buffer is not unloaded or deleted. + + Not used for ":qa" or ":q" when exiting Vim. NOTE: current buffer "%" may be different from the buffer being unloaded "<afile>". *BufLeave* BufLeave Before leaving to another buffer. Also when leaving or closing the current window and the new current window is not for the same buffer. + Not used for ":qa" or ":q" when exiting Vim. *BufNew* BufNew Just after creating a new buffer. Also used @@ -422,16 +424,17 @@ BufNewFile When starting to edit a file that doesn't *BufRead* *BufReadPost* BufRead or BufReadPost When starting to edit a new buffer, after reading the file into the buffer, before - executing the modelines. See |BufWinEnter| - for when you need to do something after - processing the modelines. - This does NOT work for ":r file". Not used - when the file doesn't exist. Also used after - successfully recovering a file. - Also triggered for the filetypedetect group - when executing ":filetype detect" and when - writing an unnamed buffer in a way that the - buffer gets a name. + processing modelines. See |BufWinEnter| to do + something after processing modelines. + Also triggered: + - when writing an unnamed buffer such that the + buffer gets a name + - after successfully recovering a file + - for the "filetypedetect" group when + executing ":filetype detect" + Not triggered: + - for ":r file" + - if the file doesn't exist *BufReadCmd* BufReadCmd Before starting to edit a new buffer. Should read the file into the buffer. |Cmd-event| @@ -440,34 +443,33 @@ BufReadPre When starting to edit a new buffer, before reading the file into the buffer. Not used if the file doesn't exist. *BufUnload* -BufUnload Before unloading a buffer. This is when the - text in the buffer is going to be freed. This - may be after a BufWritePost and before a - BufDelete. Also used for all buffers that are - loaded when Vim is going to exit. +BufUnload Before unloading a buffer, when the text in + the buffer is going to be freed. + After BufWritePost. + Before BufDelete. + Triggers for all loaded buffers when Vim is + going to exit. NOTE: Current buffer "%" may be different from the buffer being unloaded "<afile>". - Do not change to another buffer or window! + Do not switch buffers or windows! Not triggered when exiting and v:dying is 2 or more. *BufWinEnter* BufWinEnter After a buffer is displayed in a window. This - can be when the buffer is loaded (after - processing the modelines) or when a hidden - buffer is displayed in a window (and is no - longer hidden). - Does not happen for |:split| without - arguments, since you keep editing the same - buffer, or ":split" with a file that's already - open in a window, because it re-uses an - existing buffer. But it does happen for a - ":split" with the name of the current buffer, - since it reloads that buffer. + may be when the buffer is loaded (after + processing modelines) or when a hidden buffer + is displayed (and is no longer hidden). + + Not triggered for |:split| without arguments, + since the buffer does not change, or :split + with a file already open in a window. + Triggered for ":split" with the name of the + current buffer, since it reloads that buffer. *BufWinLeave* BufWinLeave Before a buffer is removed from a window. Not when it's still visible in another window. - Also triggered when exiting. It's triggered - before BufUnload or BufHidden. + Also triggered when exiting. + Before BufUnload, BufHidden. NOTE: Current buffer "%" may be different from the buffer being unloaded "<afile>". Not triggered when exiting and v:dying is 2 or @@ -515,7 +517,7 @@ CmdUndefined When a user command is used but it isn't defined. Useful for defining a command only when it's used. The pattern is matched against the command name. Both <amatch> and - <afile> are set to the name of the command. + <afile> expand to the command name. NOTE: Autocompletion won't work until the command is defined. An alternative is to always define the user command and have it @@ -524,12 +526,12 @@ CmdUndefined When a user command is used but it isn't CmdlineChanged After a change was made to the text inside command line. Be careful not to mess up the command line, it may cause Vim to lock up. - <afile> is set to the |cmdline-char|. + <afile> expands to the |cmdline-char|. *CmdlineEnter* CmdlineEnter After entering the command-line (including non-interactive use of ":" in a mapping: use |<Cmd>| instead to avoid this). - <afile> is set to the |cmdline-char|. + <afile> expands to the |cmdline-char|. Sets these |v:event| keys: cmdlevel cmdtype @@ -537,26 +539,26 @@ CmdlineEnter After entering the command-line (including CmdlineLeave Before leaving the command-line (including non-interactive use of ":" in a mapping: use |<Cmd>| instead to avoid this). - <afile> is set to the |cmdline-char|. + <afile> expands to the |cmdline-char|. Sets these |v:event| keys: abort (mutable) cmdlevel cmdtype Note: `abort` can only be changed from false - to true. An autocmd cannot execute an already - aborted cmdline by changing it to false. + to true: cannot execute an already aborted + cmdline by changing it to false. *CmdwinEnter* CmdwinEnter After entering the command-line window. Useful for setting options specifically for this special type of window. - <afile> is set to a single character, + <afile> expands to a single character, indicating the type of command-line. |cmdwin-char| *CmdwinLeave* CmdwinLeave Before leaving the command-line window. Useful to clean up any global setting done with CmdwinEnter. - <afile> is set to a single character, + <afile> expands to a single character, indicating the type of command-line. |cmdwin-char| *ColorScheme* @@ -575,8 +577,7 @@ ColorSchemePre Before loading a color scheme. |:colorscheme| CompleteChanged *CompleteChanged* After each time the Insert mode completion menu changed. Not fired on popup menu hide, - use |CompleteDone| for that. Never triggered - recursively. + use |CompleteDone| for that. Sets these |v:event| keys: completed_item See |complete-items|. @@ -587,7 +588,8 @@ CompleteChanged *CompleteChanged* size total nr of items scrollbar TRUE if visible - It is not allowed to change the text |textlock|. + Non-recursive (event cannot trigger itself). + Cannot change the text. |textlock| The size and position of the popup are also available by calling |pum_getpos()|. @@ -596,8 +598,9 @@ CompleteChanged *CompleteChanged* CompleteDone After Insert mode completion is done. Either when something was completed or abandoning completion. |ins-completion| - The |v:completed_item| variable contains the - completed item. + |complete_info()| can be used, the info is + cleared after triggering CompleteDone. + |v:completed_item| gives the completed item. *CursorHold* CursorHold When the user doesn't press a key for the time @@ -627,9 +630,9 @@ CursorHold When the user doesn't press a key for the time :let &ro = &ro *CursorHoldI* -CursorHoldI Just like CursorHold, but in Insert mode. - Not triggered when waiting for another key, - e.g. after CTRL-V, and not when in CTRL-X mode +CursorHoldI Like CursorHold, but in Insert mode. Not + triggered when waiting for another key, e.g. + after CTRL-V, and not in CTRL-X mode |insert_expand|. *CursorMoved* @@ -640,7 +643,7 @@ CursorMoved After the cursor was moved in Normal or Visual Not triggered when there is typeahead or when an operator is pending. For an example see |match-parens|. - Note: Cannot be skipped with `:noautocmd`. + Note: Cannot be skipped with |:noautocmd|. Careful: This is triggered very often, don't do anything that the user does not expect or that is slow. @@ -658,11 +661,11 @@ DirChanged After the |current-directory| was changed. Sets these |v:event| keys: cwd: current working directory scope: "global", "tab", "window" - Recursion is ignored. + Non-recursive (event cannot trigger itself). *FileAppendCmd* FileAppendCmd Before appending to a file. Should do the appending to the file. Use the '[ and '] - marks for the range of lines.|Cmd-event| + marks for the range of lines. |Cmd-event| *FileAppendPost* FileAppendPost After appending to a file. *FileAppendPre* @@ -670,19 +673,18 @@ FileAppendPre Before appending to a file. Use the '[ and '] marks for the range of lines. *FileChangedRO* FileChangedRO Before making the first change to a read-only - file. Can be used to check-out the file from + file. Can be used to checkout the file from a source control system. Not triggered when the change was caused by an autocommand. - This event is triggered when making the first - change in a buffer or the first change after - 'readonly' was set, just before the change is - applied to the text. + Triggered when making the first change in + a buffer or the first change after 'readonly' + was set, just before the change is applied to + the text. WARNING: If the autocommand moves the cursor the effect of the change is undefined. *E788* - It is not allowed to change to another buffer - here. You can reload the buffer but not edit - another one. + Cannot switch buffers. You can reload the + buffer but not edit another one. *E881* If the number of lines changes saving for undo may fail and the change will be aborted. @@ -694,34 +696,28 @@ ExitPre When using `:quit`, `:wq` in a way it makes cancelled if there is a modified buffer that isn't automatically saved, use |VimLeavePre| for really exiting. + See also |QuitPre|, |WinClosed|. *FileChangedShell* FileChangedShell When Vim notices that the modification time of a file has changed since editing started. Also when the file attributes of the file change or when the size of the file changes. |timestamp| - Mostly triggered after executing a shell - command, but also with a |:checktime| command - or when gvim regains input focus. - This autocommand is triggered for each changed - file. It is not used when 'autoread' is set - and the buffer was not changed. If a - FileChangedShell autocommand is present the - warning message and prompt is not given. - The |v:fcs_reason| variable is set to indicate - what happened and |v:fcs_choice| can be used - to tell Vim what to do next. - NOTE: When this autocommand is executed, the - current buffer "%" may be different from the - buffer that was changed, which is in "<afile>". - NOTE: The commands must not change the current - buffer, jump to another buffer or delete a - buffer. *E246* *E811* - NOTE: This event never nests, to avoid an - endless loop. This means that while executing - commands for the FileChangedShell event no - other FileChangedShell event will be - triggered. + Triggered for each changed file, after: + - executing a shell command + - |:checktime| + - |FocusGained| + Not used when 'autoread' is set and the buffer + was not changed. If a FileChangedShell + autocommand exists the warning message and + prompt is not given. + |v:fcs_reason| indicates what happened. Set + |v:fcs_choice| to control what happens next. + NOTE: Current buffer "%" may be different from + the buffer that was changed "<afile>". + *E246* *E811* + Cannot switch, jump to or delete buffers. + Non-recursive (event cannot trigger itself). *FileChangedShellPost* FileChangedShellPost After handling a file that was changed outside of Vim. Can be used to update the statusline. @@ -738,10 +734,10 @@ FileReadPre Before reading a file with a ":read" command. *FileType* FileType When the 'filetype' option has been set. The pattern is matched against the filetype. - <afile> can be used for the name of the file - where this option was set, and <amatch> for - the new value of 'filetype'. Navigating to - another window or buffer is not allowed. + <afile> is the name of the file where this + option was set. <amatch> is the new value of + 'filetype'. + Cannot switch windows or buffers. See |filetypes|. *FileWriteCmd* FileWriteCmd Before writing to a file, when not writing the @@ -838,7 +834,7 @@ TextYankPost Just after a |yank| or |deleting| command, but not and |']| marks can be used to calculate the precise region of the operation. - Recursion is ignored. + Non-recursive (event cannot trigger itself). Cannot change the text. |textlock| *InsertEnter* InsertEnter Just before starting Insert mode. Also for @@ -905,8 +901,8 @@ OptionSet After setting an option (except during always use |:noautocmd| to prevent triggering OptionSet. - Recursion is ignored, thus |:set| in the - autocommand does not trigger OptionSet again. + Non-recursive: |:set| in the autocommand does + not trigger OptionSet again. *QuickFixCmdPre* QuickFixCmdPre Before a quickfix command is run (|:make|, @@ -938,7 +934,7 @@ QuitPre When using `:quit`, `:wq` or `:qall`, before or quits Vim. Can be used to close any non-essential window if the current window is the last ordinary window. - Also see |ExitPre|. + See also |ExitPre|, ||WinClosed|. *RemoteReply* RemoteReply When a reply from a Vim that functions as server was received |server2client()|. The @@ -1014,33 +1010,32 @@ SwapExists Detected an existing swap file when starting When set to an empty string the user will be asked, as if there was no SwapExists autocmd. *E812* - It is not allowed to change to another buffer, - change a buffer name or change directory - here. + Cannot change to another buffer, change + the buffer name or change directory. *Syntax* Syntax When the 'syntax' option has been set. The pattern is matched against the syntax name. - <afile> can be used for the name of the file - where this option was set, and <amatch> for - the new value of 'syntax'. + <afile> expands to the name of the file where + this option was set. <amatch> expands to the + new value of 'syntax'. See |:syn-on|. *TabEnter* TabEnter Just after entering a tab page. |tab-page| - After triggering the WinEnter and before - triggering the BufEnter event. + After WinEnter. + Before BufEnter. *TabLeave* TabLeave Just before leaving a tab page. |tab-page| - A WinLeave event will have been triggered - first. + After WinLeave. *TabNew* TabNew When creating a new tab page. |tab-page| - After WinEnter and before TabEnter. + After WinEnter. + Before TabEnter. *TabNewEntered* TabNewEntered After entering a new tab page. |tab-page| After BufEnter. *TabClosed* -TabClosed After closing a tab page. <afile> can be used - for the tab page number. +TabClosed After closing a tab page. <afile> expands to + the tab page number. *TermOpen* TermOpen When a |terminal| job is starting. Can be used to configure the terminal buffer. @@ -1056,10 +1051,9 @@ TermClose When a |terminal| job ends. TermResponse After the response to t_RV is received from the terminal. The value of |v:termresponse| can be used to do things depending on the - terminal version. Note that this event may be - triggered halfway through another event - (especially if file I/O, a shell command, or - anything else that takes time is involved). + terminal version. May be triggered halfway + through another event (file I/O, a shell + command, or anything else that takes time). *TextChanged* TextChanged After a change was made to the text in the current buffer in Normal mode. That is after @@ -1129,6 +1123,12 @@ VimResized After the Vim window was resized, thus 'lines' VimResume After Nvim resumes from |suspend| state. *VimSuspend* VimSuspend Before Nvim enters |suspend| state. + *WinClosed* +WinClosed After closing a window. <afile> expands to the + |window-ID|. + After WinLeave. + Non-recursive (event cannot trigger itself). + See also |ExitPre|, |QuitPre|. *WinEnter* WinEnter After entering another window. Not done for the first window, when Vim has just started. @@ -1146,11 +1146,11 @@ WinLeave Before leaving a window. If the window to be executes the BufLeave autocommands before the WinLeave autocommands (but not for ":new"). Not used for ":qa" or ":q" when exiting Vim. - + After WinClosed. *WinNew* WinNew When a new window was created. Not done for the first window, when Vim has just started. - Before a WinEnter event. + Before WinEnter. ============================================================================== 6. Patterns *autocmd-pattern* *{pat}* diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 2bb798a6e6..5835c7f314 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -159,6 +159,7 @@ Events: |UILeave| |VimResume| |VimSuspend| + |WinClosed| Functions: |dictwatcheradd()| notifies a callback whenever a |Dict| is modified |