floats: implement floating windows

Co-Author: Dongdong Zhou <dzhou121@gmail.com>

src/nvim/api/private/helpers.c

@@ -1004,7 +1004,9 @@ static void init_ui_event_metadata(Dictionary *metadata)
   Array ui_options = ARRAY_DICT_INIT;
   ADD(ui_options, STRING_OBJ(cstr_to_string("rgb")));
   for (UIExtension i = 0; i < kUIExtCount; i++) {
-    ADD(ui_options, STRING_OBJ(cstr_to_string(ui_ext_names[i])));
+    if (ui_ext_names[i][0] != '_') {
+      ADD(ui_options, STRING_OBJ(cstr_to_string(ui_ext_names[i])));
+    }
   }
   PUT(*metadata, "ui_options", ARRAY_OBJ(ui_options));
 }

src/nvim/api/ui.c

@@ -17,6 +17,8 @@
 #include "nvim/popupmnu.h"
 #include "nvim/cursor_shape.h"
 #include "nvim/highlight.h"
+#include "nvim/screen.h"
+#include "nvim/window.h"
 
 #ifdef INCLUDE_GENERATED_DECLARATIONS
 # include "api/ui.c.generated.h"

src/nvim/api/ui_events.in.h

@@ -76,7 +76,7 @@ void hl_attr_define(Integer id, HlAttrs rgb_attrs, HlAttrs cterm_attrs,
 void grid_resize(Integer grid, Integer width, Integer height)
   FUNC_API_SINCE(5) FUNC_API_REMOTE_IMPL FUNC_API_COMPOSITOR_IMPL;
 void grid_clear(Integer grid)
-  FUNC_API_SINCE(5) FUNC_API_REMOTE_IMPL FUNC_API_COMPOSITOR_IMPL;
+  FUNC_API_SINCE(5) FUNC_API_REMOTE_IMPL;
 void grid_cursor_goto(Integer grid, Integer row, Integer col)
   FUNC_API_SINCE(5) FUNC_API_REMOTE_IMPL FUNC_API_COMPOSITOR_IMPL;
 void grid_line(Integer grid, Integer row, Integer col_start, Array data)
@@ -101,8 +101,15 @@ void event(char *name, Array args, bool *args_consumed)
 void win_pos(Integer grid, Integer win, Integer startrow,
              Integer startcol, Integer width, Integer height)
   FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY;
+void win_float_pos(Integer grid, Window win, String anchor, Integer anchor_grid,
+                   Float anchor_row, Float anchor_col, Boolean focusable)
+  FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY;
+void win_external_pos(Integer grid, Window win)
+  FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY;
 void win_hide(Integer grid)
   FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY;
+void win_close(Integer grid)
+  FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY;
 void win_scroll_over_start(void)
   FUNC_API_SINCE(6) FUNC_API_BRIDGE_IMPL FUNC_API_COMPOSITOR_IMPL;
 void win_scroll_over_reset(void)

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

src/nvim/api/window.c

@@ -432,3 +432,41 @@ Boolean nvim_win_is_valid(Window window)
   return ret;
 }
 
+
+/// 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.
+void nvim_win_config(Window window, Integer width, Integer height,
+                     Dictionary options, Error *err)
+  FUNC_API_SINCE(6)
+{
+  win_T *win = find_window_by_handle(window, err);
+  if (!win) {
+    return;
+  }
+  bool new_float = !win->w_floating;
+  width = width > 0 ? width: win->w_width;
+  height = height > 0 ? height : win->w_height;
+  // reuse old values, if not overriden
+  FloatConfig config = new_float ? FLOAT_CONFIG_INIT : win->w_float_config;
+
+  if (!parse_float_config(options, &config, !new_float, err)) {
+    return;
+  }
+  if (new_float) {
+    if (!win_new_float(win, (int)width, (int)height, config, err)) {
+      return;
+    }
+    redraw_later(NOT_VALID);
+  } else {
+    win_config_float(win, (int)width, (int)height, config);
+    win->w_pos_changed = true;
+  }
+}