mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-08-29 02:21:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: misc, window #39720

Browse Source 
- formalize `window-number` similar to `tabpage-number`.
- reference it from docs.
This commit is contained in:
Justin M. Keyes
2026-05-10 13:00:52 -04:00
committed by GitHub
parent eb79cf5aee
commit 1f4ad7808e
8 changed files with 176 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
runtime/doc/news.txt
View File

@@ -185,8 +185,7 @@ LUA
OPTIONS
• 'ttyfast' can be disabled during startup by setting the environment variable
`NVIM_NOTTYFAST` to disable automatic background detection.
• 'ttyfast' can be disabled during startup by setting |$NVIM_NOTTYFAST|.
• 'scrolloffpad' allows vertically centering cursor at the end of file.
• 'shortmess' flag |shm-u| silences undo/redo messages.
• 'winpinned' prevents window from closing unless specifically targeted.

2
runtime/doc/options.txt
View File

@@ -6458,7 +6458,7 @@ A jump table for the options with a short description can be found at |Q_op|.
added without modifying code that reacts on mouse clicks on
this label.
Use |getmousepos()|.winid in the specified function to get the
corresponding window id of the clicked item.
corresponding |window-ID| of the clicked item.
< - Where to truncate line if too long. Default is at the start.
No width fields allowed.
= - Separation point between alignment sections. Each section will

112
runtime/doc/vimfn.txt
View File

