GitHub/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim synced 2025-07-16 01:01:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: clarify window-id, tab-id, nvim_set_current_x #32528

Browse Source 
Problem:
Descriptions are somewhat vague. nvim_set_current_line modifies contents
but nvim_set_current_buf does not, etc.

Solution:
- Make it clear that these functions accept or return a winid/tabid by
  linking to that concept in help.
- Only these few files use the term "handles", so replace them with the
  more conventional terminology.
- Add a new help section for tab-ID. This concept is unique to neovim
  because vim exposes tabnr, but not tab handles. This section is
  modelled after `:h winid`.
This commit is contained in:
David Briscoe
2025-02-27 02:05:00 -08:00
committed by GitHub
parent 746139fa1e
commit 6a9555c0fa
12 changed files with 150 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
runtime/doc/api.txt
View File

@ -810,13 +810,13 @@ nvim_get_current_tabpage() *nvim_get_current_tabpage()*
Gets the current tabpage. Gets the current tabpage.
Return: ~ Return: ~
Tabpage handle |tab-ID|
nvim_get_current_win() *nvim_get_current_win()* nvim_get_current_win() *nvim_get_current_win()*
Gets the current window. Gets the current window.
Return: ~ Return: ~
Window handle |window-ID|
nvim_get_hl({ns_id}, {opts}) *nvim_get_hl()* nvim_get_hl({ns_id}, {opts}) *nvim_get_hl()*
Gets all or specific highlight groups in a namespace. Gets all or specific highlight groups in a namespace.
@ -1032,10 +1032,10 @@ nvim_list_runtime_paths() *nvim_list_runtime_paths()*
List of paths List of paths
nvim_list_tabpages() *nvim_list_tabpages()* nvim_list_tabpages() *nvim_list_tabpages()*
Gets the current list of tabpage handles. Gets the current list of |tab-ID|s.
Return: ~ Return: ~
List of tabpage handles List of |tab-ID|s
nvim_list_uis() *nvim_list_uis()* nvim_list_uis() *nvim_list_uis()*
Gets a list of dictionaries representing attached UIs. Gets a list of dictionaries representing attached UIs.
@ -1058,7 +1058,7 @@ nvim_list_wins() *nvim_list_wins()*
Gets the current list of window handles. Gets the current list of window handles.
Return: ~ Return: ~
List of window handles List of |window-ID|s
nvim_load_context({dict}) *nvim_load_context()* nvim_load_context({dict}) *nvim_load_context()*
Sets the current editor state from the given |context| map. Sets the current editor state from the given |context| map.
@ -1269,7 +1269,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
icon. .png or .svg format is preferred. icon. .png or .svg format is preferred.
nvim_set_current_buf({buffer}) *nvim_set_current_buf()* nvim_set_current_buf({buffer}) *nvim_set_current_buf()*
Sets the current buffer. Sets the current window's buffer to `buffer`.
Attributes: ~ Attributes: ~
not allowed when |textlock| is active or in the |cmdwin| not allowed when |textlock| is active or in the |cmdwin|
@ -1284,7 +1284,7 @@ nvim_set_current_dir({dir}) *nvim_set_current_dir()*
• {dir} Directory path • {dir} Directory path
nvim_set_current_line({line}) *nvim_set_current_line()* nvim_set_current_line({line}) *nvim_set_current_line()*
Sets the current line. Sets the text on the current line.
Attributes: ~ Attributes: ~
not allowed when |textlock| is active not allowed when |textlock| is active
@ -1299,16 +1299,16 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()*
not allowed when |textlock| is active or in the |cmdwin| not allowed when |textlock| is active or in the |cmdwin|
Parameters: ~ Parameters: ~
• {tabpage} Tabpage handle • {tabpage} |tab-ID| to focus
nvim_set_current_win({window}) *nvim_set_current_win()* nvim_set_current_win({window}) *nvim_set_current_win()*
Sets the current window. Sets the current window. Also changes tabpage, if necessary.
Attributes: ~ Attributes: ~
not allowed when |textlock| is active or in the |cmdwin| not allowed when |textlock| is active or in the |cmdwin|
Parameters: ~ Parameters: ~
• {window} Window handle • {window} |window-ID| to focus
nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()* nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()*
Sets a highlight group. Sets a highlight group.
@ -2824,7 +2824,7 @@ nvim_win_call({window}, {fun}) *nvim_win_call()*
Lua |vim.api| only Lua |vim.api| only
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
• {fun} Function to call inside the window (currently Lua callable • {fun} Function to call inside the window (currently Lua callable
only) only)
@ -2842,7 +2842,7 @@ nvim_win_close({window}, {force}) *nvim_win_close()*
not allowed when |textlock| is active not allowed when |textlock| is active
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
• {force} Behave like `:close!` The last window of a buffer with • {force} Behave like `:close!` The last window of a buffer with
unwritten changes can be closed. The buffer will become unwritten changes can be closed. The buffer will become
hidden, even if 'hidden' is not set. hidden, even if 'hidden' is not set.
@ -2851,14 +2851,14 @@ nvim_win_del_var({window}, {name}) *nvim_win_del_var()*
Removes a window-scoped (w:) variable Removes a window-scoped (w:) variable
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
• {name} Variable name • {name} Variable name
nvim_win_get_buf({window}) *nvim_win_get_buf()* nvim_win_get_buf({window}) *nvim_win_get_buf()*
Gets the current buffer in a window Gets the current buffer in a window
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
Return: ~ Return: ~
Buffer handle Buffer handle
@ -2869,7 +2869,7 @@ nvim_win_get_cursor({window}) *nvim_win_get_cursor()*
positions). |api-indexing| positions). |api-indexing|
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
Return: ~ Return: ~
(row, col) tuple (row, col) tuple
@ -2881,7 +2881,7 @@ nvim_win_get_height({window}) *nvim_win_get_height()*
Gets the window height Gets the window height
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
Return: ~ Return: ~
Height as a count of rows Height as a count of rows
@ -2890,7 +2890,7 @@ nvim_win_get_number({window}) *nvim_win_get_number()*
Gets the window number Gets the window number
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
Return: ~ Return: ~
Window number Window number
@ -2899,7 +2899,7 @@ nvim_win_get_position({window}) *nvim_win_get_position()*
Gets the window position in display cells. First position is zero. Gets the window position in display cells. First position is zero.
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
Return: ~ Return: ~
(row, col) tuple with the window position (row, col) tuple with the window position
@ -2908,7 +2908,7 @@ nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()*
Gets the window tabpage Gets the window tabpage
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
Return: ~ Return: ~
Tabpage that contains the window Tabpage that contains the window
@ -2917,7 +2917,7 @@ nvim_win_get_var({window}, {name}) *nvim_win_get_var()*
Gets a window-scoped (w:) variable Gets a window-scoped (w:) variable
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
• {name} Variable name • {name} Variable name
Return: ~ Return: ~
@ -2927,7 +2927,7 @@ nvim_win_get_width({window}) *nvim_win_get_width()*
Gets the window width Gets the window width
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
Return: ~ Return: ~
Width as a count of columns Width as a count of columns
@ -2944,13 +2944,13 @@ nvim_win_hide({window}) *nvim_win_hide()*
not allowed when |textlock| is active not allowed when |textlock| is active
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
nvim_win_is_valid({window}) *nvim_win_is_valid()* nvim_win_is_valid({window}) *nvim_win_is_valid()*
Checks if a window is valid Checks if a window is valid
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
Return: ~ Return: ~
true if the window is valid, false otherwise true if the window is valid, false otherwise
@ -2962,7 +2962,7 @@ nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()*
not allowed when |textlock| is active not allowed when |textlock| is active
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
• {buffer} Buffer handle • {buffer} Buffer handle
nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()*
@ -2970,14 +2970,14 @@ nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()*
scrolls the window even if it is not the current one. scrolls the window even if it is not the current one.
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
• {pos} (row, col) tuple representing the new position • {pos} (row, col) tuple representing the new position
nvim_win_set_height({window}, {height}) *nvim_win_set_height()* nvim_win_set_height({window}, {height}) *nvim_win_set_height()*
Sets the window height. Sets the window height.
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
• {height} Height as a count of rows • {height} Height as a count of rows
nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()* nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()*
@ -2994,7 +2994,7 @@ nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()*
Sets a window-scoped (w:) variable Sets a window-scoped (w:) variable
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
• {name} Variable name • {name} Variable name
• {value} Variable value • {value} Variable value
@ -3003,7 +3003,7 @@ nvim_win_set_width({window}, {width}) *nvim_win_set_width()*
vertically. vertically.
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
• {width} Width as a count of columns • {width} Width as a count of columns
nvim_win_text_height({window}, {opts}) *nvim_win_text_height()* nvim_win_text_height({window}, {opts}) *nvim_win_text_height()*
@ -3019,7 +3019,7 @@ nvim_win_text_height({window}, {opts}) *nvim_win_text_height()*
Line indexing is similar to |nvim_buf_get_text()|. Line indexing is similar to |nvim_buf_get_text()|.
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window. • {window} |window-ID|, or 0 for current window.
• {opts} Optional parameters: • {opts} Optional parameters:
• start_row: Starting line index, 0-based inclusive. When • start_row: Starting line index, 0-based inclusive. When
omitted start at the very top. omitted start at the very top.
@ -3224,7 +3224,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
• split: Split direction: "left", "right", "above", "below". • split: Split direction: "left", "right", "above", "below".
Return: ~ Return: ~
Window handle, or 0 on error |window-ID|, or 0 on error
nvim_win_get_config({window}) *nvim_win_get_config()* nvim_win_get_config({window}) *nvim_win_get_config()*
Gets window configuration. Gets window configuration.
@ -3234,7 +3234,7 @@ nvim_win_get_config({window}) *nvim_win_get_config()*
`relative` is empty for normal windows. `relative` is empty for normal windows.
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
Return: ~ Return: ~
Map defining the window configuration, see |nvim_open_win()| Map defining the window configuration, see |nvim_open_win()|
@ -3247,7 +3247,7 @@ nvim_win_set_config({window}, {config}) *nvim_win_set_config()*
`row`/`col` and `relative` must be reconfigured together. `row`/`col` and `relative` must be reconfigured together.
Parameters: ~ Parameters: ~
• {window} Window handle, or 0 for current window • {window} |window-ID|, or 0 for current window
• {config} Map defining the window configuration, see |nvim_open_win()| • {config} Map defining the window configuration, see |nvim_open_win()|
See also: ~ See also: ~
@ -3261,14 +3261,14 @@ nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()*
Removes a tab-scoped (t:) variable Removes a tab-scoped (t:) variable
Parameters: ~ Parameters: ~
• {tabpage} Tabpage handle, or 0 for current tabpage • {tabpage} |tab-ID|, or 0 for current tabpage
• {name} Variable name • {name} Variable name
nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()* nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()*
Gets the tabpage number Gets the tabpage number
Parameters: ~ Parameters: ~
• {tabpage} Tabpage handle, or 0 for current tabpage • {tabpage} |tab-ID|, or 0 for current tabpage
Return: ~ Return: ~
Tabpage number Tabpage number
@ -3277,7 +3277,7 @@ nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()*
Gets a tab-scoped (t:) variable Gets a tab-scoped (t:) variable
Parameters: ~ Parameters: ~
• {tabpage} Tabpage handle, or 0 for current tabpage • {tabpage} |tab-ID|, or 0 for current tabpage
• {name} Variable name • {name} Variable name
Return: ~ Return: ~
@ -3287,16 +3287,16 @@ nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()*
Gets the current window in a tabpage Gets the current window in a tabpage
Parameters: ~ Parameters: ~
• {tabpage} Tabpage handle, or 0 for current tabpage • {tabpage} |tab-ID|, or 0 for current tabpage
Return: ~ Return: ~
Window handle |window-ID|
nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()*
Checks if a tabpage is valid Checks if a tabpage is valid
Parameters: ~ Parameters: ~
• {tabpage} Tabpage handle, or 0 for current tabpage • {tabpage} |tab-ID|, or 0 for current tabpage
Return: ~ Return: ~
true if the tabpage is valid, false otherwise true if the tabpage is valid, false otherwise
@ -3305,7 +3305,7 @@ nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()*
Gets the windows in a tabpage Gets the windows in a tabpage
Parameters: ~ Parameters: ~
• {tabpage} Tabpage handle, or 0 for current tabpage • {tabpage} |tab-ID|, or 0 for current tabpage
Return: ~ Return: ~
List of windows in `tabpage` List of windows in `tabpage`
@ -3315,7 +3315,7 @@ nvim_tabpage_set_var({tabpage}, {name}, {value})
Sets a tab-scoped (t:) variable Sets a tab-scoped (t:) variable
Parameters: ~ Parameters: ~
• {tabpage} Tabpage handle, or 0 for current tabpage • {tabpage} |tab-ID|, or 0 for current tabpage
• {name} Variable name • {name} Variable name
• {value} Variable value • {value} Variable value
@ -3323,8 +3323,8 @@ nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()*
Sets the current window in a tabpage Sets the current window in a tabpage
Parameters: ~ Parameters: ~
• {tabpage} Tabpage handle, or 0 for current tabpage • {tabpage} |tab-ID|, or 0 for current tabpage
• {win} Window handle, must already belong to {tabpage} • {win} |window-ID|, must already belong to {tabpage}
============================================================================== ==============================================================================

