win_config.c File Reference

#include <assert.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "nvim/api/private/defs.h"
#include "nvim/api/private/helpers.h"
#include "nvim/api/win_config.h"
#include "nvim/ascii.h"
#include "nvim/highlight_group.h"
#include "nvim/option.h"
#include "nvim/screen.h"
#include "nvim/strings.h"
#include "nvim/syntax.h"
#include "nvim/ui.h"
#include "nvim/window.h"

Functions
Window	nvim_open_win (Buffer buffer, Boolean enter, Dict(float_config) *config, Error *err) FUNC_API_CHECK_TEXTLOCK
void	nvim_win_set_config (Window window, Dict(float_config) *config, Error *err) FUNC_API_SINCE(6)
Dictionary	nvim_win_get_config (Window window, Error *err) FUNC_API_SINCE(6)

Function Documentation

nvim_open_win()

Window nvim_open_win	(	Buffer	buffer,
		Boolean	enter,
		Dict(float_config) *	config,
		Error *	err
	)

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}})

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 WinSeparator 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.
[out]	err	Error details, if any

Returns

Window handle, or 0 on error

nvim_win_get_config()

Dictionary nvim_win_get_config	(	Window	window,
		Error *	err
	)

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
[out]	err	Error details, if any

Returns

Map defining the window configuration, see |nvim_open_win()|

nvim_win_set_config()

void nvim_win_set_config	(	Window	window,
		Dict(float_config) *	config,
		Error *	err
	)

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.

See also

|nvim_open_win()|

Parameters

	window	Window handle, or 0 for current window
	config	Map defining the window configuration, see |nvim_open_win()|
[out]	err	Error details, if any