@@ -163,8 +163,8 @@ argc([{winid}]) *argc()*
If {winid} is not supplied, the argument list of the current
window is used.
If {winid} is -1, the global argument list is used.
Otherwise {winid} specifies the window of which the argument
list is used: either the window number or the window ID.
Otherwise {winid} (a |window-number| or |window-ID|) specifies
the window of which the argument list is used.
Returns -1 if the {winid} argument is invalid.
Parameters: ~
@@ -190,7 +190,7 @@ arglistid([{winnr} [, {tabnr}]]) *arglistid()*
With {winnr} only use this window in the current tabpage.
With {winnr} and {tabnr} use the window in the specified tab
page.
{winnr} can be the window number or the |window-ID|.
{winnr} is a |window-number| or |window-ID|.
Parameters: ~
• {winnr} (`integer?`)
@@ -211,7 +211,7 @@ argv([{nr} [, {winid}]]) *argv()*
< Without the {nr} argument, or when {nr} is -1, a |List| with
the whole |arglist| is returned.
The {winid} argument specifies the window ID, see |argc()|.
The {winid} argument is a |window-ID|, see |argc()|.
For the Vim command line arguments see |v:argv|.
Returns an empty string if {nr}th argument is not present in
@@ -782,7 +782,7 @@ bufwinnr({buf}) *bufwinnr()*
resolving {buf}; only the current tabpage is checked and
no-match semantics differ.
Like |bufwinid()| but return the window number instead of the
Like |bufwinid()| but returns a |window-number| instead of a
|window-ID|.
If buffer {buf} doesn't exist or there is no such window, -1
is returned. Example: >vim
@@ -1148,8 +1148,8 @@ cindent({lnum}) *cindent()*
clearmatches([{win}]) *clearmatches()*
Clears all matches previously defined for the current window
by |matchadd()| and the |:match| commands.
If {win} is specified, use the window with this number or
window ID instead of the current window.
If {win} is specified, use this |window-number| or |window-ID|
instead of the current window.
Parameters: ~
• {win} (`integer?`)
@@ -3690,10 +3690,10 @@ getcurpos([{winid}]) *getcurpos()*
the cursor is returned in "col". To get the character
position, use |getcursorcharpos()|.
The optional {winid} argument can specify the window. It can
be the window number or the |window-ID|. The last known
cursor position is returned, this may be invalid for the
current value of the buffer if it is not the current window.
The optional {winid} (|window-number| or |window-ID|) specifies
the window. The last known cursor position is returned, this
may be invalid for the current value of the buffer if it is not
the current window.
If {winid} is invalid a list with zeroes is returned.
This can be used to save and restore the cursor position: >vim
@@ -3738,7 +3738,7 @@ getcwd([{winnr} [, {tabnr}]]) *getcwd()*
getcwd(0)
getcwd(0, 0)
< If {winnr} is -1 it is ignored, only the tab is resolved.
{winnr} can be the window number or the |window-ID|.
{winnr} is a |window-number| or |window-ID|.
If both {winnr} and {tabnr} are -1 the global working
directory is returned.
Note: When {tabnr} is -1 Vim returns an empty string to
@@ -3878,8 +3878,8 @@ getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
Returns the |jumplist| for the specified window.
Without arguments use the current window.
With {winnr} only use this window in the current tabpage.
{winnr} can also be a |window-ID|.
With {winnr} (|window-number| or |window-ID|) only use this
window in the current tabpage.
With {winnr} and {tabnr} use the window in the specified tab
page. If {winnr} or {tabnr} is invalid, an empty list is
returned.
@@ -3938,12 +3938,12 @@ getline({lnum} [, {end}]) *getline()*
getloclist({nr} [, {what}]) *getloclist()*
Returns a |List| with all the entries in the location list for
window {nr}. {nr} can be the window number or the |window-ID|.
window {nr} (|window-number| or |window-ID|).
When {nr} is zero the current window is used.
For a location list window, the displayed location list is
returned. For an invalid window number {nr}, an empty list is
returned. Otherwise, same as |getqflist()|.
returned. For an invalid {nr}, an empty list is returned.
Otherwise, same as |getqflist()|.
If the optional {what} dictionary argument is supplied, then
returns the items listed in {what} as a dictionary. Refer to
@@ -4006,9 +4006,9 @@ getmatches([{win}]) *getmatches()*
|getmatches()| is useful in combination with |setmatches()|,
as |setmatches()| can restore a list of matches saved by
|getmatches()|.
If {win} is specified, use the window with this number or
window ID instead of the current window. If {win} is invalid,
an empty list is returned.
If {win} is specified, use this |window-number| or |window-ID|
instead of the current window. If {win} is invalid, an empty
list is returned.
Example: >vim
echo getmatches()
< >
@@ -4566,7 +4566,7 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Note that {varname} must be the name without "w:".
Tabs are numbered starting with one. For the current tabpage
use |getwinvar()|.
{winnr} can be the window number or the |window-ID|.
{winnr} is a |window-number| or |window-ID|.
When {winnr} is zero the current window is used.
This also works for a global option, buffer-local option and
window-local option, but it doesn't work for a global variable
@@ -4591,8 +4591,8 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
(`any`)
gettagstack([{winnr}]) *gettagstack()*
Returns the tag stack of window {winnr} as a Dict.
{winnr} can be the window number or the |window-ID|.
Returns the tag stack of window {winnr} (|window-number| or
|window-ID|) as a Dict.
When {winnr} is not specified, the current window is used.
When window {winnr} doesn't exist, an empty Dict is returned.
@@ -4674,7 +4674,7 @@ getwininfo([{winid}]) *getwininfo()*
wincol leftmost screen column of the window;
"col" from |win_screenpos()|
winid |window-ID|
winnr window number
winnr |window-number|
winrow topmost screen line of the window;
"row" from |win_screenpos()|
@@ -4964,7 +4964,7 @@ haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
echo haslocaldir(0, 0)
< With {winnr} use that window in the current tabpage.
With {winnr} and {tabnr} use the window in that tabpage.
{winnr} can be the window number or the |window-ID|.
{winnr} is a |window-number| or |window-ID|.
If {winnr} is -1 it is ignored, only the tab is resolved.
Throw error if the arguments are invalid. |E5000| |E5001| |E5002|
@@ -6604,8 +6604,8 @@ matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
conceal Special character to show instead of the
match (only for |hl-Conceal| highlighted
matches, see |:syn-cchar|)
window Instead of the current window use the
window with this number or window ID.
window Use this |window-number| or |window-ID| instead
of the current window.
The number of matches is not limited, as it is the case with
the |:match| commands.
@@ -6756,8 +6756,7 @@ matchdelete({id} [, {win}]) *matchdelete()* *E802* *E
or one of the |:match| commands. Returns 0 if successful,
otherwise -1. See example for |matchadd()|. All matches can
be deleted in one operation by |clearmatches()|.
If {win} is specified, use the window with this number or
window ID instead of the current window.
{win} (if given) is a |window-number| or |window-ID|.
Parameters: ~
• {id} (`integer`)
@@ -9504,12 +9503,12 @@ setline({lnum}, {text}) *setline()*
(`any`)
setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
Create or replace or add to the location list for window {nr}.
{nr} can be the window number or the |window-ID|.
Create or replace or add to the location list for window {nr}
(|window-number| or |window-ID|).
When {nr} is zero the current window is used.
For a location list window, the displayed location list is
modified. For an invalid window number {nr}, -1 is returned.
modified. For an invalid {nr}, -1 is returned.
Otherwise, same as |setqflist()|.
Also see |location-list|.
@@ -9533,8 +9532,7 @@ setmatches({list} [, {win}]) *setmatches()*
current window. Returns 0 if successful, otherwise -1. All
current matches are cleared before the list is restored. See
example for |getmatches()|.
If {win} is specified, use the window with this number or
window ID instead of the current window.
{win} (if given) is a |window-number| or |window-ID|.
Parameters: ~
• {list} (`vim.fn.getmatches.ret.item[]`)
@@ -9824,7 +9822,7 @@ settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
{val}.
Tabs are numbered starting with one. For the current tabpage
use |setwinvar()|.
{winnr} can be the window number or the |window-ID|.
{winnr} is a |window-number| or |window-ID|.
When {winnr} is zero the current window is used.
This also works for a global or local buffer option, but it
doesn't work for a global or local buffer variable.
@@ -9845,8 +9843,8 @@ settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
(`any`)
settagstack({nr}, {dict} [, {action}]) *settagstack()*
Modify the tag stack of the window {nr} using {dict}.
{nr} can be the window number or the |window-ID|.
Modify the tag stack of the window {nr} (|window-number| or
|window-ID|) using {dict}.
For a list of supported items in {dict}, refer to
|gettagstack()|. "curidx" takes effect before changing the tag
@@ -12374,8 +12372,8 @@ virtcol2col({winid}, {lnum}, {col}) *virtcol2col()*
For a multi-byte character, the column number of the first
byte in the character is returned.
The {winid} argument can be the window number or the
|window-ID|. If this is zero, then the current window is used.
{winid} is a |window-number| or |window-ID|. If zero, the
current window is used.
Returns -1 if the window {winid} doesn't exist or the buffer
line {lnum} or virtual column {col} is invalid.
@@ -12521,10 +12519,9 @@ win_getid([{win} [, {tab}]]) *win_getid()*
Get the |window-ID| for the specified window.
When {win} is missing use the current window.
With {win} this is the window number. The top window has
number 1.
Without {tab} use the current tab, otherwise the tab with
number {tab}. The first tab has number one.
With {win} this is the |window-number|.
Without {tab} use the current tab, otherwise the
|tabpage-number| given by {tab}.
Return zero if the window cannot be found.
Parameters: ~
@@ -12547,8 +12544,8 @@ win_gettype([{nr}]) *win_gettype()*
"unknown" window {nr} not found
When {nr} is omitted return the type of the current window.
When {nr} is given return the type of this window by number or
|window-ID|.
When {nr} is given (|window-number| or |window-ID|) return the
type of that window.
Also see the 'buftype' option.
@@ -12562,8 +12559,7 @@ win_gotoid({expr}) *win_gotoid()*
Lua: Prefer |nvim_set_current_win()|; invalid IDs error
instead of returning FALSE.
Go to window with ID {expr}. This may also change the current
tabpage.
Go to |window-ID| {expr}. May change the current tabpage.
Return TRUE if successful, FALSE if the window cannot be
found.
@@ -12578,8 +12574,8 @@ win_id2tabwin({expr}) *win_id2tabwin()*
|nvim_win_get_number()| for valid windows; invalid IDs error
instead of returning `[0, 0]`.
Return a list with the tab number and window number of window
with ID {expr}: [tabnr, winnr].
Return [tabnr, winnr] for window with |window-ID| {expr}, where
tabnr is the |tabpage-number| and winnr is the |window-number|.
Return [0, 0] if the window cannot be found.
Parameters: ~
@@ -12592,7 +12588,7 @@ win_id2win({expr}) *win_id2win()*
Lua: Prefer |nvim_win_get_number()| for valid windows; windows
outside the current tabpage and invalid IDs differ.
Return the window number of window with ID {expr}.
Return the |window-number| of for the given |window-ID| {expr}.
Return 0 if the window cannot be found in the current tabpage.
Parameters: ~
@@ -12604,7 +12600,7 @@ win_id2win({expr}) *win_id2win()*
win_move_separator({nr}, {offset}) *win_move_separator()*
Move window {nr}'s vertical separator (i.e., the right border)
by {offset} columns, as if being dragged by the mouse. {nr}
can be a window number or |window-ID|. A positive {offset}
is a |window-number| or |window-ID|. A positive {offset}
moves right and a negative {offset} moves left. Moving a
window's vertical separator will change the width of the
window and the width of other windows adjacent to the vertical
@@ -12625,8 +12621,8 @@ win_move_separator({nr}, {offset}) *win_move_separator()*
win_move_statusline({nr}, {offset}) *win_move_statusline()*
Move window {nr}'s status line (i.e., the bottom border) by
{offset} rows, as if being dragged by the mouse. {nr} can be
a window number or |window-ID|. A positive {offset} moves
{offset} rows, as if being dragged by the mouse. {nr} is a
|window-number| or |window-ID|. A positive {offset} moves
down and a negative {offset} moves up. Moving a window's
status line will change the height of the window and the
height of other windows adjacent to the status line. The
@@ -12649,8 +12645,8 @@ win_screenpos({nr}) *win_screenpos()*
Return the screen position of window {nr} as a list with two
numbers: [row, col]. The first window always has position
[1, 1], unless there is a tabline, then it is [2, 1].
{nr} can be the window number or the |window-ID|. Use zero
for the current window.
{nr} is a |window-number| or |window-ID|. Use zero for the
current window.
Returns [0, 0] if the window cannot be found.
Parameters: ~
@@ -12665,7 +12661,7 @@ win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
Unlike commands such as |:split|, no new windows are created
(the |window-ID| of window {nr} is unchanged after the move).
Both {nr} and {target} can be window numbers or |window-ID|s.
Both {nr} and {target} are a |window-number| or |window-ID|.
Both must be in the current tabpage.
Returns zero for success, non-zero for failure.
@@ -12690,8 +12686,8 @@ win_splitmove({nr}, {target} [, {options}]) *win_splitmove()*
winbufnr({nr}) *winbufnr()*
Lua: Prefer |nvim_win_get_buf()|.
Returns the buffer number associated with window {nr}.
{nr} can be the window number or the |window-ID|.
Returns the buffer number associated with window {nr}
(|window-number| or |window-ID|).
When {nr} is zero, the number of the buffer in the current
window is returned.
When window {nr} doesn't exist, -1 is returned.

