mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-11 05:48:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc

Browse Source 
fix #10127
fix #5972
This commit is contained in:
Justin M. Keyes
2019-09-09 15:35:30 -07:00
parent 1adbdb397d
commit 06bfb07e35
9 changed files with 184 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
runtime/doc/api.txt
View File

@@ -408,34 +408,26 @@ Example using the API from Vimscript: >
============================================================================== ==============================================================================
Floating windows *api-floatwin* Floating windows *api-floatwin*
Nvim supports floating windows, windows that are displayed on top of ordinary Floating windows ("floats") are displayed on top of normal windows. This is
windows. This is useful to implement simple widgets, such as tooltips useful to implement simple widgets, such as tooltips displayed next to the
displaying information next to cursor text. Floating windows are fully cursor. Floats are fully functional windows supporting user editing, common
functional buffer windows and support user editing. They support the standard |api-window| calls, and most window options (except 'statusline').
|api-window| calls and almost all window options (with some exceptions such as
'statusline' is not supported currently).
Floating windows are created either by |nvim_open_win()| to open a new window, Two ways to create a floating window:
or |nvim_win_set_config()| to reconfigure a normal window into a float. - |nvim_open_win()| creates a new window (needs a buffer, see |nvim_create_buf()|)
Currently the position can either be grid coordinates relative to the top-left - |nvim_win_set_config()| reconfigures a normal window into a float
of some window, or a position relative to the current window cursor. The
parameters for positioning are described in detail at |nvim_open_win()|.
|nvim_open_win()| assumes an existing buffer to display in the window. To create To close it use |nvim_win_close()| or a command such as |:close|.
a scratch buffer for the float, |nvim_create_buf()| can be used. The text in
the buffer can be highlighted using standard functionality, such as syntax
highlighting, or |api-highlights|.
By default, floats will use |hl-NormalFloat| as normal highlight, which Buffer text can be highlighted by typical mechanisms (syntax highlighting,
links to |hl-Pmenu| in the builtin color scheme. The 'winhighlight' option can |api-highlights|). The |hl-NormalFloat| group highlights normal text;
be used to override it. Currently, floating windows don't support any visual 'winhighlight' can be used as usual to override groups locally. Floats inherit
decorations like a border or additional widgets like scrollbar. By default, options from the current window; specify `style=minimal` in |nvim_open_win()|
floats will inherit options from the current window. This is not always to disable various visual features such as the 'number' column.
useful for some options, like 'number'. Use `style='minimal'` flag to
|nvim_open_win()| to disable many UI features that are unwanted for a simple
float, like end-of-buffer region or special columns.
Here is an example for creating a float with scratch buffer: > Currently, floating windows don't support widgets like border or scrollbar.
Example: create a float with scratch buffer: >
let buf = nvim_create_buf(v:false, v:true) let buf = nvim_create_buf(v:false, v:true)
call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"]) call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"])
@@ -445,7 +437,6 @@ Here is an example for creating a float with scratch buffer: >
" optional: change highlight, otherwise Pmenu is used " optional: change highlight, otherwise Pmenu is used
call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight') call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight')
> >
To close the float, |nvim_win_close()| can be used.
============================================================================== ==============================================================================
Global Functions *api-global* Global Functions *api-global*
@@ -604,18 +595,18 @@ nvim_eval({expr}) *nvim_eval()*
Evaluation result or expanded object Evaluation result or expanded object
nvim_execute_lua({code}, {args}) *nvim_execute_lua()* nvim_execute_lua({code}, {args}) *nvim_execute_lua()*
Execute lua code. Parameters (if any) are available as `...` Execute Lua code. Parameters (if any) are available as `...`
inside the chunk. The chunk can return a value. inside the chunk. The chunk can return a value.
Only statements are executed. To evaluate an expression, Only statements are executed. To evaluate an expression,
prefix it with `return` : return my_function(...) prefix it with `return` : return my_function(...)
Parameters: ~ Parameters: ~
{code} lua code to execute {code} Lua code to execute
{args} Arguments to the code {args} Arguments to the code
Return: ~ Return: ~
Return value of lua code if present or NIL. Return value of Lua code if present or NIL.
nvim_call_function({fn}, {args}) *nvim_call_function()* nvim_call_function({fn}, {args}) *nvim_call_function()*
Calls a VimL function with the given arguments. Calls a VimL function with the given arguments.
@@ -830,74 +821,77 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
Exactly one of `external` and `relative` must be specified. Exactly one of `external` and `relative` must be specified.
The `width` and `height` of the new window must be specified. The `width` and `height` of the new window must be specified.
With editor positioning row=0, col=0 refers to the top-left With relative=editor (row=0,col=0) refers to the top-left
corner of the screen-grid and row=Lines-1, Columns-1 refers to corner of the screen-grid and (row=Lines-1,col=Columns-1)
the bottom-right corner. Floating point values are allowed, refers to the bottom-right corner. Fractional values are
but the builtin implementation (used by TUI and GUIs without allowed, but the builtin implementation (used by non-multigrid
multigrid support) will always round down to nearest integer. UIs) will always round down to nearest integer.
Out-of-bounds values, and configurations that make the float Out-of-bounds values, and configurations that make the float
not fit inside the main editor, are allowed. The builtin not fit inside the main editor, are allowed. The builtin
implementation will truncate values so floats are completely implementation truncates values so floats are fully within the
within the main screen grid. External GUIs could let floats main screen grid. External GUIs could let floats hover outside
hover outside of the main window like a tooltip, but this of the main window like a tooltip, but this should not be used
should not be used to specify arbitrary WM screen positions. 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}})
<
Parameters: ~ Parameters: ~
{buffer} handle of buffer to be displayed in the window {buffer} Buffer to display, or 0 for current buffer
{enter} whether the window should be entered (made the {enter} Enter the window (make it the current window)
current window) {config} Map defining the window configuration. Keys:
{config} Dictionary for the window configuration accepts • `relative` : Sets the window layout to "floating", placed
these keys: at (row,col) coordinates relative to one of:
• `relative` : If set, the window becomes a floating • "editor" The global editor grid
window. The window will be placed with row,col • "win" Window given by the `win` field, or
coordinates relative to one of the following: current window by default.
• "editor" the global editor grid • "cursor" Cursor position in current window.
• "win" a window. Use `win` to specify a
window id, or the current window will be
used by default.
• "cursor" the cursor position in current
window.
• `win` : When using relative='win', window id • `win` : |window-ID| for relative="win".
of the window where the position is defined. • `anchor` : Decides which corner of the float to place
• `anchor` : The corner of the float that the row,col at (row,col):
position defines: • "NW" northwest (default)
• "NW" north-west (default) • "NE" northeast
• "NE" north-east • "SW" southwest
• "SW" south-west • "SE" southeast
• "SE" south-east
• `height` : window height (in character cells). • `width` : Window width (in character cells).
Minimum of 1. Minimum of 1.
• `width` : window width (in character cells). • `height` : Window height (in character cells).
Minimum of 1. Minimum of 1.
• 'bufpos': position float relative text inside • `bufpos` : Places float relative to buffer
window `win` (only when relative="win"). Takes text (only when relative="win"). Takes a tuple
a tuple of zero-indexed [line, column]. Note: of zero-indexed [line, column]. `row` and
`row` and `col` if present, still applies `col` if given are applied relative to this
relative this position. By default `row=1` and position, else they default to `row=1` and
`col=0` are used (with default NW anchor), to `col=0` (thus like a tooltip near the buffer
make the float behave like a tooltip under the text).
buffer text. • `row` : Row position in units of "screen cell
• `row` : row position. Screen cell height are height", may be fractional.
used as unit. Can be floating point. • `col` : Column position in units of "screen
• `col` : column position. Screen cell width is cell width", may be fractional.
used as unit. Can be floating point. • `focusable` : Enable focus by user actions
• `focusable` : Whether window can be focused by (wincmds, mouse events). Defaults to true.
wincmds and mouse events. Defaults to true. Non-focusable windows can be entered by
Even if set to false, the window can still be |nvim_set_current_win()|.
entered using |nvim_set_current_win()| API
call.
• `external` : GUI should display the window as • `external` : GUI should display the window as
an external top-level window. Currently an external top-level window. Currently
accepts no other positioning configuration accepts no other positioning configuration
together with this. together with this.
• `style` : Configure the apparance of the window. • `style` : Configure the appearance of the window.
Currently only takes one non-empty value: Currently only takes one non-empty value:
• "minimal" Nvim will display the window with • "minimal" Nvim will display the window with
many UI options disabled. This is useful many UI options disabled. This is useful
when displaing a temporary float where the when displaying a temporary float where the
text should not be edited. Disables text should not be edited. Disables
'number', 'relativenumber', 'cursorline', 'number', 'relativenumber', 'cursorline',
'cursorcolumn', 'foldcolumn', 'spell' and 'cursorcolumn', 'foldcolumn', 'spell' and
@@ -906,8 +900,6 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
by setting `eob` flag of 'fillchars' to a by setting `eob` flag of 'fillchars' to a
space char, and clearing the |EndOfBuffer| space char, and clearing the |EndOfBuffer|
region in 'winhighlight'. region in 'winhighlight'.
• top-level window. Currently accepts no other
positioning configuration together with this.
Return: ~ Return: ~
Window handle, or 0 on error Window handle, or 0 on error
@@ -1985,35 +1977,35 @@ nvim_win_is_valid({window}) *nvim_win_is_valid()*
true if the window is valid, false otherwise true if the window is valid, false otherwise
nvim_win_set_config({window}, {config}) *nvim_win_set_config()* nvim_win_set_config({window}, {config}) *nvim_win_set_config()*
Configure window position. Currently this is only used to Configures window layout. Currently only for floating and
configure floating and external windows (including changing a external windows (including changing a split window to those
split window to these types). layouts).
See documentation at |nvim_open_win()|, for the meaning of
parameters.
When reconfiguring a floating window, absent option keys will When reconfiguring a floating window, absent option keys will
not be changed. The following restriction apply: `row` , `col` not be changed. `row` / `col` and `relative` must be
and `relative` must be reconfigured together. Only changing a reconfigured together.
subset of these is an error.
Parameters: ~ Parameters: ~
{window} Window handle, or 0 for current window {window} Window handle, or 0 for current window
{config} Dictionary of window configuration {config} Map defining the window configuration, see
|nvim_open_win()|
See also: ~
|nvim_open_win()|
nvim_win_get_config({window}) *nvim_win_get_config()* nvim_win_get_config({window}) *nvim_win_get_config()*
Return window configuration. Gets window configuration.
Return a dictionary containing the same config that can be The returned value may be given to |nvim_open_win()|.
given to |nvim_open_win()|.
`relative` will be an empty string for normal windows. `relative` is empty for normal windows.
Parameters: ~ Parameters: ~
{window} Window handle, or 0 for current window {window} Window handle, or 0 for current window
Return: ~ Return: ~
Window configuration Map defining the window configuration, see
|nvim_open_win()|
nvim_win_close({window}, {force}) *nvim_win_close()* nvim_win_close({window}, {force}) *nvim_win_close()*
Closes the window (like |:close| with a |window-ID|). Closes the window (like |:close| with a |window-ID|).

