diff options
| -rw-r--r-- | runtime/doc/api.txt | 37 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 2 |
2 files changed, 39 insertions, 0 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c9d526d9aa..f0e3f2c3a1 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* diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 955920d6ae..a773234ea0 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -998,6 +998,8 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err) /// 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. /// /// @param buffer handle of buffer to be displayed in the window |