19
runtime/doc/windows.txt
View File

@@ -78,15 +78,16 @@ Windows (especially floating windows) can have many other |api-win_config|
properties such as "hide" and "fixed" which also affect behavior.
*window-ID* *winid* *windowid*
Each window has a unique identifier called the window ID. This identifier
will not change within a Vim session. The |win_getid()| and |win_id2tabwin()|
functions can be used to convert between the window/tab number and the
identifier. There is also the window number, which may change whenever
windows are opened or closed, see |winnr()|.
The window number is only valid in one specific tab. The window ID is valid
across tabs. For most functions that take a window ID or a window number, the
window number only applies to the current tab, while the window ID can refer
to a window in any tab.
Each window has a unique identifier called the window ID, which is permanent
during the Nvim session. The |win_getid()| and |win_id2tabwin()| functions
convert between the window/tab "number" and the identifier.
*window-number*
Windows are also numbered according to their arrangement in a tabpage; this
window "number" is given by |winnr()| and may change whenever windows are
opened or closed. The window number is only valid in one specific tab, whereas
the window ID is valid globally, across tabs. For most functions that take
a window ID or a window number, the window number only applies to the current
tab, while the window ID can refer to a window in any tab.
==============================================================================

2
runtime/lua/vim/_meta/options.gen.lua generated
View File

@@ -6855,7 +6855,7 @@ vim.wo.stc = vim.wo.statuscolumn
--- added without modifying code that reacts on mouse clicks on
--- this label.
--- Use `getmousepos()`.winid in the specified function to get the
--- corresponding window id of the clicked item.
--- corresponding `window-ID` of the clicked item.
--- \< - Where to truncate line if too long. Default is at the start.
--- No width fields allowed.
--- = - Separation point between alignment sections. Each section will

112
runtime/lua/vim/_meta/vimfn.gen.lua generated
View File