4
runtime/doc/lsp.txt
View File

@ -2234,7 +2234,7 @@ make_position_params({window}, {position_encoding})
cursor position. cursor position.
Parameters: ~ Parameters: ~
• {window} (`integer?`) window handle or 0 for current, • {window} (`integer?`) |window-ID| or 0 for current,
defaults to current defaults to current
• {position_encoding} (`'utf-8'|'utf-16'|'utf-32'`) • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'`)
@ -2252,7 +2252,7 @@ make_range_params({window}, {position_encoding})
`textDocument/rangeFormatting`. `textDocument/rangeFormatting`.
Parameters: ~ Parameters: ~
• {window} (`integer?`) window handle or 0 for current, • {window} (`integer?`) |window-ID| or 0 for current,
defaults to current defaults to current
• {position_encoding} (`"utf-8"|"utf-16"|"utf-32"`) • {position_encoding} (`"utf-8"|"utf-16"|"utf-32"`)

11
runtime/doc/tabpage.txt
View File

@ -32,6 +32,17 @@ Tabs are also a nice way to edit a buffer temporarily without changing the
current window layout. Open a new tab page, do whatever you want to do and current window layout. Open a new tab page, do whatever you want to do and
close the tab page. close the tab page.
*tab-ID* *tabid* *tabpageid*
Each tab page has a unique identifier called the tab ID. This identifier will
not change within a Vim session -- even when rearranging tabs.
|nvim_get_current_tabpage()| returns the tab ID and |nvim_list_tabpages()|
lists tab IDs in the order they're displayed. Additionally, the tabs are
numbered from left to right starting at 1: this is the tab number returned by
|tabpagenr()|. However, the tab number may change when tabs are opened,
closed, or rearranged. |nvim_tabpage_get_number()| converts a tab ID to a tab
number.
============================================================================== ==============================================================================
2. Commands *tab-page-commands* 2. Commands *tab-page-commands*

