diff options
Diffstat (limited to 'runtime/doc')
| -rw-r--r-- | runtime/doc/api.txt | 156 | ||||
| -rw-r--r-- | runtime/doc/autocmd.txt | 41 | ||||
| -rw-r--r-- | runtime/doc/change.txt | 11 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/motion.txt | 5 | ||||
| -rw-r--r-- | runtime/doc/nvim_terminal_emulator.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/syntax.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/usr_40.txt | 10 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/windows.txt | 8 |
10 files changed, 211 insertions, 29 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c9d526d9aa..7172091ceb 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -232,7 +232,44 @@ An example of calling the api from vimscript: > " later call nvim_buf_clear_namespace(0, src, 0, -1) + + +============================================================================== +Floating windows *api-floatwin* + +Nvim supports floating windows, windows that are displayed on top of ordinary +windows. This is useful to implement simple widgets, such as tooltips +displaying information next to cursor text. Floating windows are fully +functional buffer windows and support user editing. They support the standard +|api-window| calls and almost all window options (with some exceptions such as +'statusline' is not supported currently). + +Floating windows are created either by |nvim_open_win()| to open a new window, +or |nvim_win_config()| to reconfigure a normal window into a float. Currently +the position can either be grid coordinates relative the top-left of some +window, or a position relative to the current window cursor. The parameters +for positioning are described in detail at |nvim_open_win()| help. + +|nvim_open_win()| assumes an existing buffer to display in the window. To create +a scratch buffer for the float, |nvim_create_buffer()| can be used. The text in +the buffer can be highlighted using standard functionality, such as syntax +highlighting, or |api-highlights|. + +By default, floats will use |hl-NormalFloat| as normal highlight, which +links to |hl-Pmenu| in the builtin color scheme. The 'winhighlight' option can +be used to override it. Currently, floating windows don't support any visual +decorations like a border or additional widgets like scrollbar. + +Here is an example for creating a float with scratch buffer: > + + let buf = nvim_create_buf(v:false, v:true) + call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"]) + let opts = {'relative': 'cursor', 'col':0, 'row':1, 'anchor': 'NW'} + let win = nvim_open_win(buf, 0, 10, 2, opts) + " optional: change highlight, otherwise Pmenu is used + call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight') > +To close the float, |nvim_win_close()| can be used. ============================================================================== Global Functions *api-global* @@ -576,6 +613,94 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Parameters: ~ {window} Window handle +nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* + Creates a new, empty, unnamed buffer. + + Parameters: ~ + {listed} Controls 'buflisted' + {scratch} Creates a "throwaway" |scratch-buffer| for + temporary work (always 'nomodified') + + Return: ~ + Buffer handle, or 0 on error + + *nvim_open_win()* +nvim_open_win({buffer}, {enter}, {width}, {height}, {options}) + Open a new window. + + Currently this is used to open floating and external windows. + Floats are windows that are drawn above the split layout, at + some anchor position in some other window. Floats can be draw + internally or by external GUI with the |ui-multigrid| + extension. External windows are only supported with multigrid + GUIs, and are displayed as separate top-level windows. + + For a general overview of floats, see |api-floatwin|. + + Exactly one of `external` and `relative` must be specified. + + Parameters: ~ + {buffer} handle of buffer to be displayed in the window + {enter} whether the window should be entered (made the + current window) + {width} width of window (in character cells) + {height} height of window (in character cells) + {options} dict of options for configuring window + positioning accepts the following keys: + + `relative`: If set, the window becomes a + floating window. The window will be placed with + row,col coordinates relative one of the + following: + "editor" the global editor grid + "win" a window. Use 'win' option below to + specify window id, or current window will + be used by default. + "cursor" the cursor position in current window. + + `anchor`: the corner of the float that the row,col + position defines + "NW" north-west (default) + "NE" north-east + "SW" south-west + "SE" south-east + + `focusable`: Whether window can be focused by wincmds and + mouse events. Defaults to true. Even if set to false, + the window can still be entered using + |nvim_set_current_win()| API call. + + `row`: row position. Screen cell height are used as unit. + Can be floating point. + + `col`: column position. Screen cell width is used as + unit. Can be floating point. + + `win`: when using relative='win', window id of the window + where the position is defined. + + `external`: GUI should display the window as an external + top-level window. Currently accepts no other + positioning options together with this. + + With editor positioning row=0, col=0 refers to the top-left + corner of the screen-grid and row=Lines-1, Columns-1 refers to + the bottom-right corner. Floating point values are allowed, + but the builtin implementation (used by TUI and GUIs without + multigrid support) will always round down to nearest integer. + + Out-of-bounds values, and configurations that make the float + not fit inside the main editor, are allowed. The builtin + implementation will truncate values so floats are completely + within the main screen grid. External GUIs could let floats + hover outside of the main window like a tooltip, but this + should not be used to specify arbitrary WM screen positions. + + Parameters: ~ + + Return: ~ + the window handle or 0 when error + nvim_list_tabpages() *nvim_list_tabpages()* Gets the current list of tabpage handles. @@ -1436,6 +1561,37 @@ nvim_win_is_valid({window}) *nvim_win_is_valid()* Return: ~ true if the window is valid, false otherwise + *nvim_win_config()* +nvim_win_config({window}, {width}, {height}, {options}) + Configure window position. Currently this is only used to + configure floating and external windows (including changing a + split window to these types). + + See documentation at |nvim_open_win()|, for the meaning of + parameters. Pass in -1 for 'witdh' and 'height' to keep + exiting size. + + When reconfiguring a floating window, absent option keys will + not be changed. The following restriction apply: `row`, `col` + and `relative` must be reconfigured together. Only changing a + subset of these is an error. + +nvim_win_close({window}, {force}) *nvim_win_close()* + Close a window. + + This is equivalent to |:close| with count except that it takes + a window id. + + Parameters: ~ + {window} Window handle + {force} Behave like `:close!` The last window of a + buffer with unwritten changes can be closed. The + buffer will become hidden, even if 'hidden' is + not set. + + Return: ~ + Window number + ============================================================================== Tabpage Functions *api-tabpage* diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 89d9e45e0d..ca10d44467 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -40,15 +40,18 @@ effects. Be careful not to destroy your text. 2. Defining autocommands *autocmd-define* *:au* *:autocmd* -:au[tocmd] [group] {event} {pat} [nested] {cmd} +:au[tocmd] [group] {event} {pat} [++once] [++nested] {cmd} Add {cmd} to the list of commands that Vim will execute automatically on {event} for a file matching {pat} |autocmd-patterns|. Note: A quote character is seen as argument to the :autocmd and won't start a comment. - Vim always adds the {cmd} after existing autocommands, - so that the autocommands execute in the order in which - they were given. See |autocmd-nested| for [nested]. + Nvim always adds {cmd} after existing autocommands so + they execute in the order in which they were defined. + See |autocmd-nested| for [++nested]. + *autocmd-once* + If [++once] is supplied the command is executed once, + then removed ("one shot"). The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand. See |autocmd-buflocal|. @@ -116,10 +119,11 @@ prompt. When one command outputs two messages this can happen anyway. ============================================================================== 3. Removing autocommands *autocmd-remove* -:au[tocmd]! [group] {event} {pat} [nested] {cmd} +:au[tocmd]! [group] {event} {pat} [++once] [++nested] {cmd} Remove all autocommands associated with {event} and - {pat}, and add the command {cmd}. See - |autocmd-nested| for [nested]. + {pat}, and add the command {cmd}. + See |autocmd-once| for [++once]. + See |autocmd-nested| for [++nested]. :au[tocmd]! [group] {event} {pat} Remove all autocommands associated with {event} and @@ -806,20 +810,25 @@ InsertCharPre When a character is typed in Insert mode, a different character. When |v:char| is set to more than one character this text is inserted literally. - It is not allowed to change the text |textlock|. - The event is not triggered when 'paste' is - set. + + Cannot change the text. |textlock| + Not triggered when 'paste' is set. *TextYankPost* TextYankPost Just after a |yank| or |deleting| command, but not if the black hole register |quote_| is used nor for |setreg()|. Pattern must be *. Sets these |v:event| keys: + inclusive operator regcontents regname regtype + The `inclusive` flag combined with the |'[| + and |']| marks can be used to calculate the + precise region of the operation. + Recursion is ignored. - It is not allowed to change the text |textlock|. + Cannot change the text. |textlock| *InsertEnter* InsertEnter Just before starting Insert mode. Also for Replace mode and Virtual Replace mode. The @@ -985,7 +994,6 @@ SwapExists Detected an existing swap file when starting It is not allowed to change to another buffer, change a buffer name or change directory here. - {only available with the +eval feature} *Syntax* Syntax When the 'syntax' option has been set. The pattern is matched against the syntax name. @@ -1340,8 +1348,7 @@ option will not cause any commands to be executed. another extension. Example: > :au BufEnter *.cpp so ~/.config/nvim/init_cpp.vim :au BufEnter *.cpp doau BufEnter x.c -< Be careful to avoid endless loops. See - |autocmd-nested|. +< Be careful to avoid endless loops. |autocmd-nested| When the [group] argument is not given, Vim executes the autocommands for all groups. When the [group] @@ -1456,9 +1463,9 @@ instead of ":q!". *autocmd-nested* *E218* By default, autocommands do not nest. If you use ":e" or ":w" in an autocommand, Vim does not execute the BufRead and BufWrite autocommands for -those commands. If you do want this, use the "nested" flag for those commands -in which you want nesting. For example: > - :autocmd FileChangedShell *.c nested e! +those commands. If you do want this, use the "++nested" flag for those +commands in which you want nesting. For example: > + :autocmd FileChangedShell *.c ++nested e! The nesting is limited to 10 levels to get out of recursive loops. It's possible to use the ":au" command in an autocommand. This can be a diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index c73b460767..1761616651 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -1635,6 +1635,17 @@ j Where it makes sense, remove a comment leader when joining lines. For // in the list ~ Becomes: int i; // the index in the list ~ +p Don't break lines at single spaces that follow periods. This is + intended to complement 'joinspaces' and |cpo-J|, for prose with + sentences separated by two spaces. For example, with 'textwidth' set + to 28: > + Surely you're joking, Mr. Feynman! +< Becomes: > + Surely you're joking, + Mr. Feynman! +< Instead of: > + Surely you're joking, Mr. + Feynman! With 't' and 'c' you can specify when Vim performs auto-wrapping: diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 2610b2683e..020427c66f 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1539,6 +1539,7 @@ v:event Dictionary of event data for the current |autocommand|. Valid cmdlevel Level of cmdline. cmdtype Type of cmdline, |cmdline-char|. cwd Current working directory. + inclusive Motion is |inclusive|, else exclusive. scope Event-specific scope name. operator Current |operator|. Also set for Ex commands (unlike |v:operator|). For @@ -4517,11 +4518,13 @@ getwininfo([{winid}]) *getwininfo()* tab pages is returned. Each List item is a Dictionary with the following entries: + botline last displayed buffer line bufnr number of buffer in the window height window height (excluding winbar) loclist 1 if showing a location list quickfix 1 if quickfix or location list window tabnr tab page number + topline first displayed buffer line variables a reference to the dictionary with window-local variables width window width diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index 84867318a4..d5a123e3ea 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -66,10 +66,11 @@ and end position. Generally, motions that move between lines affect lines characterwise). However, there are some exceptions. *exclusive* *inclusive* -A character motion is either inclusive or exclusive. When inclusive, the +Character motion is either inclusive or exclusive. When inclusive, the start and end position of the motion are included in the operation. When exclusive, the last character towards the end of the buffer is not included. -Linewise motions always include the start and end position. +Linewise motions always include the start and end position. Plugins can +check the v:event.inclusive flag of the |TextYankPost| event. Which motions are linewise, inclusive or exclusive is mentioned with the command. There are however, two general exceptions: diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index cdcb61404f..af94c60629 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -35,7 +35,7 @@ There are 3 ways to create a terminal buffer: < Note: The "term://" pattern is handled by a BufReadCmd handler, so the |autocmd-nested| modifier is required to use it in an autocmd. > - autocmd VimEnter * nested split term://sh + 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 diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index 684830b78d..b60a952def 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -4953,6 +4953,8 @@ NonText '@' at the end of the window, characters from 'showbreak' fit at the end of the line). See also |hl-EndOfBuffer|. *hl-Normal* Normal normal text + *hl-NormalFloat* +NormalFloat Normal text in floating windows. *hl-NormalNC* NormalNC normal text in non-current windows *hl-Pmenu* diff --git a/runtime/doc/usr_40.txt b/runtime/doc/usr_40.txt index e5d55fb857..9a1fe50f31 100644 --- a/runtime/doc/usr_40.txt +++ b/runtime/doc/usr_40.txt @@ -453,15 +453,15 @@ matching BufWritePre autocommands and executes them, and then it performs the ":write". The general form of the :autocmd command is as follows: > - :autocmd [group] {events} {file_pattern} [nested] {command} + :autocmd [group] {events} {file_pattern} [++nested] {command} The [group] name is optional. It is used in managing and calling the commands (more on this later). The {events} parameter is a list of events (comma separated) that trigger the command. {file_pattern} is a filename, usually with wildcards. For example, using "*.txt" makes the autocommand be used for all files whose name end in ".txt". -The optional [nested] flag allows for nesting of autocommands (see below), and -finally, {command} is the command to be executed. +The optional [++nested] flag allows for nesting of autocommands (see below), +and finally, {command} is the command to be executed. EVENTS @@ -576,9 +576,9 @@ NESTING Generally, commands executed as the result of an autocommand event will not trigger any new events. If you read a file in response to a FileChangedShell event, it will not trigger the autocommands that would set the syntax, for -example. To make the events triggered, add the "nested" argument: > +example. To make the events triggered, add the "++nested" flag: > - :autocmd FileChangedShell * nested edit + :autocmd FileChangedShell * ++nested edit EXECUTING AUTOCOMMANDS diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 25517e506b..55c3be9a57 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -133,6 +133,7 @@ Command-line highlighting: removed in the future). Commands: + |:autocmd| accepts the `++once` flag |:checkhealth| |:cquit| can use [count] to set the exit code |:drop| is always available @@ -160,6 +161,7 @@ Functions: Highlight groups: |expr-highlight| highlight groups (prefixed with "Nvim") + |hl-NormalFloat| highlights floating window |hl-NormalNC| highlights non-current windows |hl-MsgSeparator| highlights separator for scrolled messages |hl-QuickFixLine| diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 6e1ad0f1f4..63ffd91bfc 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -880,15 +880,15 @@ CTRL-W g } *CTRL-W_g}* cursor. This is less clever than using |:ptag|, but you don't need a tags file and it will also find matches in system include files. Example: > - :au! CursorHold *.[ch] nested exe "silent! psearch " . expand("<cword>") + :au! CursorHold *.[ch] ++nested exe "silent! psearch " . expand("<cword>") < Warning: This can be slow. Example *CursorHold-example* > - :au! CursorHold *.[ch] nested exe "silent! ptag " . expand("<cword>") + :au! CursorHold *.[ch] ++nested exe "silent! ptag " . expand("<cword>") This will cause a ":ptag" to be executed for the keyword under the cursor, -when the cursor hasn't moved for the time set with 'updatetime'. The "nested" +when the cursor hasn't moved for the time set with 'updatetime'. "++nested" makes other autocommands be executed, so that syntax highlighting works in the preview window. The "silent!" avoids an error message when the tag could not be found. Also see |CursorHold|. To disable this again: > @@ -898,7 +898,7 @@ be found. Also see |CursorHold|. To disable this again: > A nice addition is to highlight the found tag, avoid the ":ptag" when there is no word under the cursor, and a few other things: > - :au! CursorHold *.[ch] nested call PreviewWord() + :au! CursorHold *.[ch] ++nested call PreviewWord() :func PreviewWord() : if &previewwindow " don't do this in the preview window : return |