@@ -134,8 +134,8 @@ function vim.fn.appendbufline(buf, lnum, text) end
--- If {winid} is not supplied, the argument list of the current
--- window is used.
--- If {winid} is -1, the global argument list is used.
--- Otherwise {winid} specifies the window of which the argument
--- list is used: either the window number or the window ID.
--- Otherwise {winid} (a |window-number| or |window-ID|) specifies
--- the window of which the argument list is used.
--- Returns -1 if the {winid} argument is invalid.
---
--- @param winid? integer
@@ -157,7 +157,7 @@ function vim.fn.argidx() end
--- With {winnr} only use this window in the current tabpage.
--- With {winnr} and {tabnr} use the window in the specified tab
--- page.
--- {winnr} can be the window number or the |window-ID|.
--- {winnr} is a |window-number| or |window-ID|.
---
--- @param winnr? integer
--- @param tabnr? integer
@@ -175,7 +175,7 @@ function vim.fn.arglistid(winnr, tabnr) end
--- <Without the {nr} argument, or when {nr} is -1, a |List| with
--- the whole |arglist| is returned.
---
--- The {winid} argument specifies the window ID, see |argc()|.
--- The {winid} argument is a |window-ID|, see |argc()|.
--- For the Vim command line arguments see |v:argv|.
---
--- Returns an empty string if {nr}th argument is not present in
@@ -679,7 +679,7 @@ function vim.fn.bufwinid(buf) end
--- Lua: Prefer |nvim_tabpage_list_wins()| with |nvim_win_get_buf()| and |nvim_win_get_number()| after resolving {buf}; only the current tabpage is checked and no-match semantics differ.
---
--- Like |bufwinid()| but return the window number instead of the
--- Like |bufwinid()| but returns a |window-number| instead of a
--- |window-ID|.
--- If buffer {buf} doesn't exist or there is no such window, -1
--- is returned. Example: >vim
@@ -992,8 +992,8 @@ function vim.fn.cindent(lnum) end
--- Clears all matches previously defined for the current window
--- by |matchadd()| and the |:match| commands.
--- If {win} is specified, use the window with this number or
--- window ID instead of the current window.
--- If {win} is specified, use this |window-number| or |window-ID|
--- instead of the current window.
---
--- @param win? integer
function vim.fn.clearmatches(win) end
@@ -3295,10 +3295,10 @@ function vim.fn.getcompletiontype(pat) end
--- the cursor is returned in "col". To get the character
--- position, use |getcursorcharpos()|.
---
--- The optional {winid} argument can specify the window. It can
--- be the window number or the |window-ID|. The last known
--- cursor position is returned, this may be invalid for the
--- current value of the buffer if it is not the current window.
--- The optional {winid} (|window-number| or |window-ID|) specifies
--- the window. The last known cursor position is returned, this
--- may be invalid for the current value of the buffer if it is not
--- the current window.
--- If {winid} is invalid a list with zeroes is returned.
---
--- This can be used to save and restore the cursor position: >vim
@@ -3336,7 +3336,7 @@ function vim.fn.getcursorcharpos(winid) end
--- getcwd(0)
--- getcwd(0, 0)
--- <If {winnr} is -1 it is ignored, only the tab is resolved.
--- {winnr} can be the window number or the |window-ID|.
--- {winnr} is a |window-number| or |window-ID|.
--- If both {winnr} and {tabnr} are -1 the global working
--- directory is returned.
--- Note: When {tabnr} is -1 Vim returns an empty string to
@@ -3454,8 +3454,8 @@ function vim.fn.getftype(fname) end
--- Returns the |jumplist| for the specified window.
---
--- Without arguments use the current window.
--- With {winnr} only use this window in the current tabpage.
--- {winnr} can also be a |window-ID|.
--- With {winnr} (|window-number| or |window-ID|) only use this
--- window in the current tabpage.
--- With {winnr} and {tabnr} use the window in the specified tab
--- page. If {winnr} or {tabnr} is invalid, an empty list is
--- returned.
@@ -3514,12 +3514,12 @@ function vim.fn.getline(lnum, end_) end
function vim.fn.getline(lnum, end_) end
--- Returns a |List| with all the entries in the location list for
--- window {nr}. {nr} can be the window number or the |window-ID|.
--- window {nr} (|window-number| or |window-ID|).
--- When {nr} is zero the current window is used.
---
--- For a location list window, the displayed location list is
--- returned. For an invalid window number {nr}, an empty list is
--- returned. Otherwise, same as |getqflist()|.
--- returned. For an invalid {nr}, an empty list is returned.
--- Otherwise, same as |getqflist()|.
---
--- If the optional {what} dictionary argument is supplied, then
--- returns the items listed in {what} as a dictionary. Refer to
@@ -3576,9 +3576,9 @@ function vim.fn.getmarklist(buf) end
--- |getmatches()| is useful in combination with |setmatches()|,
--- as |setmatches()| can restore a list of matches saved by
--- |getmatches()|.
--- If {win} is specified, use the window with this number or
--- window ID instead of the current window. If {win} is invalid,
--- an empty list is returned.
--- If {win} is specified, use this |window-number| or |window-ID|
--- instead of the current window. If {win} is invalid, an empty
--- list is returned.
--- Example: >vim
--- echo getmatches()
--- < >
@@ -4101,7 +4101,7 @@ function vim.fn.gettabvar(tabnr, varname, def) end
--- Note that {varname} must be the name without "w:".
--- Tabs are numbered starting with one. For the current tabpage
--- use |getwinvar()|.
--- {winnr} can be the window number or the |window-ID|.
--- {winnr} is a |window-number| or |window-ID|.
--- When {winnr} is zero the current window is used.
--- This also works for a global option, buffer-local option and
--- window-local option, but it doesn't work for a global variable
@@ -4123,8 +4123,8 @@ function vim.fn.gettabvar(tabnr, varname, def) end
--- @return any
function vim.fn.gettabwinvar(tabnr, winnr, varname, def) end
--- Returns the tag stack of window {winnr} as a Dict.
--- {winnr} can be the window number or the |window-ID|.
--- Returns the tag stack of window {winnr} (|window-number| or
--- |window-ID|) as a Dict.
--- When {winnr} is not specified, the current window is used.
--- When window {winnr} doesn't exist, an empty Dict is returned.
---
@@ -4200,7 +4200,7 @@ function vim.fn.gettext(text) end
--- wincol leftmost screen column of the window;
--- "col" from |win_screenpos()|
--- winid |window-ID|
--- winnr window number
--- winnr |window-number|
--- winrow topmost screen line of the window;
--- "row" from |win_screenpos()|
---
@@ -4462,7 +4462,7 @@ function vim.fn.has_key(dict, key) end
--- echo haslocaldir(0, 0)
--- <With {winnr} use that window in the current tabpage.
--- With {winnr} and {tabnr} use the window in that tabpage.
--- {winnr} can be the window number or the |window-ID|.
--- {winnr} is a |window-number| or |window-ID|.
--- If {winnr} is -1 it is ignored, only the tab is resolved.
--- Throw error if the arguments are invalid. |E5000| |E5001| |E5002|
---
@@ -5967,8 +5967,8 @@ function vim.fn.match(expr, pat, start, count) end
--- conceal Special character to show instead of the
--- match (only for |hl-Conceal| highlighted
--- matches, see |:syn-cchar|)
--- window Instead of the current window use the
--- window with this number or window ID.
--- window Use this |window-number| or |window-ID| instead
--- of the current window.
---
--- The number of matches is not limited, as it is the case with
--- the |:match| commands.
@@ -6107,8 +6107,7 @@ function vim.fn.matchbufline(buf, pat, lnum, end_, dict) end
--- or one of the |:match| commands. Returns 0 if successful,
--- otherwise -1. See example for |matchadd()|. All matches can
--- be deleted in one operation by |clearmatches()|.
--- If {win} is specified, use the window with this number or
--- window ID instead of the current window.
--- {win} (if given) is a |window-number| or |window-ID|.
---
--- @param id integer
--- @param win? integer
@@ -8609,12 +8608,12 @@ function vim.fn.setfperm(fname, mode) end
--- @return any
function vim.fn.setline(lnum, text) end
--- Create or replace or add to the location list for window {nr}.
--- {nr} can be the window number or the |window-ID|.
--- Create or replace or add to the location list for window {nr}
--- (|window-number| or |window-ID|).
--- When {nr} is zero the current window is used.
---
--- For a location list window, the displayed location list is
--- modified. For an invalid window number {nr}, -1 is returned.
--- modified. For an invalid {nr}, -1 is returned.
--- Otherwise, same as |setqflist()|.
--- Also see |location-list|.
---
@@ -8635,8 +8634,7 @@ function vim.fn.setloclist(nr, list, action, what) end
--- current window. Returns 0 if successful, otherwise -1. All
--- current matches are cleared before the list is restored. See
--- example for |getmatches()|.
--- If {win} is specified, use the window with this number or
--- window ID instead of the current window.
--- {win} (if given) is a |window-number| or |window-ID|.
---
--- @param list vim.fn.getmatches.ret.item[]
--- @param win? integer
@@ -8907,7 +8905,7 @@ function vim.fn.settabvar(tabnr, varname, val) end
--- {val}.
--- Tabs are numbered starting with one. For the current tabpage
--- use |setwinvar()|.
--- {winnr} can be the window number or the |window-ID|.
--- {winnr} is a |window-number| or |window-ID|.
--- When {winnr} is zero the current window is used.
--- This also works for a global or local buffer option, but it
--- doesn't work for a global or local buffer variable.
@@ -8925,8 +8923,8 @@ function vim.fn.settabvar(tabnr, varname, val) end
--- @return any
function vim.fn.settabwinvar(tabnr, winnr, varname, val) end
--- Modify the tag stack of the window {nr} using {dict}.
--- {nr} can be the window number or the |window-ID|.
--- Modify the tag stack of the window {nr} (|window-number| or
--- |window-ID|) using {dict}.
---
--- For a list of supported items in {dict}, refer to
--- |gettagstack()|. "curidx" takes effect before changing the tag
@@ -11191,8 +11189,8 @@ function vim.fn.virtcol(expr, list, winid) end
--- For a multi-byte character, the column number of the first
--- byte in the character is returned.
---
--- The {winid} argument can be the window number or the
--- |window-ID|. If this is zero, then the current window is used.
--- {winid} is a |window-number| or |window-ID|. If zero, the
--- current window is used.
---
--- Returns -1 if the window {winid} doesn't exist or the buffer
--- line {lnum} or virtual column {col} is invalid.
@@ -11319,10 +11317,9 @@ function vim.fn.win_findbuf(bufnr) end
---
--- Get the |window-ID| for the specified window.
--- When {win} is missing use the current window.
--- With {win} this is the window number. The top window has
--- number 1.
--- Without {tab} use the current tab, otherwise the tab with
--- number {tab}. The first tab has number one.
--- With {win} this is the |window-number|.
--- Without {tab} use the current tab, otherwise the
--- |tabpage-number| given by {tab}.
--- Return zero if the window cannot be found.
---
--- @param win? integer
@@ -11342,8 +11339,8 @@ function vim.fn.win_getid(win, tab) end
--- "unknown" window {nr} not found
---
--- When {nr} is omitted return the type of the current window.
--- When {nr} is given return the type of this window by number or
--- |window-ID|.
--- When {nr} is given (|window-number| or |window-ID|) return the
--- type of that window.
---
--- Also see the 'buftype' option.
---
@@ -11353,8 +11350,7 @@ function vim.fn.win_gettype(nr) end
--- Lua: Prefer |nvim_set_current_win()|; invalid IDs error instead of returning FALSE.
---
--- Go to window with ID {expr}. This may also change the current
--- tabpage.
--- Go to |window-ID| {expr}. May change the current tabpage.
--- Return TRUE if successful, FALSE if the window cannot be
--- found.
---
@@ -11364,8 +11360,8 @@ function vim.fn.win_gotoid(expr) end
--- Lua: Prefer |nvim_win_get_tabpage()| and |nvim_win_get_number()| for valid windows; invalid IDs error instead of returning `[0, 0]`.
---
--- Return a list with the tab number and window number of window
--- with ID {expr}: [tabnr, winnr].
--- Return [tabnr, winnr] for window with |window-ID| {expr}, where
--- tabnr is the |tabpage-number| and winnr is the |window-number|.
--- Return [0, 0] if the window cannot be found.
---
--- @param expr integer
@@ -11374,7 +11370,7 @@ function vim.fn.win_id2tabwin(expr) end
--- Lua: Prefer |nvim_win_get_number()| for valid windows; windows outside the current tabpage and invalid IDs differ.
---
--- Return the window number of window with ID {expr}.
--- Return the |window-number| of for the given |window-ID| {expr}.
--- Return 0 if the window cannot be found in the current tabpage.
---
--- @param expr integer
@@ -11383,7 +11379,7 @@ function vim.fn.win_id2win(expr) end
--- Move window {nr}'s vertical separator (i.e., the right border)
--- by {offset} columns, as if being dragged by the mouse. {nr}
--- can be a window number or |window-ID|. A positive {offset}
--- is a |window-number| or |window-ID|. A positive {offset}
--- moves right and a negative {offset} moves left. Moving a
--- window's vertical separator will change the width of the
--- window and the width of other windows adjacent to the vertical
@@ -11401,8 +11397,8 @@ function vim.fn.win_id2win(expr) end
function vim.fn.win_move_separator(nr, offset) end
--- Move window {nr}'s status line (i.e., the bottom border) by
--- {offset} rows, as if being dragged by the mouse. {nr} can be
--- a window number or |window-ID|. A positive {offset} moves
--- {offset} rows, as if being dragged by the mouse. {nr} is a
--- |window-number| or |window-ID|. A positive {offset} moves
--- down and a negative {offset} moves up. Moving a window's
--- status line will change the height of the window and the
--- height of other windows adjacent to the status line. The
@@ -11421,8 +11417,8 @@ function vim.fn.win_move_statusline(nr, offset) end
--- Return the screen position of window {nr} as a list with two
--- numbers: [row, col]. The first window always has position
--- [1, 1], unless there is a tabline, then it is [2, 1].
--- {nr} can be the window number or the |window-ID|. Use zero
--- for the current window.
--- {nr} is a |window-number| or |window-ID|. Use zero for the
--- current window.
--- Returns [0, 0] if the window cannot be found.
---
--- @param nr integer
@@ -11434,7 +11430,7 @@ function vim.fn.win_screenpos(nr) end
--- Unlike commands such as |:split|, no new windows are created
--- (the |window-ID| of window {nr} is unchanged after the move).
---
--- Both {nr} and {target} can be window numbers or |window-ID|s.
--- Both {nr} and {target} are a |window-number| or |window-ID|.
--- Both must be in the current tabpage.
---
--- Returns zero for success, non-zero for failure.
@@ -11456,8 +11452,8 @@ function vim.fn.win_splitmove(nr, target, options) end
--- Lua: Prefer |nvim_win_get_buf()|.
---
--- Returns the buffer number associated with window {nr}.
--- {nr} can be the window number or the |window-ID|.
--- Returns the buffer number associated with window {nr}
--- (|window-number| or |window-ID|).
--- When {nr} is zero, the number of the buffer in the current
--- window is returned.
--- When window {nr} doesn't exist, -1 is returned.

