diff options
| -rw-r--r-- | runtime/doc/api.txt | 49 | ||||
| -rw-r--r-- | src/nvim/api/window.c | 8 |
2 files changed, 42 insertions, 15 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 7172091ceb..d057dfca96 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -245,10 +245,10 @@ functional buffer windows and support user editing. They support the standard 'statusline' is not supported currently). Floating windows are created either by |nvim_open_win()| to open a new window, -or |nvim_win_config()| to reconfigure a normal window into a float. Currently -the position can either be grid coordinates relative 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()| help. +or |nvim_win_set_config()| to reconfigure a normal window into a float. +Currently the position can either be grid coordinates relative 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_buffer()| can be used. The text in @@ -264,8 +264,9 @@ Here is an example for creating 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"]) - let opts = {'relative': 'cursor', 'col':0, 'row':1, 'anchor': 'NW'} - let win = nvim_open_win(buf, 0, 10, 2, opts) + let opts = {'relative': 'cursor', 'width': 10, 'height': 2, 'col': 0, + \ 'row': 1, 'anchor': 'NW'} + let win = nvim_open_win(buf, 0, opts) " optional: change highlight, otherwise Pmenu is used call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight') > @@ -624,8 +625,7 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* Return: ~ Buffer handle, or 0 on error - *nvim_open_win()* -nvim_open_win({buffer}, {enter}, {width}, {height}, {options}) +nvim_open_win({buffer}, {enter}, {options}) *nvim_open_win()* Open a new window. Currently this is used to open floating and external windows. @@ -643,8 +643,6 @@ nvim_open_win({buffer}, {enter}, {width}, {height}, {options}) {buffer} handle of buffer to be displayed in the window {enter} whether the window should be entered (made the current window) - {width} width of window (in character cells) - {height} height of window (in character cells) {options} dict of options for configuring window positioning accepts the following keys: @@ -670,6 +668,12 @@ nvim_open_win({buffer}, {enter}, {width}, {height}, {options}) the window can still be entered using |nvim_set_current_win()| API call. + `height`: window height in character cells. Cannot be + smaller than 1. + + `width`: window width in character cells. Cannot be + smaller than 2. + `row`: row position. Screen cell height are used as unit. Can be floating point. @@ -1561,21 +1565,38 @@ nvim_win_is_valid({window}) *nvim_win_is_valid()* Return: ~ true if the window is valid, false otherwise - *nvim_win_config()* -nvim_win_config({window}, {width}, {height}, {options}) +nvim_win_set_config({window}, {options}) *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. Pass in -1 for 'witdh' and 'height' to keep - exiting size. + parameters. Pass in 0 for `width` and `height` to keep + existing size. 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. + Parameters: ~ + {window} Window handle + {options} Dictionary of options + +nvim_win_get_config({window}) *nvim_win_get_config()* + Return window configuration. + + Return a dictionary containing the same options that can be + given to |nvim_open_win()|. + + `relative` will be empty for normal windows. + + Parameters: ~ + {window} Window handle + + Return: ~ + Window configuration + nvim_win_close({window}, {force}) *nvim_win_close()* Close a window. diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c index ba505af87e..dd63dbbb4a 100644 --- a/src/nvim/api/window.c +++ b/src/nvim/api/window.c @@ -439,11 +439,15 @@ Boolean nvim_win_is_valid(Window window) /// types). /// /// See documentation at |nvim_open_win()|, for the meaning of parameters. Pass -/// in 0 for 'witdh' and 'height' to keep exiting size. +/// in 0 for `width` and `height` to keep existing size. /// /// 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. +/// +/// @param window Window handle +/// @param options Dictionary of options +/// @param[out] err Error details, if any void nvim_win_set_config(Window window, Dictionary options, Error *err) FUNC_API_SINCE(6) { @@ -476,6 +480,8 @@ void nvim_win_set_config(Window window, Dictionary options, Error *err) /// Return a dictionary containing the same options that can be given to /// |nvim_open_win()|. /// +/// `relative` will be empty for normal windows. +/// /// @param window Window handle /// @param[out] err Error details, if any /// @return Window configuration |