mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-10-09 11:26:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: floating windows introduction

Browse Source
This commit is contained in:
Björn Linse
2019-03-03 12:38:14 +01:00
parent 81e84f2aae
commit 4ab0dcc4a9
2 changed files with 39 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
runtime/doc/api.txt
View File

@@ -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*

2
src/nvim/api/vim.c
View File

@@ -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