diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 631 |
1 files changed, 398 insertions, 233 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index df345e4981..1573bec7ac 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -130,7 +130,9 @@ end of a range, -1 denotes the last line/column. Exception: the following API functions use "mark-like" indexing (1-based lines, 0-based columns): + |nvim_get_mark()| |nvim_buf_get_mark()| + |nvim_buf_set_mark()| |nvim_win_get_cursor()| |nvim_win_set_cursor()| @@ -529,6 +531,20 @@ nvim__get_hl_defs({ns_id}) *nvim__get_hl_defs()* nvim__get_lib_dir() *nvim__get_lib_dir()* TODO: Documentation +nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* + Find files in runtime directories + + Attributes: ~ + {fast} + + Parameters: ~ + {pat} pattern of files to search for + {all} whether to return all matches or only the first + {options} is_lua: only search lua subdirs + + Return: ~ + list of absolute paths to the found files + nvim__id({obj}) *nvim__id()* Returns object given as argument. @@ -580,6 +596,9 @@ nvim__id_float({flt}) *nvim__id_float()* nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* TODO: Documentation +nvim__runtime_inspect() *nvim__runtime_inspect()* + TODO: Documentation + nvim__screenshot({path}) *nvim__screenshot()* TODO: Documentation @@ -706,7 +725,7 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* buf_open_scratch nvim_create_namespace({name}) *nvim_create_namespace()* - Creates a new namespace, or gets an existing one. + Creates a new *namespace* or gets an existing one. Namespaces are used for buffer highlights and virtual text, see |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|. @@ -735,6 +754,23 @@ nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* See also: ~ |nvim_set_keymap()| +nvim_del_mark({name}) *nvim_del_mark()* + Deletes a uppercase/file named mark. See |mark-motions|. + + Note: + fails with error if a lowercase or buffer local named mark + is used. + + Parameters: ~ + {name} Mark name + + Return: ~ + true if the mark was deleted, else false. + + See also: ~ + |nvim_buf_del_mark()| + |nvim_get_mark()| + nvim_del_var({name}) *nvim_del_var()* Removes a global (g:) variable. @@ -783,6 +819,39 @@ nvim_eval({expr}) *nvim_eval()* Return: ~ Evaluation result or expanded object +nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* + Evaluates statusline string. + + Attributes: ~ + {fast} + + Parameters: ~ + {str} Statusline string (see 'statusline'). + {opts} Optional parameters. + • winid: (number) |window-ID| of the window to use + as context for statusline. + • maxwidth: (number) Maximum width of statusline. + • fillchar: (string) Character to fill blank + spaces in the statusline (see 'fillchars'). + • highlights: (boolean) Return highlight + information. + • use_tabline: (boolean) Evaluate tabline instead + of statusline. When |TRUE|, {winid} is ignored. + + Return: ~ + Dictionary containing statusline information, with these + keys: + • str: (string) Characters that will be displayed on the + statusline. + • width: (number) Display width of the statusline. + • highlights: Array containing highlight information of + the statusline. Only included when the "highlights" key + in {opts} is |TRUE|. Each element of the array is a + |Dictionary| with these keys: + • start: (number) Byte index (0-based) of first + character that uses the highlight. + • group: (string) Name of highlight group. + nvim_exec({src}, {output}) *nvim_exec()* Executes Vimscript (multiline block of Ex-commands), like anonymous |:source|. @@ -828,7 +897,7 @@ nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* On execution error: does not fail, but updates v:errmsg. To input sequences like <C-o> use |nvim_replace_termcodes()| - (typically with escape_csi=true) to replace the keycodes. Then + (typically with escape_csi=true) to replace |keycodes|, then pass the result to nvim_feedkeys(). Example: > @@ -866,32 +935,33 @@ nvim_get_api_info() *nvim_get_api_info()* {fast} nvim_get_chan_info({chan}) *nvim_get_chan_info()* - Get information about a channel. + Gets information about a channel. Return: ~ Dictionary describing a channel, with these keys: - • "stream" the stream underlying the channel + • "id" Channel id. + • "argv" (optional) Job arguments list. + • "stream" Stream underlying the channel. • "stdio" stdin and stdout of this Nvim instance • "stderr" stderr of this Nvim instance • "socket" TCP/IP socket or named pipe - • "job" job with communication over its stdio - - • "mode" how data received on the channel is interpreted - • "bytes" send and receive raw bytes - • "terminal" a |terminal| instance interprets ASCII - sequences - • "rpc" |RPC| communication on the channel is active - - • "pty" Name of pseudoterminal, if one is used (optional). - On a POSIX system, this will be a device path like - /dev/pts/1. Even if the name is unknown, the key will - still be present to indicate a pty is used. This is - currently the case when using winpty on windows. - • "buffer" buffer with connected |terminal| instance - (optional) - • "client" information about the client on the other end - of the RPC channel, if it has added it using - |nvim_set_client_info()|. (optional) + • "job" Job with communication over its stdio. + + • "mode" How data received on the channel is interpreted. + • "bytes" Send and receive raw bytes. + • "terminal" |terminal| instance interprets ASCII + sequences. + • "rpc" |RPC| communication on the channel is active. + + • "pty" (optional) Name of pseudoterminal. On a POSIX + system this is a device path like "/dev/pts/1". If the + name is unknown, the key will still be present if a pty + is used (e.g. for winpty on Windows). + • "buffer" (optional) Buffer with connected |terminal| + instance. + • "client" (optional) Info about the peer (client on the + other end of the RPC channel), if provided by it via + |nvim_set_client_info()|. nvim_get_color_by_name({name}) *nvim_get_color_by_name()* Returns the 24-bit RGB value of a |nvim_get_color_map()| color @@ -917,7 +987,7 @@ nvim_get_color_map() *nvim_get_color_map()* Return: ~ Map of color names and RGB values. -nvim_get_commands({opts}) *nvim_get_commands()* +nvim_get_commands({*opts}) *nvim_get_commands()* Gets a map of global (non-buffer-local) Ex commands. Currently only |user-commands| are supported, not builtin Ex @@ -930,7 +1000,7 @@ nvim_get_commands({opts}) *nvim_get_commands()* Return: ~ Map of maps describing commands. -nvim_get_context({opts}) *nvim_get_context()* +nvim_get_context({*opts}) *nvim_get_context()* Gets a map of the current editor state. Parameters: ~ @@ -1008,6 +1078,27 @@ nvim_get_keymap({mode}) *nvim_get_keymap()* Array of maparg()-like dictionaries describing mappings. The "buffer" key is always zero. +nvim_get_mark({name}) *nvim_get_mark()* + Return a tuple (row, col, buffer, buffername) representing the + position of the uppercase/file named mark. See |mark-motions|. + + Marks are (1,0)-indexed. |api-indexing| + + Note: + fails with error if a lowercase or buffer local named mark + is used. + + Parameters: ~ + {name} Mark name + + Return: ~ + 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if + the mark is not set. + + See also: ~ + |nvim_buf_set_mark()| + |nvim_del_mark()| + nvim_get_mode() *nvim_get_mode()* Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for input. @@ -1079,10 +1170,6 @@ nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()* It is not an error to not find any files. An empty array is returned then. - To find a directory, `name` must end with a forward slash, - like "rplugin/python/". Without the slash it would instead - look for an ordinary file called "rplugin/python". - Attributes: ~ {fast} @@ -1251,7 +1338,7 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* For instance, for a floating display, first create an empty buffer using |nvim_create_buf()|, then display it using |nvim_open_win()|, and then call this function. Then - |nvim_chan_send()| cal be called immediately to process + |nvim_chan_send()| can be called immediately to process sequences in a virtual terminal having the intended size. Parameters: ~ @@ -1261,156 +1348,6 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* Return: ~ Channel id, or 0 on error -nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* - Open a new window. - - Currently this is used to open floating and external windows. - Floats are windows that are drawn above the split layout, at - some anchor position in some other window. Floats can be drawn - internally or by external GUI with the |ui-multigrid| - extension. External windows are only supported with multigrid - GUIs, and are displayed as separate top-level windows. - - For a general overview of floats, see |api-floatwin|. - - Exactly one of `external` and `relative` must be specified. - The `width` and `height` of the new window must be specified. - - With relative=editor (row=0,col=0) refers to the top-left - corner of the screen-grid and (row=Lines-1,col=Columns-1) - refers to the bottom-right corner. Fractional values are - allowed, but the builtin implementation (used by non-multigrid - UIs) will always round down to nearest integer. - - Out-of-bounds values, and configurations that make the float - not fit inside the main editor, are allowed. The builtin - implementation truncates values so floats are fully within the - main screen grid. External GUIs could let floats hover outside - of the main window like a tooltip, but this should not be used - to specify arbitrary WM screen positions. - - Example (Lua): window-relative float > - vim.api.nvim_open_win(0, false, - {relative='win', row=3, col=3, width=12, height=3}) -< - - Example (Lua): buffer-relative float (travels as buffer is - scrolled) > - vim.api.nvim_open_win(0, false, - {relative='win', width=12, height=3, bufpos={100,10}}) -< - - Attributes: ~ - not allowed when |textlock| is active - - Parameters: ~ - {buffer} Buffer to display, or 0 for current buffer - {enter} Enter the window (make it the current window) - {config} Map defining the window configuration. Keys: - • `relative`: Sets the window layout to "floating", placed - at (row,col) coordinates relative to: - • "editor" The global editor grid - • "win" Window given by the `win` field, or - current window. - • "cursor" Cursor position in current window. - - • `win` : |window-ID| for relative="win". - • `anchor`: Decides which corner of the float to place - at (row,col): - • "NW" northwest (default) - • "NE" northeast - • "SW" southwest - • "SE" southeast - - • `width` : Window width (in character cells). - Minimum of 1. - • `height` : Window height (in character cells). - Minimum of 1. - • `bufpos` : Places float relative to buffer - text (only when relative="win"). Takes a tuple - of zero-indexed [line, column]. `row` and - `col` if given are applied relative to this - position, else they default to `row=1` and - `col=0` (thus like a tooltip near the buffer - text). - • `row` : Row position in units of "screen cell - height", may be fractional. - • `col` : Column position in units of "screen - cell width", may be fractional. - • `focusable` : Enable focus by user actions - (wincmds, mouse events). Defaults to true. - Non-focusable windows can be entered by - |nvim_set_current_win()|. - • `external` : GUI should display the window as - an external top-level window. Currently - accepts no other positioning configuration - together with this. - • `zindex`: Stacking order. floats with higher`zindex`go on top on floats with lower indices. Must - be larger than zero. The following screen - elements have hard-coded z-indices: - • 100: insert completion popupmenu - • 200: message scrollback - • 250: cmdline completion popupmenu (when - wildoptions+=pum) The default value for - floats are 50. In general, values below 100 - are recommended, unless there is a good - reason to overshadow builtin elements. - - • `style`: Configure the appearance of the window. - Currently only takes one non-empty value: - • "minimal" Nvim will display the window with - many UI options disabled. This is useful - when displaying a temporary float where the - text should not be edited. Disables - 'number', 'relativenumber', 'cursorline', - 'cursorcolumn', 'foldcolumn', 'spell' and - 'list' options. 'signcolumn' is changed to - `auto` and 'colorcolumn' is cleared. The - end-of-buffer region is hidden by setting - `eob` flag of 'fillchars' to a space char, - and clearing the |EndOfBuffer| region in - 'winhighlight'. - - • `border`: Style of (optional) window border. This can - either be a string or an array. The string - values are - • "none": No border (default). - • "single": A single line box. - • "double": A double line box. - • "rounded": Like "single", but with rounded - corners ("╭" etc.). - • "solid": Adds padding by a single whitespace - cell. - • "shadow": A drop shadow effect by blending - with the background. - • If it is an array, it should have a length - of eight or any divisor of eight. The array - will specifify the eight chars building up - the border in a clockwise fashion starting - with the top-left corner. As an example, the - double box style could be specified as [ - "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ]. If - the number of chars are less than eight, - they will be repeated. Thus an ASCII border - could be specified as [ "/", "-", "\\", "|" - ], or all chars the same as [ "x" ]. An - empty string can be used to turn off a - specific border, for instance, [ "", "", "", - ">", "", "", "", "<" ] will only make - vertical borders but not horizontal ones. By - default, `FloatBorder` highlight is used, - which links to `VertSplit` when not defined. - It could also be specified by character: [ - {"+", "MyCorner"}, {"x", "MyBorder"} ]. - - • `noautocmd` : If true then no buffer-related - autocommand events such as |BufEnter|, - |BufLeave| or |BufWinEnter| may fire from - calling this function. - - Return: ~ - Window handle, or 0 on error - nvim_out_write({str}) *nvim_out_write()* Writes a message to the Vim output buffer. Does not append "\n", the message is buffered (won't display) until a linefeed @@ -1779,7 +1716,7 @@ nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()* default cterm attributes are same as attributes of gui color -nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* +nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* Sets a global |mapping| for the given mode. To set a buffer-local mapping, use |nvim_buf_set_keymap()|. @@ -1940,7 +1877,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* callbacks. {opts} Optional parameters. • on_lines: Lua callback invoked on change. - Return`true`to detach. Args: + Return `true` to detach. Args: • the string "lines" • buffer handle • b:changedtick @@ -1956,7 +1893,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • on_bytes: lua callback invoked on change. This callback receives more granular information about the change compared to - on_lines. Return`true`to detach. Args: + on_lines. Return `true` to detach. Args: • the string "bytes" • buffer handle • b:changedtick @@ -2063,6 +2000,24 @@ nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* See also: ~ |nvim_del_keymap()| +nvim_buf_del_mark({buffer}, {name}) *nvim_buf_del_mark()* + Deletes a named mark in the buffer. See |mark-motions|. + + Note: + only deletes marks set in the buffer, if the mark is not + set in the buffer it will return false. + + Parameters: ~ + {buffer} Buffer to set the mark on + {name} Mark name + + Return: ~ + true if the mark was deleted, else false. + + See also: ~ + |nvim_buf_set_mark()| + |nvim_del_mark()| + nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* Removes a buffer-scoped (b:) variable @@ -2107,7 +2062,7 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* Return: ~ `b:changedtick` value. -nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* +nvim_buf_get_commands({buffer}, {*opts}) *nvim_buf_get_commands()* Gets a map of buffer-local |user-commands|. Parameters: ~ @@ -2119,7 +2074,7 @@ nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* *nvim_buf_get_extmark_by_id()* nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts}) - Gets the position (0-indexed) of an extmark {id}. + Gets the position (0-indexed) of an extmark. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -2170,12 +2125,12 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace id from |nvim_create_namespace()| - {start} Start of range, given as 0-indexed (row, col) or - valid extmark id (whose position defines the - bound) - {end} End of range (inclusive), given as 0-indexed - (row, col) or valid extmark id (whose position - defines the bound) + {start} Start of range: a 0-indexed (row, col) or valid + extmark id (whose position defines the bound). + |api-indexing| + {end} End of range (inclusive): a 0-indexed (row, col) + or valid extmark id (whose position defines the + bound). |api-indexing| {opts} Optional parameters. Keys: • limit: Maximum number of marks to return • details Whether to include the details dict @@ -2217,8 +2172,8 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) Array of lines, or empty array for unloaded buffer. nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* - Return a tuple (row,col) representing the position of the - named mark. + Returns a tuple (row,col) representing the position of the + named mark. See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| @@ -2227,7 +2182,12 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* {name} Mark name Return: ~ - (row, col) tuple + (row, col) tuple, (0, 0) if the mark is not set, or is an + uppercase/file mark set in another buffer. + + See also: ~ + |nvim_buf_set_mark()| + |nvim_buf_del_mark()| nvim_buf_get_name({buffer}) *nvim_buf_get_name()* Gets the full file name for the buffer @@ -2310,7 +2270,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* Line count, or 0 for unloaded buffer. |api-buffer| *nvim_buf_set_extmark()* -nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) +nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) Creates or updates an extmark. To create a new extmark, pass id=0. The extmark id will be @@ -2328,8 +2288,10 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace id from |nvim_create_namespace()| - {line} Line where to place the mark, 0-based - {col} Column where to place the mark, 0-based + {line} Line where to place the mark, 0-based. + |api-indexing| + {col} Column where to place the mark, 0-based. + |api-indexing| {opts} Optional parameters. • id : id of the extmark to edit. • end_line : ending line of the mark, 0-based @@ -2338,6 +2300,10 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) exclusive. • hl_group : name of the highlight group used to highlight this mark. + • hl_eol : when true, for a multiline highlight + covering the EOL of a line, continue the + highlight for the rest of the screen line + (just like for diff and cursorline highlight). • virt_text : virtual text to link to this mark. A list of [text, highlight] tuples, each representing a text chunk with specified @@ -2366,17 +2332,35 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) • hl_mode : control how highlights are combined with the highlights of the text. Currently only affects virt_text highlights, but might - affect`hl_group`in later versions. + affect `hl_group` in later versions. • "replace": only show the virt_text color. This is the default • "combine": combine with background text color • "blend": blend with background text color. - • hl_eol : when true, for a multiline highlight - covering the EOL of a line, continue the - highlight for the rest of the screen line - (just like for diff and cursorline highlight). + • virt_lines : virtual lines to add next to this + mark This should be an array over lines, where + each line in turn is an array over [text, + highlight] tuples. In general, buffer and + window options do not affect the display of + the text. In particular 'wrap' and 'linebreak' + options do not take effect, so the number of + extra screen lines will always match the size + of the array. However the 'tabstop' buffer + option is still used for hard tabs. By default + lines are placed below the buffer line + containing the mark. • Note: currently virtual lines are limited to + one block per buffer. Thus setting a new mark + disables any previous `virt_lines` decoration. + However plugins should not rely on this + behaviour, as this limitation is planned to be + removed. + • virt_lines_above: place virtual lines above + instead. + • virt_lines_leftcol: Place extmarks in the + leftmost column of the window, bypassing sign + and number columns. • ephemeral : for use with |nvim_set_decoration_provider| callbacks. The mark will only be used for the current redraw @@ -2399,7 +2383,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) Id of the created/updated extmark *nvim_buf_set_keymap()* -nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts}) +nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {*opts}) Sets a buffer-local |mapping| for the given mode. Parameters: ~ @@ -2435,6 +2419,29 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement}) error. {replacement} Array of lines to use as replacement + *nvim_buf_set_mark()* +nvim_buf_set_mark({buffer}, {name}, {line}, {col}) + Sets a named mark in the given buffer, all marks are allowed + file/uppercase, visual, last change, etc. See |mark-motions|. + + Marks are (1,0)-indexed. |api-indexing| + + Note: + Passing 0 as line deletes the mark + + Parameters: ~ + {buffer} Buffer to set the mark on + {name} Mark name + {line} Line number + {col} Column/row number + + Return: ~ + true if the mark was set, else false. + + See also: ~ + |nvim_buf_del_mark()| + |nvim_buf_get_mark()| + nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* Sets the full file name for a buffer @@ -2534,20 +2541,6 @@ nvim_win_get_buf({window}) *nvim_win_get_buf()* Return: ~ Buffer handle -nvim_win_get_config({window}) *nvim_win_get_config()* - Gets window configuration. - - The returned value may be given to |nvim_open_win()|. - - `relative` is empty for normal windows. - - Parameters: ~ - {window} Window handle, or 0 for current window - - Return: ~ - Map defining the window configuration, see - |nvim_open_win()| - nvim_win_get_cursor({window}) *nvim_win_get_cursor()* Gets the (1,0)-indexed cursor position in the window. |api-indexing| @@ -2658,23 +2651,6 @@ nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* {window} Window handle, or 0 for current window {buffer} Buffer handle -nvim_win_set_config({window}, {config}) *nvim_win_set_config()* - Configures window layout. Currently only for floating and - external windows (including changing a split window to those - layouts). - - When reconfiguring a floating window, absent option keys will - not be changed. `row` / `col` and `relative` must be - reconfigured together. - - Parameters: ~ - {window} Window handle, or 0 for current window - {config} Map defining the window configuration, see - |nvim_open_win()| - - See also: ~ - |nvim_open_win()| - nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* Sets the (1,0)-indexed cursor position in the window. |api-indexing| @@ -2718,6 +2694,195 @@ nvim_win_set_width({window}, {width}) *nvim_win_set_width()* ============================================================================== +Win_Config Functions *api-win_config* + +nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* + Open a new window. + + Currently this is used to open floating and external windows. + Floats are windows that are drawn above the split layout, at + some anchor position in some other window. Floats can be drawn + internally or by external GUI with the |ui-multigrid| + extension. External windows are only supported with multigrid + GUIs, and are displayed as separate top-level windows. + + For a general overview of floats, see |api-floatwin|. + + Exactly one of `external` and `relative` must be specified. + The `width` and `height` of the new window must be specified. + + With relative=editor (row=0,col=0) refers to the top-left + corner of the screen-grid and (row=Lines-1,col=Columns-1) + refers to the bottom-right corner. Fractional values are + allowed, but the builtin implementation (used by non-multigrid + UIs) will always round down to nearest integer. + + Out-of-bounds values, and configurations that make the float + not fit inside the main editor, are allowed. The builtin + implementation truncates values so floats are fully within the + main screen grid. External GUIs could let floats hover outside + of the main window like a tooltip, but this should not be used + to specify arbitrary WM screen positions. + + Example (Lua): window-relative float > + vim.api.nvim_open_win(0, false, + {relative='win', row=3, col=3, width=12, height=3}) +< + + Example (Lua): buffer-relative float (travels as buffer is + scrolled) > + vim.api.nvim_open_win(0, false, + {relative='win', width=12, height=3, bufpos={100,10}}) +< + + Attributes: ~ + not allowed when |textlock| is active + + Parameters: ~ + {buffer} Buffer to display, or 0 for current buffer + {enter} Enter the window (make it the current window) + {config} Map defining the window configuration. Keys: + • relative: Sets the window layout to + "floating", placed at (row,col) coordinates + relative to: + • "editor" The global editor grid + • "win" Window given by the `win` field, or + current window. + • "cursor" Cursor position in current window. + + • win: |window-ID| for relative="win". + • anchor: Decides which corner of the float to + place at (row,col): + • "NW" northwest (default) + • "NE" northeast + • "SW" southwest + • "SE" southeast + + • width: Window width (in character cells). + Minimum of 1. + • height: Window height (in character cells). + Minimum of 1. + • bufpos: Places float relative to buffer text + (only when relative="win"). Takes a tuple of + zero-indexed [line, column]. `row` and `col` if given are applied relative to this + position, else they default to: + • `row=1` and `col=0` if `anchor` is "NW" or + "NE" + • `row=0` and `col=0` if `anchor` is "SW" or + "SE" (thus like a tooltip near the buffer + text). + + • row: Row position in units of "screen cell + height", may be fractional. + • col: Column position in units of "screen cell + width", may be fractional. + • focusable: Enable focus by user actions + (wincmds, mouse events). Defaults to true. + Non-focusable windows can be entered by + |nvim_set_current_win()|. + • external: GUI should display the window as an + external top-level window. Currently accepts + no other positioning configuration together + with this. + • zindex: Stacking order. floats with higher `zindex` go on top on floats with lower indices. Must + be larger than zero. The following screen + elements have hard-coded z-indices: + • 100: insert completion popupmenu + • 200: message scrollback + • 250: cmdline completion popupmenu (when + wildoptions+=pum) The default value for + floats are 50. In general, values below 100 + are recommended, unless there is a good + reason to overshadow builtin elements. + + • style: Configure the appearance of the window. + Currently only takes one non-empty value: + • "minimal" Nvim will display the window with + many UI options disabled. This is useful + when displaying a temporary float where the + text should not be edited. Disables + 'number', 'relativenumber', 'cursorline', + 'cursorcolumn', 'foldcolumn', 'spell' and + 'list' options. 'signcolumn' is changed to + `auto` and 'colorcolumn' is cleared. The + end-of-buffer region is hidden by setting + `eob` flag of 'fillchars' to a space char, + and clearing the |EndOfBuffer| region in + 'winhighlight'. + + • border: Style of (optional) window border. + This can either be a string or an array. The + string values are + • "none": No border (default). + • "single": A single line box. + • "double": A double line box. + • "rounded": Like "single", but with rounded + corners ("╭" etc.). + • "solid": Adds padding by a single whitespace + cell. + • "shadow": A drop shadow effect by blending + with the background. + • If it is an array, it should have a length + of eight or any divisor of eight. The array + will specifify the eight chars building up + the border in a clockwise fashion starting + with the top-left corner. As an example, the + double box style could be specified as [ + "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ]. If + the number of chars are less than eight, + they will be repeated. Thus an ASCII border + could be specified as [ "/", "-", "\\", "|" + ], or all chars the same as [ "x" ]. An + empty string can be used to turn off a + specific border, for instance, [ "", "", "", + ">", "", "", "", "<" ] will only make + vertical borders but not horizontal ones. By + default, `FloatBorder` highlight is used, + which links to `VertSplit` when not defined. + It could also be specified by character: [ + {"+", "MyCorner"}, {"x", "MyBorder"} ]. + + • noautocmd: If true then no buffer-related + autocommand events such as |BufEnter|, + |BufLeave| or |BufWinEnter| may fire from + calling this function. + + Return: ~ + Window handle, or 0 on error + +nvim_win_get_config({window}) *nvim_win_get_config()* + Gets window configuration. + + The returned value may be given to |nvim_open_win()|. + + `relative` is empty for normal windows. + + Parameters: ~ + {window} Window handle, or 0 for current window + + Return: ~ + Map defining the window configuration, see + |nvim_open_win()| + +nvim_win_set_config({window}, {*config}) *nvim_win_set_config()* + Configures window layout. Currently only for floating and + external windows (including changing a split window to those + layouts). + + When reconfiguring a floating window, absent option keys will + not be changed. `row` / `col` and `relative` must be + reconfigured together. + + Parameters: ~ + {window} Window handle, or 0 for current window + {config} Map defining the window configuration, see + |nvim_open_win()| + + See also: ~ + |nvim_open_win()| + + +============================================================================== Tabpage Functions *api-tabpage* nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* |