diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 480 |
1 files changed, 254 insertions, 226 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 9178f4978b..1ad0a6883e 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -708,7 +708,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()|. @@ -847,7 +847,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: > @@ -885,32 +885,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 @@ -936,7 +937,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 @@ -949,7 +950,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: ~ @@ -1119,10 +1120,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} @@ -1301,156 +1298,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 @@ -1819,7 +1666,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()|. @@ -2165,7 +2012,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: ~ @@ -2177,7 +2024,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 @@ -2228,12 +2075,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 @@ -2373,7 +2220,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 @@ -2391,8 +2238,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 @@ -2401,6 +2250,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 @@ -2436,10 +2289,28 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) 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 @@ -2462,7 +2333,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: ~ @@ -2620,20 +2491,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| @@ -2744,23 +2601,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| @@ -2804,6 +2644,194 @@ 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()* |