4
runtime/doc/eval.txt
View File

@@ -2952,9 +2952,9 @@ char2nr({expr} [, {utf8}]) *char2nr()*
char2nr("ABC") returns 65 char2nr("ABC") returns 65
char2nr("á") returns 225 char2nr("á") returns 225
char2nr("á"[0]) returns 195 char2nr("á"[0]) returns 195
char2nr("\<M-x>") returns 128
< Non-ASCII characters are always treated as UTF-8 characters. < Non-ASCII characters are always treated as UTF-8 characters.
{utf8} has no effect, and exists only for {utf8} is ignored, it exists only for backwards-compatibility.
backwards-compatibility.
A combining character is a separate character. A combining character is a separate character.
|nr2char()| does the opposite. |nr2char()| does the opposite.

1
runtime/doc/if_lua.txt
View File

@@ -525,6 +525,7 @@ inspect({object}, {options}) *vim.inspect()*
See also: ~ See also: ~
https://github.com/kikito/inspect.lua https://github.com/kikito/inspect.lua
https://github.com/mpeterv/vinspect
paste({lines}, {phase}) *vim.paste()* paste({lines}, {phase}) *vim.paste()*
Paste handler, invoked by |nvim_paste()| when a conforming UI Paste handler, invoked by |nvim_paste()| when a conforming UI

