diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 156 |
1 files changed, 156 insertions, 0 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c9d526d9aa..7172091ceb 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -232,7 +232,44 @@ An example of calling the api from vimscript: > " later call nvim_buf_clear_namespace(0, src, 0, -1) + + +============================================================================== +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_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. + +|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 +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. + +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) + " 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* @@ -576,6 +613,94 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Parameters: ~ {window} Window handle +nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* + Creates a new, empty, unnamed buffer. + + Parameters: ~ + {listed} Controls 'buflisted' + {scratch} Creates a "throwaway" |scratch-buffer| for + temporary work (always 'nomodified') + + Return: ~ + Buffer handle, or 0 on error + + *nvim_open_win()* +nvim_open_win({buffer}, {enter}, {width}, {height}, {options}) + 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 draw + 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. + + Parameters: ~ + {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: + + `relative`: If set, the window becomes a + floating window. The window will be placed with + row,col coordinates relative one of the + following: + "editor" the global editor grid + "win" a window. Use 'win' option below to + specify window id, or current window will + be used by default. + "cursor" the cursor position in current window. + + `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 + + `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. + + `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. + + `win`: when using relative='win', window id of the window + where the position is defined. + + `external`: GUI should display the window as an external + top-level window. Currently accepts no other + positioning options together with this. + + 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. + + 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: ~ + + Return: ~ + the window handle or 0 when error + nvim_list_tabpages() *nvim_list_tabpages()* Gets the current list of tabpage handles. @@ -1436,6 +1561,37 @@ 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}) + 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. + + 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. + +nvim_win_close({window}, {force}) *nvim_win_close()* + Close a window. + + This is equivalent to |:close| with count except that it takes + a window id. + + Parameters: ~ + {window} Window handle + {force} Behave like `:close!` The last window of a + buffer with unwritten changes can be closed. The + buffer will become hidden, even if 'hidden' is + not set. + + Return: ~ + Window number + ============================================================================== Tabpage Functions *api-tabpage* |