112
src/nvim/eval.lua
View File

@@ -199,8 +199,8 @@ M.funcs = {
If {winid} is not supplied, the argument list of the current
window is used.
If {winid} is -1, the global argument list is used.
Otherwise {winid} specifies the window of which the argument
list is used: either the window number or the window ID.
Otherwise {winid} (a |window-number| or |window-ID|) specifies
the window of which the argument list is used.
Returns -1 if the {winid} argument is invalid.
]=],
name = 'argc',
@@ -230,7 +230,7 @@ M.funcs = {
With {winnr} only use this window in the current tabpage.
With {winnr} and {tabnr} use the window in the specified tab
page.
{winnr} can be the window number or the |window-ID|.
{winnr} is a |window-number| or |window-ID|.
]=],
name = 'arglistid',
params = { { 'winnr', 'integer' }, { 'tabnr', 'integer' } },
@@ -251,7 +251,7 @@ M.funcs = {
<Without the {nr} argument, or when {nr} is -1, a |List| with
the whole |arglist| is returned.
The {winid} argument specifies the window ID, see |argc()|.
The {winid} argument is a |window-ID|, see |argc()|.
For the Vim command line arguments see |v:argv|.
Returns an empty string if {nr}th argument is not present in
@@ -914,7 +914,7 @@ M.funcs = {
args = 1,
base = 1,
desc = [=[
Like |bufwinid()| but return the window number instead of the
Like |bufwinid()| but returns a |window-number| instead of a
|window-ID|.
If buffer {buf} doesn't exist or there is no such window, -1
is returned. Example: >vim
@@ -1311,8 +1311,8 @@ M.funcs = {
desc = [=[
Clears all matches previously defined for the current window
by |matchadd()| and the |:match| commands.
If {win} is specified, use the window with this number or
window ID instead of the current window.
If {win} is specified, use this |window-number| or |window-ID|
instead of the current window.
]=],
name = 'clearmatches',
@@ -4076,10 +4076,10 @@ M.funcs = {
the cursor is returned in "col". To get the character
position, use |getcursorcharpos()|.
The optional {winid} argument can specify the window. It can
be the window number or the |window-ID|. The last known
cursor position is returned, this may be invalid for the
current value of the buffer if it is not the current window.
The optional {winid} (|window-number| or |window-ID|) specifies
the window. The last known cursor position is returned, this
may be invalid for the current value of the buffer if it is not
the current window.
If {winid} is invalid a list with zeroes is returned.
This can be used to save and restore the cursor position: >vim
@@ -4128,7 +4128,7 @@ M.funcs = {
getcwd(0)
getcwd(0, 0)
<If {winnr} is -1 it is ignored, only the tab is resolved.
{winnr} can be the window number or the |window-ID|.
{winnr} is a |window-number| or |window-ID|.
If both {winnr} and {tabnr} are -1 the global working
directory is returned.
Note: When {tabnr} is -1 Vim returns an empty string to
@@ -4284,8 +4284,8 @@ M.funcs = {
Returns the |jumplist| for the specified window.
Without arguments use the current window.
With {winnr} only use this window in the current tabpage.
{winnr} can also be a |window-ID|.
With {winnr} (|window-number| or |window-ID|) only use this
window in the current tabpage.
With {winnr} and {tabnr} use the window in the specified tab
page. If {winnr} or {tabnr} is invalid, an empty list is
returned.
@@ -4355,12 +4355,12 @@ M.funcs = {
args = { 1, 2 },
desc = [=[
Returns a |List| with all the entries in the location list for
window {nr}. {nr} can be the window number or the |window-ID|.
window {nr} (|window-number| or |window-ID|).
When {nr} is zero the current window is used.
For a location list window, the displayed location list is
returned. For an invalid window number {nr}, an empty list is
returned. Otherwise, same as |getqflist()|.
returned. For an invalid {nr}, an empty list is returned.
Otherwise, same as |getqflist()|.
If the optional {what} dictionary argument is supplied, then
returns the items listed in {what} as a dictionary. Refer to
@@ -4425,9 +4425,9 @@ M.funcs = {
|getmatches()| is useful in combination with |setmatches()|,
as |setmatches()| can restore a list of matches saved by
|getmatches()|.
If {win} is specified, use the window with this number or
window ID instead of the current window. If {win} is invalid,
an empty list is returned.
If {win} is specified, use this |window-number| or |window-ID|
instead of the current window. If {win} is invalid, an empty
list is returned.
Example: >vim
echo getmatches()
< >
@@ -5017,7 +5017,7 @@ M.funcs = {
Note that {varname} must be the name without "w:".
Tabs are numbered starting with one. For the current tabpage
use |getwinvar()|.
{winnr} can be the window number or the |window-ID|.
{winnr} is a |window-number| or |window-ID|.
When {winnr} is zero the current window is used.
This also works for a global option, buffer-local option and
window-local option, but it doesn't work for a global variable
@@ -5048,8 +5048,8 @@ M.funcs = {
args = { 0, 1 },
base = 1,
desc = [=[
Returns the tag stack of window {winnr} as a Dict.
{winnr} can be the window number or the |window-ID|.
Returns the tag stack of window {winnr} (|window-number| or
|window-ID|) as a Dict.
When {winnr} is not specified, the current window is used.
When window {winnr} doesn't exist, an empty Dict is returned.
@@ -5135,7 +5135,7 @@ M.funcs = {
wincol leftmost screen column of the window;
"col" from |win_screenpos()|
winid |window-ID|
winnr window number
winnr |window-number|
winrow topmost screen line of the window;
"row" from |win_screenpos()|
@@ -5447,7 +5447,7 @@ M.funcs = {
echo haslocaldir(0, 0)
<With {winnr} use that window in the current tabpage.
With {winnr} and {tabnr} use the window in that tabpage.
{winnr} can be the window number or the |window-ID|.
{winnr} is a |window-number| or |window-ID|.
If {winnr} is -1 it is ignored, only the tab is resolved.
Throw error if the arguments are invalid. |E5000| |E5001| |E5002|
@@ -7254,8 +7254,8 @@ M.funcs = {
conceal Special character to show instead of the
match (only for |hl-Conceal| highlighted
matches, see |:syn-cchar|)
window Instead of the current window use the
window with this number or window ID.
window Use this |window-number| or |window-ID| instead
of the current window.
The number of matches is not limited, as it is the case with
the |:match| commands.
@@ -7424,8 +7424,7 @@ M.funcs = {
or one of the |:match| commands. Returns 0 if successful,
otherwise -1. See example for |matchadd()|. All matches can
be deleted in one operation by |clearmatches()|.
If {win} is specified, use the window with this number or
window ID instead of the current window.
{win} (if given) is a |window-number| or |window-ID|.
]=],
name = 'matchdelete',
@@ -10351,12 +10350,12 @@ M.funcs = {
args = { 2, 4 },
base = 2,
desc = [=[
Create or replace or add to the location list for window {nr}.
{nr} can be the window number or the |window-ID|.
Create or replace or add to the location list for window {nr}
(|window-number| or |window-ID|).
When {nr} is zero the current window is used.
For a location list window, the displayed location list is
modified. For an invalid window number {nr}, -1 is returned.
modified. For an invalid {nr}, -1 is returned.
Otherwise, same as |setqflist()|.
Also see |location-list|.
@@ -10384,8 +10383,7 @@ M.funcs = {
current window. Returns 0 if successful, otherwise -1. All
current matches are cleared before the list is restored. See
example for |getmatches()|.
If {win} is specified, use the window with this number or
window ID instead of the current window.
{win} (if given) is a |window-number| or |window-ID|.
]=],
name = 'setmatches',
@@ -10675,7 +10673,7 @@ M.funcs = {
{val}.
Tabs are numbered starting with one. For the current tabpage
use |setwinvar()|.
{winnr} can be the window number or the |window-ID|.
{winnr} is a |window-number| or |window-ID|.
When {winnr} is zero the current window is used.
This also works for a global or local buffer option, but it
doesn't work for a global or local buffer variable.
@@ -10703,8 +10701,8 @@ M.funcs = {
args = { 2, 3 },
base = 2,
desc = [=[
Modify the tag stack of the window {nr} using {dict}.
{nr} can be the window number or the |window-ID|.
Modify the tag stack of the window {nr} (|window-number| or
|window-ID|) using {dict}.
For a list of supported items in {dict}, refer to
|gettagstack()|. "curidx" takes effect before changing the tag
@@ -13445,8 +13443,8 @@ M.funcs = {
For a multi-byte character, the column number of the first
byte in the character is returned.
The {winid} argument can be the window number or the
|window-ID|. If this is zero, then the current window is used.
{winid} is a |window-number| or |window-ID|. If zero, the
current window is used.
Returns -1 if the window {winid} doesn't exist or the buffer
line {lnum} or virtual column {col} is invalid.
@@ -13593,10 +13591,9 @@ M.funcs = {
desc = [=[
Get the |window-ID| for the specified window.
When {win} is missing use the current window.
With {win} this is the window number. The top window has
number 1.
Without {tab} use the current tab, otherwise the tab with
number {tab}. The first tab has number one.
With {win} this is the |window-number|.
Without {tab} use the current tab, otherwise the
|tabpage-number| given by {tab}.
Return zero if the window cannot be found.
]=],
@@ -13624,8 +13621,8 @@ M.funcs = {
"unknown" window {nr} not found
When {nr} is omitted return the type of the current window.
When {nr} is given return the type of this window by number or
|window-ID|.
When {nr} is given (|window-number| or |window-ID|) return the
type of that window.
Also see the 'buftype' option.
@@ -13639,8 +13636,7 @@ M.funcs = {
args = 1,
base = 1,
desc = [=[
Go to window with ID {expr}. This may also change the current
tabpage.
Go to |window-ID| {expr}. May change the current tabpage.
Return TRUE if successful, FALSE if the window cannot be
found.
@@ -13655,8 +13651,8 @@ M.funcs = {
args = 1,
base = 1,
desc = [=[
Return a list with the tab number and window number of window
with ID {expr}: [tabnr, winnr].
Return [tabnr, winnr] for window with |window-ID| {expr}, where
tabnr is the |tabpage-number| and winnr is the |window-number|.
Return [0, 0] if the window cannot be found.
]=],
@@ -13671,7 +13667,7 @@ M.funcs = {
args = 1,
base = 1,
desc = [=[
Return the window number of window with ID {expr}.
Return the |window-number| of for the given |window-ID| {expr}.
Return 0 if the window cannot be found in the current tabpage.
]=],
@@ -13689,7 +13685,7 @@ M.funcs = {
desc = [=[
Move window {nr}'s vertical separator (i.e., the right border)
by {offset} columns, as if being dragged by the mouse. {nr}
can be a window number or |window-ID|. A positive {offset}
is a |window-number| or |window-ID|. A positive {offset}
moves right and a negative {offset} moves left. Moving a
window's vertical separator will change the width of the
window and the width of other windows adjacent to the vertical
@@ -13711,8 +13707,8 @@ M.funcs = {
base = 1,
desc = [=[
Move window {nr}'s status line (i.e., the bottom border) by
{offset} rows, as if being dragged by the mouse. {nr} can be
a window number or |window-ID|. A positive {offset} moves
{offset} rows, as if being dragged by the mouse. {nr} is a
|window-number| or |window-ID|. A positive {offset} moves
down and a negative {offset} moves up. Moving a window's
status line will change the height of the window and the
height of other windows adjacent to the status line. The
@@ -13733,8 +13729,8 @@ M.funcs = {
Return the screen position of window {nr} as a list with two
numbers: [row, col]. The first window always has position
[1, 1], unless there is a tabline, then it is [2, 1].
{nr} can be the window number or the |window-ID|. Use zero
for the current window.
{nr} is a |window-number| or |window-ID|. Use zero for the
current window.
Returns [0, 0] if the window cannot be found.
]=],
name = 'win_screenpos',
@@ -13753,7 +13749,7 @@ M.funcs = {
Unlike commands such as |:split|, no new windows are created
(the |window-ID| of window {nr} is unchanged after the move).
Both {nr} and {target} can be window numbers or |window-ID|s.
Both {nr} and {target} are a |window-number| or |window-ID|.
Both must be in the current tabpage.
Returns zero for success, non-zero for failure.
@@ -13776,8 +13772,8 @@ M.funcs = {
args = 1,
base = 1,
desc = [=[
Returns the buffer number associated with window {nr}.
{nr} can be the window number or the |window-ID|.
Returns the buffer number associated with window {nr}
(|window-number| or |window-ID|).
When {nr} is zero, the number of the buffer in the current
window is returned.
When window {nr} doesn't exist, -1 is returned.

2
src/nvim/options.lua
View File

@@ -8918,7 +8918,7 @@ local options = {
added without modifying code that reacts on mouse clicks on
this label.
Use |getmousepos()|.winid in the specified function to get the
corresponding window id of the clicked item.
corresponding |window-ID| of the clicked item.
\< - Where to truncate line if too long. Default is at the start.
No width fields allowed.
= - Separation point between alignment sections. Each section will