floats: implement floating windows

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

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