diff options
| -rw-r--r-- | runtime/doc/api.txt | 209 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/if_lua.txt | 1 | ||||
| -rw-r--r-- | runtime/doc/index.txt | 31 | ||||
| -rw-r--r-- | src/nvim/api/ui.c | 9 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 100 | ||||
| -rw-r--r-- | src/nvim/api/window.c | 24 | ||||
| -rw-r--r-- | src/nvim/lua/vim.lua | 1 | ||||
| -rw-r--r-- | src/nvim/window.c | 4 | ||||
| -rw-r--r-- | test/functional/ui/float_spec.lua | 2 |
10 files changed, 202 insertions, 183 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 21cc114598..18129e8c39 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -408,34 +408,26 @@ Example using the API from Vimscript: > ============================================================================== Floating windows *api-floatwin* -Nvim supports floating windows, windows that are displayed on top of ordinary -windows. This is useful to implement simple widgets, such as tooltips -displaying information next to cursor text. Floating windows are fully -functional buffer windows and support user editing. They support the standard -|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, -or |nvim_win_set_config()| to reconfigure a normal window into a float. -Currently the position can either be grid coordinates relative to the top-left -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 -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 -links to |hl-Pmenu| in the builtin color scheme. The 'winhighlight' option can -be used to override it. Currently, floating windows don't support any visual -decorations like a border or additional widgets like scrollbar. By default, -floats will inherit options from the current window. This is not always -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: > +Floating windows ("floats") are displayed on top of normal windows. This is +useful to implement simple widgets, such as tooltips displayed next to the +cursor. Floats are fully functional windows supporting user editing, common +|api-window| calls, and most window options (except 'statusline'). + +Two ways to create a floating window: +- |nvim_open_win()| creates a new window (needs a buffer, see |nvim_create_buf()|) +- |nvim_win_set_config()| reconfigures a normal window into a float + +To close it use |nvim_win_close()| or a command such as |:close|. + +Buffer text can be highlighted by typical mechanisms (syntax highlighting, +|api-highlights|). The |hl-NormalFloat| group highlights normal text; +'winhighlight' can be used as usual to override groups locally. Floats inherit +options from the current window; specify `style=minimal` in |nvim_open_win()| +to disable various visual features such as the 'number' column. + +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) 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 call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight') > -To close the float, |nvim_win_close()| can be used. ============================================================================== Global Functions *api-global* @@ -604,18 +595,18 @@ nvim_eval({expr}) *nvim_eval()* Evaluation result or expanded object 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. Only statements are executed. To evaluate an expression, prefix it with `return` : return my_function(...) Parameters: ~ - {code} lua code to execute + {code} Lua code to execute {args} Arguments to the code 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()* 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. The `width` and `height` of the new window must be specified. - With editor positioning 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. Floating point values are allowed, - but the builtin implementation (used by TUI and GUIs without - multigrid support) will always round down to nearest integer. + 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 will truncate values so floats are completely - 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. - - Parameters: ~ - {buffer} handle of buffer to be displayed in the window - {enter} whether the window should be entered (made the - current window) - {config} Dictionary for the window configuration accepts - these keys: - • `relative` : If set, the window becomes a floating - window. The window will be placed with row,col - coordinates relative to one of the following: - • "editor" the global editor grid - • "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 - of the window where the position is defined. - • `anchor` : The corner of the float that the row,col - position defines: - • "NW" north-west (default) - • "NE" north-east - • "SW" south-west - • "SE" south-east - - • `height` : window height (in character cells). + 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}}) +< + + 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 one of: + • "editor" The global editor grid + • "win" Window given by the `win` field, or + current window by default. + • "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. - • `width` : window width (in character cells). + • `height` : Window height (in character cells). Minimum of 1. - • 'bufpos': position float relative text inside - window `win` (only when relative="win"). Takes - a tuple of zero-indexed [line, column]. Note: - `row` and `col` if present, still applies - relative this position. By default `row=1` and - `col=0` are used (with default NW anchor), to - make the float behave like a tooltip under the - buffer text. - • `row` : row position. Screen cell height are - used as unit. Can be floating point. - • `col` : column position. Screen cell width is - used as unit. Can be floating point. - • `focusable` : Whether window can be focused by - wincmds and mouse events. Defaults to true. - Even if set to false, the window can still be - entered using |nvim_set_current_win()| API - call. + • `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. - • `style` : Configure the apparance of the window. + • `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 displaing a temporary float where the + when displaying a temporary float where the text should not be edited. Disables 'number', 'relativenumber', 'cursorline', '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 space char, and clearing the |EndOfBuffer| region in 'winhighlight'. - • top-level window. Currently accepts no other - positioning configuration together with this. Return: ~ 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 nvim_win_set_config({window}, {config}) *nvim_win_set_config()* - Configure window position. Currently this is only used to - configure floating and external windows (including changing a - split window to these types). - - See documentation at |nvim_open_win()|, for the meaning of - parameters. + 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. The following restriction apply: `row` , `col` - and `relative` must be reconfigured together. Only changing a - subset of these is an error. + not be changed. `row` / `col` and `relative` must be + reconfigured together. Parameters: ~ {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()* - Return window configuration. + Gets window configuration. - Return a dictionary containing the same config that can be - given to |nvim_open_win()|. + The returned value may be given to |nvim_open_win()|. - `relative` will be an empty string for normal windows. + `relative` is empty for normal windows. Parameters: ~ {window} Window handle, or 0 for current window Return: ~ - Window configuration + Map defining the window configuration, see + |nvim_open_win()| nvim_win_close({window}, {force}) *nvim_win_close()* Closes the window (like |:close| with a |window-ID|). @@ -2136,4 +2128,11 @@ nvim_ui_try_resize_grid({grid}, {width}, {height}) {width} The new requested width. {height} The new requested height. +nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* + Tells Nvim the number of elements displaying in the popumenu, + to decide <PageUp> and <PageDown> movement. + + Parameters: ~ + {height} Popupmenu height, must be greater than zero. + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 53a5f247f9..f845268333 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2952,9 +2952,9 @@ char2nr({expr} [, {utf8}]) *char2nr()* char2nr("ABC") returns 65 char2nr("á") returns 225 char2nr("á"[0]) returns 195 + char2nr("\<M-x>") returns 128 < Non-ASCII characters are always treated as UTF-8 characters. - {utf8} has no effect, and exists only for - backwards-compatibility. + {utf8} is ignored, it exists only for backwards-compatibility. A combining character is a separate character. |nr2char()| does the opposite. diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt index 11950da91e..aa2d0a03c6 100644 --- a/runtime/doc/if_lua.txt +++ b/runtime/doc/if_lua.txt @@ -525,6 +525,7 @@ inspect({object}, {options}) *vim.inspect()* See also: ~ https://github.com/kikito/inspect.lua + https://github.com/mpeterv/vinspect paste({lines}, {phase}) *vim.paste()* Paste handler, invoked by |nvim_paste()| when a conforming UI diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index aebb58889a..be9e25113a 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -847,6 +847,10 @@ tag char note action in Normal mode ~ position the cursor at the start (left side) of the screen |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 |zw| zw mark word as wrong (bad) spelled word |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_<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* ============================================================================== -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 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 ~ ------------------------------------------------------------------------------ +|:| : nothing +|:range| :{range} go to last line in {range} |:!| :! filter lines or execute an external command |:!!| :!! repeat last ":!" command |:#| :# same as ":number" |:&| :& repeat last ":substitute" +|:star| :* execute contents of a register |:<| :< shift lines one 'shiftwidth' left |:=| := print the cursor line number |:>| :> shift lines one 'shiftwidth' right @@ -1160,7 +1174,7 @@ tag command action ~ |:cclose| :ccl[ose] close quickfix window |:cd| :cd change directory |: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 |:cexpr| :cex[pr] read errors from expr 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 location list |: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 -|:luafile| :luaf[ile] execute Lua script file +|:luafile| :luaf[ile] execute |Lua| script file |:lvimgrep| :lv[imgrep] search for pattern in files |:lvimgrepadd| :lvimgrepa[dd] like :vimgrep, but append to current list |:lwindow| :lw[indow] open or close location window @@ -1402,7 +1416,7 @@ tag command action ~ |:number| :nu[mber] print lines with line number |:nunmap| :nun[map] like ":unmap" but 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 |:omapclear| :omapc[lear] remove all mappings 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 |:right| :ri[ght] right align text |: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 |:runtime| :ru[ntime] source vim scripts in 'runtimepath' |:substitute| :s[ubstitute] find and replace text @@ -1570,6 +1587,8 @@ tag command action ~ |:tab| :tab create new tab when opening new window |:tag| :ta[g] jump to tag |: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 |:tfirst| :tf[irst] jump to first matching tag |:throw| :th[row] throw an exception diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c index 9ff2a529ae..ada26a2a07 100644 --- a/src/nvim/api/ui.c +++ b/src/nvim/api/ui.c @@ -314,14 +314,11 @@ void nvim_ui_try_resize_grid(uint64_t channel_id, Integer grid, Integer width, ui_grid_resize((handle_T)grid, (int)width, (int)height, err); } -/// Tell Nvim the number of element displayed in popumenu. The amount of -/// movement by <PageUp> or <PageDown> is determined by the value set by this. -/// -/// If the ext_popupmenu option is false or the height is 0 or less, fails -/// with error. +/// Tells Nvim the number of elements displaying in the popumenu, to decide +/// <PageUp> and <PageDown> movement. /// /// @param channel_id -/// @param height The popupmenu height. +/// @param height Popupmenu height, must be greater than zero. /// @param[out] err Error details, if any void nvim_ui_pum_set_height(uint64_t channel_id, Integer height, Error *err) FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index ce49045f24..147830493a 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -437,18 +437,18 @@ Object nvim_eval(String expr, Error *err) 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. /// /// Only statements are executed. To evaluate an expression, prefix it /// with `return`: return my_function(...) /// -/// @param code lua code to execute +/// @param code Lua code to execute /// @param args Arguments to the code /// @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) 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 /// `height` of the new window must be specified. /// -/// With editor positioning 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. -/// Floating point values are allowed, but the builtin implementation (used by -/// TUI and GUIs without multigrid support) will always round down to nearest -/// integer. +/// 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 will truncate -/// values so floats are completely within the main screen grid. External GUIs +/// 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. /// -/// @param buffer handle of buffer to be displayed in the window -/// @param enter whether the window should be entered (made the current window) -/// @param config Dictionary for the window configuration accepts these keys: -/// - `relative`: If set, the window becomes a floating window. The window -/// will be placed with row,col coordinates relative to one of the -/// following: -/// - "editor" the global editor grid -/// - "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 of the window where the -/// position is defined. -/// - `anchor`: The corner of the float that the row,col position defines: -/// - "NW" north-west (default) -/// - "NE" north-east -/// - "SW" south-west -/// - "SE" south-east -/// - `height`: window height (in character cells). Minimum of 1. -/// - `width`: window width (in character cells). Minimum of 1. -/// - 'bufpos': position float relative text inside window `win` (only -/// when relative="win"). Takes a tuple of zero-indexed -/// [line, column]. Note: `row` and `col` if present, still -/// applies relative this position. By default `row=1` and `col=0` -/// are used (with default NW anchor), to make the float -/// behave like a tooltip under the buffer text. -/// - `row`: row position. Screen cell height are used as unit. Can be -/// floating point. -/// - `col`: column position. Screen cell width is used as unit. Can be -/// floating point. -/// - `focusable`: Whether window can be focused by wincmds and -/// mouse events. Defaults to true. Even if set to false, the window -/// can still be entered using |nvim_set_current_win()| API call. +/// Example (Lua): window-relative float +/// <pre> +/// vim.api.nvim_open_win(0, false, +/// {relative='win', row=3, col=3, width=12, height=3}) +/// </pre> +/// +/// Example (Lua): buffer-relative float (travels as buffer is scrolled) +/// <pre> +/// vim.api.nvim_open_win(0, false, +/// {relative='win', width=12, height=3, bufpos={100,10}}) +/// </pre> +/// +/// @param buffer Buffer to display, or 0 for current buffer +/// @param enter Enter the window (make it the current window) +/// @param config Map defining the window configuration. Keys: +/// - `relative`: Sets the window layout to "floating", placed at (row,col) +/// coordinates relative to one of: +/// - "editor" The global editor grid +/// - "win" Window given by the `win` field, or current window by +/// default. +/// - "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. -/// - `style`: Configure the apparance of the window. Currently only takes +/// - `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 displaing a temporary +/// 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`. The end-of-buffer region is hidden /// by setting `eob` flag of 'fillchars' to a space char, /// 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 /// /// @return Window handle, or 0 on error diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c index 3e9f292eb9..ba43bc6cb2 100644 --- a/src/nvim/api/window.c +++ b/src/nvim/api/window.c @@ -441,18 +441,17 @@ Boolean nvim_win_is_valid(Window window) } -/// Configure window position. Currently this is only used to configure -/// floating and external windows (including changing a split window to these -/// types). -/// -/// See documentation at |nvim_open_win()|, for the meaning of parameters. +/// 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. The following restriction apply: `row`, `col` and `relative` -/// must be reconfigured together. Only changing a subset of these is an error. +/// changed. `row`/`col` and `relative` must be reconfigured together. +/// +/// @see |nvim_open_win()| /// /// @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 void nvim_win_set_config(Window window, Dictionary config, Error *err) 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 -/// |nvim_open_win()|. +/// The returned value may be given to |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[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) FUNC_API_SINCE(6) { diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua index 9149285efd..f8e52d31c9 100644 --- a/src/nvim/lua/vim.lua +++ b/src/nvim/lua/vim.lua @@ -157,6 +157,7 @@ end --- Return a human-readable representation of the given object. --- --@see https://github.com/kikito/inspect.lua +--@see https://github.com/mpeterv/vinspect local function inspect(object, options) -- luacheck: no unused error(object, options) -- Stub for gen_vimdoc.py end diff --git a/src/nvim/window.c b/src/nvim/window.c index 315b5ef759..7b6083cf29 100644 --- a/src/nvim/window.c +++ b/src/nvim/window.c @@ -969,8 +969,8 @@ bool parse_float_config(Dictionary config, FloatConfig *fconfig, bool reconf, } if (has_relative != has_row || has_row != has_col) { - api_set_error(err, kErrorTypeValidation, "All of 'relative', 'row', and " - "'col' has to be specified at once"); + api_set_error(err, kErrorTypeValidation, + "'relative' requires 'row'/'col' or 'bufpos'"); return false; } return true; diff --git a/test/functional/ui/float_spec.lua b/test/functional/ui/float_spec.lua index f6c18ba841..dbaf6f802b 100644 --- a/test/functional/ui/float_spec.lua +++ b/test/functional/ui/float_spec.lua @@ -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})) 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'})) - 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'})) eq("'width' key must be a positive Integer", pcall_err(meths.open_win,buf, false, {width=-1,height=2,relative='editor'})) |