2
runtime/doc/treesitter.txt
View File

@ -914,7 +914,7 @@ get_captures_at_cursor({winnr})
Returns a list of highlight capture names under the cursor Returns a list of highlight capture names under the cursor
Parameters: ~ Parameters: ~
• {winnr} (`integer?`) Window handle or 0 for current window (default) • {winnr} (`integer?`) |window-ID| or 0 for current window (default)
Return: ~ Return: ~
(`string[]`) List of capture names (`string[]`) List of capture names

84
runtime/lua/vim/_meta/api.lua generated
View File

@ -1361,12 +1361,12 @@ function vim.api.nvim_get_current_line() end
--- Gets the current tabpage. --- Gets the current tabpage.
--- ---
--- @return integer # Tabpage handle --- @return integer # |tab-ID|
function vim.api.nvim_get_current_tabpage() end function vim.api.nvim_get_current_tabpage() end
--- Gets the current window. --- Gets the current window.
--- ---
--- @return integer # Window handle --- @return integer # |window-ID|
function vim.api.nvim_get_current_win() end function vim.api.nvim_get_current_win() end
--- Gets all or specific highlight groups in a namespace. --- Gets all or specific highlight groups in a namespace.
@ -1619,9 +1619,9 @@ function vim.api.nvim_list_chans() end
--- @return string[] # List of paths --- @return string[] # List of paths
function vim.api.nvim_list_runtime_paths() end function vim.api.nvim_list_runtime_paths() end
--- Gets the current list of tabpage handles. --- Gets the current list of `tab-ID`s.
--- ---
--- @return integer[] # List of tabpage handles --- @return integer[] # List of |tab-ID|s
function vim.api.nvim_list_tabpages() end function vim.api.nvim_list_tabpages() end
--- Gets a list of dictionaries representing attached UIs. --- Gets a list of dictionaries representing attached UIs.
@ -1644,7 +1644,7 @@ function vim.api.nvim_list_uis() end
--- Gets the current list of window handles. --- Gets the current list of window handles.
--- ---
--- @return integer[] # List of window handles --- @return integer[] # List of |window-ID|s
function vim.api.nvim_list_wins() end function vim.api.nvim_list_wins() end
--- Sets the current editor state from the given `context` map. --- Sets the current editor state from the given `context` map.
@ -1870,7 +1870,7 @@ function vim.api.nvim_open_term(buffer, opts) end
--- - hide: If true the floating window will be hidden. --- - hide: If true the floating window will be hidden.
--- - vertical: Split vertically `:vertical`. --- - vertical: Split vertically `:vertical`.
--- - split: Split direction: "left", "right", "above", "below". --- - split: Split direction: "left", "right", "above", "below".
--- @return integer # Window handle, or 0 on error --- @return integer # |window-ID|, or 0 on error
function vim.api.nvim_open_win(buffer, enter, config) end function vim.api.nvim_open_win(buffer, enter, config) end
--- @deprecated --- @deprecated
@ -2087,7 +2087,7 @@ function vim.api.nvim_replace_termcodes(str, from_part, do_lt, special) end
--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
function vim.api.nvim_select_popupmenu_item(item, insert, finish, opts) end function vim.api.nvim_select_popupmenu_item(item, insert, finish, opts) end
--- Sets the current buffer. --- Sets the current window's buffer to `buffer`.
--- ---
--- @param buffer integer Buffer handle --- @param buffer integer Buffer handle
function vim.api.nvim_set_current_buf(buffer) end function vim.api.nvim_set_current_buf(buffer) end
@ -2097,19 +2097,19 @@ function vim.api.nvim_set_current_buf(buffer) end
--- @param dir string Directory path --- @param dir string Directory path
function vim.api.nvim_set_current_dir(dir) end function vim.api.nvim_set_current_dir(dir) end
--- Sets the current line. --- Sets the text on the current line.
--- ---
--- @param line string Line contents --- @param line string Line contents
function vim.api.nvim_set_current_line(line) end function vim.api.nvim_set_current_line(line) end
--- Sets the current tabpage. --- Sets the current tabpage.
--- ---
--- @param tabpage integer Tabpage handle --- @param tabpage integer `tab-ID` to focus
function vim.api.nvim_set_current_tabpage(tabpage) end function vim.api.nvim_set_current_tabpage(tabpage) end
--- Sets the current window. --- Sets the current window. Also changes tabpage, if necessary.
--- ---
--- @param window integer Window handle --- @param window integer `window-ID` to focus
function vim.api.nvim_set_current_win(window) end function vim.api.nvim_set_current_win(window) end
--- Set or change decoration provider for a `namespace` --- Set or change decoration provider for a `namespace`
@ -2305,52 +2305,52 @@ function vim.api.nvim_strwidth(text) end
--- Removes a tab-scoped (t:) variable --- Removes a tab-scoped (t:) variable
--- ---
--- @param tabpage integer Tabpage handle, or 0 for current tabpage --- @param tabpage integer `tab-ID`, or 0 for current tabpage
--- @param name string Variable name --- @param name string Variable name
function vim.api.nvim_tabpage_del_var(tabpage, name) end function vim.api.nvim_tabpage_del_var(tabpage, name) end
--- Gets the tabpage number --- Gets the tabpage number
--- ---
--- @param tabpage integer Tabpage handle, or 0 for current tabpage --- @param tabpage integer `tab-ID`, or 0 for current tabpage
--- @return integer # Tabpage number --- @return integer # Tabpage number
function vim.api.nvim_tabpage_get_number(tabpage) end function vim.api.nvim_tabpage_get_number(tabpage) end
--- Gets a tab-scoped (t:) variable --- Gets a tab-scoped (t:) variable
--- ---
--- @param tabpage integer Tabpage handle, or 0 for current tabpage --- @param tabpage integer `tab-ID`, or 0 for current tabpage
--- @param name string Variable name --- @param name string Variable name
--- @return any # Variable value --- @return any # Variable value
function vim.api.nvim_tabpage_get_var(tabpage, name) end function vim.api.nvim_tabpage_get_var(tabpage, name) end
--- Gets the current window in a tabpage --- Gets the current window in a tabpage
--- ---
--- @param tabpage integer Tabpage handle, or 0 for current tabpage --- @param tabpage integer `tab-ID`, or 0 for current tabpage
--- @return integer # Window handle --- @return integer # |window-ID|
function vim.api.nvim_tabpage_get_win(tabpage) end function vim.api.nvim_tabpage_get_win(tabpage) end
--- Checks if a tabpage is valid --- Checks if a tabpage is valid
--- ---
--- @param tabpage integer Tabpage handle, or 0 for current tabpage --- @param tabpage integer `tab-ID`, or 0 for current tabpage
--- @return boolean # true if the tabpage is valid, false otherwise --- @return boolean # true if the tabpage is valid, false otherwise
function vim.api.nvim_tabpage_is_valid(tabpage) end function vim.api.nvim_tabpage_is_valid(tabpage) end
--- Gets the windows in a tabpage --- Gets the windows in a tabpage
--- ---
--- @param tabpage integer Tabpage handle, or 0 for current tabpage --- @param tabpage integer `tab-ID`, or 0 for current tabpage
--- @return integer[] # List of windows in `tabpage` --- @return integer[] # List of windows in `tabpage`
function vim.api.nvim_tabpage_list_wins(tabpage) end function vim.api.nvim_tabpage_list_wins(tabpage) end
--- Sets a tab-scoped (t:) variable --- Sets a tab-scoped (t:) variable
--- ---
--- @param tabpage integer Tabpage handle, or 0 for current tabpage --- @param tabpage integer `tab-ID`, or 0 for current tabpage
--- @param name string Variable name --- @param name string Variable name
--- @param value any Variable value --- @param value any Variable value
function vim.api.nvim_tabpage_set_var(tabpage, name, value) end function vim.api.nvim_tabpage_set_var(tabpage, name, value) end
--- Sets the current window in a tabpage --- Sets the current window in a tabpage
--- ---
--- @param tabpage integer Tabpage handle, or 0 for current tabpage --- @param tabpage integer `tab-ID`, or 0 for current tabpage
--- @param win integer Window handle, must already belong to {tabpage} --- @param win integer `window-ID`, must already belong to {tabpage}
function vim.api.nvim_tabpage_set_win(tabpage, win) end function vim.api.nvim_tabpage_set_win(tabpage, win) end
--- Calls a function with window as temporary current window. --- Calls a function with window as temporary current window.
@ -2358,7 +2358,7 @@ function vim.api.nvim_tabpage_set_win(tabpage, win) end
--- ---
--- @see `:help win_execute()` --- @see `:help win_execute()`
--- @see vim.api.nvim_buf_call --- @see vim.api.nvim_buf_call
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @param fun function Function to call inside the window (currently Lua callable --- @param fun function Function to call inside the window (currently Lua callable
--- only) --- only)
--- @return any # Return value of function. --- @return any # Return value of function.
@ -2366,7 +2366,7 @@ function vim.api.nvim_win_call(window, fun) end
--- Closes the window (like `:close` with a `window-ID`). --- Closes the window (like `:close` with a `window-ID`).
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @param force boolean Behave like `:close!` The last window of a buffer with --- @param force boolean Behave like `:close!` The last window of a buffer with
--- unwritten changes can be closed. The buffer will become --- unwritten changes can be closed. The buffer will become
--- hidden, even if 'hidden' is not set. --- hidden, even if 'hidden' is not set.
@ -2374,13 +2374,13 @@ function vim.api.nvim_win_close(window, force) end
--- Removes a window-scoped (w:) variable --- Removes a window-scoped (w:) variable
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @param name string Variable name --- @param name string Variable name
function vim.api.nvim_win_del_var(window, name) end function vim.api.nvim_win_del_var(window, name) end
--- Gets the current buffer in a window --- Gets the current buffer in a window
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @return integer # Buffer handle --- @return integer # Buffer handle
function vim.api.nvim_win_get_buf(window) end function vim.api.nvim_win_get_buf(window) end
@ -2390,7 +2390,7 @@ function vim.api.nvim_win_get_buf(window) end
--- ---
--- `relative` is empty for normal windows. --- `relative` is empty for normal windows.
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @return vim.api.keyset.win_config # Map defining the window configuration, see |nvim_open_win()| --- @return vim.api.keyset.win_config # Map defining the window configuration, see |nvim_open_win()|
function vim.api.nvim_win_get_config(window) end function vim.api.nvim_win_get_config(window) end
@ -2400,19 +2400,19 @@ function vim.api.nvim_win_get_config(window) end
--- ---
--- ---
--- @see `:help getcurpos()` --- @see `:help getcurpos()`
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @return integer[] # (row, col) tuple --- @return integer[] # (row, col) tuple
function vim.api.nvim_win_get_cursor(window) end function vim.api.nvim_win_get_cursor(window) end
--- Gets the window height --- Gets the window height
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @return integer # Height as a count of rows --- @return integer # Height as a count of rows
function vim.api.nvim_win_get_height(window) end function vim.api.nvim_win_get_height(window) end
--- Gets the window number --- Gets the window number
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @return integer # Window number --- @return integer # Window number
function vim.api.nvim_win_get_number(window) end function vim.api.nvim_win_get_number(window) end
@ -2424,26 +2424,26 @@ function vim.api.nvim_win_get_option(window, name) end
--- Gets the window position in display cells. First position is zero. --- Gets the window position in display cells. First position is zero.
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @return integer[] # (row, col) tuple with the window position --- @return integer[] # (row, col) tuple with the window position
function vim.api.nvim_win_get_position(window) end function vim.api.nvim_win_get_position(window) end
--- Gets the window tabpage --- Gets the window tabpage
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @return integer # Tabpage that contains the window --- @return integer # Tabpage that contains the window
function vim.api.nvim_win_get_tabpage(window) end function vim.api.nvim_win_get_tabpage(window) end
--- Gets a window-scoped (w:) variable --- Gets a window-scoped (w:) variable
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @param name string Variable name --- @param name string Variable name
--- @return any # Variable value --- @return any # Variable value
function vim.api.nvim_win_get_var(window, name) end function vim.api.nvim_win_get_var(window, name) end
--- Gets the window width --- Gets the window width
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @return integer # Width as a count of columns --- @return integer # Width as a count of columns
function vim.api.nvim_win_get_width(window) end function vim.api.nvim_win_get_width(window) end
@ -2454,18 +2454,18 @@ function vim.api.nvim_win_get_width(window) end
--- or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to `:close` or --- or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to `:close` or
--- `nvim_win_close()`, which will close the buffer. --- `nvim_win_close()`, which will close the buffer.
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
function vim.api.nvim_win_hide(window) end function vim.api.nvim_win_hide(window) end
--- Checks if a window is valid --- Checks if a window is valid
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @return boolean # true if the window is valid, false otherwise --- @return boolean # true if the window is valid, false otherwise
function vim.api.nvim_win_is_valid(window) end function vim.api.nvim_win_is_valid(window) end
--- Sets the current buffer in a window, without side effects --- Sets the current buffer in a window, without side effects
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @param buffer integer Buffer handle --- @param buffer integer Buffer handle
function vim.api.nvim_win_set_buf(window, buffer) end function vim.api.nvim_win_set_buf(window, buffer) end
@ -2477,7 +2477,7 @@ function vim.api.nvim_win_set_buf(window, buffer) end
--- ---
--- ---
--- @see vim.api.nvim_open_win --- @see vim.api.nvim_open_win
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @param config vim.api.keyset.win_config Map defining the window configuration, --- @param config vim.api.keyset.win_config Map defining the window configuration,
--- see `nvim_open_win()` --- see `nvim_open_win()`
function vim.api.nvim_win_set_config(window, config) end function vim.api.nvim_win_set_config(window, config) end
@ -2485,13 +2485,13 @@ function vim.api.nvim_win_set_config(window, config) end
--- Sets the (1,0)-indexed cursor position in the window. `api-indexing` --- Sets the (1,0)-indexed cursor position in the window. `api-indexing`
--- This scrolls the window even if it is not the current one. --- This scrolls the window even if it is not the current one.
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @param pos integer[] (row, col) tuple representing the new position --- @param pos integer[] (row, col) tuple representing the new position
function vim.api.nvim_win_set_cursor(window, pos) end function vim.api.nvim_win_set_cursor(window, pos) end
--- Sets the window height. --- Sets the window height.
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @param height integer Height as a count of rows --- @param height integer Height as a count of rows
function vim.api.nvim_win_set_height(window, height) end function vim.api.nvim_win_set_height(window, height) end
@ -2513,7 +2513,7 @@ function vim.api.nvim_win_set_option(window, name, value) end
--- Sets a window-scoped (w:) variable --- Sets a window-scoped (w:) variable
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @param name string Variable name --- @param name string Variable name
--- @param value any Variable value --- @param value any Variable value
function vim.api.nvim_win_set_var(window, name, value) end function vim.api.nvim_win_set_var(window, name, value) end
@ -2521,7 +2521,7 @@ function vim.api.nvim_win_set_var(window, name, value) end
--- Sets the window width. This will only succeed if the screen is split --- Sets the window width. This will only succeed if the screen is split
--- vertically. --- vertically.
--- ---
--- @param window integer Window handle, or 0 for current window --- @param window integer `window-ID`, or 0 for current window
--- @param width integer Width as a count of columns --- @param width integer Width as a count of columns
function vim.api.nvim_win_set_width(window, width) end function vim.api.nvim_win_set_width(window, width) end
@ -2537,7 +2537,7 @@ function vim.api.nvim_win_set_width(window, width) end
--- Line indexing is similar to `nvim_buf_get_text()`. --- Line indexing is similar to `nvim_buf_get_text()`.
--- ---
--- @see `:help virtcol()` for text width. --- @see `:help virtcol()` for text width.
--- @param window integer Window handle, or 0 for current window. --- @param window integer `window-ID`, or 0 for current window.
--- @param opts vim.api.keyset.win_text_height Optional parameters: --- @param opts vim.api.keyset.win_text_height Optional parameters:
--- - start_row: Starting line index, 0-based inclusive. --- - start_row: Starting line index, 0-based inclusive.
--- When omitted start at the very top. --- When omitted start at the very top.

