From 9a1675b065394734ddaef91a314896028e2b1d46 Mon Sep 17 00:00:00 2001 From: Björn Linse Date: Wed, 26 Apr 2017 15:28:10 +0200 Subject: floats: implement floating windows Co-Author: Dongdong Zhou --- src/nvim/api/vim.c | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) (limited to 'src/nvim/api/vim.c') diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 5a4d0a11e7..94d1697083 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -987,6 +987,84 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err) return buf->b_fnum; } +/// 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. +/// +/// Exactly one of `external` and `relative` must be specified. +/// +/// @param buffer handle of buffer to be displayed in the window +/// @param enter whether the window should be entered (made the current window) +/// @param width width of window (in character cells) +/// @param height height of window (in character cells) +/// @param 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. +/// +/// @param[out] err Error details, if any +/// @return the window handle or 0 when error +Window nvim_open_win(Buffer buffer, Boolean enter, + Integer width, Integer height, + Dictionary options, Error *err) + FUNC_API_SINCE(6) +{ + win_T *old = curwin; + FloatConfig config = FLOAT_CONFIG_INIT; + if (!parse_float_config(options, &config, false, err)) { + return 0; + } + win_T *wp = win_new_float(NULL, (int)width, (int)height, config, err); + if (!wp) { + return 0; + } + if (buffer > 0) { + nvim_set_current_buf(buffer, err); + } + if (!enter) { + win_enter(old, false); + } + return wp->handle; +} + /// Gets the current list of tabpage handles. /// /// @return List of tabpage handles -- cgit