31
runtime/doc/index.txt
View File

@@ -847,6 +847,10 @@ tag char note action in Normal mode ~
position the cursor at the start (left position the cursor at the start (left
side) of the screen side) of the screen
|zt| zt redraw, cursor line at top of window |zt| zt redraw, cursor line at top of window
|zuw| zuw undo |zw|
|zug| zug undo |zg|
|zuW| zuW undo |zW|
|zuG| zuG undo |zG|
|zv| zv open enough folds to view the cursor line |zv| zv open enough folds to view the cursor line
|zw| zw mark word as wrong (bad) spelled word |zw| zw mark word as wrong (bad) spelled word
|zx| zx re-apply 'foldlevel' and do "zv" |zx| zx re-apply 'foldlevel' and do "zv"
@@ -1078,10 +1082,17 @@ tag command action in Command-line editing mode ~
|c_<Insert>| <Insert> toggle insert/overstrike mode |c_<Insert>| <Insert> toggle insert/overstrike mode
|c_<LeftMouse>| <LeftMouse> cursor at mouse click |c_<LeftMouse>| <LeftMouse> cursor at mouse click
==============================================================================
5. Terminal mode *terminal-mode-index*
In a |terminal| buffer all keys except |CTRL-\_CTRL-N| are forwarded to the
terminal job. Use CTRL-\_CTRL-N to go to Normal mode.
You found it, Arthur! *holy-grail* You found it, Arthur! *holy-grail*
============================================================================== ==============================================================================
5. EX commands *ex-cmd-index* *:index* 6. EX commands *ex-cmd-index* *:index*
This is a brief but complete listing of all the ":" commands, without This is a brief but complete listing of all the ":" commands, without
mentioning any arguments. The optional part of the command name is inside []. mentioning any arguments. The optional part of the command name is inside [].
@@ -1089,10 +1100,13 @@ The commands are sorted on the non-optional part of their name.
tag command action ~ tag command action ~
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
|:| : nothing
|:range| :{range} go to last line in {range}
|:!| :! filter lines or execute an external command |:!| :! filter lines or execute an external command
|:!!| :!! repeat last ":!" command |:!!| :!! repeat last ":!" command
|:#| :# same as ":number" |:#| :# same as ":number"
|:&| :& repeat last ":substitute" |:&| :& repeat last ":substitute"
|:star| :* execute contents of a register
|:<| :< shift lines one 'shiftwidth' left |:<| :< shift lines one 'shiftwidth' left
|:=| := print the cursor line number |:=| := print the cursor line number
|:>| :> shift lines one 'shiftwidth' right |:>| :> shift lines one 'shiftwidth' right
@@ -1160,7 +1174,7 @@ tag command action ~
|:cclose| :ccl[ose] close quickfix window |:cclose| :ccl[ose] close quickfix window
|:cd| :cd change directory |:cd| :cd change directory
|:cdo| :cdo execute command in each valid error list entry |:cdo| :cdo execute command in each valid error list entry
|:cfdo| :cfdo execute command in each file in error list |:cfdo| :cfd[o] execute command in each file in error list
|:center| :ce[nter] format lines at the center |:center| :ce[nter] format lines at the center
|:cexpr| :cex[pr] read errors from expr and jump to first |:cexpr| :cex[pr] read errors from expr and jump to first
|:cfile| :cf[ile] read file with error messages and jump to first |:cfile| :cf[ile] read file with error messages and jump to first
@@ -1361,9 +1375,9 @@ tag command action ~
|:ltag| :lt[ag] jump to tag and add matching tags to the |:ltag| :lt[ag] jump to tag and add matching tags to the
location list location list
|:lunmap| :lu[nmap] like ":unmap!" but includes Lang-Arg mode |:lunmap| :lu[nmap] like ":unmap!" but includes Lang-Arg mode
|:lua| :lua execute Lua command |:lua| :lua execute |Lua| command
|:luado| :luad[o] execute Lua command for each line |:luado| :luad[o] execute Lua command for each line
|:luafile| :luaf[ile] execute Lua script file |:luafile| :luaf[ile] execute |Lua| script file
|:lvimgrep| :lv[imgrep] search for pattern in files |:lvimgrep| :lv[imgrep] search for pattern in files
|:lvimgrepadd| :lvimgrepa[dd] like :vimgrep, but append to current list |:lvimgrepadd| :lvimgrepa[dd] like :vimgrep, but append to current list
|:lwindow| :lw[indow] open or close location window |:lwindow| :lw[indow] open or close location window
@@ -1402,7 +1416,7 @@ tag command action ~
|:number| :nu[mber] print lines with line number |:number| :nu[mber] print lines with line number
|:nunmap| :nun[map] like ":unmap" but for Normal mode |:nunmap| :nun[map] like ":unmap" but for Normal mode
|:nunmenu| :nunme[nu] remove menu for Normal mode |:nunmenu| :nunme[nu] remove menu for Normal mode
|:oldfiles| :o[ldfiles] list files that have marks in the ShaDa file |:oldfiles| :ol[dfiles] list files that have marks in the |shada| file
|:omap| :om[ap] like ":map" but for Operator-pending mode |:omap| :om[ap] like ":map" but for Operator-pending mode
|:omapclear| :omapc[lear] remove all mappings for Operator-pending mode |:omapclear| :omapc[lear] remove all mappings for Operator-pending mode
|:omenu| :ome[nu] add menu for Operator-pending mode |:omenu| :ome[nu] add menu for Operator-pending mode
@@ -1467,7 +1481,10 @@ tag command action ~
|:rewind| :rew[ind] go to the first file in the argument list |:rewind| :rew[ind] go to the first file in the argument list
|:right| :ri[ght] right align text |:right| :ri[ght] right align text
|:rightbelow| :rightb[elow] make split window appear right or below |:rightbelow| :rightb[elow] make split window appear right or below
|:rshada| :rsh[ada] read from ShaDa file |:rshada| :rsh[ada] read from |shada| file
|:ruby| :rub[y] execute Ruby command
|:rubydo| :rubyd[o] execute Ruby command for each line
|:rubyfile| :rubyf[ile] execute Ruby script file
|:rundo| :rund[o] read undo information from a file |:rundo| :rund[o] read undo information from a file
|:runtime| :ru[ntime] source vim scripts in 'runtimepath' |:runtime| :ru[ntime] source vim scripts in 'runtimepath'
|:substitute| :s[ubstitute] find and replace text |:substitute| :s[ubstitute] find and replace text
@@ -1570,6 +1587,8 @@ tag command action ~
|:tab| :tab create new tab when opening new window |:tab| :tab create new tab when opening new window
|:tag| :ta[g] jump to tag |:tag| :ta[g] jump to tag
|:tags| :tags show the contents of the tag stack |:tags| :tags show the contents of the tag stack
|:tcd| :tcd change directory for tab page
|:tchdir| :tch[dir] change directory for tab page
|:terminal| :te[rminal] open a terminal buffer |:terminal| :te[rminal] open a terminal buffer
|:tfirst| :tf[irst] jump to first matching tag |:tfirst| :tf[irst] jump to first matching tag
|:throw| :th[row] throw an exception |:throw| :th[row] throw an exception

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