6
runtime/lua/vim/lsp/util.lua
View File

@ -1896,7 +1896,7 @@ function M.try_trim_markdown_code_blocks(lines)
return 'markdown' return 'markdown'
end end
---@param window integer?: window handle or 0 for current, defaults to current ---@param window integer?: |window-ID| or 0 for current, defaults to current
---@param position_encoding 'utf-8'|'utf-16'|'utf-32' ---@param position_encoding 'utf-8'|'utf-16'|'utf-32'
local function make_position_param(window, position_encoding) local function make_position_param(window, position_encoding)
window = window or 0 window = window or 0
@ -1915,7 +1915,7 @@ end
--- Creates a `TextDocumentPositionParams` object for the current buffer and cursor position. --- Creates a `TextDocumentPositionParams` object for the current buffer and cursor position.
--- ---
---@param window integer?: window handle or 0 for current, defaults to current ---@param window integer?: |window-ID| or 0 for current, defaults to current
---@param position_encoding 'utf-8'|'utf-16'|'utf-32' ---@param position_encoding 'utf-8'|'utf-16'|'utf-32'
---@return lsp.TextDocumentPositionParams ---@return lsp.TextDocumentPositionParams
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
@ -1974,7 +1974,7 @@ end
--- `textDocument/codeAction`, `textDocument/colorPresentation`, --- `textDocument/codeAction`, `textDocument/colorPresentation`,
--- `textDocument/rangeFormatting`. --- `textDocument/rangeFormatting`.
--- ---
---@param window integer? window handle or 0 for current, defaults to current ---@param window integer?: |window-ID| or 0 for current, defaults to current
---@param position_encoding "utf-8"|"utf-16"|"utf-32" ---@param position_encoding "utf-8"|"utf-16"|"utf-32"
---@return { textDocument: { uri: lsp.DocumentUri }, range: lsp.Range } ---@return { textDocument: { uri: lsp.DocumentUri }, range: lsp.Range }
function M.make_range_params(window, position_encoding) function M.make_range_params(window, position_encoding)

