diff options
Diffstat (limited to 'src')
| -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 |
5 files changed, 69 insertions, 69 deletions
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; |