@@ -437,18 +437,18 @@ Object nvim_eval(String expr, Error *err)
return rv; return rv;
} }
/// Execute lua code. Parameters (if any) are available as `...` inside the /// Execute Lua code. Parameters (if any) are available as `...` inside the
/// chunk. The chunk can return a value. /// chunk. The chunk can return a value.
/// ///
/// Only statements are executed. To evaluate an expression, prefix it /// Only statements are executed. To evaluate an expression, prefix it
/// with `return`: return my_function(...) /// with `return`: return my_function(...)
/// ///
/// @param code lua code to execute /// @param code Lua code to execute
/// @param args Arguments to the code /// @param args Arguments to the code
/// @param[out] err Details of an error encountered while parsing /// @param[out] err Details of an error encountered while parsing
/// or executing the lua code. /// or executing the Lua code.
/// ///
/// @return Return value of lua code if present or NIL. /// @return Return value of Lua code if present or NIL.
Object nvim_execute_lua(String code, Array args, Error *err) Object nvim_execute_lua(String code, Array args, Error *err)
FUNC_API_SINCE(3) FUNC_API_REMOTE_ONLY FUNC_API_SINCE(3) FUNC_API_REMOTE_ONLY
{ {
@@ -1028,66 +1028,70 @@ fail:
/// Exactly one of `external` and `relative` must be specified. The `width` and /// Exactly one of `external` and `relative` must be specified. The `width` and
/// `height` of the new window must be specified. /// `height` of the new window must be specified.
/// ///
/// With editor positioning row=0, col=0 refers to the top-left corner of the /// With relative=editor (row=0,col=0) refers to the top-left corner of the
/// screen-grid and row=Lines-1, Columns-1 refers to the bottom-right corner. /// screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right
/// Floating point values are allowed, but the builtin implementation (used by /// corner. Fractional values are allowed, but the builtin implementation
/// TUI and GUIs without multigrid support) will always round down to nearest /// (used by non-multigrid UIs) will always round down to nearest integer.
/// integer.
/// ///
/// Out-of-bounds values, and configurations that make the float not fit inside /// Out-of-bounds values, and configurations that make the float not fit inside
/// the main editor, are allowed. The builtin implementation will truncate /// the main editor, are allowed. The builtin implementation truncates values
/// values so floats are completely within the main screen grid. External GUIs /// so floats are fully within the main screen grid. External GUIs
/// could let floats hover outside of the main window like a tooltip, but /// could let floats hover outside of the main window like a tooltip, but
/// this should not be used to specify arbitrary WM screen positions. /// this should not be used to specify arbitrary WM screen positions.
/// ///
/// @param buffer handle of buffer to be displayed in the window /// Example (Lua): window-relative float
/// @param enter whether the window should be entered (made the current window) /// <pre>
/// @param config Dictionary for the window configuration accepts these keys: /// vim.api.nvim_open_win(0, false,
/// - `relative`: If set, the window becomes a floating window. The window /// {relative='win', row=3, col=3, width=12, height=3})
/// will be placed with row,col coordinates relative to one of the /// </pre>
/// following: ///
/// - "editor" the global editor grid /// Example (Lua): buffer-relative float (travels as buffer is scrolled)
/// - "win" a window. Use `win` to specify a window id, /// <pre>
/// or the current window will be used by default. /// vim.api.nvim_open_win(0, false,
/// - "cursor" the cursor position in current window. /// {relative='win', width=12, height=3, bufpos={100,10}})
/// - `win`: When using relative='win', window id of the window where the /// </pre>
/// position is defined. ///
/// - `anchor`: The corner of the float that the row,col position defines: /// @param buffer Buffer to display, or 0 for current buffer
/// - "NW" north-west (default) /// @param enter Enter the window (make it the current window)
/// - "NE" north-east /// @param config Map defining the window configuration. Keys:
/// - "SW" south-west /// - `relative`: Sets the window layout to "floating", placed at (row,col)
/// - "SE" south-east /// coordinates relative to one of:
/// - `height`: window height (in character cells). Minimum of 1. /// - "editor" The global editor grid
/// - `width`: window width (in character cells). Minimum of 1. /// - "win" Window given by the `win` field, or current window by
/// - 'bufpos': position float relative text inside window `win` (only /// default.
/// when relative="win"). Takes a tuple of zero-indexed /// - "cursor" Cursor position in current window.
/// [line, column]. Note: `row` and `col` if present, still /// - `win`: |window-ID| for relative="win".
/// applies relative this position. By default `row=1` and `col=0` /// - `anchor`: Decides which corner of the float to place at (row,col):
/// are used (with default NW anchor), to make the float /// - "NW" northwest (default)
/// behave like a tooltip under the buffer text. /// - "NE" northeast
/// - `row`: row position. Screen cell height are used as unit. Can be /// - "SW" southwest
/// floating point. /// - "SE" southeast
/// - `col`: column position. Screen cell width is used as unit. Can be /// - `width`: Window width (in character cells). Minimum of 1.
/// floating point. /// - `height`: Window height (in character cells). Minimum of 1.
/// - `focusable`: Whether window can be focused by wincmds and /// - `bufpos`: Places float relative to buffer text (only when
/// mouse events. Defaults to true. Even if set to false, the window /// relative="win"). Takes a tuple of zero-indexed [line, column].
/// can still be entered using |nvim_set_current_win()| API call. /// `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 /// - `external`: GUI should display the window as an external
/// top-level window. Currently accepts no other positioning /// top-level window. Currently accepts no other positioning
/// configuration together with this. /// configuration together with this.
/// - `style`: Configure the apparance of the window. Currently only takes /// - `style`: Configure the appearance of the window. Currently only takes
/// one non-empty value: /// one non-empty value:
/// - "minimal" Nvim will display the window with many UI options /// - "minimal" Nvim will display the window with many UI options
/// disabled. This is useful when displaing a temporary /// disabled. This is useful when displaying a temporary
/// float where the text should not be edited. Disables /// float where the text should not be edited. Disables
/// 'number', 'relativenumber', 'cursorline', 'cursorcolumn', /// 'number', 'relativenumber', 'cursorline', 'cursorcolumn',
/// 'foldcolumn', 'spell' and 'list' options. 'signcolumn' /// 'foldcolumn', 'spell' and 'list' options. 'signcolumn'
/// is changed to `auto`. The end-of-buffer region is hidden /// is changed to `auto`. The end-of-buffer region is hidden
/// by setting `eob` flag of 'fillchars' to a space char, /// by setting `eob` flag of 'fillchars' to a space char,
/// and clearing the |EndOfBuffer| region in 'winhighlight'. /// and clearing the |EndOfBuffer| region in 'winhighlight'.
///
/// top-level window. Currently accepts no other positioning
/// configuration together with this.
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// ///
/// @return Window handle, or 0 on error /// @return Window handle, or 0 on error

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

@@ -441,18 +441,17 @@ Boolean nvim_win_is_valid(Window window)
} }
/// Configure window position. Currently this is only used to configure /// Configures window layout. Currently only for floating and external windows
/// floating and external windows (including changing a split window to these /// (including changing a split window to those layouts).
/// types).
///
/// See documentation at |nvim_open_win()|, for the meaning of parameters.
/// ///
/// When reconfiguring a floating window, absent option keys will not be /// When reconfiguring a floating window, absent option keys will not be
/// changed. The following restriction apply: `row`, `col` and `relative` /// changed. `row`/`col` and `relative` must be reconfigured together.
/// must be reconfigured together. Only changing a subset of these is an error. ///
/// @see |nvim_open_win()|
/// ///
/// @param window Window handle, or 0 for current window /// @param window Window handle, or 0 for current window
/// @param config Dictionary of window configuration /// @param config Map defining the window configuration,
/// see |nvim_open_win()|
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_win_set_config(Window window, Dictionary config, Error *err) void nvim_win_set_config(Window window, Dictionary config, Error *err)
FUNC_API_SINCE(6) FUNC_API_SINCE(6)
@@ -483,16 +482,15 @@ void nvim_win_set_config(Window window, Dictionary config, Error *err)
} }
} }
/// Return window configuration. /// Gets window configuration.
/// ///
/// Return a dictionary containing the same config that can be given to /// The returned value may be given to |nvim_open_win()|.
/// |nvim_open_win()|.
/// ///
/// `relative` will be an empty string for normal windows. /// `relative` is empty for normal windows.
/// ///
/// @param window Window handle, or 0 for current window /// @param window Window handle, or 0 for current window
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Window configuration /// @return Map defining the window configuration, see |nvim_open_win()|
Dictionary nvim_win_get_config(Window window, Error *err) Dictionary nvim_win_get_config(Window window, Error *err)
FUNC_API_SINCE(6) FUNC_API_SINCE(6)
{ {

1
src/nvim/lua/vim.lua
View File

@@ -157,6 +157,7 @@ end
--- Return a human-readable representation of the given object. --- Return a human-readable representation of the given object.
--- ---
--@see https://github.com/kikito/inspect.lua --@see https://github.com/kikito/inspect.lua
--@see https://github.com/mpeterv/vinspect
local function inspect(object, options) -- luacheck: no unused local function inspect(object, options) -- luacheck: no unused
error(object, options) -- Stub for gen_vimdoc.py error(object, options) -- Stub for gen_vimdoc.py
end end

4
src/nvim/window.c
View File

@@ -969,8 +969,8 @@ bool parse_float_config(Dictionary config, FloatConfig *fconfig, bool reconf,
} }
if (has_relative != has_row || has_row != has_col) { if (has_relative != has_row || has_row != has_col) {
api_set_error(err, kErrorTypeValidation, "All of 'relative', 'row', and " api_set_error(err, kErrorTypeValidation,
"'col' has to be specified at once"); "'relative' requires 'row'/'col' or 'bufpos'");
return false; return false;
} }
return true; return true;

2
test/functional/ui/float_spec.lua
View File

@@ -646,7 +646,7 @@ describe('floating windows', function()
pcall_err(meths.open_win,buf, false, {width=20,height=2,relative='shell',row=0,col=0})) pcall_err(meths.open_win,buf, false, {width=20,height=2,relative='shell',row=0,col=0}))
eq("Invalid value of 'anchor' key", eq("Invalid value of 'anchor' key",
pcall_err(meths.open_win,buf, false, {width=20,height=2,relative='editor',row=0,col=0,anchor='bottom'})) pcall_err(meths.open_win,buf, false, {width=20,height=2,relative='editor',row=0,col=0,anchor='bottom'}))
eq("All of 'relative', 'row', and 'col' has to be specified at once", eq("'relative' requires 'row'/'col' or 'bufpos'",
pcall_err(meths.open_win,buf, false, {width=20,height=2,relative='editor'})) pcall_err(meths.open_win,buf, false, {width=20,height=2,relative='editor'}))
eq("'width' key must be a positive Integer", eq("'width' key must be a positive Integer",
pcall_err(meths.open_win,buf, false, {width=-1,height=2,relative='editor'})) pcall_err(meths.open_win,buf, false, {width=-1,height=2,relative='editor'}))