2
runtime/lua/vim/treesitter.lua
View File

@ -306,7 +306,7 @@ end
--- Returns a list of highlight capture names under the cursor --- Returns a list of highlight capture names under the cursor
--- ---
---@param winnr (integer|nil) Window handle or 0 for current window (default) ---@param winnr (integer|nil): |window-ID| or 0 for current window (default)
--- ---
---@return string[] List of capture names ---@return string[] List of capture names
function M.get_captures_at_cursor(winnr) function M.get_captures_at_cursor(winnr)

12
src/nvim/api/deprecated.c
View File

@ -488,7 +488,7 @@ Object buffer_del_var(Buffer buffer, String name, Arena *arena, Error *err)
/// ///
/// @deprecated /// @deprecated
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param name Variable name /// @param name Variable name
/// @param value Variable value /// @param value Variable value
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -512,7 +512,7 @@ Object window_set_var(Window window, String name, Object value, Arena *arena, Er
/// ///
/// @deprecated /// @deprecated
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param name variable name /// @param name variable name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Old value /// @return Old value
@ -532,7 +532,7 @@ Object window_del_var(Window window, String name, Arena *arena, Error *err)
/// ///
/// @deprecated /// @deprecated
/// ///
/// @param tabpage Tabpage handle, or 0 for current tabpage /// @param tabpage |tab-ID|, or 0 for current tabpage
/// @param name Variable name /// @param name Variable name
/// @param value Variable value /// @param value Variable value
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -556,7 +556,7 @@ Object tabpage_set_var(Tabpage tabpage, String name, Object value, Arena *arena,
/// ///
/// @deprecated /// @deprecated
/// ///
/// @param tabpage Tabpage handle, or 0 for current tabpage /// @param tabpage |tab-ID|, or 0 for current tabpage
/// @param name Variable name /// @param name Variable name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Old value /// @return Old value
@ -684,7 +684,7 @@ void nvim_buf_set_option(uint64_t channel_id, Buffer buffer, String name, Object
/// Gets a window option value /// Gets a window option value
/// ///
/// @deprecated /// @deprecated
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param name Option name /// @param name Option name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Option value /// @return Option value
@ -707,7 +707,7 @@ Object nvim_win_get_option(Window window, String name, Error *err)
/// ///
/// @deprecated /// @deprecated
/// @param channel_id /// @param channel_id
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param name Option name /// @param name Option name
/// @param value Option value /// @param value Option value
/// @param[out] err Error details, if any /// @param[out] err Error details, if any

20
src/nvim/api/tabpage.c
View File

@ -17,7 +17,7 @@
/// Gets the windows in a tabpage /// Gets the windows in a tabpage
/// ///
/// @param tabpage Tabpage handle, or 0 for current tabpage /// @param tabpage |tab-ID|, or 0 for current tabpage
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return List of windows in `tabpage` /// @return List of windows in `tabpage`
ArrayOf(Window) nvim_tabpage_list_wins(Tabpage tabpage, Arena *arena, Error *err) ArrayOf(Window) nvim_tabpage_list_wins(Tabpage tabpage, Arena *arena, Error *err)
@ -46,7 +46,7 @@ ArrayOf(Window) nvim_tabpage_list_wins(Tabpage tabpage, Arena *arena, Error *err
/// Gets a tab-scoped (t:) variable /// Gets a tab-scoped (t:) variable
/// ///
/// @param tabpage Tabpage handle, or 0 for current tabpage /// @param tabpage |tab-ID|, or 0 for current tabpage
/// @param name Variable name /// @param name Variable name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Variable value /// @return Variable value
@ -64,7 +64,7 @@ Object nvim_tabpage_get_var(Tabpage tabpage, String name, Arena *arena, Error *e
/// Sets a tab-scoped (t:) variable /// Sets a tab-scoped (t:) variable
/// ///
/// @param tabpage Tabpage handle, or 0 for current tabpage /// @param tabpage |tab-ID|, or 0 for current tabpage
/// @param name Variable name /// @param name Variable name
/// @param value Variable value /// @param value Variable value
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -82,7 +82,7 @@ void nvim_tabpage_set_var(Tabpage tabpage, String name, Object value, Error *err
/// Removes a tab-scoped (t:) variable /// Removes a tab-scoped (t:) variable
/// ///
/// @param tabpage Tabpage handle, or 0 for current tabpage /// @param tabpage |tab-ID|, or 0 for current tabpage
/// @param name Variable name /// @param name Variable name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_tabpage_del_var(Tabpage tabpage, String name, Error *err) void nvim_tabpage_del_var(Tabpage tabpage, String name, Error *err)
@ -99,9 +99,9 @@ void nvim_tabpage_del_var(Tabpage tabpage, String name, Error *err)
/// Gets the current window in a tabpage /// Gets the current window in a tabpage
/// ///
/// @param tabpage Tabpage handle, or 0 for current tabpage /// @param tabpage |tab-ID|, or 0 for current tabpage
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Window handle /// @return |window-ID|
Window nvim_tabpage_get_win(Tabpage tabpage, Error *err) Window nvim_tabpage_get_win(Tabpage tabpage, Error *err)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)
{ {
@ -125,8 +125,8 @@ Window nvim_tabpage_get_win(Tabpage tabpage, Error *err)
/// Sets the current window in a tabpage /// Sets the current window in a tabpage
/// ///
/// @param tabpage Tabpage handle, or 0 for current tabpage /// @param tabpage |tab-ID|, or 0 for current tabpage
/// @param win Window handle, must already belong to {tabpage} /// @param win |window-ID|, must already belong to {tabpage}
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_tabpage_set_win(Tabpage tabpage, Window win, Error *err) void nvim_tabpage_set_win(Tabpage tabpage, Window win, Error *err)
FUNC_API_SINCE(12) FUNC_API_SINCE(12)
@ -158,7 +158,7 @@ void nvim_tabpage_set_win(Tabpage tabpage, Window win, Error *err)
/// Gets the tabpage number /// Gets the tabpage number
/// ///
/// @param tabpage Tabpage handle, or 0 for current tabpage /// @param tabpage |tab-ID|, or 0 for current tabpage
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Tabpage number /// @return Tabpage number
Integer nvim_tabpage_get_number(Tabpage tabpage, Error *err) Integer nvim_tabpage_get_number(Tabpage tabpage, Error *err)
@ -175,7 +175,7 @@ Integer nvim_tabpage_get_number(Tabpage tabpage, Error *err)
/// Checks if a tabpage is valid /// Checks if a tabpage is valid
/// ///
/// @param tabpage Tabpage handle, or 0 for current tabpage /// @param tabpage |tab-ID|, or 0 for current tabpage
/// @return true if the tabpage is valid, false otherwise /// @return true if the tabpage is valid, false otherwise
Boolean nvim_tabpage_is_valid(Tabpage tabpage) Boolean nvim_tabpage_is_valid(Tabpage tabpage)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)

20
src/nvim/api/vim.c
View File

@ -661,7 +661,7 @@ String nvim_get_current_line(Arena *arena, Error *err)
return buffer_get_line(curbuf->handle, curwin->w_cursor.lnum - 1, arena, err); return buffer_get_line(curbuf->handle, curwin->w_cursor.lnum - 1, arena, err);
} }
/// Sets the current line. /// Sets the text on the current line.
/// ///
/// @param line Line contents /// @param line Line contents
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -823,7 +823,7 @@ Buffer nvim_get_current_buf(void)
return curbuf->handle; return curbuf->handle;
} }
/// Sets the current buffer. /// Sets the current window's buffer to `buffer`.
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -844,7 +844,7 @@ void nvim_set_current_buf(Buffer buffer, Error *err)
/// Gets the current list of window handles. /// Gets the current list of window handles.
/// ///
/// @return List of window handles /// @return List of |window-ID|s
ArrayOf(Window) nvim_list_wins(Arena *arena) ArrayOf(Window) nvim_list_wins(Arena *arena)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)
{ {
@ -865,16 +865,16 @@ ArrayOf(Window) nvim_list_wins(Arena *arena)
/// Gets the current window. /// Gets the current window.
/// ///
/// @return Window handle /// @return |window-ID|
Window nvim_get_current_win(void) Window nvim_get_current_win(void)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)
{ {
return curwin->handle; return curwin->handle;
} }
/// Sets the current window. /// Sets the current window. Also changes tabpage, if necessary.
/// ///
/// @param window Window handle /// @param window |window-ID| to focus
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_set_current_win(Window window, Error *err) void nvim_set_current_win(Window window, Error *err)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)
@ -1106,9 +1106,9 @@ void nvim_chan_send(Integer chan, String data, Error *err)
VALIDATE(!error, "%s", error, {}); VALIDATE(!error, "%s", error, {});
} }
/// Gets the current list of tabpage handles. /// Gets the current list of |tab-ID|s.
/// ///
/// @return List of tabpage handles /// @return List of |tab-ID|s
ArrayOf(Tabpage) nvim_list_tabpages(Arena *arena) ArrayOf(Tabpage) nvim_list_tabpages(Arena *arena)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)
{ {
@ -1129,7 +1129,7 @@ ArrayOf(Tabpage) nvim_list_tabpages(Arena *arena)
/// Gets the current tabpage. /// Gets the current tabpage.
/// ///
/// @return Tabpage handle /// @return |tab-ID|
Tabpage nvim_get_current_tabpage(void) Tabpage nvim_get_current_tabpage(void)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)
{ {
@ -1138,7 +1138,7 @@ Tabpage nvim_get_current_tabpage(void)
/// Sets the current tabpage. /// Sets the current tabpage.
/// ///
/// @param tabpage Tabpage handle /// @param tabpage |tab-ID| to focus
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_set_current_tabpage(Tabpage tabpage, Error *err) void nvim_set_current_tabpage(Tabpage tabpage, Error *err)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)

6
src/nvim/api/win_config.c
View File

@ -214,7 +214,7 @@
/// ///
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// ///
/// @return Window handle, or 0 on error /// @return |window-ID|, or 0 on error
Window nvim_open_win(Buffer buffer, Boolean enter, Dict(win_config) *config, Error *err) Window nvim_open_win(Buffer buffer, Boolean enter, Dict(win_config) *config, Error *err)
FUNC_API_SINCE(6) FUNC_API_TEXTLOCK_ALLOW_CMDWIN FUNC_API_SINCE(6) FUNC_API_TEXTLOCK_ALLOW_CMDWIN
{ {
@ -387,7 +387,7 @@ static int win_split_flags(WinSplit split, bool toplevel)
/// ///
/// @see |nvim_open_win()| /// @see |nvim_open_win()|
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param config Map defining the window configuration, /// @param config Map defining the window configuration,
/// see |nvim_open_win()| /// see |nvim_open_win()|
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -694,7 +694,7 @@ static void config_put_bordertext(Dict(win_config) *config, WinConfig *fconfig,
/// ///
/// `relative` is empty for normal windows. /// `relative` is empty for normal windows.
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Map defining the window configuration, see |nvim_open_win()| /// @return Map defining the window configuration, see |nvim_open_win()|
Dict(win_config) nvim_win_get_config(Window window, Arena *arena, Error *err) Dict(win_config) nvim_win_get_config(Window window, Arena *arena, Error *err)

38
src/nvim/api/window.c
View File

@ -32,7 +32,7 @@
/// Gets the current buffer in a window /// Gets the current buffer in a window
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Buffer handle /// @return Buffer handle
Buffer nvim_win_get_buf(Window window, Error *err) Buffer nvim_win_get_buf(Window window, Error *err)
@ -49,7 +49,7 @@ Buffer nvim_win_get_buf(Window window, Error *err)
/// Sets the current buffer in a window, without side effects /// Sets the current buffer in a window, without side effects
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param buffer Buffer handle /// @param buffer Buffer handle
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_win_set_buf(Window window, Buffer buffer, Error *err) void nvim_win_set_buf(Window window, Buffer buffer, Error *err)
@ -75,7 +75,7 @@ void nvim_win_set_buf(Window window, Buffer buffer, Error *err)
/// ///
/// @see |getcurpos()| /// @see |getcurpos()|
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return (row, col) tuple /// @return (row, col) tuple
ArrayOf(Integer, 2) nvim_win_get_cursor(Window window, Arena *arena, Error *err) ArrayOf(Integer, 2) nvim_win_get_cursor(Window window, Arena *arena, Error *err)
@ -96,7 +96,7 @@ ArrayOf(Integer, 2) nvim_win_get_cursor(Window window, Arena *arena, Error *err)
/// Sets the (1,0)-indexed cursor position in the window. |api-indexing| /// Sets the (1,0)-indexed cursor position in the window. |api-indexing|
/// This scrolls the window even if it is not the current one. /// This scrolls the window even if it is not the current one.
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param pos (row, col) tuple representing the new position /// @param pos (row, col) tuple representing the new position
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_win_set_cursor(Window window, ArrayOf(Integer, 2) pos, Error *err) void nvim_win_set_cursor(Window window, ArrayOf(Integer, 2) pos, Error *err)
@ -152,7 +152,7 @@ void nvim_win_set_cursor(Window window, ArrayOf(Integer, 2) pos, Error *err)
/// Gets the window height /// Gets the window height
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Height as a count of rows /// @return Height as a count of rows
Integer nvim_win_get_height(Window window, Error *err) Integer nvim_win_get_height(Window window, Error *err)
@ -169,7 +169,7 @@ Integer nvim_win_get_height(Window window, Error *err)
/// Sets the window height. /// Sets the window height.
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param height Height as a count of rows /// @param height Height as a count of rows
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_win_set_height(Window window, Integer height, Error *err) void nvim_win_set_height(Window window, Integer height, Error *err)
@ -188,7 +188,7 @@ void nvim_win_set_height(Window window, Integer height, Error *err)
/// Gets the window width /// Gets the window width
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Width as a count of columns /// @return Width as a count of columns
Integer nvim_win_get_width(Window window, Error *err) Integer nvim_win_get_width(Window window, Error *err)
@ -206,7 +206,7 @@ Integer nvim_win_get_width(Window window, Error *err)
/// Sets the window width. This will only succeed if the screen is split /// Sets the window width. This will only succeed if the screen is split
/// vertically. /// vertically.
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param width Width as a count of columns /// @param width Width as a count of columns
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_win_set_width(Window window, Integer width, Error *err) void nvim_win_set_width(Window window, Integer width, Error *err)
@ -225,7 +225,7 @@ void nvim_win_set_width(Window window, Integer width, Error *err)
/// Gets a window-scoped (w:) variable /// Gets a window-scoped (w:) variable
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param name Variable name /// @param name Variable name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Variable value /// @return Variable value
@ -243,7 +243,7 @@ Object nvim_win_get_var(Window window, String name, Arena *arena, Error *err)
/// Sets a window-scoped (w:) variable /// Sets a window-scoped (w:) variable
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param name Variable name /// @param name Variable name
/// @param value Variable value /// @param value Variable value
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -261,7 +261,7 @@ void nvim_win_set_var(Window window, String name, Object value, Error *err)
/// Removes a window-scoped (w:) variable /// Removes a window-scoped (w:) variable
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param name Variable name /// @param name Variable name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_win_del_var(Window window, String name, Error *err) void nvim_win_del_var(Window window, String name, Error *err)
@ -278,7 +278,7 @@ void nvim_win_del_var(Window window, String name, Error *err)
/// Gets the window position in display cells. First position is zero. /// Gets the window position in display cells. First position is zero.
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return (row, col) tuple with the window position /// @return (row, col) tuple with the window position
ArrayOf(Integer, 2) nvim_win_get_position(Window window, Arena *arena, Error *err) ArrayOf(Integer, 2) nvim_win_get_position(Window window, Arena *arena, Error *err)
@ -298,7 +298,7 @@ ArrayOf(Integer, 2) nvim_win_get_position(Window window, Arena *arena, Error *er
/// Gets the window tabpage /// Gets the window tabpage
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Tabpage that contains the window /// @return Tabpage that contains the window
Tabpage nvim_win_get_tabpage(Window window, Error *err) Tabpage nvim_win_get_tabpage(Window window, Error *err)
@ -316,7 +316,7 @@ Tabpage nvim_win_get_tabpage(Window window, Error *err)
/// Gets the window number /// Gets the window number
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Window number /// @return Window number
Integer nvim_win_get_number(Window window, Error *err) Integer nvim_win_get_number(Window window, Error *err)
@ -337,7 +337,7 @@ Integer nvim_win_get_number(Window window, Error *err)
/// Checks if a window is valid /// Checks if a window is valid
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @return true if the window is valid, false otherwise /// @return true if the window is valid, false otherwise
Boolean nvim_win_is_valid(Window window) Boolean nvim_win_is_valid(Window window)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)
@ -355,7 +355,7 @@ Boolean nvim_win_is_valid(Window window)
/// or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to |:close| or /// or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to |:close| or
/// |nvim_win_close()|, which will close the buffer. /// |nvim_win_close()|, which will close the buffer.
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_win_hide(Window window, Error *err) void nvim_win_hide(Window window, Error *err)
FUNC_API_SINCE(7) FUNC_API_SINCE(7)
@ -381,7 +381,7 @@ void nvim_win_hide(Window window, Error *err)
/// Closes the window (like |:close| with a |window-ID|). /// Closes the window (like |:close| with a |window-ID|).
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param force Behave like `:close!` The last window of a buffer with /// @param force Behave like `:close!` The last window of a buffer with
/// unwritten changes can be closed. The buffer will become /// unwritten changes can be closed. The buffer will become
/// hidden, even if 'hidden' is not set. /// hidden, even if 'hidden' is not set.
@ -406,7 +406,7 @@ void nvim_win_close(Window window, Boolean force, Error *err)
/// @see |win_execute()| /// @see |win_execute()|
/// @see |nvim_buf_call()| /// @see |nvim_buf_call()|
/// ///
/// @param window Window handle, or 0 for current window /// @param window |window-ID|, or 0 for current window
/// @param fun Function to call inside the window (currently Lua callable /// @param fun Function to call inside the window (currently Lua callable
/// only) /// only)
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -472,7 +472,7 @@ void nvim_win_set_hl_ns(Window window, Integer ns_id, Error *err)
/// ///
/// Line indexing is similar to |nvim_buf_get_text()|. /// Line indexing is similar to |nvim_buf_get_text()|.
/// ///
/// @param window Window handle, or 0 for current window. /// @param window |window-ID|, or 0 for current window.
/// @param opts Optional parameters: /// @param opts Optional parameters:
/// - start_row: Starting line index, 0-based inclusive. /// - start_row: Starting line index, 0-based inclusive.
/// When omitted start at the very top. /// When omitted start at the very top.